The Runtime Loop Explained
Who is this for (1)
- Stakeholder Persona: Lead Developer — Written for the Lead Developer reader.
Spec Kitty offers two ways to advance work through a mission: slash commands and the runtime loop. This document explains the runtime loop — what it is, when to use it, and how to interpret what it tells you.
Terminology note
- Canonical 2.x model:
Mission Type -> Mission -> Mission Run spec-kitty nextuses--missionas the canonical tracked-mission selector
What Is spec-kitty next?
In a typical workflow, a human decides what to do next. They look at the kanban board, pick a work package, and run the appropriate slash command (/spec-kitty.implement, /spec-kitty.review, and so on). The human is the decision-maker.
spec-kitty next inverts that relationship. Instead of the human choosing the next action, the runtime decides and tells the agent what to do. The agent calls spec-kitty next, receives a decision, executes it, reports the result, and asks again. This is the runtime loop.
Agent asks: "What should I do next?" | vRuntime evaluates mission state, WP status, guards, priorities | vRuntime returns a decision: "Implement WP03 -- here is the prompt file" | vAgent executes the work, reports the result | vAgent asks again: "What should I do next?"The runtime considers several factors when making its decision:
- Mission phase — Which step in the mission workflow is active (specify, plan, tasks, implement, review, accept)
- work package status — Which WPs are planned, in progress, done, or blocked
- Guard conditions — Whether required artifacts exist, whether prerequisites are met
- Priority ordering — Reviews before new implementations, dependency-free WPs before dependent ones
When to Use the Runtime Loop
Use spec-kitty next when:
- You are running multi-agent orchestration (multiple agents working on the same mission in parallel)
- You want autonomous mission execution where agents run in a loop without human intervention
- You want the runtime to determine ordering and priority rather than choosing manually
Use slash commands directly when:
- You are working manually on a single mission
- You are a single developer working through one work package at a time
- You want explicit control over which action to take next
The two approaches are complementary. Slash commands give you direct control. The runtime loop gives you automation.
Concurrent advances are serialised
When several agents advance the same mission run in parallel (or one agent retries a slow call), advancing a run is serialised: at most one next mutates a given run’s cursor at a time, and an advance that was evaluated against a step the run has since moved past is refused with a blocked decision and a named reason — never silently completed or re-planned as success. A per-run-directory lock guards the cursor’s read-modify-write and a caller-evaluated-step compare-and-swap detects a run that moved between the caller’s read and the commit. See ADR 2026-10-08-1. A refused advance returns the ordinary blocked shape (reason + exit 1); a retrying loop should treat blocked as “re-query, do not hammer”.
Query Mode vs Advancing Mode
spec-kitty next has two distinct modes:
- Query mode is the read-only form:
spec-kitty next --mission <slug> --json - Advancing mode is the runtime loop form:
spec-kitty next --agent <name> --mission <slug> ...
Use query mode when you want to inspect the current run state without changing it. On a fresh run, the canonical query JSON returns mission_state: "not_started" and a non-null preview_step telling you which step would be issued first. unknown is a legacy transitional value and is no longer the primary contract to teach or consume.
What a query envelope tells you
Every query envelope keeps kind: "query", and mission_state keeps its values. Two fields tell you how to proceed:
-
next_commandnames the command to run next. It is additive: it appears only when set. A query sets it on every envelope except two:- a pending decision on a run that has already started, which you answer with
--answer(seedecision_requiredbelow); - a landed Mission, which has nothing left to run.
What the query sees next_commandA fresh Mission ( not_started), a first decision, an in-flight or blocked run, a board previewingimplementorreview, ablocked:*board, an unreadable WP task filespec-kitty next --agent <agent> --mission <slug> --result successA finished software-dev board, not accepted, or accepted before the board’s latest WP transition spec-kitty accept --mission <slug>A finished software-dev board, accepted after the board’s latest WP transition spec-kitty consolidate --mission <slug>A run that completed ( mission_state: "done") with no finished board, for example a Mission with no work packagesaccept, orconsolidateonce acceptedA query without
--agentnever invents an identity: the command carries the literal placeholder<agent>. A finished board of another Mission type (documentation, research, plan, custom) names the advance command, because its runtime still has steps after the work packages. - a pending decision on a run that has already started, which you answer with
-
questionanddecision_idcome together or not at all. When they are set,optionsorinput_keyis set too, so the decision can be answered. This holds by construction: an envelope that breaks it cannot be built.
The start handshake. A fresh Mission has no run yet. Its query previews the first step (mission_state: "not_started", preview_step) and names the advance command. When the first step needs input, the query also shows that decision’s decision_id, question and input_key. The decision is not pending yet, so --answer would be refused: run the advance command (--result success) first. It starts the run and returns the decision as decision_required, which you can then answer.
Use advancing mode when an agent is actively executing the loop. In this mode, --result reports the outcome of the previous issued step and the runtime may advance mission state.
Planning-artifact work packages follow the same runtime loop, but they execute in repository root outside the lane graph. Their workspace is the main checkout rather than a lane worktree.
What the Runtime Consumes: a Single Resolved Mission Type
The runtime is a finite-state machine that consumes a mission type it does not
itself define. Per-mission-type behaviour is resolved once, upstream, into a
single ResolvedMissionType bundle, and the FSM reads that bundle rather than
reaching into any mission-type catalogue directly.
The bundle is keyed off the canonical mission_type field in meta.json that
the FSM already uses to read a mission’s action sequence. The legacy mission
field remains readable for metadata compatibility; issue #2660 separately owns
removal of the meta-less software-development template fallback.
Governance rides alongside the action sequence as a sibling field of the same
resolved bundle — not a property of any individual state or transition. When
“states & transitions as config” fully lands, the state loader and the governance
slot both read the same ResolvedMissionType, but they stay distinct fields so the
two configuration axes remain separable.
This also closes the software-dev-default leak. Previously the action-scoped
context path inferred a mission’s type from template_set, defaulting to
software-dev when it was unset — so a documentation, research, or plan mission
that never set template_set silently loaded software-dev’s test-first,
implementation, and code-review doctrine. The runtime now keys governance off the
real mission_type from meta.json; a missing or unknown type is a hard error,
never a software-dev fallback. Governance, templates, expected artifacts, and
step contracts are current consumers of this bundle. Template readers select a
semantic artefact kind from the immutable doctrine-backed template_set, then
apply the existing project/user/package path precedence to its configured
filename. See
Mission-Type Resolution and
ADR 2026-07-14-2.
The Four Advancing Decisions
In advancing mode, every call to spec-kitty next returns exactly one of four decision kinds. Each tells the agent something different about what to do.
step — An action is available
The runtime has identified work to do. The decision includes an action (such as “implement” or “review”), a wp_id (which work package), and a prompt_file containing the full instructions.
What to do: Read the prompt file and execute the work described in it.
Example output:
{ "kind": "step", "agent": "claude", "mission_slug": "042-test-feature", "mission": "software-dev", "action": "implement", "wp_id": "WP02", "workspace_path": ".worktrees/042-test-feature-lane-b", "prompt_file": "/tmp/spec-kitty-next-claude-042-test-feature-implement-WP02.md", "reason": null, "guard_failures": [], "progress": { "total_wps": 5, "done_wps": 1, "in_progress_wps": 1, "planned_wps": 3, "for_review_wps": 0 }, "step_id": "implement"}decision_required — The runtime needs input
The runtime has reached a point where it cannot proceed without a choice. It provides a question, a set of options, and a decision_id that you use to send back your answer.
What to do: Read the question and options. Answer with:
spec-kitty next --agent <agent> --mission <slug> \ --answer "<your choice>" --decision-id "<decision_id>" --jsonIf the agent cannot determine the answer, escalate to the user.
blocked — Cannot proceed
Something is preventing the mission from advancing. The reason field explains the high-level problem, and guard_failures lists the specific conditions that are not met.
What to do: Read the reason and guard failures. Common blockers include:
| Blocker | Typical Resolution |
|---|---|
| Missing artifacts (spec.md, plan.md) | Run the planning workflow first |
| Upstream WP not done | Implement or review the upstream WP |
| Review feedback not addressed | Re-implement, address feedback, move back to for_review |
| Stale agent (WP stuck in doing) | Move WP to planned with --force, then re-dispatch |
| Circular dependencies | Edit WP frontmatter to break the cycle, re-run finalize-tasks |
terminal — Mission complete
There are no more steps to execute. What terminal means depends on the Mission:
- A software-dev Mission with a finalized work-package board, whose run is not authoritative
(see the next section): the Mission is accepted, with an acceptance newer than the board’s latest
work-package transition, or it has landed. An unaccepted finished board returns
blockedwithMISSION_AWAITING_ACCEPTANCEinstead. - Every other Mission (documentation, research, plan and custom Missions, a software-dev Mission with no work packages, or a run that reached the end of its runtime path): the run completed. Nothing has checked acceptance.
What to do: If the Mission is not accepted yet, run spec-kitty accept --mission <slug>. Then,
if it has not landed, run spec-kitty consolidate --mission <slug>. consolidate does not check
acceptance itself, so do not skip accept. Then run /spec-kitty-mission-review and the
retrospective workflow. A read-only query (spec-kitty next --mission <slug> --json) names the
command to run next in next_command (accept, then consolidate once accepted). Treat that field
as the authoritative hint.
A Finalized Board Is Never Rewound
These rules apply to software-dev Missions with a finalized work-package board only. Documentation, research, plan and custom Missions keep their runtime path unchanged, because their runtime has steps after the work packages.
They also depend on whether the run is authoritative. A run at analyze, implement, review
or accept is authoritative and keeps the runtime path unchanged. For example, a run at review
whose last work package is approved gets the runtime accept step. A run that is absent, untouched,
or issued at a planning step (discovery, research, specify, plan or tasks) is not
authoritative, because the board is further along than the run. For such a run, an advancing
next never sends the Mission back to an earlier step such as discovery. Two rules apply:
- The board’s own answers. These apply for every
--resultvalue (success,failedandblocked), when the run is absent, untouched, or issued atdiscovery,research,specify,planortasks:- A finished board (every work package approved, done or canceled) that is not accepted
returns
kind: "blocked"witherror_code: "MISSION_AWAITING_ACCEPTANCE"and anext_commandofspec-kitty accept --mission <slug>. Once you accept, the next advance returnskind: "terminal". - Acceptance must be newer than the board. The acceptance recorded in
meta.json(accepted_at) counts only when it is later than the board’s latest work-package transition. If a work package is reopened and approved again after acceptance, the Mission is blocked on acceptance again. - A board step that cannot be dispatched (for example a work package that is claimed or in
progress) returns
kind: "blocked"witherror_code: "BOARD_STEP_NOT_DISPATCHABLE", naming the work package, and anext_commandthat resumes it:spec-kitty agent action <implement|review> <WP> --agent <agent> --mission <slug>. When no work package can be named,next_commandisspec-kitty agent tasks status --mission <slug>, so you can inspect the board. - A board step whose work package needs
lanes.json, whenlanes.jsonis missing, returnskind: "blocked"witherror_code: "LANES_MANIFEST_MISSING". Thereasonis the error’s own message.next_commandisspec-kitty agent mission finalize-tasks --mission <slug>while every work package is stillplanned, andspec-kitty doctor mission-state --fix --mission <slug>once any work package has leftplanned(finalize-tasks refuses then; the doctor rebuildslanes.jsonfrom the event log). The same answer is returned when the board dispatch below meets a missinglanes.json. - These answers start no run and record no step as completed. A
terminalanswer carries nonext_commandin advancing mode; a read-only query namesconsolidatefor it.
- A finished board (every work package approved, done or canceled) that is not accepted
returns
- Board dispatch. A claimable work package is dispatched from the board when the run is absent,
untouched, or issued at
discovery,research,specifyorplan. A run attasksis not overridden: it advances through the runtime toanalyze, its next step.
Read-only next uses the same finished-board verdict, so the two modes agree on a finished board: a
query names accept, and names consolidate once the acceptance is fresh.
Residuals.
MissionRunCompletedand the retrospective gate are not reached throughnextfor a software-dev Mission whose run is not authoritative (its work packages were driven from the board or outsidenext).- A run that an earlier release already replayed to
analyzeor beyond cannot be told apart from a legitimate run, so it keeps the runtime path.
The Agent Loop Pattern
At a conceptual level, an agent running the runtime loop follows this pattern:
- Call
spec-kitty next --agent <name> --mission <slug> --json - Read the decision kind
- If step: read the prompt file, do the work, report the result
- If decision_required: answer the question (or escalate to the user)
- If blocked: diagnose the blocker, attempt to resolve it
- If terminal: run
acceptif the Mission is not accepted, thenconsolidateif it has not landed, and exit - Report the result of the previous step with
--result success(orfailedorblocked) - Go back to step 1
The loop continues until the runtime returns terminal or the agent hits a blocker it cannot resolve.
WP iteration within a single step
During the implementation phase, multiple calls to spec-kitty next will return different wp_id values but the same step_id (“implement”). The runtime stays on the “implement” step while cycling through work packages. It only advances to the next mission step (such as “review”) when all WPs have reached a terminal or handoff lane (done, approved, for_review, or canceled with operator provenance — an operator-recorded cancellation is an acceptable ending, mirroring is_acceptable_ending; a synthetic cancellation still blocks advancement, fail-closed — #3780).
This means that in a mission with WP01 through WP09, successive calls might return:
step_id: "implement",wp_id: "WP01"step_id: "implement",wp_id: "WP02"step_id: "implement",wp_id: "WP03"- …and so on until all WPs are accepted-ready
The same behavior applies to the review step.
Reporting results
After completing a step, tell the runtime what happened:
# After successful workspec-kitty next --agent <name> --mission <slug> --result success --json
# After a failurespec-kitty next --agent <name> --mission <slug> --result failed --json
# After hitting a blockerspec-kitty next --agent <name> --mission <slug> --result blocked --jsonIf --result is omitted, the command stays in read-only query mode. Query mode may still accept --agent as a compatibility form, but it does not advance mission state.
Things to Be Aware Of
Merged missions are recognized as terminal (#2947, was #335)
Fixed (#2947). spec-kitty next now resolves mission state from the
committed status authority before it selects a coordination workspace. When a
Mission has landed — its PRIMARY meta.json records merged_at, which
mission_has_landed (src/mission_runtime/landing.py) reads — the loop recognizes it
from that committed record instead of a stale coordination worktree checkout:
advancing mode (--result success) returns kind: "terminal" and creates no
runtime run; read-only query mode returns kind: "query" with
mission_state: "done" (query mode is structurally kind: query). If the
committed record has landed but its status is not all-accepted
(a merge/status conflict), or an actionable step needs a coordination workspace
whose checkout is missing the mission’s artifacts, the loop fails closed with a
structured kind: "blocked" — never a fabricated “unstarted” step. A landed
Mission’s query envelope carries no next_command. The former
progress-field workaround is no longer required.
Historically this class was tracked as #335; the committed-authority resolution
in mission next-committed-state-authority closes it via #2947.
Some steps may return a null prompt file (#336)
Certain mission steps (such as discovery) do not have command templates. When the runtime reaches one of these steps, it returns a step decision with prompt_file: null. An agent that tries to read a null prompt file will fail.
Workaround: Always check that prompt_file is not null before attempting to read it. If it is null, treat the decision as blocked — do not attempt to execute without a prompt.
See Also
- Multi-Agent Orchestration — The coordination model for running multiple agents
- Mission System — How missions define the workflow that the runtime follows
- Mission-Type Resolution — The doctrine → charter → core seam that resolves the bundle the runtime consumes
- Kanban Workflow — The lane-based status model that the runtime reads
This document explains the concepts behind the runtime loop. For step-by-step instructions on running agents, see the how-to guides. For the full decision output schema, see the reference documentation.