crucible-energy/spec-kitty/spec-kitty

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 <anything>", 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.

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

context.

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

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

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.

1. 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.

1. 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.