Orchestrator

# /orchestrator -- Autonomous Task Pipeline

**Arguments:** $ARGUMENTS
(e.g. "only FEAT-003", "from REFAC-002", or empty for full queue)

## Principles

1. Full autonomy -- no user intervention, queue is processed completely
2. Self-healing -- 3 attempts per problem, then skip + document
3. Resume-capable -- state.json is the runtime database
4. **Delegation** -- task execution via `/execute-task` (no duplicated code)
5. **Lean main context** -- Main = queue manager, `/execute-task` = worker
6. **Branch isolation** -- each task on its own branch (managed by /execute-task)
7. **Sequential execution** -- always 1 task at a time, no parallelism

---

## Architecture

/orchestrator (Main = Queue Manager) | |-- Phase 0: Init / Resume |-- Phase 1: Queue Build (INLINE, no sub-agent) | |-- Phase 2: Task Execution (Loop over queue) | | | |-- 2.1: Take task from queue | |-- 2.2: Run /execute-task as Sub-Agent <-- DELEGATION | | (Branch, Worktree, Impl, Test, Learn, Merge) | |-- 2.3: Process result + validation + retries | |-- 2.4: Deps check (unblocked tasks) | +-- 2.5: Post-merge validation (full test suite on base branch) | +-- Phase 3: Completion (consistency check, report)

---

## Model Selection

See `execute-task.md` for the full per-phase model table. Orchestrator-specific
sub-agents:

| Sub-Agent | Model | Rationale |
|---|---|---|
| 2.3b Fix Analysis | `sonnet` | Root cause classification (fixable/structural) |
| 3 Completion Consistency Check | `haiku` | Mechanical state.json + docs validation |

Phase 1 (Queue Build) is now inline -- no sub-agent, no model choice.

---

## Context Rules

| Rule | Details |
|------|---------|
| Main reads | ONLY `docs/orchestrator_state.json` + `.build/followup_queue.json` (after pipeline run) |
| Sub-agent prompts | Max 10 lines with all required paths |
| Sub-agent results | Max 5 lines: STATUS + MERGED + TESTS + LINT + SUMMARY |
| state.json updates | Main: queue/active/history. /execute-task: phase/status/branch/merged |
| .build/ | Runtime artifacts (Follow-Up Queue). Gitignored. Lives in repo root |

---

## State Schema

`docs/orchestrator_state.json`

features.{ID}.status: "backlog"|"approved"|"in_progress"|"done"|"blocked"|"skipped" features.{ID}.plan: "docs/backlog/features/FEAT-XXX_name.md" features.{ID}.deps: ["FEAT-XXX", ...] features.{ID}.branch: null | "feat/FEAT-XXX_name" features.{ID}.merged: false | true features.{ID}.skill: null | "your-skill-name" orchestrator.status: "idle"|"running"|"paused"|"completed"|"error" orchestrator.phase: null|"init"|"executing"|"docs_check"|"completed" orchestrator.base_branch: "main" queue: [IDs] active: [IDs] history: [{id, result, timestamp}] errors: [{id, phase, error, category, attempts: [{attempt, phase, error, timestamp}]}]

**Error Schema Details:**
- `category`: `"fixable"` | `"structural"` -- set by the analysis agent
- `attempts[]`: Complete history of all attempts (not just last error)
- The analysis agent uses the full attempt history to avoid loops

---

## Phase 0: Init / Resume

Read `docs/orchestrator_state.json`.

- **running**: RESUME. Active tasks without "done" back to queue. Done tasks out of queue.
- **paused**: Check blockers. Resolved -> continue. Done tasks out of queue.
- **idle/completed**: Fresh start -> Phase 1.
- **error**: Recovery. "done" -> history. Rest -> queue. Done tasks out of queue.

**Queue Hygiene (on EVERY start/resume):**
Filter queue: only tasks with status "approved" or "in_progress" remain.
Remove tasks with "done", "draft", "skipped".
(`in_progress` = crash recovery or retry with existing branch)

State: status -> "running", base_branch -> "main" (or your configured branch).

---

## Phase 1: Queue Build (Inline)

**No sub-agent.** Toposort is trivial and state.json is already in the main
context. Main builds the queue inline with `jq`.

```bash
cd {ABS_PATH}

# 1. Extract all candidate tasks (status "approved" or "in_progress") across
#    features/bugfixes/refactors/tests categories.
jq -r '
  [.features, .bugfixes, .refactors, .tests]
  | map(to_entries[] | select(.value.status == "approved" or .value.status == "in_progress"))
  | flatten
  | map({id: .key, deps: (.value.deps // [])})
' docs/orchestrator_state.json > /tmp/orch_candidates.json

# 2. Apply $ARGUMENTS filter if provided
#    (e.g. "only FEAT-003" -> keep only FEAT-003; "from REFAC-002" -> from that ID onward)

# 3. Topological sort: tasks with no unresolved deps first.
#    An unresolved dep = referenced ID whose status != "done".
#    Iterate: pick ready tasks (all deps done or not in candidates),
#    append to queue, remove from pool, repeat until empty or stalled.

Implementation: Main executes the above inline, produces a flat ordered list of task IDs, writes queue + orchestrator.phase = "executing" to state.json. If the loop stalls (remaining tasks all have unresolved deps on each other): flag circular dependency, pause, report.

Expected output (for log only):

QUEUE: [FEAT-001, BUG-003, FEAT-002, ...]

---

Phase 2: Task Execution (Loop)

2.1 Prepare Task (Main)

Take task ID from queue, move to active, status -> "in_progress".

2.2 Delegate to /execute-task (Sub-Agent)

Read and follow {ABS_PATH}/.claude/commands/execute-task.md. Task-ID: {ID} Working directory: {ABS_PATH} cd {ABS_PATH} as first bash command. Execute the COMPLETE /execute-task workflow (pre-flight through Phase 7).

Result (ONLY 5 lines): STATUS: done|blocked|failed MERGED: true|false TESTS: {new} new, {total} total, {passed} passed, {failed} failed LINT: OK|FAILED ({N} errors) SUMMARY: [1 sentence]

2.3 Process Result (Main)

Validation:

1. STATUS != "done" -> blocked/failed handling
2. TESTS: {failed} > 0 -> rejected
3. LINT: "FAILED" -> rejected
4. TESTS: {new} < 1 -> rejected (exception: REFAC/docs tasks)

On success: active -> history with `{id, result: "done", ```