Profile Invocation Reference
Profile invocation is the local audit-trail mechanism used by standalone
spec-kitty dispatch calls. Each dispatch loads Charter context, opens an Op,
and writes an append-only JSONL record. For an explanation of the model, see
Understanding Governed Profile Invocation.
spec-kitty next is the canonical mission loop. In the current 3.2.x CLI it
issues governed prompt files and separate mission-step lifecycle records; it
does not open these standalone Op JSONL files directly.
spec-kitty dispatch
Synopsis: spec-kitty dispatch [OPTIONS] REQUEST
Description: Dispatch a natural-language request to a governed Op. The
router picks the best profile by default. Pass --profile only when the caller
has a specific profile in mind or needs to bypass routing.
| Argument/Flag | Description |
|---|---|
REQUEST | Natural-language request [required] |
--profile TEXT | Optional profile ID; bypasses routing |
--json | Output JSON payload |
--dry-run | Route the request only; no Op is opened and nothing is written |
--owned-checkout PATH | Keep the Op record in this owned checkout (a linked checkout of the repository) instead of the checkout the command runs in. The repository root checkout is refused. |
Example:
uv run spec-kitty dispatch "Review this implementation approach" --jsonuv run spec-kitty dispatch "Implement token validation" --profile implementer-ivan --jsonHow routing picks a profile
dispatch stops at the first signal that matches. --profile <id>, when given,
bypasses the router entirely. Otherwise a canonical verb in the request (review,
implement, plan, …) selects every profile with that role; failing that, a
profile’s declared domain keywords are consulted.
Documentation-artifact nouns — adr, docs, documentation, docstring,
readme, changelog, guide, handbook, tutorial — belong to the
documentation domain, so a docs-maintenance request routes without --profile.
Bare index is deliberately not a documentation signal: “index the invoice
table” is a database request, not a docs request.
A declared keyword or canonical verb containing a space or hyphen
(knowledge base, transcribe-notes) matches its own words as a phrase. That
phrase pass, and the documentation vocabulary above, run only when no literal
single-word keyword matched, so adding that vocabulary can never move a request
that already routed.
When routing refuses
Two refusals are possible, and both exit 1:
ROUTER_NO_MATCH— nothing matched.candidateslists up to three profiles sharing at least one word with the request, ordered by overlap, then routing priority, then profile id; each entry carriesprofile_id,action,match_reasonand apartialconfidence. When nothing overlaps,candidatesis empty rather than inventing a closest match.ROUTER_AMBIGUOUS— several profiles tied.candidateslists the tied profiles and the router does not pick a winner.
Both carry a suggestion with a runnable remedy. Without --json the refusal
prints the error code, one line per candidate and the remedy as text; with
--json it prints the five-key routing_failed envelope (error,
error_code, message, candidates, suggestion).
uv run spec-kitty dispatch "mark ADR-0068 Accepted and regenerate the ADR index" --dry-run --jsonuv run spec-kitty dispatch "reticulate the splines" --profile curator-carlauv run spec-kitty profiles list--dry-run keeps its own contract: a routed request returns the exit-0
dry_run payload including alternatives, and a ROUTER_AMBIGUOUS request
keeps that exit-0 payload; only ROUTER_NO_MATCH exits 1.
spec-kitty profile-invocation complete
Synopsis: spec-kitty profile-invocation complete [OPTIONS]
Description: Close an open invocation record. This is the signal that closes
the invocation trail. Call it when execution finishes to append a completed
event to the trail file.
| Flag | Description |
|---|---|
--invocation-id, -i TEXT | Invocation ULID to close [required] |
--outcome TEXT | done, failed, or abandoned [required] |
--evidence TEXT | Path to a UTF-8 text evidence file (Tier 2 promotion). Accepted for evidence-eligible records. |
--artifact TEXT | Path to an artifact produced by this invocation (repeatable) |
--commit TEXT | Git commit SHA most directly produced by this invocation (singular) |
--json | Output JSON payload |
--owned-checkout PATH | Look for the Op record in this owned checkout first (a linked checkout of the repository) instead of the checkout the command runs in. The repository root checkout is refused. |
Example:
uv run spec-kitty profile-invocation complete \ --invocation-id 01KQABCDEF1234567890 \ --outcome done \ --artifact docs/guides/my-guide.md \ --commit abc123def456
uv run spec-kitty profile-invocation complete \ --invocation-id 01KQABCDEF1234567890 \ --outcome failedInvocation Trail Fields
Trail records are stored in kitty-ops/{invocation_id}.jsonl. Each file
contains a started event and, once closed, a completed event. It may also
contain additional append-only events such as glossary_checked,
artifact_link, or commit_link.
started event fields
| Field | Type | Description |
|---|---|---|
invocation_id | ULID string | Unique identifier for this invocation |
event | string | started |
profile_id | string | Resolved profile identifier |
action | string | Action token resolved for governance context |
request_text | string | Natural-language request supplied to dispatch |
governance_context_hash | string | First 16 hex characters of the rendered Charter context SHA-256 |
governance_context_available | boolean | Whether Charter context was available when the record was opened |
actor | string | Caller identity such as operator, claude, or codex |
router_confidence | string/null | Router confidence for auto-routed requests |
started_at | ISO 8601 timestamp | When the invocation was opened |
mode_of_work | string | task_execution, mission_step, or query |
mission_id, wp_id | string/null | Mission-scoped dispatch context, when supplied |
No model identifier is recorded (#7013). actor is the harness key and the
only runtime identity the record carries. Records written before this change may
still hold model_id; they are immutable history, still readable, and never
rewritten.
completed event fields
| Field | Type | Description |
|---|---|---|
event | string | completed |
invocation_id | ULID string | Matches the started event |
outcome | string | done, failed, or abandoned |
completed_at | ISO 8601 timestamp | When profile-invocation complete was called |
closed_by | string | agent or doctor_sweep |
evidence_ref | string/null | Evidence path or text supplied with --evidence |
correlation events
When --artifact or --commit is supplied to profile-invocation complete,
the CLI appends separate correlation events after the completed record:
| Event | Key fields | Description |
|---|---|---|
artifact_link | kind, ref, at | Repo-relative or absolute artifact reference |
commit_link | sha, at | Primary git commit SHA |
Lifecycle States
An invocation passes through two durable states:
- open: A
startedevent has been written. The invocation ID is available. Execution has not yet completed. - closed:
profile-invocation completehas been called. Acompletedevent with the final outcome is appended to the trail file.
An invocation that was opened but never completed is stale. Use
spec-kitty invocations list to find open records. It lists the records of the
checkout it runs in; pass --owned-checkout PATH to list those kept in an owned
checkout instead.
Mode-of-work Enforcement
--evidence on profile-invocation complete is enforced against the
invocation’s mode_of_work. Attempting to promote evidence on a non-eligible
record results in InvalidModeForEvidenceError, and no write occurs. Re-run
complete without --evidence to close the invocation cleanly.
Evidence must be UTF-8 text. A file that is not (for example a PNG screenshot),
or inline text that cannot be encoded as UTF-8, is refused before any write
with complete_failed (exit 1) and the message “No completion was recorded”.
The invocation stays open, so re-run complete with a text evidence file. A
path that cannot be read, or a relative path that escapes the repository, is
still stored as the inline text you passed.
| mode_of_work | Tier 2 evidence (--evidence) eligible |
|---|---|
task_execution | Yes |
mission_step | Yes |
query | No |
Example Trail Record
{"event":"started","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","profile_id":"implementer-ivan","action":"implement","request_text":"Implement token validation","governance_context_hash":"0123abcd4567ef89","governance_context_available":true,"actor":"operator","started_at":"2026-04-29T10:00:00Z","mode_of_work":"task_execution"}{"event":"completed","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","completed_at":"2026-04-29T10:45:00Z","outcome":"done","closed_by":"agent"}{"event":"artifact_link","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","kind":"artifact","ref":"src/auth/token.py","at":"2026-04-29T10:45:02Z"}{"event":"commit_link","invocation_id":"01KQA1B2C3D4E5F6G7H8J9K0","sha":"abc123def456789","at":"2026-04-29T10:45:03Z"}