Build a Custom Orchestrator
Who is this for (1)
- Stakeholder Persona: External Architect Evaluator — Written for the External Architect Evaluator reader.
Use this guide to implement your own orchestration strategy while keeping spec-kitty as the workflow host.
Contract Rules
Your orchestrator must:
- Call only
spec-kitty orchestrator-api ...subcommands for workflow state (output is always JSON). - Treat
spec-kittyas source of truth for lane state and dependencies. - Never write
kitty-specs/<feature>/tasks/*.mdlanes directly.
Required Flow
- Check API compatibility.
- Poll for ready WPs.
- Start implementation for selected WPs.
- Transition WPs through implementation, review, approval, and rework loops.
- Accept when all WPs are terminal/accepted, then merge through your normal landing process.
1. Check compatibility
spec-kitty orchestrator-api contract-version2. Discover work
spec-kitty orchestrator-api mission-state --mission <slug>spec-kitty orchestrator-api list-ready --mission <slug>3. Start implementation
spec-kitty orchestrator-api start-implementation \ --mission <slug> \ --wp WP01 \ --actor my-orchestrator \ --policy '<json>' \Use returned workspace_path and prompt_path to run your agent process.
4. Drive transitions
# implementation completespec-kitty orchestrator-api transition \ --mission <slug> --wp WP01 --to for_review \ --actor my-orchestrator --policy '<json>' \ --subtasks-complete --implementation-evidence-present# reviewer claims active reviewspec-kitty orchestrator-api start-review \ --mission <slug> --wp WP01 --actor my-orchestrator \ --policy '<json>' --review-ref review/WP01/attempt-1
# review approvedspec-kitty orchestrator-api transition \ --mission <slug> --wp WP01 --to done \ --actor my-orchestrator \ --policy '<json>' \ --review-ref review/WP01/attempt-1 \ --review-result-json '{"reviewer":"reviewer-bot","verdict":"approved","reference":"review/WP01/attempt-1"}' \ --evidence-json '{"review":{"reviewer":"reviewer-bot","verdict":"approved","reference":"review/WP01/attempt-1"}}' \ --note "Approved by reviewer-bot"
# review rejected -> reworkspec-kitty orchestrator-api transition \ --mission <slug> --wp WP01 --to in_progress \ --actor my-orchestrator \ --policy '<json>' \ --review-ref review/WP01/attempt-1 \ --review-result-json '{"reviewer":"reviewer-bot","verdict":"changes_requested","reference":"review/WP01/attempt-1"}' \ --note "Rejected by reviewer-bot; rework required"5. Finalize
spec-kitty orchestrator-api accept-mission --mission <slug> --actor my-orchestratorspec-kitty orchestrator-api merge-mission --mission <slug> --target main --strategy mergePolicy JSON Template
Run-affecting operations require --policy with these keys:
{ "orchestrator_id": "my-orchestrator", "orchestrator_version": "0.1.0", "agent_family": "claude", "approval_mode": "supervised", "sandbox_mode": "workspace_write", "network_mode": "none", "dangerous_flags": []}Lane and Error Semantics
- Use API lane
in_progress; host maps it to internaldoing. - Expect deterministic
error_codeon failures. - Build retry/backoff logic based on
error_code, not message text.
Common retry-relevant failures:
WP_ALREADY_CLAIMEDTRANSITION_REJECTEDPOLICY_VALIDATION_FAILED
Minimal Loop Skeleton
while true: ready = list-ready(feature) if no ready and all accepted-ready: break for wp in ready up to concurrency limit: start-implementation(wp) run implementation agent transition(wp, for_review) run reviewer start-review(wp, review_ref) if approved: transition(wp, done, review_result, done_evidence) else: transition(wp, in_progress, review_result)accept-mission(mission)merge-mission(mission)Reference Implementation
Use spec-kitty-orchestrator as a concrete provider example.