Agent skill

Spec Kitty Orchestrator API Operator

by spec-kitty in spec-kitty/spec-kitty

Teach agents and external systems how to use spec-kitty orchestrator-api to drive workflows from outside the host CLI.

MITAuto-check passedAgent Workflows

Install Spec Kitty Orchestrator API Operator

skills CLI
$ npx skills add spec-kitty/spec-kitty --skill spec-kitty-orchestrator-api-operator -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install spec-kitty/spec-kitty spec-kitty-orchestrator-api-operator --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/spec-kitty/spec-kitty.git skills-src && mkdir -p .claude/skills && cp -r skills-src/src/charter/offering/skills/spec-kitty-orchestrator-api-operator .claude/skills/spec-kitty-orchestrator-api-operator && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
spec-kitty-orchestrator-api-operator
GitHub stars
1.7k
Token cost
~3k tokens
SKILL.md length
1,076 words
Files
3 (incl. references)
Skills in repo
50
Repo updated
First seen
Licence
MIT

At a glance

Teach agents and external systems how to use spec-kitty orchestrator-api to drive workflows from outside the host CLI.

  • Works in 7 steps: Verify the API Contract → Query Mission State → Respect the Host Boundary → …
  • Tasks that involve Multi-agent orchestration
  • SKILL.md covers When to Use This Skill, How the Orchestrator API Works, Step 1: Verify the API Contract and Step 2: Query Mission State, plus 7 more sections
  • Calls git

What it does

Spec Kitty Orchestrator API Operator is an agent skill from spec-kitty/spec-kitty. 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…

