Build a Custom Orchestrator

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-kitty as source of truth for lane state and dependencies.
Never write kitty-specs/<feature>/tasks/*.md lanes 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-version

2. 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 complete
spec-kitty orchestrator-api transition \
  --mission <slug> --wp WP01 --to for_review \
  --actor my-orchestrator --policy '<json>' \
  --subtasks-complete --implementation-evidence-present
# reviewer claims active review
spec-kitty orchestrator-api start-review \
  --mission <slug> --wp WP01 --actor my-orchestrator \
  --policy '<json>' --review-ref review/WP01/attempt-1

# review approved
spec-kitty orchestrator-api transition \
  --mission <slug> --wp WP01 --to done \
  --actor my-orchestrator \
  --policy '<json>' \
  --review-ref review/WP01/attempt-1 \
  --force \
  --note "Approved by reviewer-bot"

# review rejected -> rework
spec-kitty orchestrator-api transition \
  --mission <slug> --wp WP01 --to in_progress \
  --actor my-orchestrator \
  --policy '<json>' \
  --review-ref review/WP01/attempt-1 \
  --force \
  --note "Rejected by reviewer-bot; rework required"

5. Finalize

spec-kitty orchestrator-api accept-mission --mission <slug> --actor my-orchestrator
spec-kitty orchestrator-api merge-mission --mission <slug> --target main --strategy merge

Policy 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 internal doing.
Expect deterministic error_code on failures.
Build retry/backoff logic based on error_code, not message text.

Common retry-relevant failures:

WP_ALREADY_CLAIMED
TRANSITION_REJECTED
POLICY_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, force=True)
    else: transition(wp, in_progress, force=True)
accept-mission(mission)
merge-mission(mission)

Reference Implementation

Use spec-kitty-orchestrator as a concrete provider example.

Table of Contents