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 ... --json for workflow state.
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 review/complete loops.
Accept and optionally merge when all WPs are done.

1. Check compatibility

spec-kitty orchestrator-api contract-version --json

2. Discover work

spec-kitty orchestrator-api feature-state --feature <slug> --json
spec-kitty orchestrator-api list-ready --feature <slug> --json

3. Start implementation

spec-kitty orchestrator-api start-implementation \
  --feature <slug> \
  --wp WP01 \
  --actor my-orchestrator \
  --policy '<json>' \
  --json

Use returned workspace_path and prompt_path to run your agent process.

4. Drive transitions

# implementation complete
spec-kitty orchestrator-api transition \
  --feature <slug> --wp WP01 --to for_review \
  --actor my-orchestrator --policy '<json>' --json

# review approved
spec-kitty orchestrator-api transition \
  --feature <slug> --wp WP01 --to done \
  --actor reviewer-bot --json

# review rejected -> rework
spec-kitty orchestrator-api start-review \
  --feature <slug> --wp WP01 --actor my-orchestrator \
  --policy '<json>' --review-ref review/WP01/attempt-2 --json

5. Finalize

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

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 terminal: break
  for wp in ready up to concurrency limit:
    start-implementation(wp)
    run implementation agent
    transition(wp, for_review)
    run reviewer
    if approved: transition(wp, done)
    else: start-review(wp, review_ref)
accept-feature(feature)
merge-feature(feature)

Reference Implementation

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

Table of Contents