EmanuProds/dotfiles / skills/agent-orchestrator
agent-orchestrator"
VerifiedOrchestrates multi-agent workflows for complex tasks. Use when a task requires coordination between multiple specialized agents (architect, debug, code-reviewer, refactor, etc.).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.4 KB |
SKILL.md
View on GitHub---
name: agent-orchestrator"
description: Orchestrates multi-agent workflows for complex tasks. Use when a task requires coordination between multiple specialized agents (architect, debug, code-reviewer, refactor, etc.).
---
# Agent Orchestrator Skill
## Orchestration Patterns
### Sequential Pipeline
```
Task → Architect → Build → Test → Review → Done
```
Each agent completes its phase before the next starts.
### Parallel Fan-out
```
Task → [Architect, Security-Audit, Performance-Analysis] → Aggregator → Done
```
Multiple agents work simultaneously on different aspects.
### Iterative Loop
```
Task → Build → Review → (issues?) → Build → Review → Done
```
Build and review iterate until quality bar met.
### Hierarchical Delegation
```
Orchestrator
├── Architect (plans)
├── Build Team
│ ├── Backend Agent
│ ├── Frontend Agent
│ └── DevOps Agent
└── QA Team
├── Test Agent
├── Security Agent
└── Performance Agent
```
## Workflow Templates
### Feature Development
```yaml
name: feature-development
phases:
- name: plan
agent: architect
input: requirements
output: spec.md
- name: implement
agent: build
input: spec.md
output: code changes
- name: test
agent: build
input: code changes
output: test results
- name: review
agent: code-reviewer
input: code changes + test results
output: review feedback
- name: refine
agent: build
input: review feedback
output: final code
```
### Bug Fix
```yaml
name: bug-fix
phases:
- name: reproduce
agent: debug
input: bug report
output: reproduction steps + root cause
- name: fix
agent: build
input: root cause
output: fix + test
- name: verify
agent: debug
input: fix
output: verification results
- name: review
agent: code-reviewer
input: fix
output: approval
```
### Refactoring
```yaml
name: refactoring
phases:
- name: analyze
agent: refactor
input: target code
output: refactoring plan
- name: test-baseline
agent: build
input: target code
output: characterization tests
- name: execute
agent: refactor
input: plan + tests
output: refactored code
- name: verify
agent: build
input: refactored code
output: all tests pass
- name: review
agent: code-reviewer
input: refactored code
output: approval
```
### Code Review (Automated)
```yaml
name: pr-review
trigger: pull_request
phases:
- name: static-analysis
agents: [security-audit, performance-check]
parallel: true
- name: logic-review
agent: code-reviewer
depends_on: static-analysis
- name: test-validation
agent: build
depends_on: static-analysis
- name: aggregate
agent: orchestrator
input: all reviews
output: summary report
```
## Agent Definitions
### Primary Agents (User-facing)
| Agent | Role | When to Use |
|-------|------|-------------|
| `build` | Default implementation | Writing code, tests, fixes |
| `plan` | Planning only | High-level design, no code |
| `architect` | System design | Architecture decisions, ADRs |
### Subagents (Task-invoked)
| Agent | Role | Specialization |
|-------|------|----------------|
| `debug` | Troubleshooting | Root cause analysis, tracing |
| `code-reviewer` | Quality gate | Security, perf, maintainability |
| `refactor` | Code improvement | Structure, patterns, modernization |
| `explore` | Research | Codebase understanding, docs |
| `general` | Multi-step | Complex workflows, orchestration |
## Invocation Patterns
### Direct Invocation
```bash
# In OpenCode chat
@architect Design a user authentication system
@debug Why is the login API returning 500?
@code-reviewer Review the auth PR #123
```
### Task Tool (Programmatic)
```typescript
// In agent or script
await task({
agent: "architect",
prompt: "Design auth system with JWT, refresh tokens, OAuth2",
context: { files: ["src/auth/"], requirements: "..." }
});
await task({
agent: "code-reviewer",
prompt: "Review PR #123 for security issues",
context: { pr: 123 }
});
```
### Orchestrated Workflow
```typescript
async function runFeatureWorkflow(requirements: string) {
// Phase 1: Plan
const spec = await task({ agent: "architect", prompt: requirements });
// Phase 2: Implement
const implementation = await task({
agent: "build",
prompt: `Implement: ${spec}`
});
// Phase 3: Test (parallel with review prep)
const [testResults, reviewPrep] = await Promise.all([
task({ agent: "build", prompt: `Write tests for: ${implementation}` }),
task({ agent: "explore", prompt: `Summarize changes for review: ${implementation}` })
]);
// Phase 4: Review
const review = await task({
agent: "code-reviewer",
prompt: `Review: ${reviewPrep}`,
context: { testResults }
});
// Phase 5: Refine if needed
if (review.hasChanges) {
return runFeatureWorkflow(`${requirements}\n\nAddress: ${review.feedback}`);
}
return { spec, implementation, testResults, review };
}
```
## Coordination Mechanisms
### Shared Context
```json
{
"workflowId": "feat-auth-20240115",
"phase": "implement",
"artifacts": {
"spec": "docs/spec/auth.md",
"implementation": "src/auth/",
"tests": "tests/auth/"
},
"agents": {
"architect": { "status": "done", "output": "spec.md" },
"build": { "status": "in_progress", "started": "2024-01-15T10:00Z" }
}
}
```
### Handoff Protocol
```
FROM: architect
TO: build
ARTIFACT: spec.md
CONTEXT:
- Requirements: JWT + refresh + OAuth2
- Constraints: Use existing user model, Redis for sessions
- Decisions: Stateless auth, 15min access / 7d refresh
HANDOFF_NOTES: "Pay attention to token rotation security"
```
### Progress Tracking
```bash
# Check workflow status
opencode-skill agent-orchestrator status feat-auth-20240115
# Output:
# Workflow: feat-auth-20240115
# Phase: implement (2/5)
# ✓ architect - spec.md created
# ⟳ build - implementing login endpoint
# ○ test - pending
# ○ review - pending
# ○ refine - pending
```
## Best Practices
### When to Orchestrate
- Multi-phase tasks (plan → build → test → review)
- Cross-cutting concerns (security + performance + maintainability)
- Complex features requiring multiple specializations
- Quality gates needed before merge
### When NOT to Orchestrate
- Simple, single-purpose tasks
- Exploratory work (use explore agent directly)
- Quick fixes (use debug or build directly)
- Learning/experimentation
### Anti-Patterns
- ❌ Too many agents for simple task
- ❌ No clear handoff artifacts
- ❌ Circular dependencies between agents
- ❌ Orchestrator doing work instead of coordinating
- ❌ Skipping review phases for speed
## Integration with OpenCode
### Skill Commands
```
/orchestrate feature-development "Add user dashboard"
/orchestrate bug-fix "Login fails with special chars"
/orchestrate refactoring "Extract payment service"
/orchestrate pr-review 123
```
### Status Dashboard
```bash
# In OpenCode terminal
opencode-skill agent-orchestrator dashboard
# Shows active workflows, agent statuses, pending handoffs
```
## When to Use
- Complex feature development (3+ phases)
- Bug fixes requiring investigation + fix + verification
- Large refactoring with safety requirements
- Automated PR review pipelines
- Multi-team coordination
- Quality-critical changesRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |