orchestrator

name	orchestrator
description	Orchestrates implementation and review of phase plans via subagents. Use when given a phase MD file to complete.

Orchestrator Skill

Read and follow agent-conduct, testing-principles, and subagents before starting. subagents covers orchestrator role, agent selection (always writable), briefing, skill discovery, and error handling. This skill covers only the orchestrator-specific procedure.

Use skills named in the phase file's Instructions section if specified; otherwise follow the skill-discovery procedure in subagents.

Input

A phase MD file containing items with - [ ] implemented and - [ ] reviewed checkboxes, possibly grouped into ordered batches.

Procedure

1. Read the phase file. Note which items are already checked (skip those).

2. Process items in order

• Sequential items: one at a time.
• Parallel batch: one implementation subagent per item concurrently.
• Complete and review each batch before starting the next.

3. For each item (or batch)

a. Implementation

Launch an implementor subagent with:

• Conventions, testing-principles, and implementor skill names + file paths (to read).
• Item description, spec.md section reference, phase instructions.
• "Read spec.md for acceptance tests. Follow TDD cycle and testing-principles. Run tests and linters."

On success, check - [x] implemented.

b. Review

Launch a reviewer subagent with:

• Conventions, testing-principles, and reviewer skill names + file paths (to read).
• Item(s) description, spec.md section reference(s), phase instructions.
• "You have clean context. Read spec.md, source and test files, run tests and linter, return PASS or FAIL with specific feedback."

PASS: check - [x] reviewed. FAIL: launch new implementor with feedback, then fresh reviewer. Repeat until PASS.

4. Phase completion

All checkboxes checked -> commit with Implement phase <N>.

5. Spec-aware PR review (after all phases)

Launch a pr-reviewer subagent with:

• pr-reviewer skill name + file path.
• Path to spec document.
• "Review all changes on this branch vs base. Check code quality, bugs, usability, and spec conformance. Fix via implementor subagents."

Follow fix-and-commit cycle. Repeat with fresh context until 2 consecutive clean passes.

6. Spec-free PR review

Same as step 5 but without the spec document (focus on code quality and usability only). Repeat until 2 consecutive clean passes.

Error Handling

• Transient failures: see subagents.
• File removal: delete normally. If deletion fails (e.g. NFS refusing the unlink), move the file to .tmp/trash/ in the repo instead; clean up after all phases.
• Blocker reported by subagent (per agent-conduct § Honesty About Blockers - e.g. an external API cannot do what the spec requires):
  1. Do NOT relaunch the implementor to "find a way". Do NOT check the item.
  2. Write blocker-phase<N>-<item-id>.md next to the phase file, containing: the item, the impossibility (what was tried, what failed and why), and 1-3 proposed alternatives or clarifications needed from the user.
  3. Abort the current phase and any later phases that depend on the blocked item. Continue only with independent phases.
  4. At the end, report all blocker files and which phases were skipped.

Rules

• Follow the rules in subagents (no direct implementation, no read-only agents for writing work, etc.).
• NEVER check a checkbox until the subagent confirms success.
• NEVER skip or reorder items unless the phase file allows parallel execution.
• Do not git push unless the user asked for it or the phase work is on a PR branch that must be updated. Never push to master, main, or develop.