Its SKILL.md is about 3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/host-boundary-rules.md` and `references/orchestrator-api-contract.md`).

It sits in Agent Workflows, covering Multi-agent orchestration. The repository describes itself as: Spec-Driven Development with organizational governance. Specs tell AI agents what to build; Charter governs how they build it. Git-native missions, enforceable workflows, and… The licence is MIT.

When your agent uses it

  • Tasks that involve Multi-agent orchestration

Example prompts

  • “use orchestrator-api”
  • “build a custom orchestrator”
  • “automate externally”
  • “/spec-kitty-orchestrator-api-operator”

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Verify the API Contract
  2. Query Mission State
  3. Respect the Host Boundary
  4. Start Implementation with Policy
  5. Transition Work Packages
  6. Start Review
  7. Record History and Complete

What it can do on your machine

Read from SKILL.md and the folder at commit 4cabb90. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Spec Kitty Orchestrator API Operator loads about 3k tokens when it runs, and up to ~16k if it reads all its reference files. Until then it costs about 144 tokens; SKILL.md has 1,076 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~144
When it runs · the whole SKILL.md, loaded when a task matches
~3k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~16k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from spec-kitty/spec-kitty at commit 4cabb90, republished under its MIT licence (© spec-kitty). 1,076 words, ~2,956 tokens.

Download SKILL.mdSave it as .claude/skills/spec-kitty-orchestrator-api-operator/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
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)
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
CommandPurposeMutates State
contract-versionVerify API compatibilityNo
mission-stateQuery full mission stateNo
list-readyList WPs ready to startNo
start-implementationClaim + begin WP (atomic)Yes
start-reviewClaim a WP for review (for_review -> in_review)Yes
transitionExplicit single lane changeYes
append-historyAdd note to WP activity logYes
accept-missionMark mission as accepted without closing approved WPsYes
consolidate-missionMerge lane branches into the mission branch, then land the mission branchYes
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:

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": []
}
FieldPurpose
orchestrator_idWho is driving the workflow
orchestrator_versionVersion of the orchestrator
agent_familyAgent type (claude, codex, gemini, cursor, etc.)
approval_modemanual, auto, or supervised
sandbox_modecontainer, none, vm, etc.
network_moderestricted, full, none
dangerous_flagsArray 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
CodeCause
CONTRACT_VERSION_MISMATCHProvider version below minimum
MISSION_NOT_FOUNDMission slug doesn't resolve
WP_NOT_FOUNDWP ID doesn't exist in mission
TRANSITION_REJECTEDInvalid transition or guard failure
WP_ALREADY_CLAIMEDAnother actor owns the WP
POLICY_METADATA_REQUIREDPolicy missing on run-affecting lane
POLICY_VALIDATION_FAILEDPolicy JSON invalid or contains secrets
USAGE_ERRORCLI usage or missing required arguments
DEPENDENCIES_NOT_SATISFIEDWP dependencies do not permit the requested transition
MISSION_NOT_READYNot all WPs approved or done
PREFLIGHT_FAILEDWorktree dirty, target diverged, or missing WPs
UNSUPPORTED_STRATEGYMerge 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-specs/...)
  • Skip contract-version check
  • Skip --policy on run-affecting transitions

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


Show full SKILL.md (467 more words)Show less

Step 4: Start Implementation with Policy

bash
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 stateSame actorDifferent actor
plannedTransitions to in_progressTransitions to in_progress
claimed by this actorTransitions to in_progressWP_ALREADY_CLAIMED error
in_progress by this actorno_op=true, successWP_ALREADY_CLAIMED error
Other laneTRANSITION_REJECTEDTRANSITION_REJECTED

Step 5: Transition Work Packages

bash
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, in_review, approved, done, blocked, canceled.

Rules:

  • Run-affecting lanes (claimed, in_progress, for_review, in_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 claim/start (not an implementation rollback):

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

This moves the WP from for_review to in_review. --review-ref is optional; use it when there is an external review artifact to record.


Step 7: Record History and Complete

bash
# 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 consolidate-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.

Once every WP is approved/done, accept-mission (contract >= 1.7.0) ALSO applies the host readiness verdict — the same collect_feature_summary(..., strict_metadata=True) check the accept CLI runs (a pending/failing acceptance matrix, a missing/corrupt lanes.json, a dirty working tree, etc.). A failing verdict refuses with MISSION_NOT_READY again, this time carrying outstanding / activity_issues / skipped_checks / blocked_checks, and records no acceptance (meta.json gains no accepted_at, HEAD unchanged; the gate may still update judged matrix rows in the working tree). Acceptance is only ever recorded inside the same locked pre-stamp re-check the host CLI uses, so a verdict committed between the check and the write is still refused.

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.

consolidate-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), squash (default), 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

© spec-kitty, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in src/charter/offering/skills/spec-kitty-orchestrator-api-operator of spec-kitty/spec-kitty.

  • SKILL.md
  • references/host-boundary-rules.md
  • references/orchestrator-api-contract.md

Open the folder on GitHubat commit 4cabb90

Compare with similar skills

Spec Kitty Orchestrator API Operator next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Spec Kitty Orchestrator API Operator compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Spec Kitty Orchestrator API Operator this skillspec-kitty/spec-kitty1.7k—~3kAutomated safety check: PassMIT
Orca CLIstablyai/orca87k2 repos~593Automated safety check: PassMIT
Paseo Advisor Second Opiniongetpaseo/paseo20k1 repos~756Automated safety check: PassCustom licence
O2 Review Loopopenobserve/openobserve22k—~3.7kAutomated safety check: PassAGPL-3.0
Paseo Committeegetpaseo/paseo20k1 repos~496Automated safety check: PassCustom licence
Mission Control Agent APIbuilderz-labs/mission-control6.3k—~2.1kAutomated safety check: PassMIT

Similar skills

  • Orca CLI

    stablyai/orca

    Operate Orca-managed worktrees, folder contexts, terminals, repos, automations, artifacts, skill sharing, worktree comments, and Orca's embedded browser…

    87k GitHub starsUsed in 2 repos~593 tokens
    Agent WorkflowsAuto-check passed
  • Launches one separate agent through Paseo to give a second opinion on the current task, with a self-contained briefing and no permission to edit files.

    20k GitHub starsUsed in 1 repo~756 tokens
    Agent WorkflowsAuto-check passed
  • O2 Review Loop

    openobserve/openobserve

    Splits a change into planner, coder and independent reviewer roles: you confirm a spec, a subagent implements it, and a separate reviewer checks each round's local WIP commit.

    22k GitHub stars~3.7k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Paseo Committee

    getpaseo/paseo

    Forms a two-agent committee with contrasting profiles to analyze a stuck problem in parallel, reconcile their views and return a consensus plan without editing files.

    20k GitHub starsUsed in 1 repo~496 tokens
    Agent WorkflowsAuto-check passed
  • Mission Control Agent API

    builderz-labs/mission-control

    Teaches an agent to use the Mission Control dashboard API: register, send heartbeats, fetch assigned tasks, report progress and disconnect, with API key auth.

    6.3k GitHub stars~2.1k tokensUpdated 10 days ago
    Agent WorkflowsAuto-check passed
  • Paseo Agent Handoff

    getpaseo/paseo

    Hands off the current task, including context, decisions and failed attempts, to a fresh agent through Paseo by writing a self-contained briefing prompt and launching that agent.

    20k GitHub starsUsed in 1 repo~606 tokens
    Agent WorkflowsAuto-check passed

More from spec-kitty/spec-kitty

All 50 skills in this repo
  • Spec Kitty Setup Doctor

    spec-kitty/spec-kitty

    Install, verify, and recover the modern Spec Kitty 2.0.11+ operating surface.

    1.7k GitHub stars~1.4k tokensUpdated today
    Auto-check passed
  • Spk Doctrine Show Me

    spec-kitty/spec-kitty

    Explain Spec Kitty work with compact, checkable visuals. An agent skill from spec-kitty/spec-kitty.

    1.7k GitHub stars~944 tokensUpdated today
    Auto-check passed
  • Spec Kitty Git Workflow

    spec-kitty/spec-kitty

    Understand how Spec Kitty manages git: what git operations Python handles automatically, what agents must do manually, worktree lifecycle, auto-commit behavior, merge execution, and the safe-commit…

    1.7k GitHub stars~2.3k tokensUpdated today
    Auto-check passed
  • Spec Kitty Glossary Context

    spec-kitty/spec-kitty

    Curate and apply canonical terminology across Spec Kitty missions.

    1.7k GitHub stars~3.1k tokensUpdated today
    Auto-check passed
  • Spec Kitty Mission System

    spec-kitty/spec-kitty

    Understand how Spec Kitty missions work: the 4 built-in mission types, how they define workflows via step contracts and action indices, how missions and work packages relate, how templates are…

    1.7k GitHub stars~4.3k tokensUpdated today
    Auto-check passed
  • Spec Kitty Runtime Review

    spec-kitty/spec-kitty

    Review runtime-owned outputs using the Spec Kitty review workflow surface, then direct approval or rejection with structured feedback.

    1.7k GitHub stars~1.5k tokensUpdated today
    Auto-check passed

Categories

Questions about Spec Kitty Orchestrator API Operator

What does Spec Kitty Orchestrator API Operator do?

Teach agents and external systems how to use spec-kitty orchestrator-api to drive workflows from outside the host CLI. Spec Kitty Orchestrator API Operator is an agent skill from spec-kitty/spec-kitty. Teach agents and external systems how to use spec-kitty orchestrator-api to drive workflows from outside the host CLI.

When should I use Spec Kitty Orchestrator API Operator?

Spec Kitty Orchestrator API Operator fits situations like: tasks that involve Multi-agent orchestration.

How do I install Spec Kitty Orchestrator API Operator in Claude Code?

Run `npx skills add spec-kitty/spec-kitty --skill spec-kitty-orchestrator-api-operator -a claude-code`. Or copy the skill folder (src/charter/offering/skills/spec-kitty-orchestrator-api-operator in spec-kitty/spec-kitty) into .claude/skills/spec-kitty-orchestrator-api-operator in your project. Claude Code loads it when a task matches its description.

How do I install Spec Kitty Orchestrator API Operator in Codex?

Run `npx skills add spec-kitty/spec-kitty --skill spec-kitty-orchestrator-api-operator -a codex`. Or copy the skill folder (src/charter/offering/skills/spec-kitty-orchestrator-api-operator in spec-kitty/spec-kitty) into .agents/skills/spec-kitty-orchestrator-api-operator in your project. Codex loads it when a task matches its description.

Can I use Spec Kitty Orchestrator API Operator in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add spec-kitty/spec-kitty --skill spec-kitty-orchestrator-api-operator -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/spec-kitty-orchestrator-api-operator, .gemini/skills/spec-kitty-orchestrator-api-operator, .github/skills/spec-kitty-orchestrator-api-operator and .opencode/skills/spec-kitty-orchestrator-api-operator in your project.

What does Spec Kitty Orchestrator API Operator need to run?

Going by SKILL.md and its folder, Spec Kitty Orchestrator API Operator needs the command-line tools its instructions call (git).

Does Spec Kitty Orchestrator API Operator access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Spec Kitty Orchestrator API Operator safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Spec Kitty Orchestrator API Operator use?

Spec Kitty Orchestrator API Operator is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Spec Kitty Orchestrator API Operator use?

About 3k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 13k tokens, read only when the agent opens those files.

What are the alternatives to Spec Kitty Orchestrator API Operator?

Skills that share tags, products or a category with Spec Kitty Orchestrator API Operator: Orca CLI (stablyai/orca, 87k stars), Paseo Advisor Second Opinion (getpaseo/paseo, 20k stars), O2 Review Loop (openobserve/openobserve, 22k stars) and Paseo Committee (getpaseo/paseo, 20k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Spec Kitty Orchestrator API Operator?

spec-kitty (a GitHub organization) maintains it in spec-kitty/spec-kitty, which has 1,677 GitHub stars. The repository holds 50 skills in this directory. The repository was last updated on October 8, 2026.

Source: spec-kitty/spec-kitty on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.