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)

```json
{
  "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**:

```json
{
  "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

```bash
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

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

Returns summary counts and per-WP details:

```json
{
  "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"}
  ]
}
```

```bash
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.

```json
{
  "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-sp