Skip to content

Orchestrator Quickstart

Who is this for (1)

This tutorial shows the external orchestration model end to end:

  • spec-kitty owns mission state and lane transitions.
  • spec-kitty-orchestrator runs agents and calls spec-kitty orchestrator-api.
  • Implementation and review happen in git worktrees, not on protected main.

By the end, you will know how to check the host contract, run the reference orchestrator, watch mission state, and recover from a stopped run.

Prerequisites

You need:

  • a git repository initialized with Spec Kitty
  • spec-kitty on PATH
  • a host-compatible spec-kitty-orchestrator build on PATH
  • at least one agent CLI supported by the orchestrator, such as Claude Code, Codex, or OpenCode
  • a mission with at least one tasks/WP*.md file

If you do not have a mission yet, finish Your First Mission first.

Orchestrator quickstart - Mission Kitty splash

Stylized splash — the conductor’s podium is decorative. Host contract, orchestrator run, and recovery steps are in the sections below.

Version compatibility

The orchestrator is published on PyPI as spec-kitty-orchestrator. Install the latest compatible package from PyPI, then verify the host contract before running a mission.

1. Install the orchestrator

Use pipx for an isolated command-line install:

Terminal window
pipx install spec-kitty-orchestrator

If you already have it installed:

Terminal window
pipx upgrade spec-kitty-orchestrator

If you prefer uv tool management:

Terminal window
uv tool install spec-kitty-orchestrator

Or upgrade an existing uv-managed install:

Terminal window
uv tool upgrade spec-kitty-orchestrator

Confirm the CLI is now available:

Terminal window
spec-kitty-orchestrator --help
spec-kitty-orchestrator orchestrate --help

If either command is missing, check that the Python environment where you installed the package is on PATH.

The source repository is spec-kitty/spec-kitty-orchestrator if you want to inspect code, issues, or release history. Do not install from GitHub unless you are intentionally testing unreleased provider changes.

Return to your Spec Kitty project root before continuing.

2. Confirm the host API works

Run this from the project root:

Terminal window
spec-kitty orchestrator-api contract-version

The output is a JSON envelope. For a compatible host it includes:

{
"success": true,
"data": {
"api_version": "1.0.0"
}
}

The orchestrator performs this check at startup too, but running it yourself confirms that the host CLI is installed and that JSON output is available.

3. Find your mission slug

Use kitty-specs/ or the mission commands to identify the mission slug:

Terminal window
ls kitty-specs

Examples look like:

034-payment-retry-flow
099-orchestrator-e2e

The orchestrator API selector is always --mission, even when the selector is a slug, mission id, or short mission id.

4. Inspect ready work

Terminal window
spec-kitty orchestrator-api list-ready --mission 034-payment-retry-flow

Ready work packages are WPs in planned whose dependencies are already done. If no WPs are ready, inspect the whole mission:

Terminal window
spec-kitty orchestrator-api mission-state --mission 034-payment-retry-flow

5. Dry-run the orchestrator

Terminal window
spec-kitty-orchestrator orchestrate \
--mission 034-payment-retry-flow \
--impl-agent claude-code \
--review-agent codex \
--max-concurrent 1 \
--dry-run

Use --dry-run before the first real run. It validates configuration without moving WP lanes.

6. Run implementation and review

Terminal window
spec-kitty-orchestrator orchestrate \
--mission 034-payment-retry-flow \
--impl-agent claude-code \
--review-agent codex \
--max-concurrent 1

With a host-compatible provider build, the orchestrator loop will:

  1. call list-ready
  2. call start-implementation for a ready WP
  3. prepare a usable WP worktree and run the implementation agent there
  4. transition the WP to for_review
  5. run the review agent
  6. claim in_review before completing approved review
  7. transition to done with the required review evidence when the review passes
  8. move rejected work back to in_progress for rework

The orchestrator writes its local run state under .kittify/ and agent logs under .kittify/logs/.

7. Check progress

In another terminal:

Terminal window
spec-kitty-orchestrator status
spec-kitty orchestrator-api mission-state --mission 034-payment-retry-flow

Use mission-state as the source of truth for WP lanes. Use spec-kitty-orchestrator status for provider-local details such as retry counts and the last agent log path.

8. Resume or abort

If the process is interrupted:

Terminal window
spec-kitty-orchestrator resume

If you need to stop tracking the run state:

Terminal window
spec-kitty-orchestrator abort --cleanup-worktrees

abort --cleanup-worktrees removes provider-local state. It does not rewrite authoritative mission lane history.