Understanding Governed Profile Invocation
Who is this for (1)
- Stakeholder Persona: Lead Developer — Written for the Lead Developer reader.
This document explains governed profile invocation. For how to run a governed mission, see How to Run a Governed Mission. For the CLI reference, see Profile Invocation Reference.
The Governed Invocation Primitive
Standalone governed work in Spec Kitty is a triple:
- Profile: the resolved agent profile used to select the right governance
context. Users normally do not need to choose this; the router does it. A
caller can pass
--profile <profile-id>when they intentionally want a specific profile. - Action: the action token resolved for the request, such as
implement,review, orplan. - Governance context: the Charter bundle context injected at invocation time. This is the DRG-derived, action-scoped set of directives, tactics, and glossary terms that the agent receives.
When spec-kitty next prepares a prompt for the current mission step, it
resolves the action and renders governance context into the prompt file returned
to the calling agent. For standalone work, spec-kitty dispatch "<request>"
does the same governance-context loading and records an Op trail.
Standalone Dispatch
Use standalone dispatch when the user wants Spec Kitty involved but is not asking for a full mission:
uv run spec-kitty dispatch "Review this approach" --jsonuv run spec-kitty dispatch "Implement token validation" --profile implementer-ivan --jsonThe command returns governance_context_text, invocation_id, and a
close_contract. The host agent must read governance_context_text, treat it
as binding context, do the work, then close the Op.
Re-dispatching without re-embedding the payload (#6990)
Every dispatch assembles and returns the whole governance context — ~24 KB on
this repository, mostly the profile-cited directives. A harness that dispatches
repeatedly pays that as prompt context on every call, although after the first
read the marginal information is near zero. --brief makes that re-read
cheap without changing what is loaded:
uv run spec-kitty dispatch "Implement token validation" --profile python-pedro --brief --jsonWith --brief the envelope keeps every routing and orientation field (profile,
action, router confidence, alternatives, model-routing advice,
governance_context_hash, invocation_id, close_contract) and replaces
governance_context_text with null plus
governance_context_reference:
"governance_context_reference": { "digest": "367d55bc23c18daf", "bytes": 23739, "lines": 308, "fetch_command": "spec-kitty charter context --action generate --profile python-pedro --json --no-mark-loaded"}action here is the payload’s own derived action — generate, the
implementer role’s default verb for that request, not the word “Implement” the
caller typed. The reference therefore always names the grain that was actually
omitted, and the printed command re-renders that grain. digest is the first
16 hex characters of the SHA-256 of the text, the same value the envelope’s
governance_context_hash carries, so a consumer can verify a fetched text
against it.
Three rules make this safe:
- Opt-in, never automatic. There is no session detection and no state file;
dispatch still assembles governance on every call. Use
--briefonly when this session has already read the full text for the resolved profile and action — the first contact must be the full payload (or the fetch command). - The reference must resolve.
--briefleaves the payload untouched when there is no text or no way to reproduce it — governance unavailable, an empty render, or the empty-charter fallback (whose render suppresses the project resolver andcharter contextcannot reproduce it) — so it never hides governance it cannot hand back. - The fetch command is exact.
--jsongives the byte-identicaltextfield (the plain render wraps long lines to the terminal width), and--no-mark-loadedmirrors dispatch’s ownmark_loaded=False, so fetching does not record a first-load and shrink the next mission prompt.
The reference is a command that rebuilds the text on fetch, not a snapshot, so
a charter, DRG or profile change made between dispatch and fetch can make the
fetched text differ from the one digest describes. The consumer must compare
the first 16 hex characters of the SHA-256 of the fetched text with digest
and, on a mismatch, discard it and re-dispatch without --brief.
The Op record, the glossary scan and the routing decision are unchanged in brief mode: only the rendered text is replaced.
Invocation Lifecycle
Every standalone dispatch follows the same append-only lifecycle:
- Opened: A
startedevent is written tokitty-ops/{invocation_id}.jsonlbefore the executor returns. This write is unconditional: it happens regardless of SaaS connectivity or charter state. - Work happens outside the CLI: The CLI has returned the context payload. The caller or agent performs the work.
- Completed: When execution finishes,
spec-kitty profile-invocation completecloses the trail. This appends acompletedevent to the same JSONL file.--artifactand--commitappend separate correlation events after the completed event.
uv run spec-kitty profile-invocation complete \ --invocation-id <ULID> \ --outcome done \ --artifact path/to/produced/file.md \ --commit <git-sha>Options for profile-invocation complete:
--outcome:done,failed, orabandoned--artifact: path to an artifact produced by this invocation (repeatable)--commit: the primary git commit SHA produced by this invocation (singular)--evidence: promote a file to a Tier 2 evidence artifact when the record is evidence-eligible
The Invocation Trail
The invocation trail is the local audit record written by every governed invocation. It provides:
- Local accountability: operators can reconstruct what happened on any checkout without SaaS connectivity.
- SaaS coherence: the dashboard timeline shows the same history as the local audit log.
- Governance provenance: retrospective and doctrine work can reference specific invocations.
Trail files live at kitty-ops/{invocation_id}.jsonl: one JSONL file per
invocation. Each line is an event (started, completed, glossary_checked,
artifact_link, commit_link, or future additive events).
Key fields on the started event:
| Field | Type | Description |
|---|---|---|
profile_id | string | Resolved profile identifier |
action | string | Resolved action token |
request_text | string | Request supplied to dispatch |
governance_context_hash | string | Hash of the rendered Charter context |
governance_context_available | boolean | Whether Charter context was available |
started_at | ISO timestamp | When the invocation was opened |
mode_of_work | string | Work mode used for trail policy |
Key fields on the completed event:
| Field | Type | Description |
|---|---|---|
invocation_id | ULID | Matches the started event |
outcome | string | done, failed, or abandoned |
completed_at | ISO 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 |
Evidence and Artifact Correlation
Artifacts produced during an invocation are linked back to the trail record via
separate artifact_link and commit_link events appended by the --artifact
and --commit options on profile-invocation complete. This correlation
provides:
- A local audit link from an invocation to the artifacts or commit it produced
- Governance provenance context for humans and future automated consumers
Evidence files promoted via --evidence receive Tier 2 status in the trail.