Orchestrator Agent

The Orchestrator coordinates all development work. It reads state, delegates to specialists, tracks progress, and never writes code directly.

What It Does

Classifies work type - Feature, bugfix, enhancement, refactor
Reads project state - Completion tracking, pending decisions, blockers
Delegates to specialists - Routes work to appropriate agents
Manages autonomous loops - Continues until 100% complete
Validates results - Ensures quality through Reviewer
Tracks progress - Updates .agentful/completion.json

Model: Opus (requires highest reasoning for coordination)

Tools: Read, Write, Edit, Glob, Grep, Task, AskUserQuestion, TodoWrite

Core Rule

The Orchestrator NEVER writes code. It only coordinates other agents.

Work Classification

The Orchestrator intelligently classifies incoming work:

Type	Examples	Loops?
FEATURE_DEVELOPMENT	"Build auth", "Add dashboard"	Yes
BUGFIX	"Fix login error", "Resolve crash"	No
ENHANCEMENT	"Add X to Y", "Improve Z"	No
REFACTOR	"Clean up code", "Improve structure"	No
MAINTENANCE	"Update deps", "Security scan"	No

Feature Development (Autonomous)

User: "Build authentication"
 
Orchestrator:
1. Reads product spec
2. Picks next feature (login)
3. @backend → API routes
4. @frontend → Login page
5. @tester → Tests
6. @reviewer → Validation
7. @fixer → Fix issues
8. Updates completion.json
9. Picks next feature (register)
10. Repeats until auth = 100%

Loops until complete.

Bugfix (One-Shot)

User: "Fix login bug"
 
