priivacy-ai/spec-kitty-orchestrator-api-operator

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

| Command | Purpose | Mutates State | |---|---|:---:| | contract-version | Verify API compatibility | No | | mission-state | Query full mission state | No | | list-ready | List WPs ready to start | No | | start-implementation | Claim + begin WP (atomic) | Yes | | start-review | Reviewer rollback (for_review → in_progress) | Yes | | transition | Explicit single lane change | Yes | | append-history | Add note to WP activity log | Yes | | accept-mission | Mark mission as accepted without closing approved WPs | Yes | | merge-mission | Merge lane branches into the mission branch, then land the mission branch | Yes |

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": []
}

| Field | Purpose | |---|---| | orchestrator_id | Who is driving the workflow | | orchestrator_version | Version of the orchestrator | | agent_family | Agent type (claude, codex, gemini, cursor, etc.) | | approval_mode | manual, auto, or supervised | | sandbox_mode | container, none, vm, etc. | | network_mode | restricted, full, none | | dangerous_flags | Array of dangerous flags enabled (can be []) |

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

| Code | Cause | |---|---| | CONTRACT_VERSION_MISMATCH | Provider version below minimum | | MISSION_NOT_FOUND | Mission slug doesn't resolve | | WP_NOT_FOUND | WP ID doesn't exist in mission | | TRANSITION_REJECTED | Invalid transition or guard failure | | WP_ALREADY_CLAIMED | Another actor owns the WP | | POLICY_METADATA_REQUIRED | Policy missing on run-affecting lane | | POLICY_VALIDATION_FAILED | Policy JSON invalid or contains secrets | | MISSION_NOT_READY | Not all WPs approved or done | | PREFLIGHT_FAILED | Worktree dirty, target diverged, or missing WPs | | UNSUPPORTED_STRATEGY | Merge strategy not in {merge, squash, rebase} |

---

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:

| Current state | Same actor | Different actor | |---|---|---| | planned | Transitions to in_progress | Transitions to in_progress | | claimed by this actor | Transitions to in_progress | WP_ALREADY_CLAIMED error | | in_progress by this actor | no_op=true, success | WP_ALREADY_CLAIMED error | | Other lane | TRANSITION_REJECTED | TRANSITION_REJECTED |

---

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 are approved or done 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 approved or done.

accept-mission reports accepted_wps, approved_wps, done_wps, and merge_pending_wps. It does not move WPs from approved to done; merge owns that transition.

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