spec-kitty-orchestrator-api-operator

Teach agents and external systems how to use spec-kitty orchestrator-api to drive workflows from outside the host CLI. The orchestrator-api is the only supported entry point for external automation -- direct frontmatter mutation, git worktree manipulation, or internal CLI internals are not part of the contract.

When to Use This Skill

• Build an external orchestrator that drives spec-kitty workflows
• Integrate CI/CD pipelines with spec-kitty state transitions
• Query mission and work package state from an external tool
• Understand the boundary between host CLI and external API

Do NOT use when the caller is an agent inside the host CLI (use spec-kitty next), wants setup/repair (use setup-doctor), or wants mission sequencing (the state machine owns that).

How the Orchestrator API Works

The orchestrator-api is a stable JSON contract — every command returns a canonical JSON envelope. External systems parse success first, then error_code for programmatic handling, then data for command-specific results. No command returns prose or mixed text/JSON.

JSON Envelope (All Commands)

{
  "contract_version": "1.0.0",
  "command": "orchestrator-api.<subcommand>",
  "timestamp": "2026-03-22T10:00:00+00:00",
  "correlation_id": "corr-<uuid>",
  "success": true,
  "error_code": null,
  "data": { ... }
}

• success=true → error_code is always null
• success=false → error_code is a machine-readable string, exit code is 1
• correlation_id is unique per invocation — use for audit trails and log correlation

The 9 Commands

Policy Metadata (Required for Run-Affecting Lanes)

Transitions to claimed, in_progress, or for_review require --policy with a JSON object containing 7 required fields:

{
  "orchestrator_id": "my-ci-bot",
  "orchestrator_version": "1.0.0",
  "agent_family": "claude",
  "approval_mode": "manual",
  "sandbox_mode": "container",
  "network_mode": "restricted",
  "dangerous_flags": []
}

Optional: tool_restrictions (string or null).

Policy is recorded in the append-only event log for every run-affecting transition, enabling post-incident review of exactly what orchestrator drove each state change.

Validation: Fields cannot contain secret-like values (pattern: token|secret|key|password|credential). Invalid JSON or missing fields returns POLICY_VALIDATION_FAILED.

Error Codes

Step 1: Verify the API Contract

spec-kitty orchestrator-api contract-version --provider-version "1.0.0"

Check that api_version matches your orchestrator's expected version and min_supported_provider_version is at or below your version. A CONTRACT_VERSION_MISMATCH error means the orchestrator must be updated.

Rule: Always call contract-version at orchestrator startup.

Step 2: Query Mission State

spec-kitty orchestrator-api mission-state --mission <slug>

Returns summary counts and per-WP details:

{
  "mission_slug": "042-test-mission",
  "summary": {
    "planned": 2, "claimed": 0, "in_progress": 1,
    "for_review": 1, "approved": 0, "done": 3,
    "blocked": 0, "canceled": 0
  },
  "work_packages": [
    {"wp_id": "WP01", "lane": "done", "dependencies": [], "last_actor": "claude"},
    {"wp_id": "WP02", "lane": "in_progress", "dependencies": ["WP01"], "last_actor": "codex"}
  ]
}

spec-kitty orchestrator-api list-ready --mission <slug>

Returns only WPs whose dependencies are satisfied (in planned lane with all deps in done). The host runtime computes the lane workspace; orchestrators do not choose a base branch manually.

{
  "mission_slug": "042-test-mission",
  "ready_work_packages": [
    {"wp_id": "WP03", "lane": "planned", "dependencies_satisfied": true}
  ]
}

Both commands are query-only and safe to poll.

Step 3: Respect the Host Boundary

The orchestrator-api is the ONLY supported interface for external systems.

Anti-patterns (do NOT do):

• Edit frontmatter directly (lane: in_progress in WP files)
• Call internal CLI commands (spec-kitty agent tasks move-task)
• Create worktrees manually (git worktree add)
• Poll by reading files (grep "lane:" kitty-specs/...)
• Skip contract-version check
• Skip --policy on run-affecting transitions

See references/host-boundary-rules.md for the full boundary specification.

Step 4: Start Implementation with Policy

spec-kitty orchestrator-api start-implementation \
  --mission <slug> --wp WP01 --actor "ci-bot" \
  --policy '{"orchestrator_id":"my-orch","orchestrator_version":"1.0.0","agent_family":"claude","approval_mode":"auto","sandbox_mode":"container","network_mode":"restricted","dangerous_flags":[]}'

This transitions planned → claimed → in_progress atomically (two events in one call). The response includes:

• workspace_path — The computed worktree path. The caller must create the worktree — start-implementation does not create it.
• prompt_path — Path to the WP task file to present to the agent.
• no_op — true if the WP is already in_progress by the same actor (idempotent, no new events emitted).

Idempotency behavior:

Step 5: Transition Work Packages

spec-kitty orchestrator-api transition \
  --mission <slug> --wp WP01 --to for_review --actor "ci-bot" \
  --policy '{"orchestrator_id":"my-orch",...}'

Valid target lanes: planned, claimed, in_progress, for_review, approved, done, blocked, canceled.

Rules:

• Run-affecting lanes (claimed, in_progress, for_review) require --policy
• Use --force only when recovering from a known-bad state
• Use --note to record transition reasoning in the audit trail
• Use --review-ref when transitioning from for_review or approved back to in_progress or planned (required guard for these rollback transitions)

Step 6: Start Review

For reviewer rollback (not the same as transition --to in_progress):

spec-kitty orchestrator-api start-review \
  --mission <slug> --wp WP01 --actor "reviewer-bot" \
  --review-ref "PR#42" \
  --policy '{"orchestrator_id":"my-orch",...}'

--review-ref is required — it records the review feedback reference. This is the guard condition for the for_review → in_progress transition.

Step 7: Record History and Complete

# Append a history note
spec-kitty orchestrator-api append-history \
  --mission <slug> --wp WP01 --actor "ci-bot" --note "Tests passed"

# Accept mission (validates all WPs in done lane via dependency graph)
spec-kitty orchestrator-api accept-mission --mission <slug> --actor "ci-bot"

# Merge mission
spec-kitty orchestrator-api merge-mission \
  --mission <slug> --target main --strategy squash --push

accept-mission returns MISSION_NOT_READY if any WP from the dependency graph is not in done.

merge-mission runs 4 preflight checks before merging:

1. All expected WPs have worktrees
2. All worktrees are clean (no uncommitted changes)
3. Target branch is not behind origin
4. Missing WPs in done lane are handled (skipped with warnings)

On preflight failure, returns PREFLIGHT_FAILED with detailed error list.

Supports 3 merge strategies: merge (--no-ff, default), squash, rebase. Use --push to push the target branch after merge.

What This Skill Does NOT Cover

• Mission sequencing -- use spec-kitty next (the state machine owns that)
• Host-internal mutations -- agents inside the host CLI use spec-kitty agent tasks move-task, not orchestrator-api
• Setup and repair -- use the setup-doctor skill

References

• references/orchestrator-api-contract.md -- Full command reference with all 9 commands, flags, output fields, and error codes
• references/host-boundary-rules.md -- When to use orchestrator-api vs host CLI, anti-patterns, boundary rules