Orchestrator:
1. @backend → Fix the bug
2. @tester → Add regression test
3. @reviewer → Validate fix
4. Done (doesn't continue)

Stops after fixing.

State Management

Three key files in .agentful/:

1. state.json

Current work state:

{
  "current_task": "implement-user-auth",
  "current_phase": "implementation",
  "iterations": 5,
  "blocked_on": []
}

2. completion.json

Feature completion tracking:

{
  "features": {
    "authentication": {
      "status": "in_progress",
      "score": 65,
      "completed_at": null
    },
    "dashboard": {
      "status": "pending",
      "score": 0
    }
  },
  "gates": {
    "tests_passing": true,
    "no_type_errors": true,
    "no_dead_code": false,
    "coverage_80": false
  },
  "overall": 32
}

Quality gates must all be true for 100% completion.

3. decisions.json

Pending user decisions:

{
  "pending": [
    {
      "id": "decision-001",
      "question": "JWT or session cookies?",
      "options": ["JWT", "Sessions", "Clerk"],
      "blocking": ["authentication"],
      "timestamp": "2026-01-20T00:00:00Z"
    }
  ]
}

Standard Workflow

1. Read product spec (.claude/product/index.md)
2. Read state.json (current progress)
3. Read completion.json (what's done)
4. Read decisions.json (what's blocked)
5. Pick highest priority unblocked work
6. Delegate to specialist agent
7. Run Reviewer
8. If issues → Fixer → Reviewer again
9. Update completion.json
10. Loop (if FEATURE_DEVELOPMENT)

Delegation Pattern

Always reference the product spec:

Task("backend", "Implement JWT login per .claude/product/ auth section")
Task("frontend", "Create login page per .claude/product/ auth UI spec")
Task("tester", "Write tests for auth service")
Task("reviewer", "Review all auth changes")

After ANY implementation, always run Reviewer:

Task("reviewer", "Review changes in src/auth/")

If Reviewer fails, delegate to Fixer:

Task("fixer", "Fix issues from last review")

Decision Handling

When user input needed:

1. Add to decisions.json:

{
  "id": "decision-001",
  "question": "Should we use JWT or session cookies for auth?",
  "options": ["JWT", "Sessions", "Clerk"],
  "context": "Building authentication system",
  "blocking": ["authentication"],
  "timestamp": "2026-01-20T00:00:00Z"
}

2. Stop work on blocked features

Move to next non-blocked work.

3. Notify user:

⚠️ Decision needed: Should we use JWT or session cookies?
 
Run /agentful-decide to answer.
 
Blocked: authentication

Loop Termination

The Orchestrator stops when:

completion.overall === 100 &&
all gates === true &&
all features.status === "complete"

Then outputs:

<promise>AGENTFUL_COMPLETE</promise>

Example: Full Cycle

User: "Build the authentication system"
 
[Read .claude/product/] → Auth spec found
[Read state.json] → No current work
[Read completion.json] → Auth = 0%
 
[Classify] → FEATURE_DEVELOPMENT (autonomous loop)
 
[Delegate] Task("backend", "Implement JWT auth API per .claude/product/")
[Wait] Backend completes
 
[Delegate] Task("frontend", "Create login page per .claude/product/")
[Wait] Frontend completes
 
[Delegate] Task("tester", "Write tests for auth")
[Wait] Tester completes
 
[Delegate] Task("reviewer", "Review auth changes")
[Wait] Reviewer finds: unused import, missing test, console.log
 
[Delegate] Task("fixer", "Fix issues from last review")
[Wait] Fixer completes
 
[Delegate] Task("reviewer", "Re-review auth")
[Wait] Reviewer passes
 
[Update] completion.json: auth.score = 100, status = "complete"
[Check] More features? No
[Check] All gates true? Yes
[Output] <promise>AGENTFUL_COMPLETE</promise>

Product Spec Format

Uses the hierarchical structure:

.claude/product/
├── index.md           # Project overview
├── domains/           # Business domains (for complex projects)
│   ├── authentication/
│   │   ├── index.md
│   │   └── features/
│   │       ├── login.md
│   │       └── register.md
│   └── dashboard/
│       └── features/
│           └── overview.md
└── README.md

The Orchestrator reads this structure and tracks completion accordingly.

Key Behaviors

Always run Reviewer:

After implementation → Always run Reviewer
If Reviewer fails → Always run Fixer
After Fixer → Always run Reviewer again

Never skip validation:

Code written → Tests added → Reviewer validates → Gates checked

Move on when blocked:

Feature needs decision → Add to decisions.json → Pick next feature

Update state after every step:

Work completed → Update completion.json → Continue

Common Issues

Stuck on Same Task

Check:

.agentful/decisions.json for blockers
.agentful/last-validation.json for validation failures
If work type is one-off (bugfix), it won't loop

Fix:

Resolve decisions with /agentful-decide
Check why Reviewer keeps failing

Completion Not Updating

Check:

Reviewer is passing (all gates true)
Feature status set to "complete"
Quality gates are all true

Fix:

Fix remaining validation issues
Ensure all subtasks complete

Wrong Work Classification

Check: If treating bugfix as feature (looping incorrectly)

Fix:

User should be explicit: "Fix the bug" vs "Build the feature"
Orchestrator should detect one-off vs multi-step work

Monitoring

# Current state
cat .agentful/state.json
 
# Completion progress
cat .agentful/completion.json
 
# Pending decisions
cat .agentful/decisions.json
 
# Last review results
cat .agentful/last-validation.json
 
# Full status
# Run /agentful-status command

Integration with Other Agents

Architect:

Orchestrator → "I need Next.js specialist"
Architect → Generates nextjs-agent.md
Orchestrator → Can now delegate to @nextjs-agent

Backend/Frontend:

Orchestrator → Delegates implementation
Backend/Frontend → Implements code
Orchestrator → Runs Reviewer

Tester:

Orchestrator → "Implementation done, need tests"
Tester → Writes tests
Orchestrator → Runs Reviewer for coverage check

Reviewer:

Orchestrator → "Validate this work"
Reviewer → Runs 9 checks, finds issues
Orchestrator → Delegates to Fixer

Fixer:

Orchestrator → "Fix these issues"
Fixer → Reads last-validation.json, fixes problems
Orchestrator → Re-runs Reviewer

Advanced Usage

Manual invocation

/agentful-start

Starts autonomous loop.

Selective execution

Focus on specific feature:

User: "Only work on authentication, don't continue to other features"

Orchestrator will complete auth and stop.

Sequential Execution

Agents execute one at a time in the order called:

Task("backend", "Implement user API")
Task("frontend", "Implement user profile UI")
Task("tester", "Prepare test fixtures")

Each task blocks until complete before the next starts.

See Background Agent Patterns for details on current sequential execution and future parallel execution plans.

What It Does

Core Rule

Work Classification

Feature Development (Autonomous)

Bugfix (One-Shot)

State Management

1. state.json

2. completion.json

3. decisions.json

Standard Workflow

Delegation Pattern

Decision Handling

Loop Termination

Example: Full Cycle

Product Spec Format

Key Behaviors

Common Issues

Stuck on Same Task

Completion Not Updating

Wrong Work Classification

Monitoring

Integration with Other Agents

Advanced Usage

Manual invocation

Selective execution

Sequential Execution

See Also