/spec-kitty-orchestrator-api-operator

name: spec-kitty-orchestrator-api-operator
description: >-
  Teach agents and external systems how to use spec-kitty orchestrator-api to
  drive workflows from outside the host CLI.
  Triggers: "use orchestrator-api", "build a custom orchestrator",
  "automate externally", "integrate CI with spec-kitty",
  "call spec-kitty from another tool", "orchestrator contract",
  "external automation".
  Does NOT handle: host-internal lane mutation (use the host CLI directly),
  runtime loop advancement (use spec-kitty next), mission sequencing logic
  (the mission state machine owns that), or setup/repair diagnostics.

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` | Claim a WP for review (for_review -> in_review) | 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`, `for_review`, or `in_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 | | `USAGE_ERROR` | CLI usage or missing required arguments | | `DEPENDENCIES_NOT_SATISFIED` | WP dependencies do not permit the requested transition | | `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 --missio