Skip to content

How to Run a Governed Mission

Who is this for (1)

This guide covers running a mission action under Charter governance using spec-kitty next.

For background on governed profile invocation, see How Charter Works.


Before you begin

Confirm your governance is ready before running a mission:

  1. Charter bundle is current: uv run spec-kitty charter status
  2. Bundle validates: uv run spec-kitty charter bundle validate
  3. Doctrine is synthesized: check that .kittify/charter-packs/ is present. Fresh projects may only have PROVENANCE.md; in that state the runtime falls back to the built-in Charter Pack until agent-generated artifacts are promoted.

If the bundle is stale, run the synthesis flow first. See How to Synthesize and Maintain Doctrine.


1. Run a governed mission action

The primary loop command is spec-kitty next. It inspects the mission’s state machine, evaluates guards, and returns the next deterministic action with its prompt file:

Terminal window
uv run spec-kitty next --agent claude --mission my-feature-slug --json

--agent identifies the agent name used for the issued action. --mission is the mission slug (the human-readable identifier, e.g., my-feature-slug).

When --result is omitted, next operates in query mode: it reads and returns the current mission state without advancing it. This is safe to call repeatedly to check what step is next.

Terminal window
# Query mode — inspect without advancing
uv run spec-kitty next --mission my-feature-slug --json

Charter context is rendered automatically into the prompt file returned by next. The command does not spawn the agent itself; it emits the action, state, and prompt_file for the caller to read and execute. You do not need to pass governance flags manually.


2. Read the output

spec-kitty next --json emits a structured decision object. Key fields:

FieldTypeDescription
kindstringDecision kind: query, step, decision_required, blocked, or terminal
actionstring/nullThe action the agent should perform (e.g., specify, plan, implement)
mission_statestringCurrent state machine state
step_idstring/nullRuntime step identifier for the issued step
prompt_filestring/nullAbsolute path to the prompt file. Non-null and resolvable for kind: "step"
preview_stepstring/nullNext step preview in query mode
decision_idstring/nullPending decision identifier for decision_required responses
question / optionsstring/list/nullDecision prompt data when input is required
reason / guard_failuresstring/listExplanation for blocked or guarded states
progressobject/nullWork-package progress summary when available

A fresh-run query returns mission_state: "not_started" and a preview_step showing the first step. Do not depend on unknown as the fresh-run state — that is a legacy value.


3. Advance through composed steps

To advance the mission after completing a step, report the result:

Terminal window
# Report success and get the next step
uv run spec-kitty next --agent claude --mission my-feature-slug --result success --json
# Report failure (mission may loop or escalate)
uv run spec-kitty next --agent claude --mission my-feature-slug --result failed --json
# Report blocked (mission pauses pending a decision)
uv run spec-kitty next --agent claude --mission my-feature-slug --result blocked --json

A composed mission (e.g., software-dev) has multiple steps: discover, specify, plan, implement, review, and so on. Each call to next --result success advances the state machine to the next step. The runtime returns the action and prompt file for that step.


4. Prompt resolution

spec-kitty next resolves which prompt template to use for the current step from the mission’s mission-runtime.yaml configuration. The step’s prompt_template field points to a packaged mission template or resolved local prompt template.

When prompt resolution succeeds, the output includes a prompt_file path. When it fails (for example, the mission type is unrecognized or the step template is missing), next returns a non-zero exit code with a structured error explaining the resolution failure.

If you encounter a resolution failure:

  • Verify the mission type is valid: uv run spec-kitty mission list
  • Check that the mission slug matches a real mission: uv run spec-kitty mission current

5. Handle blocked decisions

When a mission action encounters a question that requires a concrete answer before proceeding, the mission opens a decision moment and blocks. spec-kitty next will return with mission_state: "blocked" or result: "blocked".

To resolve a blocked decision:

Terminal window
# View the decision (from the --json output, extract the decision_id)
uv run spec-kitty next --mission my-feature-slug --json
# Resolve the decision with a final answer
uv run spec-kitty agent decision resolve <decision-id> \
--mission my-feature-slug \
--final-answer "yes" \
--json

After resolving, resume the mission:

Terminal window
uv run spec-kitty next --agent claude --mission my-feature-slug --result success --json

You can also answer a decision inline while reporting a result:

Terminal window
uv run spec-kitty next --agent claude --mission my-feature-slug \
--answer "approve" \
--decision-id "input:review" \
--result success \
--json

See Also