spec-kitty

name

spec-kitty

description

Standalone Spec Kitty governance invocation: run Spec Kitty when the user indicates they want Spec Kitty involved, load governance context, open an Op, do the work under that context, and close the Op with the real outcome. Documents dispatch, profiles list, invocations list, and profile-invocation complete. Triggers: "use spec kitty to", "hey spec kitty", "spec kitty <anything>", ad-hoc requests that are not part of a running full mission workflow.

spec-kitty

Use this skill when the user seems to want Spec Kitty involved and the request is not clearly a full mission workflow.

Spec Kitty does not spawn another LLM. You are the host. Spec Kitty routes the request, assembles governance context, opens an Op record, and returns. You then do the work under that governance context and close the Op with the real outcome.

Default Mental Model

If the user says anything like "use spec kitty to ...", "hey spec kitty ...", "spec kitty fix ...", or "spec kitty ", treat it as a standalone governed invocation unless they clearly ask for a full mission.

Run:

spec-kitty dispatch "<request verbatim>" --json

If the user names a specific profile, or you have a strong reason to bypass routing, pass it explicitly:

spec-kitty dispatch "<request verbatim>" --profile <profile-id> --json

Do not answer directly before dispatching. The point is to load governance and record the Op before doing the work.

The open->work->close contract

Every standalone invocation follows the same three-step lifecycle:

1. Open — spec-kitty dispatch opens the Op and loads governance context. It does not do the work and it does not close the Op.

2. Work — read governance_context_text and do the work under that binding context.

3. Close — close the Op with the real outcome:

   spec-kitty profile-invocation complete \
     --invocation-id <id> \
     --outcome <done|failed|abandoned> [--evidence <path>]
   

Failed work closes as failed; dropped work closes as abandoned. Never leave an Op open deliberately. spec-kitty doctor ops reports orphaned open Ops, and spec-kitty doctor ops --close-stale sweeps stale ones closed as abandoned with closed_by: doctor_sweep.

Usage

Discover profiles

spec-kitty profiles list --json

Profiles are an optional routing escape hatch, not the primary UX.

Open a governed invocation

spec-kitty dispatch "implement WP03" --json
spec-kitty dispatch "review this migration" --profile reviewer --json

Response fields:

Field	Type	Description
invocation_id	string (ULID)	Unique ID for this Op
profile_id	string	Resolved profile identifier
action	string	Normalised action string
governance_context_text	string	Full governance context assembled from the project DRG
governance_context_hash	string	SHA-256 hash of governance_context_text
governance_context_available	boolean	false when charter has not been synthesised
router_confidence	string or null	Routing confidence score
status	"open"	The Op is open until you close it
close_contract	object	Exact close command, accepted outcomes, and flags

Governance context injection

After calling dispatch, the response includes governance_context_text.

You must inject this text into your working context before executing the task.

Steps:

1. Read governance_context_text from the JSON response.
2. Add the text to the beginning of your task execution context. Treat it as binding governance: follow any directives, constraints, and guidelines it contains when generating code, plans, or analyses.
3. If governance_context_available is false, note it to the user ("governance context unavailable — run spec-kitty charter synthesize to build the DRG") but proceed with the task. The Op trail is still recorded.
4. After completing the work, close the Op.

Close the Op

spec-kitty profile-invocation complete \
  --invocation-id <id> \
  --outcome <done|failed|abandoned>

--outcome is required and must reflect what actually happened: done for completed work, failed for work that did not succeed, abandoned for work that was dropped. Optional flags: --evidence <path>, --artifact <ref>, --commit <sha>.

Review recent invocations

spec-kitty invocations list --json
spec-kitty invocations list --profile <profile-id> --json
spec-kitty invocations list --limit 10 --json

What Gets Recorded

Every dispatch call writes one JSONL file to kitty-ops/<invocation_id>.jsonl with a started event. Closing the Op appends a completed event carrying the real outcome and closed_by.

An Op without a completed event is an orphan: visible in spec-kitty invocations list as open, reported by spec-kitty doctor ops, and surfaced at session boundaries.

Invariants

• dispatch never spawns a separate LLM call.
• dispatch opens the Op and returns. The working agent closes it with the real outcome.
• governance_context_text is assembled from the project DRG; no network calls are made if the charter has already been synthesised.
• If governance_context_available is false, run spec-kitty charter synthesize to build the DRG before the next invocation.