CLI Command Reference
This reference lists the user-facing spec-kitty CLI commands and their flags exactly as surfaced by --help. For agent-only commands, see docs/api/agent-subcommands.md.
Terminology note:
Mission Type= reusable workflow blueprintMission= tracked item underkitty-specs/<mission-slug>/Mission Run= runtime/session instance- As of 3.1.0,
--missionis the canonical flag name for specifying the mission slug.--featurewas a hidden deprecated alias; as of 3.2.x it has been removed everywhere — from the internal/agent command cluster (#1060-A) and from the user-facing top-level commands (#1060).--missionis now the sole selector; passing--featureexits withNo such option. mission-state/accept-mission/consolidate-missionare the canonical orchestrator-api command names
Getting Started
Practical Usage
Command Internals
For non-obvious runtime behaviour an operator may encounter:
finalize-tasksinternals — explicit emptyowned_filessemantics, lane-depth cycle safety, and the planning-commit pin refresh.- Issue-matrix verdict reference — the five
issue-verdictverdict values, which gate atapprovedvsdone, and the reference-classification model behindmove-task's approval gate.move-task's--actor/--reasonaliases andissue-verdict'snot-applicableverdict are agent-only commands documented in full indocs/api/agent-subcommands.md(regenerated from the live Typer surface); this reference page is the durable, hand-authored explanation of the vocabulary and gating rules those generated sections don't narrate (#3469).
Coordination-routed Missions: where writes land
These notes are the hand-authored companion to the generated sections below (which are
regenerated from live --help and cannot carry them). They apply to a Mission whose topology is
coord or lanes_with_coord; lanes and single_branch Missions are unchanged. The design
record is the 2026-10-01 amendment of
ADR 2026-06-19-1 and the
architecture page.
- One home for coordination records. A coordination record (status log, decision events,
issue matrix, and so on) is written only to the coordination worktree, never to the
repository root checkout. If the worktree is not there yet, the command creates it (when the
coordination branch exists locally) or refuses with
COORDINATION_WORKTREE_UNMATERIALIZEDand a recovery hint (when the branch exists only on a remote). spec-kitty spec-commitreports one outcome per surface it touched.successisfalseand the exit code is non-zero when any surface is refused or errored. The--jsonpayload gains two additive keys,surfaces(one entry per surface with its outcome) andarguments; existing keys are unchanged.spec-kitty acceptcommits the current Mission's uncommitted PRIMARY-partition decision ledger (decisions/index.jsonandDM-*.md) before its cleanliness check, instead of refusing on it. Which files count is decided by the artifact taxonomy, not by a filename allowlist, and only for the Mission being accepted. Another Mission's ledger and any other uncommitted change still fail closed. With--jsonthe payload addsresidual_commit.surfaces.spec-kitty consolidatematerializes anUNMATERIALIZEDcoordination surface whose branch is present locally, and proceeds. A remote-only branch, a deleted branch, a forked coordination log or a held status lock abort the run before any state change.consolidate --dry-rundoes not materialize and stays fail-closed: on an unmaterialized or deleted coordination surface the forecast stops with the same error rather than creating a worktree. The asymmetry is deliberate: a preview must not change the repository. Consolidation and coordination teardown also refuse withCOORDINATION_LEDGER_UNREPAIREDwhile a Mission's decision ledger exists only on the coordination branch (seedoctor decisionsbelow).spec-kitty materializecreates the coordination worktree (once per coordination-routed Mission) and seeds a Mission created before the fix; see its generated help below. A remote-only branch or a forked log is listed in the error summary and the remaining Missions are still processed.spec-kitty agent mission create(agent-only; seeagent-subcommands.md) materializes and seeds the coordination worktree for a coordination-routed Mission and commits the creation records there; the target branch receives no coordination record.spec-kitty doctor decisionsalso reports forks. The decision ledger is a PRIMARY partition kind, while its events live on the coordination surface. A ledger that exists only on the coordination branch is reported asDECISION_LEDGER_ONLY_ON_COORDINATION, and two logs that disagree asDECISION_LOG_FORKED.--repaircopies a coordination-only ledger into the PRIMARY partition without committing (commit it withspec-commitoraccept), and exits 1 on a fork without dropping any entry.--repairkeeps an index entry whose event exists on either surface; an entry with no event on any surface is still dropped.- Fresh clone. The coordination status log is not part of a fresh clone, so on one,
doctor decisionsreportsclean: falsewithorphaned_in_indexentries: the index is there, its events are not. Restore the coordination log before using--repair, because--repairdrops a genuine orphan.agent decision verifyon the same clone is not reported as forked, finds every opened decision id, and reportsledger.state == "primary". - Decision-index merge driver.
.gitattributesregistersmerge=spec-kitty-decision-indexforkitty-specs/**/decisions/index.json, so concurrent additions on lane branches union bydecision_idinstead of conflicting. Projects initialised earlier get the driver from the upgrade migrationm_4_0_0rc5_decision_index_merge_driver; runspec-kitty upgrade. Git runs the driver itself during a merge; it is an internal command you never invoke by hand.
spec-kitty consolidate: exit codes and refusal codes
Hand-authored companion to the generated consolidate section below. consolidate lands a
Mission on its local target branch only; it never publishes to a remote unless --push
is passed.
| Exit code | Meaning |
|---|---|
0 |
The Mission landed and the cleanup finished. |
75 |
The landing stands, but the coordination branch (or the mission branch of a Mission without a coordination topology) moved after it and was kept instead of deleted. Error code COORD_MOVED_AFTER_LANDING. Nothing was lost and nothing was rolled back. |
| any other non-zero | A refusal or a failure. The message says whether anything had moved and reports, per branch, what the rollback restored. |
Stable codes that appear in the output. Match on the code, not on the surrounding prose:
| Code | When | What to do |
|---|---|---|
APPROVAL_STAMP_MISSING |
A work package in the approved claim has no recorded approval stamp (its approval has no lane_head, for example one recorded before the stamp existed, or a work package forced to done with no approved transition), so the commit review approved cannot be determined. Exit code 1, before any branch moves. |
Move the work package back for review and approve it again, or check the lane by hand and re-run with --attest-approved-reviewed <WP> --attest-reason "...". The message prints both as commands for your Mission, with one attest command that lists every unstamped work package. |
APPROVAL_STAMP_NOT_ON_LANE |
An approval stamp names a commit that is not on the lane (the lane was rewritten after review approved it). Exit code 1, before any branch moves. |
Move the work package back for review and approve it again. Not overridable. |
APPROVED_CONTENT_MISSING |
The reconciliation gate found that an approved code lane's own net change to a path is not on the target, while the target left that path alone since the lane was cut and no later approved lane superseded it. The run FAILs and rolls back. Typical cause: the staged deletions of a lagging worktree were committed before a --resume. |
Restore the change on the mission branch (for example revert the commit that recorded the deletions), then re-run. Not overridable. |
CANCELED_REACHABLE_VIA_DEPENDENCY |
Content of a fully-canceled dependency lane reached an approved lane, is still live there and is on the target. The run FAILs and rolls back. Content that every carrying lane fully superseded is not counted. | Undo the change on the carrying lane through a surviving WP's governed work, then re-run. Not overridable: --attest-canceled-superseded never lifts it. |
COORD_MOVED_AFTER_LANDING |
Exit code 75, see above. The message ends with Error code: COORD_MOVED_AFTER_LANDING. |
Coordination branch: review the late commit(s) with the git log command in the message, then run spec-kitty consolidate --resume, which lands them on the target and finishes the teardown. Mission branch without a coordination topology: land the commit(s) and delete the branch yourself. |
LANE_MOVED_AFTER_APPROVAL |
A code lane holds a content commit made after review approved it (or after an --attest-approved-reviewed attestation). Exit code 1, before any branch moves; also checked again at the reconciliation gate. |
Move the work package back for review so the new content is reviewed, approve it again, re-run. The message names the late commits and the command to move each work package of the lane back; see a commit with git show <sha>. No attestation lifts it: --attest-approved-reviewed and --attest-canceled-superseded never do. On a lane that mixes an approved and a canceled work package, --attest-canceled-superseded still exempts lane commits up to its own lane head from the closed-world refusal, but the commit still needs its work package approved again. Nothing a canceled work package does covers a commit: no commit of its own, no status move of a work package that stays canceled, no attestation. Forcing a canceled work package into approved is a forced approval, which stamps the lane at its current tip; the bound is as strong as the review model (issue #5721). If a canceled work package committed on the lane after the approval, also when that work was reverted, the approved work package needs a new approval. When both refusals apply, the first message names both under This Mission also has:. |
RELEASE_BRANCH_INVALID |
--release-branch without --abort or without --release-reason, naming a branch that is not the record's target, mission or coordination branch (a lane branch or an unknown name), or naming a branch that does not resolve to a commit. Exit code 2; nothing changed. |
Correct the flags and re-run spec-kitty consolidate --abort. |
UNEXPLAINED_BRANCH_MOVE |
A re-run or --resume found a target, mission or coordination branch of an unfinished record at a commit the record cannot explain: neither its restore target nor a commit this run recorded or saved as its next move (for example a run killed right after it moved the branch). Refused before anything moves; the record is kept. Exit code 1. Not raised while the target still sits at a verified landing. |
Inspect git log <restore-target>..<live>. If the commits should not stay, move the branch yourself. To keep them, spec-kitty consolidate --abort --release-branch <branch> --release-reason "<why>"; a release keeps every listed commit. See troubleshooting. |
PROJECTION_TEARDOWN_ABORTED |
The same race caught earlier: the coordination branch moved before anything was torn down, so the coordination worktree, branch and marker all survive. Exit code 1. |
Re-run spec-kitty consolidate --resume. |
--attest-canceled-superseded <WP>lifts a REFUSE whose attribution evidence can never appear later, for the named WP only. Since #5613 that includes a canceled WP without alane_headstamp on a fully-canceled dependency lane, which REFUSEs before any branch moves. It never lifts a FAIL, and it never approves content: a commit made after an approved work package's approval is still refused withLANE_MOVED_AFTER_APPROVAL. The verdict table and the override rules are stated once, in the status model.--attest-approved-reviewed <WP>(repeatable, shares--attest-reason) records, after you checked by hand that the lane holds only reviewed work, an operator attestation for an approved work package whose approval recorded no lane head. It liftsAPPROVAL_STAMP_MISSINGfor that work package only: the lane head at the moment of the attestation becomes its bound, so a commit made afterwards is still refused withLANE_MOVED_AFTER_APPROVAL. A work package that already has an approval stamp, or is not approved, is refused and nothing is recorded; with--dry-runnothing is recorded and a notice says so. The attestation is a forced operator transition in the Mission's status log. Attesting again after an unrelated failure is accepted while the lane holds nothing beyond the earlier attestation; once it holds a later commit the repeat is refused, nothing is recorded, and the work package must go back for review.--abort --release-branch <branch> --release-reason "<why>"(repeatable) keeps a branch that--abortreportsNOT restoredat the commit it has when you run the command, reports itkeptwith the reason and a warning that it may contain this consolidation's unverified changes, and lets the record clear once every other branch is restored. A release never keeps a branch that can be restored, and it no longer applies once the branch moves. A release saved by an--abortthat then fails on another branch stays in the record and is still honoured by a later plain--abortwhile the branch sits at that commit. See Keep a branch that cannot be restored.--resumerefreshes in place a repository root checkout, coordination worktree, mission worktree or lane worktree that only lags its own HEAD, and refuses with the exact recovery commands when such a worktree also holds an edit of your own. See Recover from an Interrupted Consolidation.spec-kitty orchestrator-api consolidate-missionreportsCOORD_MOVED_AFTER_LANDINGasdata.teardown_error_code; see the orchestrator API reference.- A status write that follows a rolled-back consolidation can be refused with
COORD_STATUS_SURFACE_DIVERGED; see the status model.
Schema references
CLI Command Reference
spec-kitty accept
Usage: spec-kitty accept [OPTIONS]
Validate mission readiness before merging to main.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug to │
│ accept │
│ --mode <str> Acceptance mode: │
│ auto, pr, local, or │
│ checklist │
│ [default: auto] │
│ --actor <str> Name to record as │
│ the acceptance │
│ actor │
│ --test <str> Validation command │
│ executed │
│ (repeatable) │
│ --json Emit JSON instead │
│ of formatted text │
│ --lenient Skip strict │
│ metadata validation │
│ and downgrade │
│ missing │
│ path-convention │
│ checks to warnings │
│ --no-commit Report acceptance │
│ readiness without │
│ writing metadata or │
│ status changes │
│ --diagnose Diagnose acceptance │
│ blockers without │
│ writing metadata or │
│ matrix artifacts │
│ --allow-fail Return checklist │
│ even when issues │
│ remain │
│ --normalize-encod… --no-normalize-e… Repair │
│ acceptance-artifact │
│ encoding │
│ (Windows-1252/Lati… │
│ -> UTF-8) before │
│ validating. │
│ [default: │
│ no-normalize-encod… │
│ --owned-checkout <path> Run against an │
│ owned checkout: a │
│ linked checkout │
│ that owns this │
│ mission. Refuses │
│ the repository root │
│ checkout, lane │
│ worktrees and │
│ coordination │
│ worktrees. │
│ --origin-check <function> Refuse (enforce, │
│ the default) or │
│ only warn (warn) │
│ when the mission's │
│ status evidence is │
│ behind or │
│ unreachable on its │
│ remote; off │
│ contacts nothing │
│ and accepts stale │
│ evidence. Overrides │
│ SPEC_KITTY_ORIGIN_… │
│ --no-commit and │
│ --diagnose always │
│ warn. │
│ --merge-commit SHA With --mode pr: │
│ record this PR │
│ merge commit as the │
│ mission's │
│ post-merge review │
│ baseline. The │
│ commit is verified │
│ against git before │
│ anything is written │
│ — it must carry │
│ kitty-specs/<slug>… │
│ its first parent │
│ must not, and it │
│ must have landed on │
│ the target branch. │
│ Every landing shape │
│ additionally needs │
│ --attest-first-lan… │
│ --target-branch <str> With │
│ --merge-commit: the │
│ branch the PR │
│ merged into (the │
│ PR's base branch). │
│ Defaults to the │
│ mission's declared │
│ target_branch, else │
│ the repository's │
│ primary branch. │
│ --attest-first-la… With │
│ --merge-commit: │
│ attest that the │
│ supplied commit's │
│ first parent is the │
│ pre-landing target │
│ tip — for a │
│ two-parent merge │
│ commit, that the │
│ merge was performed │
│ ON the target │
│ branch (an internal │
│ merge │
│ fast-forwarded onto │
│ the target is │
│ graph-identical, │
│ and its first │
│ parent is an │
│ implementation │
│ commit); for a │
│ single-parent │
│ landing (squash or │
│ corpus-first │
│ stack), that it was │
│ the first commit of │
│ the landing. │
│ Required for every │
│ landing shape: git │
│ cannot prove │
│ either, and a wrong │
│ anchor silently │
│ under-scans the │
│ dead-code gate. The │
│ attestation is │
│ recorded in │
│ pr_merge_evidence, │
│ never presented as │
│ a git proof. │
│ --help -h Show this message │
│ and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty archive
Archive a terminal mission (operator-invoked only).
Usage: spec-kitty archive [OPTIONS] COMMAND [ARGS]...
Archive a terminal mission (operator-invoked only).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ create Archive a terminal mission (AM-1..AM-5). │
│ list Enumerate archived missions (AM-3). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty archive create
Usage: spec-kitty archive create [OPTIONS] {mission}
Archive a terminal mission (AM-1..AM-5).
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission <str> Mission selector (slug or mission_id). [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --by <str> Operator identity performing the archive │
│ (required). │
│ [required] │
│ * --reason <str> Why the mission is being archived (required). │
│ [required] │
│ --json Emit the archive record as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty archive list
Usage: spec-kitty archive list [OPTIONS]
Enumerate archived missions (AM-3).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit the archive registry as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter
Charter management commands
Usage: spec-kitty charter [OPTIONS] COMMAND [ARGS]...
Charter management commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ activate Activate a doctrine artifact by kind and ID (FR-004), or │
│ apply a pack's preset. │
│ deactivate Deactivate a doctrine artifact by kind and ID (FR-005), │
│ with optional cascade. │
│ consistency-check Check the active charter for coherence against the │
│ offering (FR-011). │
│ new Scaffold a stub doctrine artifact YAML (FR-016). │
│ validate Validate project-layer doctrine artifacts against their │
│ schemas (FR-017). │
│ fetch Fetch org Charter Pack(s) from their configured remote │
│ sources. │
│ interview Capture charter interview answers for later generation. │
│ generate Generate charter bundle from interview answers + doctrine │
│ references. │
│ context Render charter context for a specific workflow action. │
│ status Display charter sync status plus synthesis/operator │
│ state. │
│ synthesize Validate and promote agent-generated project-local │
│ doctrine artifacts. │
│ resynthesize Regenerate a bounded set of project-local doctrine │
│ artifacts (partial resynthesis). │
│ lint Detect decay in charter artifacts via graph-native │
│ checks. │
│ preflight Verify charter-derived state before a governed session │
│ begins. │
│ bundle Charter bundle validation commands. │
│ mission-type Mission type commands (activated types only). │
│ list List activated charter artifacts by kind. │
│ pack Charter pack management commands. │
│ org Manage org Charter Pack authoring (init, validate). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter activate
Usage: spec-kitty charter activate [OPTIONS] [kind] [artifact_id]
Activate a doctrine artifact by kind and ID (FR-004), or apply a pack's
preset.
Two forms:
spec-kitty charter activate KIND ARTIFACT_ID [--cascade SCOPE
[--include-deactivated]]
spec-kitty charter activate [--pack PACK] --preset PRESET [--force] [--json]
A preset replaces every activation key it governs: keys it lists are
written (plus the org's required ids), keys it leaves out are removed.
A change to a customised key is refused without --force. A deactivated
id the preset lists stays deactivated (and is left out) unless --force,
which also clears its exclusion.
The cascade stops at a deactivated artifact and reports it;
--include-deactivated walks through and clears the exclusions.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ kind <str> Activation kind (e.g. directive, agent-profile). │
│ artifact_id <str> Artifact ID to activate. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --cascade <str> Cascade activation scope: │
│ 'all' for every referenced │
│ kind, or a comma-separated │
│ kind list (e.g. │
│ 'agent-profile,tactic'). │
│ Omit to skip cascade │
│ (referenced artifacts are │
│ reported as a warning). │
│ --resynthesize --no-resynthesize Eagerly refresh the FULL │
│ derived bundle/DRG (bundle │
│ content hash + project DRG │
│ layer, not just the compiled │
│ catalog) after this │
│ activation via the EXISTING │
│ synthesize pipeline (the │
│ same one `charter generate` │
│ + `charter synthesize` use). │
│ Default activation already │
│ recompiles │
│ `catalog.references` on its │
│ own via `charter generate`'s │
│ own compile seam (see │
│ --no-compile to opt out of │
│ that lightweight recompile); │
│ --resynthesize goes further │
│ and reconciles the freshness │
│ signal to fresh immediately │
│ (NFR-001). │
│ [default: no-resynthesize] │
│ --compile --no-compile Skip the default │
│ post-activation catalog │
│ recompile (FR-003): the fast │
│ config-only write from │
│ before issue #4785's fix. │
│ `catalog.references` is left │
│ as-is and may go stale until │
│ a later `charter generate` │
│ or `charter activate │
│ --resynthesize`. │
│ [default: compile] │
│ --preset <str> Apply this activation preset │
│ of the pack with replace │
│ semantics instead of │
│ activating one artifact. │
│ --pack <str> Pack whose preset --preset │
│ applies (built-in, an org │
│ pack name). Only with │
│ --preset. │
│ [default: built-in] │
│ --force Apply the preset even when │
│ it changes a customised │
│ activation key, and clear │
│ the exclusion of every │
│ deactivated id the preset │
│ lists. Only with --preset. │
│ --json Output the applied preset as │
│ JSON. Only with --preset. │
│ --only Replace this kind's │
│ activation list with this id │
│ plus org-required ids │
│ (prints what stops being in │
│ force). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Cascade options ────────────────────────────────────────────────────────────╮
│ --include-deactivated Walk through deactivated artifacts during the │
│ cascade: activate them and clear their │
│ exclusions. Without it the cascade stops at a │
│ deactivated artifact and reports it. Only │
│ with --cascade. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter bundle
Charter bundle validation commands.
Usage: spec-kitty charter bundle [OPTIONS] COMMAND [ARGS]...
Charter bundle validation commands.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ validate Validate the charter bundle against CharterBundleManifest v1.0.0. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter bundle validate
Usage: spec-kitty charter bundle validate [OPTIONS]
Validate the charter bundle against CharterBundleManifest v1.0.0.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit structured JSON to stdout instead of a human-readable │
│ report. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter consistency-check
Usage: spec-kitty charter consistency-check [OPTIONS]
Check the active charter for coherence against the offering (FR-011).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter context
Usage: spec-kitty charter context [OPTIONS]
Render charter context for a specific workflow action.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --action <str> Workflow action │
│ (specify|plan|implement|revi… │
│ --include <str> Fetch selector, e.g. │
│ agent-profile:<id>, │
│ template:<mission>/<name>, │
│ directive:<id>, │
│ section:<slug>. │
│ --mark-loaded --no-mark-loaded Persist first-load state │
│ [default: mark-loaded] │
│ --mission-type <str> Canonical mission type (e.g. │
│ documentation|research|plan|… │
│ for the action doctrine │
│ grain. Required when │
│ rendering action context from │
│ the repo root — without it, │
│ and without a mission's │
│ meta.json, the action grain │
│ is typeless and never │
│ inherits software-dev (#883). │
│ --json Output JSON. │
│ `context_schema_version` │
│ stamps the top-level payload │
│ shape (#2787, tracking │
│ contract -- not yet frozen). │
│ `directives` is │
│ action-scoped; │
│ `all_directives` and │
│ `project_charter` describe │
│ the project-local charter, │
│ while `org_charter` describes │
│ imported org packs. │
│ --include-all Escape hatch: materialise the │
│ entire reachable closure │
│ inline in the structured │
│ (--json) payload instead of │
│ the default progressive │
│ disclosure (requires eager, │
│ suggests linked). Output is a │
│ superset of the progressive │
│ render for the same grain. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter deactivate
Usage: spec-kitty charter deactivate [OPTIONS] [kind] [artifact_id]
Deactivate a doctrine artifact by kind and ID (FR-005), with optional cascade.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ kind <str> Activation kind (e.g. directive, agent-profile). │
│ artifact_id <str> Artifact ID to deactivate. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --cascade <str> Cascade deactivation scope: │
│ 'all' for every │
│ exclusively-referenced kind, │
│ or a comma-separated kind │
│ list. Shared artifacts are │
│ never removed. Omit to │
│ deactivate only the named │
│ artifact. │
│ --resynthesize --no-resynthesize Eagerly refresh the FULL │
│ derived bundle/DRG (bundle │
│ content hash + project DRG │
│ layer, not just the compiled │
│ catalog) after this │
│ activation via the EXISTING │
│ synthesize pipeline (the │
│ same one `charter generate` │
│ + `charter synthesize` use). │
│ Default activation already │
│ recompiles │
│ `catalog.references` on its │
│ own via `charter generate`'s │
│ own compile seam (see │
│ --no-compile to opt out of │
│ that lightweight recompile); │
│ --resynthesize goes further │
│ and reconciles the freshness │
│ signal to fresh immediately │
│ (NFR-001). │
│ [default: no-resynthesize] │
│ --compile --no-compile Skip the default │
│ post-activation catalog │
│ recompile (FR-003): the fast │
│ config-only write from │
│ before issue #4785's fix. │
│ `catalog.references` is left │
│ as-is and may go stale until │
│ a later `charter generate` │
│ or `charter activate │
│ --resynthesize`. │
│ [default: compile] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter fetch
Usage: spec-kitty charter fetch [OPTIONS]
Fetch org Charter Pack(s) from their configured remote sources.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --pack <str> Fetch only the named pack (default: fetch all │
│ configured packs). │
│ --dry-run Show what would be fetched without contacting any │
│ remote. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter generate
Usage: spec-kitty charter generate [OPTIONS]
Generate charter bundle from interview answers + doctrine references.
Behavior contract (issue #841 / WP06 T029-T030):
- On success in a git working tree, the produced
``.kittify/charter/charter.md``
is auto-staged via ``git add`` so a subsequent ``charter bundle validate``
finds it tracked without any operator ``git add`` between the two
commands. Staging (not committing) matches the parity contract — the
``bundle validate`` tracked-files check keys on ``git ls-files``.
- When the cwd is not inside a git working tree, ``generate`` exits
non-zero before any side effect with an actionable error message that
names the remediation (``git init``).
- When ``.kittify/charter/charter.md`` is a symlink, ``generate`` exits
non-zero before interview/default loading, compilation, sync,
gitignore updates, or staging. Update the symlink target directly or
replace it with a regular runtime charter.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission-type <str> Mission type for │
│ template-set defaults │
│ --template-set <str> Override charter │
│ offering template set │
│ (must exist in packaged │
│ charter offering │
│ missions) │
│ --from-interview --no-from-interview Load interview answers │
│ if present │
│ [default: │
│ from-interview] │
│ --profile <str> Default profile when no │
│ interview is available │
│ [default: minimal] │
│ --force -f Overwrite existing │
│ charter bundle │
│ --json Output JSON │
│ --owned-checkout <path> Run against an owned │
│ checkout: a linked │
│ checkout that owns this │
│ mission. Refuses the │
│ repository root │
│ checkout, lane │
│ worktrees and │
│ coordination worktrees. │
│ --mission-handle <str> Mission identity owned │
│ by the explicitly │
│ selected checkout │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter interview
Usage: spec-kitty charter interview [OPTIONS]
Capture charter interview answers for later generation.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission-type <str> Mission type for charter defaults │
│ (default: software-dev) │
│ --profile <str> Interview profile: minimal or │
│ comprehensive │
│ [default: minimal] │
│ --defaults Use deterministic defaults without │
│ prompts │
│ --selected-paradigms <str> Comma-separated paradigm IDs override │
│ --selected-directives <str> Comma-separated directive IDs override │
│ --available-tools <str> Comma-separated tool IDs override │
│ --narrow-activation Replace (not append to) activated │
│ directives, tactics and paradigms with │
│ the selection plus org-required ids │
│ --json Output JSON │
│ --mission-slug <str> Mission slug for Decision Moment paper │
│ trail (optional) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter lint
Usage: spec-kitty charter lint [OPTIONS]
Detect decay in charter artifacts via graph-native checks.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Scope lint to a specific mission slug │
│ --orphans Run only orphan checks │
│ --contradictions Run only contradiction checks │
│ --stale Run only staleness checks │
│ --json Output findings as JSON │
│ --severity <str> Minimum severity (low/medium/high/critical) │
│ [default: low] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter list
List activated charter artifacts by kind.
Usage: spec-kitty charter list [OPTIONS] COMMAND [ARGS]...
List activated charter artifacts by kind.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --show-available Also show available-but-not-activated artifacts. │
│ --all Show every available artifact per kind across │
│ the built-in, org, and project layers (annotated │
│ by source layer), including the template kind. │
│ Supersedes --show-available. │
│ --json Output JSON. Every kind row always carries an │
│ 'available' key and the payload always carries a │
│ top-level 'templates' key — both are null unless │
│ requested (available: null without │
│ --show-available/--all; templates: null without │
│ --all) rather than absent, so callers can rely │
│ on key presence and branch on the value instead │
│ of on which flags were passed. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter mission-type
Mission type commands (activated types only).
Usage: spec-kitty charter mission-type [OPTIONS] COMMAND [ARGS]...
Mission type commands (activated types only).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list List mission types for the current project (FR-016). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter mission-type list
Usage: spec-kitty charter mission-type list [OPTIONS]
List mission types for the current project (FR-016).
By default, returns only mission types that are explicitly activated in
this project's charter. Pass ``--include-inactive`` to also see every
type registered in the built-in/org/project layers regardless of
activation state (it replaced the removed doctrine-group listing; it is
not a straight alias: activation state still distinguishes the two row
classes -- see ACTION SEQUENCE below).
Output columns (table): ID, SOURCE, DISPLAY NAME, ACTION SEQUENCE. A
non-activated ``--include-inactive`` row shows ``(not activated)`` in
ACTION SEQUENCE: resolving a real action sequence requires activation
(the FR-006 gate), so there is nothing to compute for it.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output as JSON. │
│ --include-inactive Also list mission types registered in the │
│ built-in/org/project layers but NOT activated │
│ for this project (activation-blind). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter new
Usage: spec-kitty charter new [OPTIONS] {kind} {ID}
Scaffold a stub doctrine artifact YAML (FR-016).
The scaffolder pre-fills the canonical schema's required fields with
``TODO …`` placeholders so the file passes ``charter validate`` on
first emit. Refuses to overwrite an existing file.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * kind <str> Artifact kind (singular): one of agent_profile, asset, │
│ directive, mission_step_contract, paradigm, procedure, │
│ styleguide, tactic, toolguide. │
│ [required] │
│ * ID <str> Artifact identifier (kebab-case for most kinds; │
│ SCREAMING_SNAKE for directives). │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --pack <path> Scaffold inside a Charter Pack directory instead of │
│ the project layer. When omitted, the stub lands │
│ under .kittify/charter-packs/. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter org
Manage org Charter Pack authoring (init, validate).
Usage: spec-kitty charter org [OPTIONS] COMMAND [ARGS]...
Manage org Charter Pack authoring (init, validate).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ init Scaffold a minimal org pack or render from a template. │
│ validate Validate an org Charter Pack using schema and DRG checks (FR-006). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter org init
Usage: spec-kitty charter org init [OPTIONS] {pack_path}
Scaffold a minimal org pack or render from a template.
Without ``--template``, creates four files under *pack-path*::
org-charter.yaml — governance policy stub
drg/fragment.yaml — DRG extension stub (with pydantic_model:
frontmatter)
presets/starter.yaml — example activation preset
README.md — authoring quickstart
With ``--template``, copies the full template tree (minus
``.templateignore``),
substitutes ``{{ORG_NAME}}`` / ``{{LOCAL_PATH}}``, and writes under
*pack-path*.
Refuses to overwrite an existing directory unless ``--force`` is passed.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * pack_path <path> Destination directory for the scaffold or │
│ rendered charter pack tree. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force Overwrite an existing pack directory. │
│ --template <str> Local template directory or git URL (HTTPS/SSH; │
│ optional #branch). When omitted, scaffolds the │
│ minimal four-file pack. │
│ --org-name <str> Validated org/pack identity for {{ORG_NAME}} │
│ (required with --template). │
│ --local-path <str> Value for {{LOCAL_PATH}} (default: pack). │
│ Distinct from PACK_PATH. │
│ --branch <str> Git ref when --template is a git URL (may also │
│ be encoded in TEMPLATE). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter org validate
Usage: spec-kitty charter org validate [OPTIONS] {pack_path}
Validate an org Charter Pack using schema and DRG checks (FR-006).
Calls the WP06 :func:`charter.offering.packs.pack_validator.validate_pack`
loader. Prints per-file findings with file paths. Exits non-zero when
at least one error is found.
Org fragments use id and plural kind (for example, directives) for nodes.
Validation uses the runtime loader, which supplies pack provenance fields.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * pack_path <path> Path to the org Charter Pack directory to │
│ validate. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack
Charter pack management commands.
Usage: spec-kitty charter pack [OPTIONS] COMMAND [ARGS]...
Charter pack management commands.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list List the packs of the project's offering and the presets │
│ each ships (FR-004). │
│ path Print a pack's root, or with --preset the preset file │
│ (FR-006). │
│ validate Validate a Charter Pack against schema and DRG │
│ constraints. │
│ assemble Assemble multiple Charter Packs into a single │
│ distributable. │
│ regenerate-graph Regenerate the shipped DRG graph source deterministically │
│ (FR-009). │
│ vendor Bump (or verify) a pack pin; the pack tree itself is │
│ fetched by ``make sync-packs``. │
│ asset Resolve shipped and overlay charter pack assets (no │
│ install — C-002). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack assemble
Usage: spec-kitty charter pack assemble [OPTIONS] {output_path}
{input_packs}...
Assemble multiple Charter Packs into a single distributable.
Exits 0 on success and 1 when conflicts block the merge or when the
assembled output fails validation.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * output_path <path> Output directory for the assembled │
│ distributable pack. │
│ [required] │
│ * input_packs <path> One or more input pack directories to │
│ assemble. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --conflicts-out <path> Write the conflict report to this path │
│ (JSON). │
│ --force Resolve artifact-id conflicts by │
│ last-pack-wins and drop duplicate DRG edges │
│ silently. │
│ --json Emit machine-readable JSON instead of rich │
│ text. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack asset
Resolve shipped and overlay charter pack assets (no install — C-002).
Usage: spec-kitty charter pack asset [OPTIONS] COMMAND [ARGS]...
Resolve shipped and overlay charter pack assets (no install — C-002).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list List all resolvable charter pack assets and their source tiers. │
│ path Resolve an asset identifier to a filesystem path (fail-closed on │
│ miss). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack asset list
Usage: spec-kitty charter pack asset list [OPTIONS]
List all resolvable charter pack assets and their source tiers.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit machine-readable JSON instead of rich text. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack asset path
Usage: spec-kitty charter pack asset path [OPTIONS] {ASSET_ID}
Resolve an asset identifier to a filesystem path (fail-closed on miss).
Exits ``0`` and prints the path on success. An unknown id or a containment
refusal exits non-zero with the offending id named (A-7 / NFR-006).
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * ASSET_ID <str> Identifier of the asset to resolve (see `charter │
│ pack asset list`). │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit machine-readable JSON instead of rich text. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack list
Usage: spec-kitty charter pack list [OPTIONS]
List the packs of the project's offering and the presets each ships (FR-004).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack path
Usage: spec-kitty charter pack path [OPTIONS] {pack}
Print a pack's root, or with --preset the preset file (FR-006).
Fails closed (exit 1) with PACK_NOT_FOUND or PRESET_NOT_FOUND, listing the
valid names.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * pack <str> Pack name (built-in, an org pack name, or project). │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --preset <str> Print this preset's file instead of the pack root. │
│ --json Output as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack regenerate-graph
Usage: spec-kitty charter pack regenerate-graph [OPTIONS]
Regenerate the shipped DRG graph source deterministically (FR-009).
Composes the DRG extractor + calibrator into per-populated-node-kind
``packs/built-in/*.graph.yaml`` fragments (sharded per mission #2680 WP05;
relocated from ``src/charter/offering/`` by the pack flatten),
retiring the legacy ``graph.yaml`` monolith in the same write. Running twice
on unchanged inputs yields byte-identical fragments. With ``--check`` the
command never writes: it regenerates into a temp directory and compares the
fragment set against the committed source, exiting non-zero when stale — the
operator-facing twin of the freshness gate.
Both the write path and ``--check`` merge in the enumerable hand-authored
overlay (:mod:`charter.offering.drg.migration.hand_authored_overlay`) — the
``in_tension_with``/``reconciles_tension``/``rejects`` edges and
``anti_pattern`` nodes hand-authored directly in the graph fragments
(mission doctrine-tension-edges-01KY1WPC). The extractor has no
frontmatter mechanism that could ever mint these, so a bare pure
regeneration would (a) silently drop them from the committed source on
write, and (b) always report "stale" under ``--check`` even when nothing
is actually stale.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --check Do not write; regenerate into a temp directory │
│ and compare the per-kind graph fragments │
│ against the committed packs/built-in source. │
│ Exit 1 when stale (operator-runnable freshness │
│ gate). Exit 0 when fresh. │
│ --pack-root <path> Regenerate the DRG fragments and pack manifest │
│ for the BUILT-IN-level pack at this root │
│ instead of the shipped built-in pack (e.g. a │
│ vendored copy). The root must carry a pack.yaml │
│ declaring pack_level: built-in; org and project │
│ packs are refused. Applies to both the write │
│ path and --check. Defaults to the built-in pack │
│ root, leaving the no-flag behaviour │
│ byte-identical. │
│ --json Emit machine-readable JSON instead of rich │
│ text. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack validate
Usage: spec-kitty charter pack validate [OPTIONS] {pack_path}
Validate a Charter Pack against schema and DRG constraints.
Exits 0 when the pack passes validation (advisories do not affect the
exit code) and 1 when at least one error is reported.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * pack_path <path> Path to the Charter Pack directory to validate. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit machine-readable JSON instead of rich text. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter pack vendor
Usage: spec-kitty charter pack vendor [OPTIONS]
Bump (or verify) a pack pin; the pack tree itself is fetched by ``make
sync-packs``.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --check Verify only (offline): compare packs/<pack>/ with │
│ its pin lockfile; exit 1 on drift. Mutates │
│ nothing. │
│ --ref <str> Bump the pin to this open-packs commit SHA or │
│ branch (resolved to a SHA; only the SHA is │
│ persisted). │
│ --pack <str> Pack whose packs/<pack>.source.yaml pin to use. │
│ [default: built-in] │
│ --subtree <str> Override the pin's subtree (the pack's path inside │
│ the open-packs repository). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter preflight
Usage: spec-kitty charter preflight [OPTIONS]
Verify charter-derived state before a governed session begins.
Pipeline:
1. Resolve the repo root (same logic as the rest of the ``charter``
subcommand group).
2. Invoke :func:`run_charter_preflight`.
3. Render JSON or a Rich summary, then exit per the contract.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit the result as JSON (binding shape, see │
│ contracts/charter-preflight-json.md). │
│ --auto-refresh When checks fail and the worktree has no │
│ uncommitted generated artifacts, run the safe │
│ refresh sequence (charter generate / upgrade --yes │
│ -> synthesize -> bundle validate). │
│ --strict Exit non-zero on any non-fresh state (default: │
│ exit zero unless a hard error occurs). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter resynthesize
Usage: spec-kitty charter resynthesize [OPTIONS]
Regenerate a bounded set of project-local doctrine artifacts (partial
resynthesis).
Uses a structured selector to identify the target set:
- ``directive:PROJECT_001`` — regenerate a specific project directive.
- ``tactic:how-we-apply-directive-003`` — regenerate one tactic.
- ``directive:DIRECTIVE_003`` — regenerate every artifact whose provenance
references the built-in DIRECTIVE_003 URN.
- ``testing-philosophy`` — regenerate all artifacts from that interview
section.
Unrelated artifacts are never touched (FR-017).
Examples
--------
Resynthesize a single tactic::
spec-kitty charter resynthesize --topic tactic:how-we-apply-directive-003
Resynthesize all artifacts referencing a built-in directive::
spec-kitty charter resynthesize --topic directive:DIRECTIVE_003
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --topic <str> Structured topic selector: │
│ <kind>:<slug> (project-local), │
│ <drg-urn> (built-in+project graph), or │
│ <interview-section-label>. │
│ --list-topics List valid structured topic selectors │
│ and exit. │
│ --adapter <str> Adapter to use. 'generated' (default) │
│ validates agent-authored YAML under │
│ .kittify/charter/generated/. 'fixture' │
│ is offline/testing only. │
│ [default: generated] │
│ --skip-code-evidence Skip code-reading evidence collection. │
│ --skip-corpus Skip best-practice corpus loading. │
│ --json Output JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter status
Usage: spec-kitty charter status [OPTIONS]
Display charter sync status plus synthesis/operator state.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output JSON │
│ --provenance Include per-artifact provenance details. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter synthesize
Usage: spec-kitty charter synthesize [OPTIONS]
Validate and promote agent-generated project-local doctrine artifacts.
Reads the charter interview answers, resolves synthesis targets from the
DRG + doctrine, and writes all artifacts to ``.kittify/charter-packs/``.
Doctrine generation is performed by the LLM harness (Claude Code, Codex,
Cursor, etc.) via the spk-charter-governance skill. This command
validates and promotes the artifacts the agent has written.
Fresh-project behavior (issue #839 / WP06 T031-T033)
----------------------------------------------------
On a fresh project where ``.kittify/charter/generated/`` is missing or
empty (i.e. the LLM harness has not yet written agent artifacts), this
command short-circuits the adapter pipeline and materializes the
**minimal artifact set** the runtime requires:
1. ``.kittify/charter-packs/`` — directory marker. The project-root
resolver (``charter.activation._project_root_candidates``) is a
presence-only check; an empty directory is a valid project layer.
2. ``.kittify/charter-packs/PROVENANCE.md`` — human-readable record of the
fresh-project seed path, citing #839.
The runtime falls back to the built-in doctrine (``packs/built-in/``) for
all artifact lookups until the harness writes per-target YAML and the
operator re-runs ``synthesize`` (which then takes the normal adapter
path). The fresh-project path is **idempotent**: re-running produces
bytewise-identical output (T033). Charter prerequisites are still
enforced — ``charter.md`` must exist (else ``TaskCliError`` is raised
via ``_build_synthesis_request``).
Examples
--------
Validate + promote generated artifacts written by the harness::
spec-kitty charter synthesize
Validate + promote with fixture adapter (offline/testing)::
spec-kitty charter synthesize --adapter fixture
Dry-run (stage + validate, no promote)::
spec-kitty charter synthesize --dry-run
Preserve-and-warn default (WP03): a plain run never drops backed
content -- it exits 0 and reports what it retained. Remove divergent
content explicitly::
spec-kitty charter synthesize --prune
Only orphaned content (backing artifact deleted) or an unparseable
on-disk overlay make a plain run refuse (exit 1); backed divergence is
always preserved and reported, never a refusal.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --adapter <str> Adapter to use. 'generated' (default) │
│ validates agent-authored YAML under │
│ .kittify/charter/generated/. 'fixture' │
│ is offline/testing only. │
│ [default: generated] │
│ --dry-run Stage and validate artifacts but do not │
│ promote to live tree. Also reports the │
│ reconciliation delta --prune would │
│ remove. Wins over --prune when both are │
│ given (preview only, no write). │
│ --prune Remove on-disk content the current run │
│ no longer targets and list every │
│ deletion. Without this flag, that │
│ content is preserved (default) unless │
│ it is orphaned (backing artifact │
│ deleted), which refuses instead of │
│ silently keeping a dangling reference. │
│ --json Output JSON │
│ --skip-code-evidence Skip code-reading evidence collection. │
│ --skip-corpus Skip best-practice corpus loading. │
│ --dry-run-evidence Print evidence summary and exit without │
│ running synthesis. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty charter validate
Usage: spec-kitty charter validate [OPTIONS] {path}
Validate project-layer doctrine artifacts against their schemas (FR-017).
When *path* is a single file, validates that file. When *path* is a
directory, walks the tree for ``*.yaml`` files whose filename suffix
matches a canonical artifact kind and validates each one.
Exit code: ``0`` if every artifact validates; ``1`` if any artifact
fails. A per-file error report is printed for failures.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * path <path> Artifact YAML file or a directory containing │
│ project-layer doctrine artifacts (recurses into │
│ per-kind subdirectories). │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty config
Usage: spec-kitty config [OPTIONS]
Display project configuration and asset resolution information.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --show-origin Show where each resolved asset comes from │
│ (tier label + path) │
│ --mission -m <str> Mission to resolve assets for │
│ [default: software-dev] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty consolidate
Usage: spec-kitty consolidate [OPTIONS]
Consolidate a lane-based mission into its target branch.
Exit codes: 0 on success. 75 (error code COORD_MOVED_AFTER_LANDING) when the
landing stands but the coordination or mission branch moved after it and was
kept instead of deleted; for a coordination branch, --resume lands the late
commits and finishes the teardown. Any other non-zero code is a refusal or
failure.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --strategy <merge|squash|r Strategy for the │
│ ebase> branch-integrati… │
│ step (git merge │
│ of │
│ mission→target): │
│ merge | squash | │
│ rebase. Default: │
│ squash. │
│ --delete-branch --keep-branch Delete lane │
│ branches after │
│ merge. Unset (the │
│ default) defers │
│ to the mission's │
│ meta.json │
│ retention policy │
│ (#3131), falling │
│ back to delete │
│ when no policy is │
│ recorded. Passing │
│ either flag │
│ explicitly always │
│ wins over the │
│ mission's policy. │
│ --remove-worktree --keep-worktree Remove lane │
│ worktrees after │
│ merge. Unset (the │
│ default) defers │
│ to the mission's │
│ meta.json │
│ retention policy │
│ (#3131), falling │
│ back to remove │
│ when no policy is │
│ recorded. Passing │
│ either flag │
│ explicitly always │
│ wins over the │
│ mission's policy. │
│ --push Publish to origin │
│ after the local │
│ merge (the │
│ operator publish │
│ step; distinct │
│ from local lane │
│ consolidation) │
│ --target <str> Target branch for │
│ the │
│ branch-integrati… │
│ step │
│ (auto-detected) │
│ --dry-run Show what would │
│ be done without │
│ executing │
│ --json Output │
│ deterministic │
│ JSON (dry-run │
│ mode) │
│ --mission <str> Mission slug when │
│ merging from main │
│ branch │
│ --resume Resume an │
│ interrupted merge │
│ from the last │
│ incomplete WP │
│ --abort Abort an │
│ in-progress │
│ merge, cleaning │
│ up state and │
│ worktrees │
│ --context <str> Unused │
│ compatibility │
│ flag │
│ --keep-workspace Unused │
│ compatibility │
│ flag │
│ --allow-sparse-c… Proceed even if │
│ legacy │
│ sparse-checkout │
│ state is │
│ detected. Use of │
│ this override is │
│ logged. Does not │
│ bypass the │
│ commit-time │
│ data-loss │
│ backstop. │
│ --yes -y Proceed after │
│ merge warnings │
│ without prompts │
│ --skip-review-ar… Bypass the │
│ review-artifact │
│ consistency gate │
│ (the #2959 escape │
│ hatch). Requires │
│ --note; the skip │
│ is recorded as │
│ durable override │
│ evidence in the │
│ status log, never │
│ a silent bypass. │
│ --note <str> Reason recorded │
│ as override │
│ evidence when │
│ using │
│ --skip-review-ar… │
│ (required with │
│ it). │
│ --skip-lanes,--n… Complete a │
│ merge-ready │
│ direct-on-target │
│ mission that has │
│ no lane branch │
│ (#2745, FR-012): │
│ when lanes.json │
│ is genuinely │
│ absent, │
│ synthesize a │
│ no-lane manifest │
│ instead of │
│ hard-failing with │
│ the missing-lanes │
│ error. A mission │
│ that has real │
│ lanes is │
│ unaffected -- an │
│ existing │
│ lanes.json is │
│ always honored │
│ as-is. Does NOT │
│ bypass the │
│ merge-ready │
│ precondition: a │
│ not-merge-ready │
│ mission still │
│ refuses before │
│ any mutation. │
│ --attest-cancele… <str> Operator │
│ attestation │
│ (repeatable, one │
│ WP id each): the │
│ named canceled │
│ WP's content is │
│ absent or │
│ superseded, │
│ verified by hand. │
│ Lifts, for that │
│ WP only, a REFUSE │
│ whose attribution │
│ evidence can │
│ never appear │
│ later (a mixed │
│ lane, or an │
│ unstamped │
│ canceled WP on a │
│ canceled │
│ dependency lane); │
│ never lifts a │
│ FAIL. Requires │
│ --attest-reason; │
│ recorded durably │
│ in the status │
│ event log. │
│ --attest-approve… <str> Operator │
│ attestation │
│ (repeatable, one │
│ WP id each): the │
│ named approved │
│ work package, │
│ whose approval │
│ recorded no lane │
│ head, was │
│ reviewed as it │
│ stands on its │
│ lane. Requires │
│ --attest-reason. │
│ Does not lift a │
│ refusal for │
│ commits made │
│ after a recorded │
│ approval. │
│ --attest-reason <str> What you checked, │
│ recorded with │
│ --attest-cancele… │
│ or │
│ --attest-approve… │
│ (required with │
│ either); one │
│ reason serves │
│ every attestation │
│ of the run. │
│ --release-branch <str> With --abort │
│ (repeatable): │
│ keep this branch │
│ at its current │
│ commit instead of │
│ refusing because │
│ it cannot be │
│ restored. The │
│ branch keeps all │
│ of its current │
│ commits, │
│ including this │
│ consolidation's │
│ unverified │
│ changes; review │
│ them afterwards. │
│ Only the record's │
│ target, mission │
│ or coordination │
│ branch can be │
│ released. │
│ Requires │
│ --release-reason. │
│ --release-reason <str> Why the released │
│ branches are │
│ kept, printed in │
│ the --abort │
│ report (required │
│ with │
│ --release-branch… │
│ --origin-check <function> Origin freshness │
│ check before │
│ anything lands: │
│ enforce (the │
│ default) refuses │
│ when the remote's │
│ status log or an │
│ approved lane │
│ branch of this │
│ Mission is ahead │
│ of this clone, or │
│ the remote cannot │
│ be reached; warn │
│ reports the same │
│ findings and │
│ continues; off │
│ contacts nothing │
│ and accepts stale │
│ evidence. │
│ Overrides │
│ SPEC_KITTY_ORIGI… │
│ --help -h Show this message │
│ and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty context
Query workspace context information
Usage: spec-kitty context [OPTIONS] COMMAND [ARGS]...
Query workspace context information
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ info Show context information for current or specified │
│ workspace. │
│ list List all workspace contexts. │
│ cleanup Clean up orphaned workspace contexts. │
│ mission-resolve Resolve and persist a MissionContext token. │
│ mission-show Show all fields of a persisted MissionContext token. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty context cleanup
Usage: spec-kitty context cleanup [OPTIONS]
Clean up orphaned workspace contexts.
Removes context files for workspaces that no longer exist.
Examples:
# Preview cleanup
spec-kitty context cleanup --dry-run
# Clean up orphaned contexts
spec-kitty context cleanup
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run Show what would be cleaned up without deleting │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty context info
Usage: spec-kitty context info [OPTIONS]
Show context information for current or specified workspace.
Examples:
# Auto-detect from current directory (if inside worktree)
spec-kitty context info
# Explicit workspace
spec-kitty context info --workspace 010-mission-lane-a
# JSON output
spec-kitty context info --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --workspace -w <str> Workspace name (auto-detected if inside │
│ worktree) │
│ --json Output in JSON format │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty context list
Usage: spec-kitty context list [OPTIONS]
List all workspace contexts.
Examples:
# List all contexts
spec-kitty context list
# List only orphaned contexts (worktree deleted)
spec-kitty context list --orphaned
# JSON output
spec-kitty context list --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output in JSON format │
│ --orphaned Show only orphaned contexts │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty context mission-resolve
Usage: spec-kitty context mission-resolve [OPTIONS]
Resolve and persist a MissionContext token.
Creates a new bound context for the given work package and mission,
writes it to .kittify/runtime/contexts/, and prints the token.
The token can be passed to other commands via --context <token>.
Examples:
# Resolve and print token for piping
TOKEN=$(spec-kitty context mission-resolve --wp WP01 --mission
057-my-mission)
# Resolve and print full JSON
spec-kitty context mission-resolve --wp WP01 --mission 057-my-mission
--json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --wp <str> Work package code (e.g., WP01) [required] │
│ --mission <str> Mission slug (e.g., 057-mission-name) │
│ --agent <str> Agent name (default: 'unknown') │
│ --json Output full JSON context (default: token only) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty context mission-show
Usage: spec-kitty context mission-show [OPTIONS]
Show all fields of a persisted MissionContext token.
Loads the context file and pretty-prints its bound fields.
Examples:
spec-kitty context mission-show --context ctx-01HVXYZ...
spec-kitty context mission-show --context ctx-01HVXYZ... --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --context <str> Context token (e.g., ctx-01HV...) [required] │
│ --json Output raw JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty cutover-guard
Diff-scoped fail-closed cut-over gate (pre-merge required check).
Usage: spec-kitty cutover-guard [OPTIONS]
Diff-scoped fail-closed cut-over gate (pre-merge required check).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --base-ref <str> Diff HEAD against the merge-base with this ref │
│ to discover touched kitty-specs/<mission> paths │
│ (e.g. origin/main). │
│ --paths-from PATH Read already-known changed paths from this file │
│ (one per line) instead of running git diff. Use │
│ when the CI host already provides the diff │
│ (e.g. a PR file list). │
│ --json Emit the guard verdict as structured JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty dispatch
Dispatch a request to a governed Op (canonical surface).
Usage: spec-kitty dispatch [OPTIONS] {request}
Dispatch a request to a governed Op (canonical surface).
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * request <str> Natural language request. The router picks the best │
│ profile. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --profile <str> Optional profile ID. Bypasses the router — use │
│ when the request is ambiguous. │
│ --json Output JSON payload │
│ --dry-run Route the request and return the routing signal │
│ without opening an Op or writing anything. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty docs
Common Docs retrieval commands
Usage: spec-kitty docs [OPTIONS] COMMAND [ARGS]...
Common Docs retrieval commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ query Query the Common Docs retrieval index for pages matching TERM. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty docs query
Usage: spec-kitty docs query [OPTIONS] {term}
Query the Common Docs retrieval index for pages matching TERM.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * term <str> Case-insensitive substring matched against title, │
│ anchor text/slug, and abstract. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit machine-readable JSON via plain print (no │
│ Rich markup). │
│ --divio-type <str> Restrict to pages of this Divio type │
│ (tutorial|how-to|reference|explanation|none). │
│ --section <str> Restrict to pages containing an anchor with │
│ this slug. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor
Project health diagnostics
Usage: spec-kitty doctor [OPTIONS] COMMAND [ARGS]...
Project health diagnostics
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ bytecode Flag a corrupt installed-package .pyc before it │
│ bites (#4124, #4130). │
│ channel Report the active release channel (stable vs. │
│ prerelease-opt-in). │
│ env-file Report ``.kitty.env`` operator env-file health │
│ (presence/tier/ignore). │
│ provenance Flag committed absolute built-in-pack leaks and │
│ ambiguous template sources (C-PRV-5). │
│ run-index Flag absolute run_dir paths in the run index that │
│ break on copy/move (#5390). │
│ command-files Check all agent command files for correctness. │
│ skills Check command-skill manifest drift for Codex, Vibe, │
│ Pi, Letta, and Antigravity. │
│ tool-surfaces Audit (and optionally repair) every configured tool │
│ surface. │
│ state-roots Show state roots, surface classification, and safety │
│ warnings. │
│ workspaces Report .worktrees/ husk directories (entries lacking │
│ a .git entry). │
│ identity Report mission-identity health across kitty-specs/. │
│ topology Report each mission's STORED topology across │
│ kitty-specs/. │
│ mission-type Report mission-type resolution health across │
│ kitty-specs/. │
│ sparse-checkout Detect and optionally remediate legacy │
│ sparse-checkout state. │
│ shim-registry Check for overdue compatibility shims in the shim │
│ registry. │
│ contracts Validate the Contract Registry for well-formedness. │
│ invocation-pairing List orphan profile-invocation lifecycle records. │
│ ops List orphan Op records; --close-stale sweeps stale │
│ ones closed as abandoned. │
│ mission-state Audit, repair, or TeamSpace-validate mission-state │
│ shapes. │
│ charter-packs Check org charter pack snapshot status and list │
│ installed pack artifacts. │
│ coordination Run the WP04 #1348 coordination + sparse-checkout │
│ health checks. │
│ cutover Audit every mission's cut-over status outside CI │
│ (FR-007). │
│ review-cycle-reconcile Find review-cycle / arbiter-override records │
│ stranded under a retired │
│ resolver path, ahead of WP13's consumer-unification │
│ (FR-008). │
│ decisions Diagnose or repair divergence between │
│ ``decisions/index.json`` and the │
│ authoritative │
│ ``DecisionPointOpened``/``DecisionPointResolved`` │
│ event log │
│ (#4919). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor bytecode
Usage: spec-kitty doctor bytecode [OPTIONS]
Flag a corrupt installed-package .pyc before it bites (#4124, #4130).
Reads each .pyc under the installed specify_cli package and flags one
whose header Python's import machinery would trust (so it would be
used as-is) but whose body fails to unmarshal into a code object --
the truncated-write shape that crashed a training machine in #4124.
A cache Python would already recompile from source (bad magic, stale
timestamp/size) is not flagged; it never bites. Read-only -- never
deletes anything.
Examples:
spec-kitty doctor bytecode
spec-kitty doctor bytecode --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor channel
Usage: spec-kitty doctor channel [OPTIONS]
Report the active release channel (stable vs. prerelease-opt-in).
Reads SPEC_KITTY_PRERELEASE (default OFF — stable channel). Never
mutates state.
Examples:
spec-kitty doctor channel
spec-kitty doctor channel --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor charter-packs
Usage: spec-kitty doctor charter-packs [OPTIONS]
Check org charter pack snapshot status and list installed pack artifacts.
Exit code reflects health (WP01, operator directive: loud over hidden): the
command exits **1 when the report is unhealthy** and 0 only when healthy
(``report.healthy`` drives the code on every output path). A clear RC=1 with
a surfaced error is preferred over an RC=0 that hides a defect. It
enumerates each configured org pack (from ``.kittify/config.yaml``), prints
its on-disk version (``git describe`` for git-managed packs, otherwise the
``pack-manifest.yaml`` ``pack_version``), per-artifact YAML counts, and
``org-charter.yaml`` policy status when present.
Override governance (FR-010 / FR-012): when org packs are configured, any
``org:``-provenance override of a built-in DRG node that is NOT sanctioned
by ``.kittify/charter-packs/replaceable-builtins.yaml`` or by the overriding
pack's own pack-root ``replaceable-builtins.yaml`` is reported as an
``unsanctioned_overrides`` finding and flips the report unhealthy (RC=1).
A pack sanction applies only to overrides that same pack contributes, and
the consumer file can withdraw it with ``revoked_pack_sanctions``. Sanctioned
overrides and their source are listed as ``sanctioned_overrides``.
Project-tier (``.kittify/charter-packs/``) overrides of built-ins are
intentionally **ungoverned** — the project layer is the trusted operator tier
and is not gated by the consumer-facing allowlist; only org-tier overrides
are adjudicated.
Examples:
spec-kitty doctor charter-packs
spec-kitty doctor charter-packs --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor command-files
Usage: spec-kitty doctor command-files [OPTIONS]
Check all agent command files for correctness.
Verifies that every configured agent has the correct command files:
- Full rendered prompts for prompt-driven commands (specify, plan, tasks, ...)
- Thin shims for CLI-driven commands (implement, review, merge, ...)
- Current version markers on all files
Examples:
spec-kitty doctor command-files
spec-kitty doctor command-files --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor contracts
Usage: spec-kitty doctor contracts [OPTIONS]
Validate the Contract Registry for well-formedness.
Reads docs/contracts/contract-registry.yaml and validates every record
against the schema: required fields present, kind/status/enforcement in
range, semver + tracker refs well-formed, anchors resolve, and — the DIR-041
self-consistency gate (NFR-003) — NO positional file:line anchoring anywhere.
Structural validation is the only enforcing gate in v1; the retirement
absence-sweep is advisory.
Exit codes:
0 Registry is well-formed (or empty).
2 Configuration error (registry file missing) or a schema violation.
Examples:
spec-kitty doctor contracts
spec-kitty doctor contracts --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor coordination
Usage: spec-kitty doctor coordination [OPTIONS]
Run the WP04 #1348 coordination + sparse-checkout health checks.
Iterates over every mission under ``kitty-specs/`` whose ``meta.json``
declares a ``coordination_branch`` field, runs the coord-worktree
and lane-sparse-checkout health checks, and prints findings.
Also runs the minimum git-version (RR-01) check.
Exits with code 1 if any ``error`` finding is emitted; ``warning``
findings exit 0 but are still printed.
With ``--fix``, automatically materializes a missing coordination worktree
whose declared branch still exists in git (#5113 / FR-014, via the
canonical ``materialize_coord_surface_for_write`` helper — idempotent, and
it refuses rather than crashing when the branch is remote-only), flattens
missions that have a stale ``coordination_branch`` key (branch never
created or already deleted), re-derives topology, and attempts the Gap-1
coord-vs-target fast-forward (FR-009) -- which fails loud with a unified
diff and mutates nothing when
the coord branch has diverged or its worktree is dirty, and refuses
without mutating when the coord worktree is on another branch, detached,
or not a worktree of this repository. ``Fast-forwarded`` is printed only
once the coord branch really matches the target. Safe to run on
100%-done missions before ``spec-kitty next`` or ``spec-kitty consolidate``.
With ``--check-staleness``, also reports Gap-1 coord-branch-vs-target
staleness (FR-008) — non-blocking either way.
With ``--mission <handle>``, scopes every per-mission check (and the
``--fix`` Gap-1 fast-forward) to the single mission the shared resolver maps
the handle to. An unresolvable / ambiguous handle fails closed with exit 1.
Examples:
spec-kitty doctor coordination
spec-kitty doctor coordination --fix
spec-kitty doctor coordination --json
spec-kitty doctor coordination --check-staleness
spec-kitty doctor coordination --mission 083-my-mission
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix Repair coordination topology: materialize │
│ a missing coordination worktree whose │
│ branch exists, remove stale │
│ `coordination_branch` keys for │
│ never-created branches (then `migrate │
│ backfill-topology`), and revert stranded │
│ coordination state. │
│ --json Machine-readable JSON output │
│ --check-staleness Also report coord-branch-vs-target-branch │
│ staleness (Gap-1, FR-008): non-blocking, │
│ whether the coord branch is behind or has │
│ diverged from its mission's target_branch. │
│ --mission <str> Scope the checks to a single mission │
│ handle (mission_id / mid8 / slug), │
│ resolved via the same resolver as `doctor │
│ mission-state`. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor cutover
Usage: spec-kitty doctor cutover [OPTIONS]
Audit every mission's cut-over status outside CI (FR-007).
Backed by ``migration.runtime_state_cutover.cutover_repo(dry_run=True)``:
the same fail-closed seed-then-verify spine the birth-cutover migration
uses, read-only and writing nothing. Reports each mission slug, whether
it is cut over, and a reason when it is not.
Informational only: always exits 0 with a summary count.
Examples:
spec-kitty doctor cutover
spec-kitty doctor cutover --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor decisions
Usage: spec-kitty doctor decisions [OPTIONS]
Diagnose or repair divergence between ``decisions/index.json`` and the
authoritative ``DecisionPointOpened``/``DecisionPointResolved`` event log
(#4919).
Diagnose (default): read-only; reports decisions present in the event
log but missing from the index, index entries with no backing event, a
decision_id whose event group cannot be folded at all (e.g. an
``open -> open`` corruption), and an index entry whose status disagrees
with the folded log (a stale entry). Always exits 0 (report only).
``--repair``: rebuilds ``index.json`` from the log via the single
canonical ``event -> IndexEntry`` fold
(:mod:`specify_cli.decisions.index_fold`) under the same sidecar lock the
write path uses — never invents an entry absent from the log, never
drops a log-backed entry. A no-op (no write) when the log and index
already agree. The fold is order-independent: a decision's documented
``open -> defer -> resolve`` flow emits a ``deferred``-outcome event and
a later ``resolved``-outcome event, and folds to ``resolved`` regardless
of which one the (git-merge-driver-resorted) log lists first (#4919).
When a decision cannot be reconciled, ``--repair`` leaves it unchanged
(never drops it), names it in the report, and the command then exits
**1**. It exits 0 only when every decision the repair touched
folds cleanly.
Run ``--repair`` as an offline maintenance step, not concurrently with
live decision traffic: a decision that is mid-open (its index entry
written under the sidecar lock, its event not yet appended) is briefly
invisible to a log-authoritative rebuild, so a repair racing that window
can drop the in-flight entry (a later ``--repair`` heals it). Like
``fsck``, it is meant to run when writers are quiesced.
Examples:
spec-kitty doctor decisions --mission my-mission-01ABCD
spec-kitty doctor decisions --mission my-mission-01ABCD --repair
spec-kitty doctor decisions --mission my-mission-01ABCD --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission handle (mission_id / mid8 / slug) │
│ [required] │
│ --json Machine-readable JSON output │
│ --repair Rebuild decisions/index.json from the event log │
│ (run offline; not against live decision │
│ traffic) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor env-file
Usage: spec-kitty doctor env-file [OPTIONS]
Report ``.kitty.env`` operator env-file health (presence/tier/ignore).
Reads the repo- and home-tier ``.kitty.env`` files and the
config.yaml ``env_file`` pointer, and reports which governed vars
are set and from which tier -- names/presence only for anything not
on the printable-var allowlist (C-SEC-1), values never leaked.
Read-only -- never mutates state.
Examples:
spec-kitty doctor env-file
spec-kitty doctor env-file --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor identity
Usage: spec-kitty doctor identity [OPTIONS]
Report mission-identity health across kitty-specs/.
Classifies every mission into one of four states (FR-045):
\b
- assigned: mission_id present AND mission_number non-null (fully migrated)
- pending: mission_id present AND mission_number null (pre-merge)
- legacy: mission_id missing AND mission_number present (needs backfill)
- orphan: both fields missing or meta.json unreadable (needs triage)
Also reports duplicate numeric prefixes (FR-011) and ambiguous selectors
that would resolve to multiple missions (FR-012).
Examples:
spec-kitty doctor identity
spec-kitty doctor identity --json
spec-kitty doctor identity --mission 083-foo
spec-kitty doctor identity --fail-on legacy,orphan
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit structured JSON output (suitable for CI) │
│ --mission <str> Scope report to a single mission slug │
│ --fail-on <str> Exit non-zero if any mission is in the given │
│ state(s). Comma-separated list of: assigned, │
│ pending, legacy, orphan. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor invocation-pairing
Usage: spec-kitty doctor invocation-pairing [OPTIONS]
List orphan profile-invocation lifecycle records.
WP05 (#843) wiring: scans
``.kittify/events/profile-invocation-lifecycle.jsonl`` for ``started``
records with no paired ``completed`` or ``failed`` partner. Mid-cycle
agent crashes show up here. The check observes; it does not remediate.
Exit codes:
0 No orphans observed.
1 At least one orphan found.
Examples:
spec-kitty doctor invocation-pairing
spec-kitty doctor invocation-pairing --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor mission-state
Usage: spec-kitty doctor mission-state [OPTIONS]
Audit, repair, or TeamSpace-validate mission-state shapes.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --audit Run mission-state audit (required to │
│ proceed) │
│ --fix Repair mission-state artifacts in place │
│ and write a migration manifest │
│ --teamspace-dry-run Synthesize canonical TeamSpace │
│ envelopes from local state and validate │
│ them │
│ --json Emit JSON report to stdout │
│ --mission <str> Scope to a single mission handle │
│ --fail-on <str> Exit 1 if findings meet a gate │
│ (error|warning|info|teamspace-blocker) │
│ --fixture-dir <path> Override scan root (for testing) │
│ --include-fixtures Audit the bundled mission-state survey │
│ fixtures │
│ --manifest-path <path> Path for --fix migration manifest │
│ --allow-dirty Allow --fix when relevant git paths are │
│ already dirty │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor mission-type
Usage: spec-kitty doctor mission-type [OPTIONS]
Report mission-type resolution health across kitty-specs/.
Classifies every mission into one of six states (FR-008):
\b
- resolved: mission_type present, activated, and loadable
- activated-unresolvable: activated but has no loadable profile on disk
- unknown: mission_type present but not activated/registered anywhere
- typeless: no mission_type key (or a blank/null/non-string value)
- legacy-key-only: only the retired `mission` key is present
- error: meta.json unreadable or malformed
Examples:
spec-kitty doctor mission-type
spec-kitty doctor mission-type --json
spec-kitty doctor mission-type --mission 083-foo
spec-kitty doctor mission-type --fail-on unknown,activated-unresolvable
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit structured JSON output (suitable for CI) │
│ --mission <str> Scope report to a single mission slug │
│ --fail-on <str> Exit non-zero if any mission is in the given │
│ state(s). Comma-separated list of: resolved, │
│ activated-unresolvable, unknown, typeless, │
│ legacy-key-only, error. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor ops
Usage: spec-kitty doctor ops [OPTIONS]
List orphan Op records; --close-stale sweeps stale ones closed as abandoned.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --close-stale Close open Ops older than --threshold as │
│ abandoned (closed_by=doctor_sweep) │
│ --threshold <float> Staleness threshold in hours (default 24; 0 │
│ closes all). Requires --close-stale. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor provenance
Usage: spec-kitty doctor provenance [OPTIONS]
Flag committed absolute built-in-pack leaks and ambiguous template sources
(C-PRV-5).
Scans .kittify/charter/charter.yaml's catalog and
.kittify/agent_profiles_manifest.json for source_path values that
should be portable pack tokens. Read-only -- never mutates state;
ambiguous former-checkout paths are reported without a heal hint.
Examples:
spec-kitty doctor provenance
spec-kitty doctor provenance --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor review-cycle-reconcile
Usage: spec-kitty doctor review-cycle-reconcile [OPTIONS]
Find review-cycle / arbiter-override records stranded under a retired resolver
path, ahead of WP13's consumer-unification (FR-008).
Every retired resolver comes from WP08's reviewed retirement set, not a
guessed set. Reports two DISTINCT stranded classes per finding: a
deleted-coordination-branch mission (absorbed to PRIMARY, the measured
45-mission corpus) and a live-coordination-branch mission still carrying a
pre-ADR PRIMARY record. Never a bare count — every finding names its
mission, WP, retired resolver, and resolved directory.
Informational only: always exits 0. No ``--fix`` — a stranded record may
have a legitimate divergent sibling, and this command does not pick a
winner.
Examples:
spec-kitty doctor review-cycle-reconcile
spec-kitty doctor review-cycle-reconcile --mission my-mission-01ABCD
spec-kitty doctor review-cycle-reconcile --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Scope to a single mission (mission_id / mid8 / │
│ slug) │
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor run-index
Usage: spec-kitty doctor run-index [OPTIONS]
Flag absolute run_dir paths in the run index that break on copy/move (#5390).
Scans .kittify/runtime/feature-runs.json for run_dir values stored as
absolute paths (nonportable — a copied or moved project resolves the
original folder's cursor). Read-only; heal with ``spec-kitty migrate``.
Examples:
spec-kitty doctor run-index
spec-kitty doctor run-index --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor shim-registry
Usage: spec-kitty doctor shim-registry [OPTIONS]
Check for overdue compatibility shims in the shim registry.
Reads docs/migrations/shim-registry.yaml and compares each entry's
removal_target_release against the current project version. Fails with
exit code 1 if any shim is overdue (removal release has shipped but
shim file still exists on disk).
Exit codes:
0 All entries are pending, removed, or grandfathered.
1 At least one entry is overdue — shim must be deleted or window extended.
2 Configuration error (registry file or pyproject.toml missing/invalid).
Examples:
spec-kitty doctor shim-registry
spec-kitty doctor shim-registry --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor skills
Usage: spec-kitty doctor skills [OPTIONS]
Check command-skill manifest drift for Codex, Vibe, Pi, Letta, and Antigravity.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix Repair missing command-skill files │
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor sparse-checkout
Usage: spec-kitty doctor sparse-checkout [OPTIONS]
Detect and optionally remediate legacy sparse-checkout state.
Without ``--fix``: scans the repo and prints a warning finding
describing any active sparse-checkout state (primary + lane
worktrees). Exits 0 when clean, 1 when state is present.
With ``--fix``: in an interactive TTY, prints a step-by-step plan,
prompts once for consent, and calls WP03's ``remediate()``. In
non-interactive / CI environments, prints a remediation pointer and
exits non-zero without mutating state (FR-023).
Examples:
spec-kitty doctor sparse-checkout
spec-kitty doctor sparse-checkout --fix
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix Apply remediation (disable sparse-checkout on primary + │
│ worktrees). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor state-roots
Usage: spec-kitty doctor state-roots [OPTIONS]
Show state roots, surface classification, and safety warnings.
Displays the three state roots with resolved paths, all registered
state surfaces grouped by root with authority and Git classification,
and warnings for any runtime surfaces not covered by .gitignore.
Examples:
spec-kitty doctor state-roots
spec-kitty doctor state-roots --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor tool-surfaces
Usage: spec-kitty doctor tool-surfaces [OPTIONS]
Audit (and optionally repair) every configured tool surface.
Examples:
spec-kitty doctor tool-surfaces --json
spec-kitty doctor tool-surfaces --kind command-skill --json
spec-kitty doctor tool-surfaces --tool codex --fix
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --kind <str> Filter to surface kind(s), e.g. command-skill │
│ --tool <str> Filter to a single configured tool key │
│ --fix Repair missing or stale surfaces │
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor topology
Usage: spec-kitty doctor topology [OPTIONS]
Report each mission's STORED topology across kitty-specs/.
Reads the authoritative ``topology`` value persisted in ``meta.json`` WITHOUT
re-inferring from disk/git. Missions not yet backfilled surface
``topology: null`` — run ``spec-kitty migrate backfill-topology`` to persist
the computed value.
Examples:
spec-kitty doctor topology
spec-kitty doctor topology --json
spec-kitty doctor topology --mission 083-foo
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit structured JSON output (suitable for CI) │
│ --mission <str> Scope report to a single mission slug │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty doctor workspaces
Usage: spec-kitty doctor workspaces [OPTIONS]
Report .worktrees/ husk directories (entries lacking a .git entry).
A husk is not a usable git worktree: git commands run inside it fall
through to the primary repository (#1833). Workspace resolution refuses
husks with a structured error; this check is the recovery path.
Examples:
spec-kitty doctor workspaces
spec-kitty doctor workspaces --fix
spec-kitty doctor workspaces --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --fix Remove husks that are NOT registered in `git worktree │
│ list` (registered worktrees are never removed) │
│ --json Machine-readable JSON output │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty events
Event log tailing commands
Usage: spec-kitty events [OPTIONS] COMMAND [ARGS]...
Event log tailing commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ tail Tail a mission's event log (``status.events.jsonl``) as JSON lines on │
│ stdout. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty events tail
Usage: spec-kitty events tail [OPTIONS]
Tail a mission's event log (``status.events.jsonl``) as JSON lines on stdout.
Ordered dispatch (plan.md's CLI Surface section -- "exactly four things, none
of
them novel domain logic"):
1. FR-004 usage check: ``--from-invariant`` without ``--from-offset``.
2. FR-009 mission resolve.
3. FR-013 resume validation (only when ``--from-offset`` is given).
4. Drive the core.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug/handle whose │
│ status.events.jsonl to tail (no legacy │
│ feature-alias flag, C-003). │
│ [required] │
│ --json JSON output. Currently the only │
│ supported mode (accepted for parity with │
│ the issue's invocation and with `docs │
│ query --json`; no human-readable mode │
│ exists, so this flag has no observable │
│ effect either way). │
│ [default: True] │
│ --once Poll exactly once and exit -- no │
│ generator, no sleep, ever. │
│ --max-events <int> Stop the stream after emitting this many │
│ events/signals. │
│ --from-offset <int> Resume from this byte offset in │
│ status.events.jsonl (FR-004/FR-013). │
│ --from-invariant <str> Content invariant (SHA-256 hex digest) │
│ paired with --from-offset for │
│ cross-restart content verification │
│ (FR-004/FR-013). Requires --from-offset; │
│ supplying this alone is a usage error. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty glossary
Glossary management commands
Usage: spec-kitty glossary [OPTIONS] COMMAND [ARGS]...
Glossary management commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list List all terms in glossary. │
│ conflicts Display conflict history from event log. │
│ resolve Resolve a conflict asynchronously. │
│ show Render the entity page for a glossary term. │
│ validate Validate glossary seed file(s) against the schema. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty glossary conflicts
Usage: spec-kitty glossary conflicts [OPTIONS]
Display conflict history from event log.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Filter conflicts by mission ID │
│ --unresolved Show only unresolved conflicts │
│ --strictness <str> Filter by effective strictness level (off, │
│ medium, max) │
│ --json Output as JSON (machine-parseable) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty glossary list
Usage: spec-kitty glossary list [OPTIONS]
List all terms in glossary.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --scope <str> Filter by scope (mission_local, team_domain, │
│ audience_domain, spec_kitty_core) │
│ --status <str> Filter by status (active, deprecated, draft) │
│ --json Output as JSON (machine-parseable) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty glossary resolve
Usage: spec-kitty glossary resolve [OPTIONS] {conflict_id}
Resolve a conflict asynchronously.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * conflict_id <str> Conflict ID to resolve [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission ID for event log (auto-detected if │
│ omitted) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty glossary show
Usage: spec-kitty glossary show [OPTIONS] {term}
Render the entity page for a glossary term.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * term <str> Term surface name or glossary URN (e.g. │
│ 'deployment-target' or 'glossary:deployment-target') │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty glossary validate
Usage: spec-kitty glossary validate [OPTIONS] {path}
Validate glossary seed file(s) against the schema.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * path <path> Path to a glossary seed file (.yaml) or directory of │
│ seed files │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output validation results as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty implement
Usage: spec-kitty implement [OPTIONS] {wp_id}
Internal — allocate or reuse the lane worktree for a work package.
This command is internal infrastructure, used by ``spec-kitty agent action
implement``
for workspace creation. It is not the canonical user-facing implementation
path for
spec-kitty 3.1.1.
Canonical user workflow::
spec-kitty next --agent <name> --mission <slug> (loop entry)
spec-kitty agent action implement <WP> --agent <name> (per-WP verb)
This command remains available as a compatibility surface for direct callers.
See FR-503 and D-4 in the 3.1.1 spec.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * wp_id <str> Work package ID (for example, WP01) [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug (for │
│ example, │
│ 001-my-feature) │
│ --auto-commit --no-auto-commit Auto-commit status and │
│ planning changes │
│ (default: from project │
│ config) │
│ --json Output in JSON format │
│ --recover Recover from crashed │
│ implementation session │
│ --base <str> Explicit base ref for │
│ the lane workspace │
│ (default: │
│ auto-detect). Use this │
│ when upstream │
│ dependency branches │
│ have been │
│ merged-and-deleted and │
│ you want to start from │
│ the current target │
│ branch tip, e.g. │
│ --base main. │
│ --acknowledge-not-bu… Suppress the bulk-edit │
│ inference warning when │
│ spec language │
│ resembles a bulk edit │
│ but the mission is not │
│ one. │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty init
Usage: spec-kitty init [OPTIONS] [project_name]
Initialize a new Spec Kitty project.
Creates project files only. Does not initialize a git repository.
Does not create any commits.
If PROJECT_NAME is omitted, init runs in the current directory.
Re-running init in an already-initialized directory is idempotent for project
state: it verifies the configured agents' skill surfaces, additively restoring
missing per-agent skill roots (e.g. .claude/skills/) through the canonical
installer, and exits 1 with the recovery command
`spec-kitty agent config sync --create-missing --keep-orphaned` when shared
command skills (codex/vibe/pi/letta) are missing or empty. An existing
per-agent skill file that is empty, a directory, or a symlink exits 1 naming
its path and is preserved untouched — rename or remove it and re-run init.
Note: The --no-git flag from previous versions has been removed.
init never touches git state regardless of flags.
Interactive Mode (default):
- Prompts you to select AI assistants
Non-Interactive Mode:
- Enabled with --non-interactive/--yes, SPEC_KITTY_NON_INTERACTIVE=1, or
non-TTY
- Skips all prompts; --ai is required
- Perfect for CI/CD and automation
What Gets Created:
- .kittify/ - Project scaffold (memory, config)
- Agent command and skill surfaces (.claude/commands/, .agents/skills/, etc.)
- .gitignore and .claudeignore
Specifying AI Assistants (--ai flag):
Use comma-separated agent keys (no spaces). Valid keys include:
codex, claude, gemini, cursor, qwen, opencode, windsurf, kilocode,
auggie, copilot, q, kiro, antigravity, vibe, pi, letta, llxprt.
Template Discovery (Development Mode):
Set SPEC_KITTY_TEMPLATE_ROOT to override bundled templates for local
development.
Examples:
spec-kitty init --ai codex # Current directory (default)
spec-kitty init my-project # Interactive mode
spec-kitty init my-project --ai codex # With Codex
spec-kitty init my-project --ai codex,claude # Multiple agents
spec-kitty init --ai claude --non-interactive # Non-interactive
Canonical Next Steps (after init):
spec-kitty next --agent <agent> --mission <slug> # Enter mission
loop
spec-kitty agent action implement <WP> --agent <name> # Implement a work
package
spec-kitty agent action review <WP> --agent <name> # Review a work
package
Missions:
- Missions are selected per-feature during /spec-kitty.specify
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ project_name <str> Name for your new project directory (omit to │
│ initialize current directory) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --non-interactive,--yes Run without interactive prompts (suitable │
│ for CI/CD) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Selection ──────────────────────────────────────────────────────────────────╮
│ --ai <str> Comma-separated AI assistants (claude,codex,gemini,...) │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty intake
Usage: spec-kitty intake [OPTIONS] [path]
Ingest a plan document as a mission brief for /spec-kitty.specify.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ path <str> Path to plan document, or '-' to read from stdin. Omit │
│ when using --show or --auto. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force Overwrite existing brief. │
│ --show Print current brief and provenance; no writes. │
│ --auto Scan known harness plan locations and ingest │
│ automatically. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty invocations
Query local invocation records.
Usage: spec-kitty invocations [OPTIONS] COMMAND [ARGS]...
Query local invocation records.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list List recent invocation records from the local audit log. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty invocations list
Usage: spec-kitty invocations list [OPTIONS]
List recent invocation records from the local audit log.
# FR-008 / T031: This command does not open an InvocationRecord at baseline.
# If a future version of `invocations list` opens an invocation, it should
use:
# derive_mode("invocations.list") -> ModeOfWork.QUERY
# The mapping is reserved in _ENTRY_COMMAND_MODE (modes.py) for enforcement
# consistency (QUERY mode disallows Tier 2 evidence promotion per FR-009).
# TODO(future): wire derive_mode("invocations.list") when InvocationRecord is
opened here.
Records are returned newest-first, sorted by ``started_at`` from file
content. Use ``--profile`` to narrow to one agent profile. Use
``--json`` for machine-readable output.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --profile -p <str> Filter by profile ID (reads file content, not │
│ filename) │
│ --limit -n <int> Maximum number of records to return (default: 20) │
│ [default: 20] │
│ --json Emit a JSON array instead of a table │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty issue-matrix
Issue-matrix commands (structured issue-matrix.json).
Usage: spec-kitty issue-matrix [OPTIONS] COMMAND [ARGS]...
Issue-matrix commands (structured issue-matrix.json).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ migrate Bulk-migrate legacy ``issue-matrix.md`` missions to │
│ ``issue-matrix.json`` (FR-013). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty issue-matrix migrate
Usage: spec-kitty issue-matrix migrate [OPTIONS]
Bulk-migrate legacy ``issue-matrix.md`` missions to ``issue-matrix.json``
(FR-013).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Scope to a single mission handle. Omit to migrate │
│ all missions. │
│ --json Emit structured JSON output. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty lint
Usage: spec-kitty lint [OPTIONS] [file_path]
Run ruff and mypy on a file and report errors.
This command is designed to be used as a post-edit hook for AI agents,
providing immediate feedback on linting and type-checking violations.
When invoked without a path (the wired hook form), the target file is read
from the harness JSON payload on stdin.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ file_path <path> File to lint/type-check; omit to read the path from │
│ a hook stdin payload │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output in JSON format for AI agents │
│ --fix Attempt to automatically fix lint errors │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty materialize
Usage: spec-kitty materialize [OPTIONS]
Regenerate all derived views from the canonical event log.
For each feature (or a single feature when --mission is given),
writes the following files to ``.kittify/derived/<slug>/``:
- ``status.json`` — full StatusSnapshot
- ``board-summary.json`` — lane counts and WP lists
- ``progress.json`` — lane-weighted progress percentage
- ``lifecycle.json`` — canonical active/recent/stale/abandoned mission state
A coordination-routed Mission is reduced from its coordination surface's
event log. To find that log this command may create the coordination
worktree (one ``git worktree add`` per coordination-routed Mission, done
once) and, for a Mission created before the coordination surface was
seeded, seed it. ``lanes`` and ``single_branch`` Missions are reduced from
the repository root checkout exactly as before. A Mission whose coordination
branch exists only on a remote, or whose logs diverged, is reported in the
error summary and the remaining Missions are still processed.
Examples::
spec-kitty materialize
spec-kitty materialize --mission 034-my-feature
spec-kitty materialize --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug to materialise (all if omitted) │
│ --json Output a machine-readable JSON summary │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate
Migration commands: update .kittify/ layout and backfill identity fields in legacy missions.
Usage: spec-kitty migrate [OPTIONS] COMMAND [ARGS]...
Migration commands: update .kittify/ layout and backfill identity fields in
legacy missions.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run Show what would change without modifying the │
│ filesystem. Before a subcommand, forwarded if the │
│ subcommand declares it, else rejected (exit 2) — place │
│ it after the subcommand when unsure. │
│ --verbose -v Show file-by-file detail. Before a subcommand, │
│ forwarded if the subcommand declares it, else rejected │
│ (exit 2) — place it after the subcommand when unsure. │
│ --force Skip confirmation prompt. Before a subcommand, │
│ forwarded if the subcommand declares it, else rejected │
│ (exit 2) — place it after the subcommand when unsure. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ backfill-identity Write a ULID mission_id into any meta.json that │
│ lacks one. │
│ backfill-merge-commit Record a GitHub PR's real merge commit as a │
│ mission's review baseline (#4231). │
│ backfill-topology Persist each legacy mission's MissionTopology │
│ into its meta.json. │
│ backfill-mission-type Mint a profile-resolving ``mission_type`` into │
│ legacy ``meta.json`` (rc3 M0). │
│ charter-encoding Scan charter content for non-UTF-8 encodings; │
│ normalize-or-fail-loud. │
│ backfill-provenance FR-014: backfill provenance onto legacy │
│ acceptance-matrix.json invariants. │
│ normalize-lifecycle Normalize legacy ``kitty-specs`` missions for the │
│ MVP lifecycle model. │
│ rewrite-opposed-by Rewrite a pack's legacy ``opposed_by`` entries │
│ into DRG edges. │
│ backfill-runtime-state Seed legacy runtime state as events, verify │
│ fail-closed, and flip status_phase. │
│ backfill-wp-status Seed the lane events a Mission's WP files lack, │
│ so the status snapshot counts every WP (#5579). │
│ rebaseline-dossier-hashes One-time re-baseline of recorded dossier snapshot │
│ hashes (FR-009, WP05). │
│ repin-hooks Re-pin this repository's pre-commit hook to the │
│ current interpreter (#254). │
│ ledger Report the migration ledger: which setup steps │
│ have run, and their state. │
│ activation-ledger Move charter activation keys into the activation │
│ ledger, and nothing else. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate ledger
Report the migration ledger: which setup steps have run, and their state.
Usage: spec-kitty migrate ledger [OPTIONS]
Report the migration ledger: which setup steps have run, and their state.
A read-only view of the two-partition migration ledger. It lists every
declared setup step in declared (manifest) order and, for each, shows whether
it is already in place (recorded, effect present here), recorded elsewhere but
not here (a per-clone step the ledger records but whose effect is absent on
this checkout — e.g. a freshly pulled clone), not yet applied, and whether its
source content changed since it ran (drift). Drift is audit-only: reported,
never re-applied. This command never commits and never writes a file.
``--json`` emits the one structured shape the human summary renders from.
Examples:
spec-kitty migrate ledger
spec-kitty migrate ledger --json
╭─ Options ──────────────────────────────────────────────────────────────────╮
│ --json Emit the recorded setup steps and summary as structured │
│ JSON (the same shape the human summary renders). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate activation-ledger
Usage: spec-kitty migrate activation-ledger [OPTIONS]
Move charter activation keys into the activation ledger, and nothing else.
Runs exactly the move of the ``4.0.0rc8_activation_ledger`` upgrade
migration: the ``activated_<kind>``, ``activated_kinds`` and
``mission_type_activations`` keys leave the ``charter.yaml`` that
``.kittify/config.yaml`` points to (or ``config.yaml`` itself, and any
leftover copy there) for ``.kittify/charter/activation.yaml``, verbatim,
and the synthesis manifest is re-stamped. Use it on a project that an
older CLI wrote activation keys into again, without a full upgrade.
* It refuses, writing nothing (exit 1), when the files disagree about a
key, or when a legacy file holds a ``deactivated_<kind>`` key.
* It is idempotent: a re-run reports nothing to do and writes nothing.
* When ``.kittify/migration-ledger.jsonl`` exists it records the
migration as applied (``ledger_record: written``); otherwise it records
nothing (``not_recorded``) and a later upgrade finds nothing to move.
Exit codes: 0 moved or nothing to do, 1 refused (nothing written), 2 usage
error.
Examples:
spec-kitty migrate activation-ledger --dry-run
spec-kitty migrate activation-ledger
spec-kitty migrate activation-ledger --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run List the moves (key, from-file, to-file) and write │
│ nothing. │
│ --json Emit the result, the moves, any refusal and the │
│ migration-ledger record as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
--jsonshape.{"result", "moves", "refusal", "ledger_record"}:resultisnoop,dry_run,movedorrefused; each move is{key, from, to}; a refusal is{key, files, reason}withreasondivergentorlegacy_deny_key(exit 1, nothing written);ledger_recordiswrittenornot_recorded. Field table and examples: Charter CLI Reference.
spec-kitty migrate backfill-identity
Usage: spec-kitty migrate backfill-identity [OPTIONS]
Write a ULID mission_id into any meta.json that lacks one.
This command is **idempotent** — running it twice produces identical
state. Existing ``mission_id`` values are never overwritten. The
command also coerces legacy string-typed ``mission_number`` values
(e.g. ``"042"`` → ``42``) while walking each mission.
After writing, the dossier parity hash is recomputed for every mission
that was modified. Individual dossier failures are logged as warnings
and do not abort the run.
**When to run:**
- After upgrading from a spec-kitty version that predates ``mission_id``
- After pulling a clone that has legacy missions (no ``mission_id``)
- As part of CI checks on legacy repositories
Exit codes:
- ``0`` — all results are ``wrote`` or ``skip``
- ``1`` — one or more ``error`` results (corrupt JSON, sentinel strings, …)
Examples:
spec-kitty migrate backfill-identity --dry-run --json
spec-kitty migrate backfill-identity --mission 083-foo-bar
spec-kitty migrate backfill-identity
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit per-mission result list as structured JSON │
│ --dry-run Report what would change without writing any files. │
│ The JSON shape is identical to a live run. │
│ --mission SLUG Scope to a single mission slug (e.g. 083-foo-bar). │
│ Omit to process all. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate backfill-merge-commit
Usage: spec-kitty migrate backfill-merge-commit [OPTIONS]
Record a GitHub PR's real merge commit as a mission's review baseline (#4231).
A mission accepted through ``acceptance_mode: pr`` never passes through
``spec-kitty consolidate``, so its ``meta.json`` never carried
``baseline_merge_commit`` — leaving ``spec-kitty review --mode post-merge``
unreachable (``MISSION_REVIEW_MODE_MISMATCH``) and the lightweight
dead-code gate failing a cleanly merged mission. This command repairs
that state from REAL evidence: the merge commit you supply is verified
against git (it must resolve in this repository, carry the mission's
``kitty-specs/<slug>/meta.json``, its first parent must not — proving it
is the commit that introduced the mission corpus — and it must have
landed on the target branch, so an unmerged mission-branch commit is
refused) before ``baseline_merge_commit`` (the first parent) and the
provenance pair ``pr_merge_commit`` (the landing commit itself) /
``pr_merge_evidence`` (what the anchor's completeness rests on) are
written through the same canonical seam ``spec-kitty consolidate`` and
``accept --mode pr --merge-commit`` use.
**What the anchor proves depends on the landing shape — and on your
attestation, never on git.** Checks 1–6 prove the commit landed on the
target branch and introduced the mission corpus; they cannot prove its
first parent is the PRE-LANDING TARGET TIP for any shape. A two-parent
merge commit's first parent is the tip only if the merge was performed
on the target branch — an internal merge (the corpus branch merged into
the implementation branch, the target then fast-forwarded to the
result) is graph-identical and its first parent is an implementation
commit. A single-parent landing commit (squash, or a corpus-first stack)
has the tip as its parent only if it was the first commit of the
landing. Both shapes therefore require ``--attest-first-landing-commit``
— your explicit attestation — and record it as the anchor's evidence
class (``pr_merge_evidence: merge-commit-parent-attested`` /
``corpus-parent-attested``), so the anchor's completeness rests on a
recorded operator attestation, never on a claim git did not make.
Anchoring at the wrong tip would silently under-scan the dead-code
gate. Full forge commit-list evidence, which would prove the tip
outright, is tracked in #4277.
**Idempotent**: a mission whose ``meta.json`` already carries a
``baseline_merge_commit`` is skipped and never overwritten.
Exit codes:
- ``0`` — recorded, skipped (already recorded), or ``--dry-run``
- ``1`` — the merge evidence could not be verified, or the mission handle
is unknown
Examples:
spec-kitty migrate backfill-merge-commit --mission 321-mission
--merge-commit <sha> --dry-run
spec-kitty migrate backfill-merge-commit --mission 321-mission
--merge-commit <sha>
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission HANDLE Mission to repair │
│ (mission_id / mid8 / slug). │
│ [required] │
│ * --merge-commit SHA The PR merge commit that │
│ landed the mission on its │
│ target branch. Read it off │
│ the merged PR, then supply │
│ it here; the migration │
│ verifies it against git │
│ before writing anything — it │
│ must carry the mission's │
│ kitty-specs/<slug>/meta.jso… │
│ its first parent must not, │
│ and it must have landed on │
│ the target branch. Every │
│ landing shape additionally │
│ needs │
│ --attest-first-landing-comm… │
│ [required] │
│ --target-branch <str> The branch the PR merged │
│ into (the PR's base branch), │
│ for the landing check. │
│ Defaults to the mission's │
│ declared target_branch, else │
│ the repository's primary │
│ branch. │
│ --attest-first-landing-com… Attest that the supplied │
│ --merge-commit's first │
│ parent is the pre-landing │
│ target tip. Required for │
│ every landing shape: for a │
│ two-parent merge commit, │
│ attest the merge was │
│ performed ON the target │
│ branch (a merge performed on │
│ a mission or sibling branch │
│ and then fast-forwarded onto │
│ the target is │
│ graph-identical, and its │
│ first parent is an │
│ implementation commit, not │
│ the tip); for a │
│ single-parent landing │
│ (squash or corpus-first │
│ stack), attest the supplied │
│ commit was the FIRST commit │
│ of the landing. Git cannot │
│ prove either — and a wrong │
│ anchor silently under-scans │
│ the dead-code gate. The │
│ attestation is recorded in │
│ pr_merge_evidence, never │
│ presented as a git proof. │
│ --dry-run Verify the merge evidence │
│ and report what would be │
│ written without writing any │
│ files. The JSON shape is │
│ identical to a live run. │
│ --json Emit the per-mission │
│ backfill result row as │
│ structured JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate backfill-mission-type
Usage: spec-kitty migrate backfill-mission-type [OPTIONS]
Mint a profile-resolving ``mission_type`` into legacy ``meta.json`` (rc3 M0).
Legacy missions store their type only in the deprecated ``mission`` field.
This command writes a canonical ``mission_type`` for every candidate whose
legacy value resolves a governance profile at *any* layer (built-in / org
/ project) — activation-independent, per the M3 tolerance authority. A
mission that already has a ``mission_type`` key is always skipped and
left byte-for-byte unchanged.
This command is **idempotent** — running it twice reports ``wrote=0`` on
the second pass.
A candidate whose legacy value resolves **no** governance profile is
never written; it is reported ``needs_manual_resolution`` instead. This
does **not** by itself fail the command — see the exit codes below — but
a distinct, actionable diagnostic is printed naming the affected
mission(s): the fix is to assign a valid mission type whose governance
profile resolves at some layer, or to author/activate that type. It is
not necessarily a typo.
Exit codes:
- ``0`` — ``--dry-run`` (always, regardless of findings), or a live run
with zero ``error`` results (``needs_manual_resolution`` alone does not
fail the command)
- ``1`` — a live run with one or more ``error`` results (corrupt /
unreadable ``meta.json``), or ``--mission`` naming a slug that has no
matching directory under ``kitty-specs/``
Examples:
spec-kitty migrate backfill-mission-type --dry-run --json
spec-kitty migrate backfill-mission-type --mission 083-foo-bar
spec-kitty migrate backfill-mission-type
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit the per-mission backfill result list as │
│ structured JSON. │
│ --dry-run Report what would change without writing any files. │
│ The JSON shape is identical to a live run. │
│ --mission SLUG Scope to a single mission slug (e.g. 083-foo). Omit │
│ to process all missions. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate backfill-provenance
Usage: spec-kitty migrate backfill-provenance [OPTIONS]
FR-014: backfill provenance onto legacy acceptance-matrix.json invariants.
Walks every ``kitty-specs/*/acceptance-matrix.json`` and, for each negative
invariant whose ``result`` is not ``pending`` and lacks ``provenance_origin``,
stamps the ``legacy_unrecorded`` sentinel (data-model.md NI-1 / contract
``negative-invariant-provenance.md`` C1). ``verified_ref`` and
``verified_surface_kind`` are left null for those rows — the sentinel means
the surface a pre-schema judgement was established against is genuinely
unknowable, not empty by omission.
This migration is **idempotent** (NI-2 / C3): re-running it on an
already-migrated corpus is a no-op — a row already carrying
``provenance_origin`` (``recorded`` or ``legacy_unrecorded``) is never
re-stamped.
The whole-corpus write is enrolled in a commit-or-revert transaction: on
any failure partway through, every file already written in that run is
restored to its pre-migration bytes — no partial migration state is left
on disk.
AM-4: this migration never auto-archives. A matrix it cannot parse is
reported as an error and skipped; it never routes into an archive
operation.
Exit codes:
- ``0`` — every matrix migrated cleanly (or needed no change)
- ``1`` — one or more matrices could not be parsed (see the reported errors)
Examples:
spec-kitty migrate backfill-provenance --dry-run
spec-kitty migrate backfill-provenance --json
spec-kitty migrate backfill-provenance
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run Report what would be stamped without writing │
│ any files. The JSON shape is identical to a │
│ live run. │
│ --json Emit a JSON-stable summary report on stdout. │
│ --project-root DIR Root of the Spec Kitty project (default: │
│ current working directory). │
│ [default: .] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate backfill-runtime-state
Usage: spec-kitty migrate backfill-runtime-state [OPTIONS]
Seed legacy runtime state as events, verify fail-closed, and flip
status_phase.
Drives the shared
:func:`~specify_cli.migration.runtime_state_cutover.cutover_mission`
helper over the corpus (or a single ``--mission``). For every mission it seeds
the frontmatter/checkbox runtime state into the event log, verifies the
reduced
snapshot equals the OLD reader by **count + value**, and flips ``meta.json``
``status_phase`` to snapshot-authority **only** for missions that verify.
Per-mission best-effort (research D-03): a mission whose verify fails is left
un-flipped (``status_phase`` untouched) and named in the summary; other
missions
still flip. Use ``--dry-run`` to preview would-seed and would-flip counts
without writing. The summary's ``Flipped`` counter names the missions this
run actually flipped — a mission with event-log evidence but no legacy
frontmatter state to seed still flips and is counted there, never as
"Skipped (already migrated)" (#3212).
Exit codes:
- ``0`` — every visited mission flipped or is already migrated (verify ok, no
error)
- ``1`` — one or more missions failed verify / errored, or ``--mission`` named
an
unknown handle
Examples:
spec-kitty migrate backfill-runtime-state --dry-run
spec-kitty migrate backfill-runtime-state --mission my-mission-01ABCD
spec-kitty migrate backfill-runtime-state --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run Seed nothing and flip nothing; report per-mission │
│ would-seed counts and would-flip. │
│ --mission HANDLE Scope to a single mission (mission_id / mid8 / │
│ slug). Omit to process the whole corpus. │
│ --json Emit the per-mission cutover result list as │
│ structured JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate backfill-topology
Usage: spec-kitty migrate backfill-topology [OPTIONS]
Persist each legacy mission's MissionTopology into its meta.json.
Computes every mission's topology (the coordination × lanes grid cell) from
its current on-disk signals via the single WP01 classifier and writes it to
``meta.json`` as the authoritative ``topology`` value. This command is
**idempotent** — a mission that already has a valid ``topology`` is skipped
and its value is never overwritten.
Exit codes:
- ``0`` — all results are ``wrote`` or ``skip``
- ``1`` — one or more ``error`` results (corrupt / unreadable meta.json)
Examples:
spec-kitty migrate backfill-topology --dry-run --json
spec-kitty migrate backfill-topology --mission 083-foo-bar
spec-kitty migrate backfill-topology
spec-kitty migrate backfill-topology --restamp-single-branch --dry-run
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit per-mission result list as │
│ structured JSON │
│ --dry-run Report what would change without │
│ writing any files. The JSON shape is │
│ identical to a live run. │
│ --mission SLUG Scope to a single mission slug (e.g. │
│ 083-foo-bar). Omit to process all. │
│ --restamp-single-branch Re-stamp every single_branch mission │
│ whose lanes.json has a code lane to │
│ topology: lanes (Invariant T-1 │
│ repair, #5100). Mutually exclusive │
│ with the ordinary backfill this │
│ command otherwise runs; combine with │
│ --dry-run to preview. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate backfill-wp-status
Usage: spec-kitty migrate backfill-wp-status [OPTIONS]
Seed the lane events a Mission's WP files lack, so the status snapshot counts
every WP (#5579).
The reduced status snapshot omits any WP with no lane event, so a Mission
whose event log never seeded some ``tasks/WP*.md`` file under-counts on
every read surface that lists WPs from the files. This command appends one
deterministic ``planned`` seed per missing WP (actor
``migration:backfill_wp_status``)
through the existing migration writer, on the Mission's resolved
PRIMARY-partition status surface. It is idempotent: a re-run appends
nothing. WPs the snapshot carries without a WP file are reported, never
repaired. A Mission whose status log lives on a live coordination surface
is refused (``COORD_SURFACE_LIVE``, counted as refused rather than skipped,
nothing written):
consolidate it first and rerun once the coordination branch is gone.
A Mission with terminal evidence (``meta.json`` ``merged_at`` /
``accepted_at``, or an entry in ``--evidence-manifest``) has its freshly
seeded WPs driven on to ``done`` with a forced, evidence-citing event, so
its progress reads 100%. Nothing else counts as evidence.
The evidence manifest must be complete on the first live run. Terminal
evidence applies only to WPs seeded in that same run: a WP an earlier run
already seeded ``planned`` is no longer a gap, so evidence supplied later
is a silent no-op (the summary warns for every manifest entry that had
nothing to seed). Run ``--dry-run`` with the full manifest first.
The manifest is YAML, keyed by exact ``kitty-specs/`` directory name:
missions:
my-mission-01ABCDEF:
reason: "PR #1234 merged 2026-09-01; dossier landed on main"
A missing/empty reason or a slug that does not resolve is refused up front
(exit 1, nothing written).
Exit codes:
- ``0`` — every visited Mission was repaired, needed nothing, or was refused
as ``COORD_SURFACE_LIVE``
- ``1`` — a per-Mission error, an invalid evidence manifest, or (with
``--json``) an unknown or ambiguous ``--mission`` handle
- ``2`` — an unknown or ambiguous ``--mission`` handle (human output)
Examples:
spec-kitty migrate backfill-wp-status --dry-run
spec-kitty migrate backfill-wp-status --mission my-mission-01ABCDEF --json
spec-kitty migrate backfill-wp-status --evidence-manifest evidence.yaml
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run Report per-Mission would-seed plans; │
│ write nothing. │
│ --mission HANDLE Scope to a single mission (mission_id / │
│ mid8 / slug). Omit to process the whole │
│ corpus. │
│ --evidence-manifest FILE YAML file marking Missions finished: │
│ missions: {<slug>: {reason: <text>}}. │
│ Applies only to WPs seeded in the same │
│ run, so it must be complete on the │
│ first live run. │
│ --json Emit the per-Mission repair result and │
│ summary as structured JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate charter-encoding
Usage: spec-kitty migrate charter-encoding [OPTIONS]
Scan charter content for non-UTF-8 encodings; normalize-or-fail-loud.
Walks every existing mission's charter content
(``kitty-specs/*/charter/*.{yaml,md,txt}``) and the global charter store
(``.kittify/charter/*.{yaml,md,txt}``), detects the encoding of each file
via the WP06 chokepoint, and either:
\b
* **skips** the file (already pure UTF-8; idempotency pre-check passes)
* **normalizes** the file to UTF-8 in-place with a provenance record
* **surfaces** the file as ambiguous (exits non-zero; manual repair required)
This migration is **idempotent** (NFR-006): running it twice on an
already-normalized corpus is a near-instant no-op — no new provenance
records are written for already-UTF-8 files.
Implements FR-026, FR-027, NFR-006.
Exit codes:
- ``0`` — corpus is fully UTF-8 compliant (all files already-UTF-8 or
successfully normalized)
- ``1`` — one or more files are ambiguous (manual repair required)
Examples:
spec-kitty migrate charter-encoding --dry-run
spec-kitty migrate charter-encoding --yes --json
spec-kitty migrate charter-encoding
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run Show what would change without writing any │
│ files. Returns exit 0 unless ambiguous files │
│ are found. │
│ --yes -y Apply normalizations without prompting. Exits │
│ non-zero if any file is ambiguous (CI-safe). │
│ Do NOT pass --yes to silently bypass ambiguous │
│ files — manual repair is required for those. │
│ --json Emit a JSON-stable summary report on stdout. │
│ --project-root DIR Root of the Spec Kitty project (default: │
│ current working directory). │
│ [default: .] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate normalize-lifecycle
Usage: spec-kitty migrate normalize-lifecycle [OPTIONS]
Normalize legacy ``kitty-specs`` missions for the MVP lifecycle model.
This command repairs enough historical mission state to make the canonical
lifecycle model reliable across old repositories. It backfills identity
where needed, rebuilds missing event logs from legacy state, and regenerates
status/progress/lifecycle projections used by the CLI and Teamspace.
Exit codes:
- ``0`` — all targeted missions normalized or skipped cleanly
- ``1`` — one or more missions hit an unrecoverable error
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit a structured per-mission normalization report │
│ --dry-run Preview lifecycle normalization without modifying │
│ the filesystem │
│ --mission SLUG Scope to a single mission slug (e.g. 083-foo-bar). │
│ Omit to process all. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate rebaseline-dossier-hashes
Usage: spec-kitty migrate rebaseline-dossier-hashes [OPTIONS]
One-time re-baseline of recorded dossier snapshot hashes (FR-009, WP05).
Recomputes every recorded ``.kittify/dossiers/<slug>/snapshot-latest.json``
hash under the canonical definition (WP01/WP02) so content that did not
change is not flagged divergent after the cutover. Idempotent (snapshots
already in canonical ``sha256:`` form are skipped) and read-only over source
artifacts — only the recorded snapshot cache files are written (#2263).
Exit codes:
- ``0`` — completed (some snapshots may be reported as errors and skipped)
- ``1`` — project root could not be located
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit a structured per-mission re-baseline report │
│ --dry-run Preview which recorded snapshot hashes would be │
│ re-baselined, without writing │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate repin-hooks
Usage: spec-kitty migrate repin-hooks [OPTIONS]
Re-pin this repository's pre-commit hook to the current interpreter (#254).
``policy/hook_installer.py`` pins the absolute Python interpreter path
into the pre-commit hook at install time. An install-method migration
(e.g. pipx -> uv) moves that interpreter, and the OLD hook keeps pointing
at a path that no longer exists. This command re-runs the same install
the ``implement`` lane calls internally, but without requiring a mission
or workspace — the repair does not depend on the very thing it is
repairing (the ability to commit).
Idempotent: safe to re-run; a hook already pinned to the current
interpreter is re-written to the same effective hook (only the
``# Installed:`` timestamp comment differs).
Exit codes:
- ``0`` — the hook was (re-)installed
- ``1`` — project root could not be located, or the current
``sys.executable`` does not refer to an existing file
Examples:
spec-kitty migrate repin-hooks
spec-kitty migrate repin-hooks --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Emit a JSON-stable summary report on stdout. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty migrate rewrite-opposed-by
Usage: spec-kitty migrate rewrite-opposed-by [OPTIONS]
Rewrite a pack's legacy ``opposed_by`` entries into DRG edges.
Scans every ``*.directive.yaml``/``*.tactic.yaml``/``*.paradigm.yaml``
file under ``--pack`` for ``opposed_by`` entries, classifies each as
tension-style (rewritten to an ``in_tension_with`` edge) or
anti-pattern-rejection-style (rewritten to a ``rejects`` edge, creating
the target ``anti_pattern`` node if absent), writes the new edges into
the pack's ``<kind>.graph.yaml`` fragments, and removes the migrated
``opposed_by`` key from the source YAML.
This command is **idempotent** — once a pack has no remaining
``opposed_by`` entries, running it again is a no-op.
**When to run:**
- Before upgrading to a spec-kitty release that drops ``opposed_by``
from the ``directive``/``tactic``/``paradigm`` schemas
- As part of CI checks on an org pack that still authors ``opposed_by``
Exit codes:
- ``0`` — every entry was rewritten (or, in ``--dry-run``, would be)
- ``1`` — one or more entries could not be unambiguously classified
Examples:
spec-kitty migrate rewrite-opposed-by --pack ./org-packs/acme --dry-run
spec-kitty migrate rewrite-opposed-by --pack ./org-packs/acme --json
spec-kitty migrate rewrite-opposed-by --pack ./org-packs/acme
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --pack PATH Root directory of the target pack to migrate (org │
│ pack or any directory shaped like the built-in │
│ charter pack tree). │
│ [default: .] │
│ --dry-run Report planned rewrites without writing any files. │
│ The JSON shape is identical to a live run. │
│ --json Emit a structured JSON report on stdout. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission
Inspect mission types for this project.
Usage: spec-kitty mission [OPTIONS] COMMAND [ARGS]...
Inspect mission types for this project.
Use 'list' to see activated types (charter-filtered) and 'show <id>' for a
full resolved definition.
Mission types are selected per mission run during /spec-kitty.specify.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ current Show currently active mission for a mission │
│ (auto-detects mission from cwd). │
│ info Show details for a specific mission without │
│ switching. │
│ run Start (or attach to) a runtime for a │
│ project-authored custom mission definition. │
│ close Close a mission. Wraps FR-016 lifecycle teardown. │
│ reopen Re-open a merged/closed mission, returning it to │
│ an actionable state (FR-002). │
│ follow-up Record a follow-up commit or PR against a mission │
│ (FR-001). │
│ switch [REMOVED] Switch active mission - this command was (deprecated) │
│ removed in v0.8.0. │
│ list List activated mission types for the current │
│ project (FR-016). │
│ show Show the fully resolved MissionType definition for │
│ this project (FR-017). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission close
Usage: spec-kitty mission close [OPTIONS]
Close a mission. Wraps FR-016 lifecycle teardown.
Without ``--discard``: fail-closed precondition (FR-004/FR-005, #4765) —
refuses (non-zero exit, no writes) unless the mission has a recorded merge
baseline (``is_mission_merged``). An all-terminal-but-unmerged mission
(e.g. every work package cancelled) still refuses here; use ``--discard``
to abandon it. Once merged: runs the merge-completion teardown — persists
the mission retrospective to its durable home and tears down the
coordination worktree. Idempotent after a successful ``spec-kitty
consolidate``
(which already ran the same teardown); useful when the teardown was
skipped (e.g. the legacy plain-git/GitHub merge path) or interrupted.
NOTE: on a merged mission without a retrospective, this generates one
(``kitty-specs/<slug>/retrospective.yaml``) plus a ``RetrospectiveCaptured``
event and commits both — it is not a pure no-op in that case. Tolerates a
mission left with an orphaned ``coordination_branch`` marker (FR-013,
#2745) — no traceback, the mission slug is rendered once.
With ``--discard``: abandon the mission mid-flight. Deletes the
coordination branch and every lane branch named in
``lanes.json``, then tears down the coordination worktree and the
operator-visible lane worktrees. Requires confirmation unless
``--force`` is also passed. The coordination + lane branches are
deleted with ``git branch -D`` (force-delete) because mid-flight
abandonment by definition leaves uncommitted or unmerged work.
A deleted Mission branch whose commits exist on no other branch keeps its
tip under ``refs/spec-kitty/discarded/<branch>``; remove it with
``git update-ref -d refs/spec-kitty/discarded/<branch>`` once it is no
longer needed.
Implements FR-016 from
``kitty-specs/mission-coordination-branch-atomic-event-log-01KSPTVW``.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug (auto-detected from cwd if omitted) │
│ --discard Discard the mission mid-flight: delete the │
│ coordination branch + all lane branches and tear │
│ down all worktrees. Without --discard, requires │
│ that the mission has already been merged (no-op │
│ cleanup otherwise). │
│ --force Skip the confirmation prompt when --discard is │
│ set. │
│ --json Emit a JSON envelope instead of a rich panel. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission current
Usage: spec-kitty mission current [OPTIONS]
Show currently active mission for a mission (auto-detects mission from cwd).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission follow-up
Usage: spec-kitty mission follow-up [OPTIONS] {handle}
Record a follow-up commit or PR against a mission (FR-001).
Exactly one of ``--commit <40-hex>`` / ``--pr <int>`` must be supplied.
Appends a ``FollowUpRecorded`` lifecycle event attributed to ``mission_id``.
Fail-closed (#1926): only valid once the mission has reached completion
(merged, or all WPs terminal) — a follow-up against a not-yet-completed
mission exits non-zero with a structured error and writes no event.
Idempotent on its dedup key ``(mission_id, commit_sha | pr_number)`` —
re-recording the same reference is a successful no-op.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * handle <str> Mission handle: mission_id (ULID), mid8, or slug. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --commit <str> 40-hex commit SHA of the follow-up. │
│ --pr <int> Pull-request number of the follow-up. │
│ --json Emit a JSON envelope instead of a rich panel. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission info
Usage: spec-kitty mission info [OPTIONS] {mission_name}
Show details for a specific mission without switching.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_name <str> Mission name to display details for [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission list
Usage: spec-kitty mission list [OPTIONS]
List activated mission types for the current project (FR-016).
Alias for ``spec-kitty charter mission-type list``.
Returns only mission types that are explicitly activated in this
project's charter (activation-filtered). For all doctrine-layer
types regardless of activation, use ``spec-kitty charter mission-type list
--include-inactive``.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission reopen
Usage: spec-kitty mission reopen [OPTIONS] {handle}
Re-open a merged/closed mission, returning it to an actionable state (FR-002).
Appends a ``MissionReopened`` lifecycle event (the authority for
actionability — ``derive_mission_lifecycle`` reports the ``reopened``
surface_state) and clears the ``merged_*`` markers from ``meta.json``. Does
NOT mutate WP lanes — the operator repositions WPs explicitly afterwards.
Fail-closed (NFR-004): the mission is unrecoverable when ``meta.json`` is
absent/corrupt OR the mission branch resolves in neither the local repo nor
any configured remote. A missing worktree directory alone is recoverable. On
unrecoverable input the command exits non-zero with a remediation hint and
writes no event / no metadata change.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * handle <str> Mission handle: mission_id (ULID), mid8, or slug. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --reason <str> Why the mission is being re-opened (required, │
│ audited). │
│ [required] │
│ --json Emit a JSON envelope instead of a rich panel. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission run
Usage: spec-kitty mission run [OPTIONS] {mission_key}
Start (or attach to) a runtime for a project-authored custom mission
definition.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_key <str> The reusable custom mission key. [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Tracked mission slug. [required] │
│ --json --no-json Emit JSON envelope to stdout instead │
│ of a rich panel. │
│ [default: no-json] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission show
Usage: spec-kitty mission show [OPTIONS] {mission_type_id}
Show the fully resolved MissionType definition for this project (FR-017).
Displays all fields of the activated mission type:
id, display_name, action_sequence, template_set,
source_layer, extends.
Exits with code 1 and lists registered IDs when ``mission_type_id``
is not an activated type.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_type_id <str> Mission type ID (e.g. software-dev). │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission switch
Deprecated: this command is deprecated
Usage: spec-kitty mission switch [OPTIONS] {mission_name}
(deprecated)
[REMOVED] Switch active mission - this command was removed in v0.8.0.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_name <str> Mission name (no longer supported) [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force (ignored) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type
Inspect mission types for this project.
Usage: spec-kitty mission-type [OPTIONS] COMMAND [ARGS]...
Inspect mission types for this project.
Use 'list' to see activated types (charter-filtered) and 'show <id>' for a
full resolved definition.
Mission types are selected per mission run during /spec-kitty.specify.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ current Show currently active mission for a mission │
│ (auto-detects mission from cwd). │
│ info Show details for a specific mission without │
│ switching. │
│ run Start (or attach to) a runtime for a │
│ project-authored custom mission definition. │
│ close Close a mission. Wraps FR-016 lifecycle teardown. │
│ reopen Re-open a merged/closed mission, returning it to │
│ an actionable state (FR-002). │
│ follow-up Record a follow-up commit or PR against a mission │
│ (FR-001). │
│ switch [REMOVED] Switch active mission - this command was (deprecated) │
│ removed in v0.8.0. │
│ list List activated mission types for the current │
│ project (FR-016). │
│ show Show the fully resolved MissionType definition for │
│ this project (FR-017). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type close
Usage: spec-kitty mission-type close [OPTIONS]
Close a mission. Wraps FR-016 lifecycle teardown.
Without ``--discard``: fail-closed precondition (FR-004/FR-005, #4765) —
refuses (non-zero exit, no writes) unless the mission has a recorded merge
baseline (``is_mission_merged``). An all-terminal-but-unmerged mission
(e.g. every work package cancelled) still refuses here; use ``--discard``
to abandon it. Once merged: runs the merge-completion teardown — persists
the mission retrospective to its durable home and tears down the
coordination worktree. Idempotent after a successful ``spec-kitty
consolidate``
(which already ran the same teardown); useful when the teardown was
skipped (e.g. the legacy plain-git/GitHub merge path) or interrupted.
NOTE: on a merged mission without a retrospective, this generates one
(``kitty-specs/<slug>/retrospective.yaml``) plus a ``RetrospectiveCaptured``
event and commits both — it is not a pure no-op in that case. Tolerates a
mission left with an orphaned ``coordination_branch`` marker (FR-013,
#2745) — no traceback, the mission slug is rendered once.
With ``--discard``: abandon the mission mid-flight. Deletes the
coordination branch and every lane branch named in
``lanes.json``, then tears down the coordination worktree and the
operator-visible lane worktrees. Requires confirmation unless
``--force`` is also passed. The coordination + lane branches are
deleted with ``git branch -D`` (force-delete) because mid-flight
abandonment by definition leaves uncommitted or unmerged work.
A deleted Mission branch whose commits exist on no other branch keeps its
tip under ``refs/spec-kitty/discarded/<branch>``; remove it with
``git update-ref -d refs/spec-kitty/discarded/<branch>`` once it is no
longer needed.
Implements FR-016 from
``kitty-specs/mission-coordination-branch-atomic-event-log-01KSPTVW``.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug (auto-detected from cwd if omitted) │
│ --discard Discard the mission mid-flight: delete the │
│ coordination branch + all lane branches and tear │
│ down all worktrees. Without --discard, requires │
│ that the mission has already been merged (no-op │
│ cleanup otherwise). │
│ --force Skip the confirmation prompt when --discard is │
│ set. │
│ --json Emit a JSON envelope instead of a rich panel. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type current
Usage: spec-kitty mission-type current [OPTIONS]
Show currently active mission for a mission (auto-detects mission from cwd).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type follow-up
Usage: spec-kitty mission-type follow-up [OPTIONS] {handle}
Record a follow-up commit or PR against a mission (FR-001).
Exactly one of ``--commit <40-hex>`` / ``--pr <int>`` must be supplied.
Appends a ``FollowUpRecorded`` lifecycle event attributed to ``mission_id``.
Fail-closed (#1926): only valid once the mission has reached completion
(merged, or all WPs terminal) — a follow-up against a not-yet-completed
mission exits non-zero with a structured error and writes no event.
Idempotent on its dedup key ``(mission_id, commit_sha | pr_number)`` —
re-recording the same reference is a successful no-op.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * handle <str> Mission handle: mission_id (ULID), mid8, or slug. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --commit <str> 40-hex commit SHA of the follow-up. │
│ --pr <int> Pull-request number of the follow-up. │
│ --json Emit a JSON envelope instead of a rich panel. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type info
Usage: spec-kitty mission-type info [OPTIONS] {mission_name}
Show details for a specific mission without switching.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_name <str> Mission name to display details for [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type list
Usage: spec-kitty mission-type list [OPTIONS]
List activated mission types for the current project (FR-016).
Alias for ``spec-kitty charter mission-type list``.
Returns only mission types that are explicitly activated in this
project's charter (activation-filtered). For all doctrine-layer
types regardless of activation, use ``spec-kitty charter mission-type list
--include-inactive``.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type reopen
Usage: spec-kitty mission-type reopen [OPTIONS] {handle}
Re-open a merged/closed mission, returning it to an actionable state (FR-002).
Appends a ``MissionReopened`` lifecycle event (the authority for
actionability — ``derive_mission_lifecycle`` reports the ``reopened``
surface_state) and clears the ``merged_*`` markers from ``meta.json``. Does
NOT mutate WP lanes — the operator repositions WPs explicitly afterwards.
Fail-closed (NFR-004): the mission is unrecoverable when ``meta.json`` is
absent/corrupt OR the mission branch resolves in neither the local repo nor
any configured remote. A missing worktree directory alone is recoverable. On
unrecoverable input the command exits non-zero with a remediation hint and
writes no event / no metadata change.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * handle <str> Mission handle: mission_id (ULID), mid8, or slug. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --reason <str> Why the mission is being re-opened (required, │
│ audited). │
│ [required] │
│ --json Emit a JSON envelope instead of a rich panel. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type run
Usage: spec-kitty mission-type run [OPTIONS] {mission_key}
Start (or attach to) a runtime for a project-authored custom mission
definition.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_key <str> The reusable custom mission key. [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Tracked mission slug. [required] │
│ --json --no-json Emit JSON envelope to stdout instead │
│ of a rich panel. │
│ [default: no-json] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type show
Usage: spec-kitty mission-type show [OPTIONS] {mission_type_id}
Show the fully resolved MissionType definition for this project (FR-017).
Displays all fields of the activated mission type:
id, display_name, action_sequence, template_set,
source_layer, extends.
Exits with code 1 and lists registered IDs when ``mission_type_id``
is not an activated type.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_type_id <str> Mission type ID (e.g. software-dev). │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output as JSON. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty mission-type switch
Deprecated: this command is deprecated
Usage: spec-kitty mission-type switch [OPTIONS] {mission_name}
(deprecated)
[REMOVED] Switch active mission - this command was removed in v0.8.0.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission_name <str> Mission name (no longer supported) [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force (ignored) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty next
Usage: spec-kitty next [OPTIONS]
Decide and emit the next agent action for the current mission.
Agents call this command repeatedly in a loop. The system inspects the
mission state machine, evaluates guards, and returns a deterministic
decision with an action and prompt file.
Examples:
spec-kitty next --mission 034-my-feature --json
# query mode
spec-kitty next --agent claude --mission 034-my-feature --result success
--json
spec-kitty next --agent codex --mission 034-my-feature
spec-kitty next --agent gemini --mission 034-my-feature --result failed
--json
spec-kitty next --agent claude --mission 034-my-feature --answer "yes"
--result success --json
spec-kitty next --agent claude --mission 034-my-feature --answer "approve"
--decision-id "input:review" --result success --json
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --agent <str> Agent name (required for advancing mode) │
│ --result <str> Result of previous step: │
│ success|failed|blocked. If omitted, │
│ returns current state without advancing │
│ (query mode). │
│ --mission <str> Mission slug │
│ --json Output JSON decision only │
│ --answer <str> Answer to a pending decision │
│ --decision-id <str> Decision ID (required if multiple pending) │
│ --owned-checkout <path> Run against an owned checkout: a linked │
│ checkout that owns this mission. Refuses │
│ the repository root checkout, lane │
│ worktrees and coordination worktrees. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty ops
Operation history (git reflog)
Usage: spec-kitty ops [OPTIONS] COMMAND [ARGS]...
Operation history (git reflog)
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ log Show operation history. │
│ undo Undo is not supported for git. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty ops log
Usage: spec-kitty ops log [OPTIONS]
Show operation history.
Shows the git reflog (read-only history).
Examples:
# Show recent operations
spec-kitty ops log
# Show last 5 operations
spec-kitty ops log --limit 5
# Show with full details
spec-kitty ops log --verbose
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit -n <int> Number of operations to show [default: 20] │
│ --verbose -v Show full operation IDs and details │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty ops undo
Usage: spec-kitty ops undo [OPTIONS]
Undo is not supported for git.
Git does not have reversible operation history.
Consider using these alternatives manually:
- git reset --soft HEAD~1 (undo last commit, keep changes)
- git reset --hard HEAD~1 (undo last commit, discard changes)
- git revert <commit> (create reverting commit)
- git reflog (find previous states)
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api
Machine-contract API for external orchestrators (JSON-first)
Usage: spec-kitty orchestrator-api [OPTIONS] COMMAND [ARGS]...
Machine-contract API for external orchestrators (JSON-first)
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ contract-version Return the current API contract version. │
│ mission-state Return the full state of a mission (all WPs, lanes, │
│ dependencies). │
│ list-ready List WPs that are ready to start (planned and all deps │
│ approved or done). │
│ resolve-workspace Read-only: resolve a WP's lane workspace_path + │
│ prompt_path (+ lane fields). │
│ start-implementation Composite transition: planned->claimed->in_progress │
│ (idempotent). │
│ start-review Transition a WP from for_review to in_review (reviewer │
│ claims review). │
│ transition Emit a single lane transition for a WP. │
│ append-history Append a history entry via an ``InnerStateChanged`` │
│ ``note`` annotation. │
│ accept-mission Accept a mission after all WPs are approved or done. │
│ consolidate-mission Consolidate a lane-based mission into target. │
│ specify Create a mission scaffold, matching the host CLI's │
│ enriched ``specify --json`` contract. │
│ plan Scaffold plan.md for a mission -- an unenriched │
│ pass-through of ``setup_plan``. │
│ tasks Finalize WP task metadata -- an unenriched │
│ pass-through of ``finalize_tasks``. │
│ check-prerequisites Read-only mission-prerequisite context for │
│ ``/spec-kitty.analyze`` (FR-004). │
│ record-analysis Persist an ``/spec-kitty.analyze`` report, verified │
│ against disk (FR-005). │
│ open-decision Open a new Decision Moment ledger entry, or return │
│ idempotently if one │
│ already exists (FR-006). Wraps │
│ ``decisions/service.py.open_decision`` 1:1. │
│ resolve-decision Resolve a decision with a concrete final answer │
│ (FR-007). Wraps │
│ ``decisions/service.py.resolve_decision`` 1:1. │
│ defer-decision Defer a decision for later resolution (FR-008). Wraps │
│ ``decisions/service.py.defer_decision`` 1:1. │
│ cancel-decision Cancel a decision (deemed no longer relevant) │
│ (FR-009). Wraps │
│ ``decisions/service.py.cancel_decision`` 1:1. │
│ answer-decision Resolve a ``spec-kitty next`` ``decision_required`` │
│ moment (FR-013, │
│ Mechanism B) with full CLI event/lifecycle-log parity │
│ (FR-014, operator │
│ ruling SPEC-FRESH2-001). See the module comment block │
│ above this │
│ function for the full five-step composite and the │
│ response-shape │
│ contract. │
│ design-status Read-only design-phase status query (FR-010) -- │
│ mirrors ``list-ready``'s │
│ no-state-transition, no-event-emission, │
│ no-``--policy`` contract for the │
│ design pipeline instead of the WP loop. │
│ artifact-read Read bounded canonical content and its exact revision │
│ (absent is explicit). │
│ artifact-submit Submit design content through host placement, │
│ validators and commit authority. │
│ design-validate Check current canonical prerequisites without │
│ completing a lifecycle step. │
│ design-context Read bounded resolved templates, governance and │
│ required interview slots. │
│ interview-record Record incremental interview answers through the │
│ existing decision service. │
│ next Query or advance exactly the same authority and │
│ lifecycle as native next. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api accept-mission
Usage: spec-kitty orchestrator-api accept-mission [OPTIONS]
Accept a mission after all WPs are approved or done.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --actor <str> Actor identity [required] │
│ --origin-check <function> Refuse (enforce, the default) or only │
│ warn (warn) when the mission's status │
│ evidence or approved lanes are behind │
│ or unreachable on their remote; off │
│ contacts nothing and accepts stale │
│ evidence. Overrides │
│ SPEC_KITTY_ORIGIN_CHECK. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api answer-decision
Usage: spec-kitty orchestrator-api answer-decision [OPTIONS]
Resolve a ``spec-kitty next`` ``decision_required`` moment (FR-013, Mechanism
B) with full CLI event/lifecycle-log parity (FR-014, operator ruling
SPEC-FRESH2-001). See the module comment block above this function for the
full five-step composite and the response-shape contract.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --agent <str> Agent/actor identity performing this call │
│ (required) │
│ [required] │
│ * --answer <str> The answer value to persist for the pending │
│ decision │
│ [required] │
│ --result <str> Outcome of the current issuance: success | │
│ failed | blocked (required alongside │
│ --answer) │
│ --decision-id <str> Run-snapshot pending decision id to answer │
│ (auto-resolved when omitted and exactly one │
│ decision is pending) │
│ --policy <str> Policy metadata JSON (required) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api append-history
Usage: spec-kitty orchestrator-api append-history [OPTIONS]
Append a history entry via an ``InnerStateChanged`` ``note`` annotation.
WP08 / FR-007 / T031: this cross-package (ACL-boundary) writer no longer
mutates the WP prompt file's ``## Activity Log`` section directly -- it
emits a ``note``-append delta through WP01's ``emit_inner_state_changed``.
The write target is the coord-aware STATUS-partition mission directory
(:func:`_resolve_mission_dir_or_fail` -- the SAME seam every other STATUS
read/write in this module uses, e.g. ``accept_mission``'s
``materialize(mission_dir)``), never a ``Path.cwd()``-derived join
(C-003 / #2647 -- see the SC-008 test).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --wp <str> Work package ID [required] │
│ * --actor <str> Actor identity [required] │
│ * --note <str> History note to append [required] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api artifact-read
Usage: spec-kitty orchestrator-api artifact-read [OPTIONS]
Read bounded canonical content and its exact revision (absent is explicit).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --kind <str> Registered authoring artifact kind │
│ [required] │
│ --artifact-id <str> Declared package key or contract basename │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api artifact-submit
Usage: spec-kitty orchestrator-api artifact-submit [OPTIONS]
Submit design content through host placement, validators and commit authority.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --request-json <str> Closed bounded artifact batch JSON; '-' │
│ reads UTF-8 stdin │
│ [required] │
│ * --actor <str> Accountable author [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api cancel-decision
Usage: spec-kitty orchestrator-api cancel-decision [OPTIONS]
Cancel a decision (deemed no longer relevant) (FR-009). Wraps
``decisions/service.py.cancel_decision`` 1:1.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --decision-id <str> Decision ledger entry ID (ULID) │
│ [required] │
│ * --rationale <str> Explanation of why (required) [required] │
│ --resolved-by <str> Identity of the │
│ resolving/deferring/canceling party │
│ (falls back to --actor) │
│ * --actor <str> Actor identity [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --owned-checkout <str> Path to a linked owned checkout that │
│ owns this mission (single_branch only); │
│ omit for the repository-root checkout │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api check-prerequisites
Usage: spec-kitty orchestrator-api check-prerequisites [OPTIONS]
Read-only mission-prerequisite context for ``/spec-kitty.analyze`` (FR-004).
C-002: this verb supplies context ONLY -- it never performs `analyze`'s
cross-artifact reasoning itself (mirrors ``start-review``'s "cannot
perform WP implementation itself" pattern). No ``--policy`` is required
(read-only, per spec Edge Cases: "Read-only verbs (check-prerequisites,
design-status) do not require --policy").
In-process only (FR-001-style parity): calls the host CLI's OWN
``check_prerequisites`` Typer command function
(``mission_check_prerequisites.py:498``) directly -- the exact
established pattern WP03's ``plan``/``tasks`` verbs already use for a
registered ``agent mission`` Typer command (``setup_plan``/
``finalize_tasks`` are registered identically:
``app.command(...)(func)`` in ``mission.py``), so field-parity with
``agent mission check-prerequisites --json --include-tasks`` is
guaranteed by construction rather than by re-deriving
``validate_feature_structure``'s shaping logic a second time.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --include-tasks Include tasks.md validation (matches the │
│ host CLI's own --include-tasks default) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api consolidate-mission
Usage: spec-kitty orchestrator-api consolidate-mission [OPTIONS]
Consolidate a lane-based mission into target.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --target <str> Target branch to merge into │
│ (auto-detected from meta.json) │
│ --strategy <str> Merge strategy: merge, squash, or │
│ rebase │
│ [default: merge] │
│ --push Push target branch after merge │
│ --origin-check <function> Refuse (enforce, the default) or only │
│ warn (warn) when the mission's status │
│ evidence or approved lanes are behind │
│ or unreachable on their remote; off │
│ contacts nothing and accepts stale │
│ evidence. Overrides │
│ SPEC_KITTY_ORIGIN_CHECK. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api contract-version
Usage: spec-kitty orchestrator-api contract-version [OPTIONS]
Return the current API contract version.
Pass --provider-version to check compatibility before running state-mutating
commands.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --provider-version <str> Caller's provider version; returns │
│ CONTRACT_VERSION_MISMATCH if below │
│ minimum │
│ --require-capability <str> Require a supported Python command │
│ before performing work │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api defer-decision
Usage: spec-kitty orchestrator-api defer-decision [OPTIONS]
Defer a decision for later resolution (FR-008). Wraps
``decisions/service.py.defer_decision`` 1:1.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --decision-id <str> Decision ledger entry ID (ULID) │
│ [required] │
│ * --rationale <str> Explanation of why (required) [required] │
│ --resolved-by <str> Identity of the │
│ resolving/deferring/canceling party │
│ (falls back to --actor) │
│ * --actor <str> Actor identity [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --owned-checkout <str> Path to a linked owned checkout that │
│ owns this mission (single_branch only); │
│ omit for the repository-root checkout │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api design-context
Usage: spec-kitty orchestrator-api design-context [OPTIONS]
Read bounded resolved templates, governance and required interview slots.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission handle; omitted before creation │
│ --stage <str> specify | plan | tasks [default: specify] │
│ --mission-type <str> Activated mission type before creation │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api design-status
Usage: spec-kitty orchestrator-api design-status [OPTIONS]
Read-only design-phase status query (FR-010) -- mirrors ``list-ready``'s
no-state-transition, no-event-emission, no-``--policy`` contract for the
design pipeline instead of the WP loop.
Never delegates to ``resolve_next_workflow_action`` or
``decide_next``/``query_current_state`` -- see the Clarification-6
module comment above ``_tasks_are_finalized``.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api design-validate
Usage: spec-kitty orchestrator-api design-validate [OPTIONS]
Check current canonical prerequisites without completing a lifecycle step.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --stage <str> specify | plan | tasks [required] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api interview-record
Usage: spec-kitty orchestrator-api interview-record [OPTIONS]
Record incremental interview answers through the existing decision service.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission handle [required] │
│ * --stage <str> specify | plan [required] │
│ * --answers <str> JSON mapping of canonical question IDs to │
│ nonempty answers │
│ [required] │
│ * --actor <str> Actor identity [required] │
│ --policy <str> Required orchestrator policy JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api list-ready
Usage: spec-kitty orchestrator-api list-ready [OPTIONS]
List WPs that are ready to start (planned and all deps approved or done).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api mission-state
Usage: spec-kitty orchestrator-api mission-state [OPTIONS]
Return the full state of a mission (all WPs, lanes, dependencies).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api next
Usage: spec-kitty orchestrator-api next [OPTIONS]
Query or advance exactly the same authority and lifecycle as native next.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission handle [required] │
│ --agent <str> Agent required for advancement │
│ --result <str> Prior result; omit for read-only query │
│ --answer <str> Native pending decision answer │
│ --decision-id <str> Native decision identity │
│ --policy <str> Policy JSON required for advancement │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api open-decision
Usage: spec-kitty orchestrator-api open-decision [OPTIONS]
Open a new Decision Moment ledger entry, or return idempotently if one already
exists (FR-006). Wraps ``decisions/service.py.open_decision`` 1:1.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --origin <str> Origin flow: charter | specify | plan │
│ [required] │
│ * --input-key <str> The input key this decision governs │
│ [required] │
│ * --question <str> Human-readable question text [required] │
│ --step-id <str> Interview step identifier │
│ --slot-key <str> Slot key (use when step_id unavailable) │
│ --options <str> Candidate answers as a JSON array string │
│ * --actor <str> Actor identity [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --owned-checkout <str> Path to a linked owned checkout that │
│ owns this mission (single_branch only); │
│ omit for the repository-root checkout │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api plan
Usage: spec-kitty orchestrator-api plan [OPTIONS]
Scaffold plan.md for a mission -- an unenriched pass-through of
``setup_plan``.
FR-002 / Clarification 1: deliberately asymmetric with ``specify`` -- the
host CLI's own ``--json`` path returns ``agent_feature.setup_plan``'s raw
dict verbatim (``lifecycle.py`` adds no enrichment here), so this verb
does the same. Do not add fields ``setup_plan`` does not already return.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api record-analysis
Usage: spec-kitty orchestrator-api record-analysis [OPTIONS]
Persist an ``/spec-kitty.analyze`` report, verified against disk (FR-005).
NFR-004 / SK-93 (verified): a subprocess/call-level success signal
(return code, "did not raise") is UNTRUSTWORTHY -- SK-93 documented
``record-analysis`` reporting a false timeout FAILURE after a write had
already genuinely succeeded. This verb instead:
1. Captures ``now_utc_iso()`` immediately before invoking the write path.
2. Calls ``write_analysis_report``/``commit_for_mission`` directly
(bypassing ``record_analysis``'s own unbounded dossier-sync trigger
entirely -- option (a), plan.md § (j)), under an enforced
:func:`_run_write_with_timeout` bound as defense-in-depth.
3. Re-reads ``analysis-report.md`` off disk unconditionally afterward.
``success: true`` ONLY if BOTH (a) the re-read ``verdict`` matches
what THIS call submitted, AND (b) the re-read ``generated_at`` is
STRICTLY LATER than the call-start timestamp -- a verdict-string
match alone is never sufficient (distinguishes a genuine fresh write
from a stale, coincidentally-matching pre-existing artifact).
SK-06 / #3133: an ``unknown`` verdict (no valid ``analysis-findings/v1``
carrier in the submitted body) is NEVER reported as ``success: true``,
even when the write genuinely, freshly succeeds -- silently writing
``verdict: unknown`` for an explicitly-intended report is this repo's
dominant failure mode and this verb refuses to propagate it as success.
A mutating verb: ``--policy`` is required (``POLICY_METADATA_REQUIRED``
pattern, matching ``specify``/``plan``/``tasks``).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --input-file <str> Markdown report path, or '-' to read the │
│ report body from stdin │
│ [default: -] │
│ --agent <str> Agent name that produced the analysis report │
│ --policy <str> Policy metadata JSON (required) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api resolve-decision
Usage: spec-kitty orchestrator-api resolve-decision [OPTIONS]
Resolve a decision with a concrete final answer (FR-007). Wraps
``decisions/service.py.resolve_decision`` 1:1.
Terminal-transition rejection (Edge Cases, spec.md): resolving an
already-terminal decision with a DIFFERENT outcome/payload is NOT
pre-checked here -- it is the service layer's own
``DecisionError(TERMINAL_CONFLICT)``, propagated verbatim, matching the
host-CLI ``decision_app resolve`` subcommand's own error code. A
redundant pre-check here could drift from the service layer's own
validation.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --decision-id <str> Decision ledger entry ID (ULID) │
│ [required] │
│ * --final-answer <str> The chosen answer (non-empty) [required] │
│ --other-answer True if answer is a write-in │
│ --rationale <str> Explanation of the choice │
│ --resolved-by <str> Identity of the │
│ resolving/deferring/canceling party │
│ (falls back to --actor) │
│ * --actor <str> Actor identity [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --owned-checkout <str> Path to a linked owned checkout that │
│ owns this mission (single_branch only); │
│ omit for the repository-root checkout │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api resolve-workspace
Usage: spec-kitty orchestrator-api resolve-workspace [OPTIONS]
Read-only: resolve a WP's lane workspace_path + prompt_path (+ lane fields).
Does NOT allocate/create/validate-clean/transition — the read-only companion
of ``start-implementation`` for a WP already past implementation (e.g. a
``for_review`` WP an external orchestrator wants to review on resume, where
calling start-implementation would wrongly re-transition it). Contract >=
1.2.0.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --wp <str> Work package ID [required] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api specify
Usage: spec-kitty orchestrator-api specify [OPTIONS]
Create a mission scaffold, matching the host CLI's enriched ``specify --json``
contract.
In-process only (FR-001): calls
``specify_cli.cli.commands.lifecycle._create_mission_for_specify_json``,
the SAME enrichment step the host CLI's ``--json`` path runs (adds
``scaffold_only``/``spec_state``/``next_action``/``next_step`` on top of
``agent_feature.create_mission``'s raw payload) -- never the unenriched
payload one layer beneath it.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --mission-type <str> Mission type (e.g., │
│ software-dev) │
│ [required] │
│ --topology <single_branch|lanes|co Create-time mission │
│ ord|lanes_with_coord> shape: single_branch | │
│ lanes | coord | │
│ lanes_with_coord. │
│ Default: context-derived │
│ (matches the host CLI's │
│ own --topology default). │
│ --policy <str> Policy metadata JSON │
│ (required) │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api start-implementation
Usage: spec-kitty orchestrator-api start-implementation [OPTIONS]
Composite transition: planned->claimed->in_progress (idempotent).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --wp <str> Work package ID [required] │
│ * --actor <str> Actor identity [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api start-review
Usage: spec-kitty orchestrator-api start-review [OPTIONS]
Transition a WP from for_review to in_review (reviewer claims review).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --wp <str> Work package ID [required] │
│ * --actor <str> Actor identity [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --review-ref <str> Review feedback reference (optional, not │
│ required for for_review→in_review) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api tasks
Usage: spec-kitty orchestrator-api tasks [OPTIONS]
Finalize WP task metadata -- an unenriched pass-through of ``finalize_tasks``.
FR-003 / Clarification 1: same deliberate asymmetry as ``plan`` -- the
host CLI's own ``--json`` path returns ``agent_feature.finalize_tasks``'s
raw dict verbatim, so this verb does the same.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ --policy <str> Policy metadata JSON (required) │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty orchestrator-api transition
Usage: spec-kitty orchestrator-api transition [OPTIONS]
Emit a single lane transition for a WP.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug [required] │
│ * --wp <str> Work package ID [required] │
│ * --to <str> Target lane [required] │
│ * --actor <str> Actor identity [required] │
│ --note <str> Reason/note for the │
│ transition (required with │
│ --force out of in_review or │
│ approved) │
│ --policy <str> Policy metadata JSON │
│ (required for run-affecting │
│ lanes) │
│ --force Force the transition │
│ --review-ref <str> Review reference │
│ --review-result-json <str> JSON structured review │
│ outcome for transitions from │
│ in_review │
│ --evidence-json <str> JSON string with done │
│ evidence │
│ --subtasks-complete Whether required subtasks are │
│ complete for │
│ in_progress->for_review │
│ --implementation-evidence-… Whether implementation │
│ evidence exists for │
│ in_progress->for_review │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty plan
Usage: spec-kitty plan [OPTIONS]
Scaffold plan.md for a Mission.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug (e.g., │
│ 001-user-authentication) │
│ --json Emit JSON result │
│ --owned-checkout <path> Run against an owned checkout: a linked │
│ checkout that owns this mission. Refuses │
│ the repository root checkout, lane │
│ worktrees and coordination worktrees. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty plugin
Plugin bundle commands
Usage: spec-kitty plugin [OPTIONS] COMMAND [ARGS]...
Plugin bundle commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ build Build a Spec Kitty plugin bundle for a specific target harness. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty plugin build
Usage: spec-kitty plugin build [OPTIONS]
Build a Spec Kitty plugin bundle for a specific target harness.
The bundle is written to ``<output-dir>/<target>/`` and includes a
``plugin.json`` manifest, rendered command skills, and agent profiles.
Example::
spec-kitty plugin build --target claude-code
spec-kitty plugin build --target claude-code --output-dir /tmp/out
spec-kitty plugin build --target claude-code --skip-validate
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --target <str> Plugin target (claude-code, codex). │
│ [required] │
│ --output-dir <path> Root directory under which the bundle is │
│ written. │
│ [default: dist/spec-kitty-plugins] │
│ --skip-validate Skip the 'claude plugin validate │
│ --strict' step. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty profile-invocation
Manage invocation records.
Usage: spec-kitty profile-invocation [OPTIONS] COMMAND [ARGS]...
Manage invocation records.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ complete Close an open invocation record. --invocation-id and --outcome are │
│ required. │
╰──────────────────────────────────────────────────────────────────────────────╯
Open: spec-kitty dispatch "<request>"
Close: spec-kitty profile-invocation complete --invocation-id <id> --outcome
<outcome>
spec-kitty profile-invocation complete
Usage: spec-kitty profile-invocation complete [OPTIONS]
Close an open invocation record. --invocation-id and --outcome are required.
Use --artifact (repeatable) to link output artifacts to this invocation.
Use --commit (singular) to link the primary git commit produced.
Use --evidence to promote a file to a Tier 2 evidence artifact.
Note: --evidence is rejected for records that are not execution records.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --invocation-id -i <str> Invocation ULID to close [required] │
│ * --outcome <str> done | failed | abandoned [required] │
│ --evidence <str> Path to a UTF-8 text evidence file (Tier │
│ 2 promotion); checked before the Op │
│ closes │
│ --artifact <str> Path (repo-relative or absolute) or URL │
│ of an artifact produced by this │
│ invocation. Repeatable. │
│ --commit <str> Git commit SHA most directly produced by │
│ this invocation. Singular. │
│ --json Output JSON payload │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty profiles
Manage and list agent profiles.
Usage: spec-kitty profiles [OPTIONS] COMMAND [ARGS]...
Manage and list agent profiles.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list List agent profiles (activated-only by default; --all for the full │
│ catalog). │
│ show Show the full resolved definition of an agent profile │
│ (FR-013/014/015). │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty profiles list
Usage: spec-kitty profiles list [OPTIONS]
List agent profiles (activated-only by default; --all for the full catalog).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output JSON array. │
│ --all Show every profile across all source layers │
│ (annotated by source layer and │
│ activated|available state). Supersedes the │
│ activated-only default and --show-available. │
│ --show-available Also show available-but-not-activated profiles │
│ (annotated by state). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty profiles show
Usage: spec-kitty profiles show [OPTIONS] {profile_id}
Show the full resolved definition of an agent profile (FR-013/014/015).
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * profile_id <str> Profile ID to show. [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Output JSON object. │
│ --all Bypass the activation gate for inspection (show │
│ non-activated profiles). │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty reconcile
Reconcile a mission dossier against its recorded snapshot (exit 0=parity, non-zero=divergence).
Usage: spec-kitty reconcile [OPTIONS]
Reconcile a mission dossier against its recorded snapshot (exit 0=parity,
non-zero=divergence).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission slug to reconcile against its recorded │
│ snapshot │
│ [required] │
│ --json Emit a machine-readable JSON result │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty regen
Regenerate the committed generated agent-command + skill fixtures from source (#3447).
Usage: spec-kitty regen [OPTIONS]
Regenerate the committed generated agent-command + skill fixtures from source
(#3447).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --check Do not write; render into memory and byte-compare against │
│ the committed fixtures. Exit 1 when stale (prints the │
│ diff + the exact regen command), 0 when fresh. This is │
│ the fork-PR-safe freshness gate — a read-only token │
│ cannot commit back, so contributors run `spec-kitty │
│ regen` locally and push the result. │
│ --json Emit a machine-readable JSON result instead of text. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty research
Usage: spec-kitty research [OPTIONS]
Scaffold research artifacts from the mission type's shipped templates.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug to target │
│ --force Overwrite existing research artifacts │
│ --owned-checkout <path> Run against an owned checkout: a linked │
│ checkout that owns this mission. Refuses │
│ the repository root checkout, lane │
│ worktrees and coordination worktrees. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty retrospect
Retrospective authoring and summary (create / backfill / summary)
Usage: spec-kitty retrospect [OPTIONS] COMMAND [ARGS]...
Retrospective authoring and summary (create / backfill / summary)
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ create Author a retrospective for one completed mission. │
│ backfill Author retrospective records for historical missions in bulk. │
│ summary Cross-mission retrospective summary. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty retrospect backfill
Author retrospective records for historical missions in bulk.
Usage: spec-kitty retrospect backfill [OPTIONS]
Author retrospective records for historical missions in bulk.
Iterates completed missions in the given time window and authors
retrospective.yaml records for those that don't already have one.
Per-mission failures are NOT fatal; aggregate report shows them.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --since <str> Only consider missions completed on or after │
│ this ISO date (default: 30 days ago) │
│ --until <str> Only consider missions completed on or │
│ before this ISO date (default: now) │
│ --mission <str> Restrict backfill to a single mission handle │
│ --dry-run Report what would be authored without │
│ writing │
│ --emit-skipped Append a RetrospectiveSkipped event for │
│ skipped missions │
│ --emit-failures Append RetrospectiveCaptureFailed events for │
│ failed missions │
│ --json Emit a single aggregate JSON object at the │
│ end │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty retrospect create
Author a retrospective for one completed mission.
Usage: spec-kitty retrospect create [OPTIONS]
Author a retrospective for one completed mission.
Validates mission completion, resolves policy, runs the generator,
and writes the record. Use --overwrite or --update to handle existing records.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --mission <str> Mission handle (mission_id, mid8, or │
│ mission_slug) │
│ [required] │
│ --overwrite Replace an existing record (mutually │
│ exclusive with --update) │
│ --update Merge into an existing record (mutually │
│ exclusive with --overwrite) │
│ --json Emit structured JSON output instead of Rich │
│ rendering │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty retrospect summary
Cross-mission retrospective summary.
Usage: spec-kitty retrospect summary [OPTIONS]
Cross-mission retrospective summary.
Reads kitty-specs/*/retrospective.yaml and kitty-specs/*/status.events.jsonl
to produce a cross-mission view.
Distinguishes four record states: has_findings / ran_no_findings / missing /
failed.
No mutation is performed.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project <path> Project root (default: │
│ current working │
│ directory) │
│ --json Emit JSON to stdout │
│ instead of Rich │
│ rendering │
│ --json-out <path> Also write JSON to this │
│ file path │
│ --limit <int range> Top-N for ranked │
│ [1<=x<=100] sections (default: 20) │
│ [default: 20] │
│ --since <str> ISO-8601 date; only │
│ include missions │
│ started on or after │
│ DATE │
│ --include-malformed Include malformed │
│ record detail in output │
│ --filter <str> Only show missions in │
│ this record state │
│ (has_findings|ran_no_f… │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty review
Usage: spec-kitty review [OPTIONS]
Validate a merged mission: WP lane check, dead-code scan, BLE001 audit.
Writes kitty-specs/<slug>/mission-review-report.md with a machine-readable
verdict. See module docstring for known false-positive scenarios in the
dead-code scan step.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission handle (id, mid8, or slug). │
│ --mode <str> Review mode: 'lightweight' (consistency check │
│ only) or 'post-merge' (full release-gate │
│ contract). Auto-detected from │
│ meta.json.baseline_merge_commit when omitted. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty safe-commit
Usage: spec-kitty safe-commit [OPTIONS] {files}...
Commit only the requested files via Spec Kitty's safe-commit path.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * files <path> Files or directories to commit, relative to the │
│ current worktree root or absolute. Directory │
│ arguments expand to their contained │
│ changed/untracked files with an explicit expansion │
│ report. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --message -m <str> Commit message. Repeat -m to add paragraphs │
│ (joined by a blank line, the same way git │
│ does). │
│ [required] │
│ --to-branch <str> Short branch name the commit must land on. │
│ The helper asserts HEAD matches this branch │
│ before staging. When omitted, the current │
│ HEAD branch is used (deprecated; --to-branch │
│ becomes required in v3.3). This is the only │
│ destination authority — no env-var inference. │
│ --json Output JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty session-start
Emit spec-kitty orientation for the Claude Code SessionStart hook.
Usage: spec-kitty session-start [OPTIONS]
Emit spec-kitty orientation for the Claude Code SessionStart hook.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty session-stop
Emit the open-Ops reminder for the Claude Code Stop hook.
Usage: spec-kitty session-stop [OPTIONS]
Emit the open-Ops reminder for the Claude Code Stop hook.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty spec-commit
Usage: spec-kitty spec-commit [OPTIONS] {files}...
Commit spec artifacts to the mission's resolved placement.
SPEC is a primary/planning artifact: it lands on the mission's primary target
branch for every topology. On an unprotected or flattened primary the commit
is direct. On a PROTECTED primary the commit is refused (there is no fallback
surface); recover by either creating/checking out a non-protected feature
branch ('spec-kitty agent mission create --start-branch <topic-branch>') or
setting SPEC_KITTY_ALLOW_PROTECTED_BRANCH_COMMITS=1 to commit on the current
branch.
Pass individual FILES, not directories.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * files <path> Spec artifacts to commit (absolute or relative │
│ paths). Must belong to the mission resolved via │
│ --mission or the kitty-specs/<slug>/ path. │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --message -m <str> Commit message. Repeat -m to add │
│ paragraphs (joined by a blank line, the │
│ same way git does). │
│ [required] │
│ --mission <str> Mission slug (e.g. '001-my-mission'). │
│ When omitted, the slug is derived from │
│ the first file argument's │
│ kitty-specs/<slug>/ path. │
│ --target-branch <str> Short TARGET branch name for this │
│ Mission (not the repository-root │
│ checkout). Passed to the commit router │
│ for placement resolution and, on an │
│ --owned-checkout run, as the owned │
│ checkout's target override. No longer │
│ used for a post-commit fast-forward -- │
│ that best-effort advance was retired │
│ (FR-008). Optional. │
│ --json Output JSON. │
│ --owned-checkout <path> Run against an owned checkout: a linked │
│ checkout that owns this mission. │
│ Refuses the repository root checkout, │
│ lane worktrees and coordination │
│ worktrees. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty specify
Usage: spec-kitty specify [OPTIONS] {mission}
Create a feature scaffold in kitty-specs/.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * mission <str> Mission name or slug (e.g., user-authentication) │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission-type <str> Mission type (e.g., │
│ software-dev, research) │
│ --topology <single_branch|lanes|coo Create-time mission shape: │
│ rd|lanes_with_coord> single_branch | lanes | │
│ coord | lanes_with_coord. │
│ Coordination-bearing │
│ shapes (coord, │
│ lanes_with_coord) mint a │
│ coordination branch; │
│ branch-flat shapes │
│ (single_branch, lanes) do │
│ not. Default: │
│ context-derived (#2581, │
│ #2602) — coord on the │
│ primary branch or with │
│ --pr-bound when │
│ coordination is reachable; │
│ lanes otherwise. │
│ single_branch only when │
│ requested explicitly (or │
│ via --owned-checkout). │
│ --json Emit JSON result │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tasks
Usage: spec-kitty tasks [OPTIONS]
Finalize tasks metadata after task generation.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug (e.g., 001-user-authentication) │
│ --json Emit JSON result │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker
Task tracker commands
Usage: spec-kitty tracker [OPTIONS] COMMAND [ARGS]...
Task tracker commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ providers List supported tracker providers. │
│ bind Bind the current project to a local issue tracker (beads, fp). │
│ status Show tracker binding and sync status. │
│ unbind Remove tracker binding for this project. │
│ map Work-package mapping commands │
│ sync Tracker synchronization commands │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker bind
Usage: spec-kitty tracker bind [OPTIONS]
Bind the current project to a local issue tracker (beads, fp).
Requires --provider and --workspace; --credential supplies connector
credentials stored locally.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --provider <str> Provider name (beads, fp) [required] │
│ --workspace <str> Provider workspace/team/project │
│ identifier │
│ --ownership-mode <str> Ownership mode: external_authoritative | │
│ spec_kitty_authoritative | │
│ split_ownership │
│ --field-owner <str> Split ownership mapping: field=owner │
│ --credential <str> Provider credential key/value: key=value │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker map
Work-package mapping commands
Usage: spec-kitty tracker map [OPTIONS] COMMAND [ARGS]...
Work-package mapping commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ add Add or update a WP-to-external issue mapping. │
│ list List tracker mappings from the local SQLite database. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker map add
Usage: spec-kitty tracker map add [OPTIONS]
Add or update a WP-to-external issue mapping.
Stores the mapping in the local SQLite database.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --wp-id <str> Work package ID (e.g., WP01) [required] │
│ * --external-id <str> External issue ID [required] │
│ --external-key <str> External issue key │
│ --external-url <str> External issue URL │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker map list
Usage: spec-kitty tracker map list [OPTIONS]
List tracker mappings from the local SQLite database.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Render mappings as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker providers
Usage: spec-kitty tracker providers [OPTIONS]
List supported tracker providers.
Local providers use direct connectors with locally stored credentials. The
former SaaS/hosted providers (linear, jira, github, gitlab) are no longer
supported (#6164) and are listed only to explain the refusal a bind for one
of them produces.
This command is purely informational and prints the hard-coded provider
categories.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Render provider list as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker status
Usage: spec-kitty tracker status [OPTIONS]
Show tracker binding and sync status.
Displays local cache statistics and configuration for the bound local
provider.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Render status as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker sync
Tracker synchronization commands
Usage: spec-kitty tracker sync [OPTIONS] COMMAND [ARGS]...
Tracker synchronization commands
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ pull Pull tracker updates into the local cache via the direct connector. │
│ push Push local mutations to the upstream provider via the direct │
│ connector. │
│ run Run pull+push synchronization in one operation via the direct │
│ connector. │
│ publish Publish local tracker snapshot. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker sync publish
Usage: spec-kitty tracker sync publish [OPTIONS]
Publish local tracker snapshot.
Local providers (beads/fp) have no snapshot-publish transport; the facade
raises a clean error directing the operator to ``tracker sync push``.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json Render publish result as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker sync pull
Usage: spec-kitty tracker sync pull [OPTIONS]
Pull tracker updates into the local cache via the direct connector.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit <int range> [1<=x<=10000] [default: 100] │
│ --json Render sync result as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker sync push
Usage: spec-kitty tracker sync push [OPTIONS]
Push local mutations to the upstream provider via the direct connector.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit <int range> [1<=x<=10000] Max items [default: 100] │
│ --json Render sync result as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker sync run
Usage: spec-kitty tracker sync run [OPTIONS]
Run pull+push synchronization in one operation via the direct connector.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --limit <int range> [1<=x<=10000] [default: 100] │
│ --json Render sync result as JSON │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty tracker unbind
Usage: spec-kitty tracker unbind [OPTIONS]
Remove tracker binding for this project.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty upgrade
Usage: spec-kitty upgrade [OPTIONS]
Upgrade a Spec Kitty project to the current version.
Detects the project's current version and applies all necessary migrations
to bring it to the installed CLI version.
**New flags (WP09)**:
``--cli`` Emit CLI upgrade guidance only. No project detection;
succeeds outside any project (FR-014).
``--project`` Run project migrations only; suppresses CLI nag.
Errors outside a project.
``--yes``/``-y`` Non-interactive confirmation (alias for ``--force``).
Does NOT bypass schema-incompatibility blocks
(CHK037/A-006).
``--no-nag`` Suppress upgrade-nag banner even when a CLI update exists.
Mutual exclusion: ``--cli`` and ``--project`` together exit 2.
**Exit codes** (R-08):
0 Success / ALLOW / ALLOW_WITH_NAG / a completed ``--dry-run`` preview
2 ``--cli --project`` flag conflict
4 Project migration required (BLOCK_PROJECT_MIGRATION)
5 Project is too new for this CLI (BLOCK_CLI_UPGRADE) — not bypassable
6 Project metadata corrupt (BLOCK_PROJECT_CORRUPT)
1 General error, a managed file left for your review, or a ``--dry-run``
preview that could not be completed
See also: ``docs/guides/how-to/installation/install-and-upgrade.md``
Examples:
spec-kitty upgrade # Upgrade to current version
spec-kitty upgrade --dry-run # Preview changes
spec-kitty upgrade --target 0.6.5 # Upgrade to specific version
spec-kitty upgrade --cli # Show CLI upgrade hint, no project needed
spec-kitty upgrade --project # Project migrations only
spec-kitty upgrade --yes # Non-interactive (same as --force)
spec-kitty upgrade --dry-run --json # Machine-readable plan
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dry-run Preview changes without applying │
│ --force Skip confirmation prompts │
│ --target <str> Target version (defaults to current CLI │
│ version) │
│ --json Output results as JSON │
│ --plan-json Output the complete preview plan as JSON │
│ --verbose -v Show detailed migration information │
│ --no-worktrees Skip upgrading worktrees │
│ --cli Restrict to CLI guidance only; works outside │
│ any project (FR-014) │
│ --project Restrict to current-project compat + │
│ migrations (FR-015) │
│ --yes -y Non-interactive confirmation; alias for │
│ --force (FR-017). Upgrade never runs the │
│ mission-state repair; use `spec-kitty doctor │
│ mission-state --fix`. │
│ --no-nag Suppress upgrade-nag output explicitly │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty validate-encoding
Usage: spec-kitty validate-encoding [OPTIONS]
Validate and optionally fix file encoding in feature artifacts.
Scans markdown files for Windows-1252 smart quotes and other problematic
characters that cause UTF-8 encoding errors. Can automatically fix issues
by replacing problematic characters with safe alternatives.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug to validate │
│ --fix Automatically fix encoding errors by │
│ sanitizing files │
│ --all Check all features, not just one │
│ --backup --no-backup Create .bak files before fixing │
│ [default: backup] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty validate-tasks
Usage: spec-kitty validate-tasks [OPTIONS]
LEGACY: Validate and repair directory/frontmatter lane mismatches.
This command is for legacy projects that used directory-based lanes
(tasks/planned/, tasks/doing/, etc.). Modern projects (3.0+) use
flat tasks/ directories with canonical status in status.events.jsonl.
For modern projects, use `spec-kitty agent mission finalize-tasks`
to ensure canonical status state exists.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug to validate │
│ --fix Automatically repair metadata inconsistencies │
│ --all Check all features, not just one │
│ --agent <str> Agent name for activity log │
│ --shell-pid <str> Shell PID for activity log │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty verify-setup
Usage: spec-kitty verify-setup [OPTIONS]
Verify that the current environment matches Spec Kitty expectations.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mission <str> Mission slug to verify │
│ --json Output in JSON format for AI agents │
│ --check-files Check mission file integrity [default: True] │
│ --check-tools Check for installed development tools │
│ [default: True] │
│ --diagnostics Show detailed project diagnostics │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty workflow
Manage mission workflow definitions
Usage: spec-kitty workflow [OPTIONS] COMMAND [ARGS]...
Manage mission workflow definitions
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ list List workflow ids available to a project. │
│ export Export a resolvable workflow YAML file. │
│ import Import a workflow YAML into `.kittify/overrides/workflows`. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty workflow export
Usage: spec-kitty workflow export [OPTIONS] {workflow_id} {output}
Export a resolvable workflow YAML file.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * workflow_id <str> Workflow id to export. [required] │
│ * output <path> Destination file or directory. [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project-root <path> Project root used for .kittify workflow │
│ discovery. │
│ [default: .] │
│ --force Overwrite an existing destination file. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty workflow import
Usage: spec-kitty workflow import [OPTIONS] {source}
Import a workflow YAML into `.kittify/overrides/workflows`.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * source <path> Workflow YAML file to import. [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project-root <path> Project root that receives the workflow │
│ override. │
│ [default: .] │
│ --force Overwrite an existing workflow file. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
spec-kitty workflow list
Usage: spec-kitty workflow list [OPTIONS]
List workflow ids available to a project.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project-root <path> Project root used for .kittify workflow │
│ discovery. │
│ [default: .] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