Skip to content

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/FlagDescription
REQUESTNatural-language request [required]
--profile TEXTOptional profile ID; bypasses routing
--jsonOutput JSON payload
--dry-runRoute the request only; no Op is opened and nothing is written
--owned-checkout PATHKeep 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:

Terminal window
uv run spec-kitty dispatch "Review this implementation approach" --json
uv run spec-kitty dispatch "Implement token validation" --profile implementer-ivan --json

How 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. candidates lists up to three profiles sharing at least one word with the request, ordered by overlap, then routing priority, then profile id; each entry carries profile_id, action, match_reason and a partial confidence. When nothing overlaps, candidates is empty rather than inventing a closest match.
  • ROUTER_AMBIGUOUS — several profiles tied. candidates lists 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).

Terminal window
uv run spec-kitty dispatch "mark ADR-0068 Accepted and regenerate the ADR index" --dry-run --json
uv run spec-kitty dispatch "reticulate the splines" --profile curator-carla
uv 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.

FlagDescription
--invocation-id, -i TEXTInvocation ULID to close [required]
--outcome TEXTdone, failed, or abandoned [required]
--evidence TEXTPath to a UTF-8 text evidence file (Tier 2 promotion). Accepted for evidence-eligible records.
--artifact TEXTPath to an artifact produced by this invocation (repeatable)
--commit TEXTGit commit SHA most directly produced by this invocation (singular)
--jsonOutput JSON payload
--owned-checkout PATHLook 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:

Terminal window
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 failed

Invocation 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

FieldTypeDescription
invocation_idULID stringUnique identifier for this invocation
eventstringstarted
profile_idstringResolved profile identifier
actionstringAction token resolved for governance context
request_textstringNatural-language request supplied to dispatch
governance_context_hashstringFirst 16 hex characters of the rendered Charter context SHA-256
governance_context_availablebooleanWhether Charter context was available when the record was opened
actorstringCaller identity such as operator, claude, or codex
router_confidencestring/nullRouter confidence for auto-routed requests
started_atISO 8601 timestampWhen the invocation was opened
mode_of_workstringtask_execution, mission_step, or query
mission_id, wp_idstring/nullMission-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

FieldTypeDescription
eventstringcompleted
invocation_idULID stringMatches the started event
outcomestringdone, failed, or abandoned
completed_atISO 8601 timestampWhen profile-invocation complete was called
closed_bystringagent or doctor_sweep
evidence_refstring/nullEvidence 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:

EventKey fieldsDescription
artifact_linkkind, ref, atRepo-relative or absolute artifact reference
commit_linksha, atPrimary git commit SHA

Lifecycle States

An invocation passes through two durable states:

  1. open: A started event has been written. The invocation ID is available. Execution has not yet completed.
  2. closed: profile-invocation complete has been called. A completed event 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_workTier 2 evidence (--evidence) eligible
task_executionYes
mission_stepYes
queryNo

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"}

See Also