<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/runtime-loop/">
  <id>https://docs.spec-kitty.ai/architecture/runtime-loop/</id>
  <title>The Runtime Loop Explained</title>
  <updated>2026-11-12T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/runtime-loop/"/>
  <summary>How spec-kitty next inverts control so the runtime picks the next action: query versus advancing mode and the four decisions, step, decision_required, blocked, and terminal.</summary>
  <content type="html">&lt;span id=&quot;the-runtime-loop-explained&quot;&gt;&lt;/span&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Terminology note&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Canonical 2.x model: &lt;code dir=&quot;auto&quot;&gt;Mission Type -&gt; Mission -&gt; Mission Run&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; uses &lt;code dir=&quot;auto&quot;&gt;--mission&lt;/code&gt; as the canonical tracked-mission selector&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;what-is-spec-kitty-next&quot;&gt;What Is &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt;?&lt;/h2&gt;
&lt;p&gt;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 (&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.implement&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.review&lt;/code&gt;, and so on). The human is the decision-maker.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; inverts that relationship. Instead of the human choosing the next action, the &lt;strong&gt;runtime decides&lt;/strong&gt; and tells the agent what to do. The agent calls &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt;, receives a decision, executes it, reports the result, and asks again. This is the runtime loop.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Agent asks: &quot;What should I do next?&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;|&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;v&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Runtime evaluates mission state, WP status, guards, priorities&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;|&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;v&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Runtime returns a decision: &quot;Implement WP03 -- here is the prompt file&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;|&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;v&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Agent executes the work, reports the result&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;|&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;v&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Agent asks again: &quot;What should I do next?&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The runtime considers several factors when making its decision:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Mission phase&lt;/strong&gt; — Which step in the mission workflow is active (specify, plan, tasks, implement, review, accept)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;work package status&lt;/strong&gt; — Which WPs are planned, in progress, done, or blocked&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Guard conditions&lt;/strong&gt; — Whether required artifacts exist, whether prerequisites are met&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Priority ordering&lt;/strong&gt; — Reviews before new implementations, dependency-free WPs before dependent ones&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;when-to-use-the-runtime-loop&quot;&gt;When to Use the Runtime Loop&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Use &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; when:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;You are running multi-agent orchestration (multiple agents working on the same mission in parallel)&lt;/li&gt;
&lt;li&gt;You want autonomous mission execution where agents run in a loop without human intervention&lt;/li&gt;
&lt;li&gt;You want the runtime to determine ordering and priority rather than choosing manually&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Use slash commands directly when:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;You are working manually on a single mission&lt;/li&gt;
&lt;li&gt;You are a single developer working through one work package at a time&lt;/li&gt;
&lt;li&gt;You want explicit control over which action to take next&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The two approaches are complementary. Slash commands give you direct control. The runtime loop gives you automation.&lt;/p&gt;
&lt;h3 id=&quot;concurrent-advances-are-serialised&quot;&gt;Concurrent advances are serialised&lt;/h3&gt;
&lt;p&gt;When several agents advance the same mission run in parallel (or one agent retries a slow call), advancing a run is &lt;strong&gt;serialised&lt;/strong&gt;: at most one &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; 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 &lt;strong&gt;refused&lt;/strong&gt; with a &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; decision and a named reason — never silently completed or re-planned as &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt;. 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 &lt;a href=&quot;/adr/4.x/2026-10-08-1-serialise-run-dir-advance/&quot;&gt;2026-10-08-1&lt;/a&gt;. A refused advance returns the ordinary &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; shape (reason + exit 1); a retrying loop should treat &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; as “re-query, do not hammer”.&lt;/p&gt;
&lt;h2 id=&quot;query-mode-vs-advancing-mode&quot;&gt;Query Mode vs Advancing Mode&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; has two distinct modes:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Query mode&lt;/strong&gt; is the read-only form: &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --mission &amp;#x3C;slug&gt; --json&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Advancing mode&lt;/strong&gt; is the runtime loop form: &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent &amp;#x3C;name&gt; --mission &amp;#x3C;slug&gt; ...&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Use query mode when you want to inspect the current run state without changing it. On a fresh run, the canonical query JSON returns &lt;code dir=&quot;auto&quot;&gt;mission_state: &quot;not_started&quot;&lt;/code&gt; and a non-null &lt;code dir=&quot;auto&quot;&gt;preview_step&lt;/code&gt; telling you which step would be issued first. &lt;code dir=&quot;auto&quot;&gt;unknown&lt;/code&gt; is a legacy transitional value and is no longer the primary contract to teach or consume.&lt;/p&gt;
&lt;h3 id=&quot;what-a-query-envelope-tells-you&quot;&gt;What a query envelope tells you&lt;/h3&gt;
&lt;p&gt;Every query envelope keeps &lt;code dir=&quot;auto&quot;&gt;kind: &quot;query&quot;&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;mission_state&lt;/code&gt; keeps its values. Two fields tell you how to proceed:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt;&lt;/strong&gt; names the command to run next. It is additive: it appears only when set. A query sets it on every envelope except two:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;a pending decision on a run that has already started, which you answer with &lt;code dir=&quot;auto&quot;&gt;--answer&lt;/code&gt; (see &lt;code dir=&quot;auto&quot;&gt;decision_required&lt;/code&gt; below);&lt;/li&gt;
&lt;li&gt;a landed Mission, which has nothing left to run.&lt;/li&gt;
&lt;/ul&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;What the query sees&lt;/th&gt;&lt;th&gt;&lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;A fresh Mission (&lt;code dir=&quot;auto&quot;&gt;not_started&lt;/code&gt;), a first decision, an in-flight or blocked run, a board previewing &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt;, a &lt;code dir=&quot;auto&quot;&gt;blocked:*&lt;/code&gt; board, an unreadable WP task file&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent &amp;#x3C;agent&gt; --mission &amp;#x3C;slug&gt; --result success&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A finished software-dev board, not accepted, or accepted before the board’s latest WP transition&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty accept --mission &amp;#x3C;slug&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A finished software-dev board, accepted after the board’s latest WP transition&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate --mission &amp;#x3C;slug&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A run that completed (&lt;code dir=&quot;auto&quot;&gt;mission_state: &quot;done&quot;&lt;/code&gt;) with no finished board, for example a Mission with no work packages&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; once accepted&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A query without &lt;code dir=&quot;auto&quot;&gt;--agent&lt;/code&gt; never invents an identity: the command carries the literal placeholder &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;agent&gt;&lt;/code&gt;. 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.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;question&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;decision_id&lt;/code&gt;&lt;/strong&gt; come together or not at all. When they are set, &lt;code dir=&quot;auto&quot;&gt;options&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;input_key&lt;/code&gt; is set too, so the decision can be answered. This holds by construction: an envelope that breaks it cannot be built.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;The start handshake.&lt;/strong&gt; A fresh Mission has no run yet. Its query previews the first step (&lt;code dir=&quot;auto&quot;&gt;mission_state: &quot;not_started&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;preview_step&lt;/code&gt;) and names the advance command. When the first step needs input, the query also shows that decision’s &lt;code dir=&quot;auto&quot;&gt;decision_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;question&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;input_key&lt;/code&gt;. The decision is not pending yet, so &lt;code dir=&quot;auto&quot;&gt;--answer&lt;/code&gt; would be refused: run the advance command (&lt;code dir=&quot;auto&quot;&gt;--result success&lt;/code&gt;) first. It starts the run and returns the decision as &lt;code dir=&quot;auto&quot;&gt;decision_required&lt;/code&gt;, which you can then answer.&lt;/p&gt;
&lt;p&gt;Use advancing mode when an agent is actively executing the loop. In this mode, &lt;code dir=&quot;auto&quot;&gt;--result&lt;/code&gt; reports the outcome of the previous issued step and the runtime may advance mission state.&lt;/p&gt;
&lt;p&gt;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.&lt;/p&gt;
&lt;h2 id=&quot;what-the-runtime-consumes-a-single-resolved-mission-type&quot;&gt;What the Runtime Consumes: a Single Resolved Mission Type&lt;/h2&gt;
&lt;p&gt;The runtime is a finite-state machine that consumes a mission type it does not
itself define. Per-mission-type behaviour is resolved &lt;strong&gt;once&lt;/strong&gt;, upstream, into a
single &lt;code dir=&quot;auto&quot;&gt;ResolvedMissionType&lt;/code&gt; bundle, and the FSM reads that bundle rather than
reaching into any mission-type catalogue directly.&lt;/p&gt;
&lt;p&gt;The bundle is keyed off the canonical &lt;code dir=&quot;auto&quot;&gt;mission_type&lt;/code&gt; field in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; that
the FSM already uses to read a mission’s action sequence. The legacy &lt;code dir=&quot;auto&quot;&gt;mission&lt;/code&gt;
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 &lt;strong&gt;sibling field of the same
resolved bundle — not a property of any individual state or transition&lt;/strong&gt;. When
“states &amp;#x26; transitions as config” fully lands, the state loader and the governance
slot both read the same &lt;code dir=&quot;auto&quot;&gt;ResolvedMissionType&lt;/code&gt;, but they stay distinct fields so the
two configuration axes remain separable.&lt;/p&gt;
&lt;p&gt;This also closes the &lt;strong&gt;software-dev-default leak&lt;/strong&gt;. Previously the action-scoped
context path inferred a mission’s type from &lt;code dir=&quot;auto&quot;&gt;template_set&lt;/code&gt;, defaulting to
&lt;code dir=&quot;auto&quot;&gt;software-dev&lt;/code&gt; when it was unset — so a documentation, research, or plan mission
that never set &lt;code dir=&quot;auto&quot;&gt;template_set&lt;/code&gt; silently loaded software-dev’s test-first,
implementation, and code-review doctrine. The runtime now keys governance off the
real &lt;code dir=&quot;auto&quot;&gt;mission_type&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;; 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 &lt;code dir=&quot;auto&quot;&gt;template_set&lt;/code&gt;, then
apply the existing project/user/package path precedence to its configured
filename. See
&lt;a href=&quot;/architecture/mission-type-resolution/&quot;&gt;Mission-Type Resolution&lt;/a&gt; and
&lt;a href=&quot;/adr/3.x/2026-07-14-2-doctrine-to-core-mission-type-resolution-unification/&quot;&gt;ADR 2026-07-14-2&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;the-four-advancing-decisions&quot;&gt;The Four Advancing Decisions&lt;/h2&gt;
&lt;p&gt;In advancing mode, every call to &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; returns exactly one of four decision kinds. Each tells the agent something different about what to do.&lt;/p&gt;
&lt;h3 id=&quot;step--an-action-is-available&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;step&lt;/code&gt; — An action is available&lt;/h3&gt;
&lt;p&gt;The runtime has identified work to do. The decision includes an &lt;code dir=&quot;auto&quot;&gt;action&lt;/code&gt; (such as “implement” or “review”), a &lt;code dir=&quot;auto&quot;&gt;wp_id&lt;/code&gt; (which work package), and a &lt;code dir=&quot;auto&quot;&gt;prompt_file&lt;/code&gt; containing the full instructions.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What to do:&lt;/strong&gt; Read the prompt file and execute the work described in it.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Example output:&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;json&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;kind&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;step&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;agent&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;mission_slug&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;042-test-feature&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;mission&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;software-dev&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;action&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;implement&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;wp_id&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;WP02&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;workspace_path&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;.worktrees/042-test-feature-lane-b&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;prompt_file&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;/tmp/spec-kitty-next-claude-042-test-feature-implement-WP02.md&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;reason&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;null&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;guard_failures&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: [],&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;progress&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: {&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;total_wps&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;5&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;done_wps&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;in_progress_wps&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;planned_wps&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;3&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;for_review_wps&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;},&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;step_id&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;implement&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;decision_required--the-runtime-needs-input&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;decision_required&lt;/code&gt; — The runtime needs input&lt;/h3&gt;
&lt;p&gt;The runtime has reached a point where it cannot proceed without a choice. It provides a question, a set of options, and a &lt;code dir=&quot;auto&quot;&gt;decision_id&lt;/code&gt; that you use to send back your answer.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What to do:&lt;/strong&gt; Read the question and options. Answer with:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;next&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;agent&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;slug&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--answer&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&amp;#x3C;your choice&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--decision-id&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&amp;#x3C;decision_id&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If the agent cannot determine the answer, escalate to the user.&lt;/p&gt;
&lt;h3 id=&quot;blocked--cannot-proceed&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; — Cannot proceed&lt;/h3&gt;
&lt;p&gt;Something is preventing the mission from advancing. The &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt; field explains the high-level problem, and &lt;code dir=&quot;auto&quot;&gt;guard_failures&lt;/code&gt; lists the specific conditions that are not met.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What to do:&lt;/strong&gt; Read the reason and guard failures. Common blockers include:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Blocker&lt;/th&gt;&lt;th&gt;Typical Resolution&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Missing artifacts (spec.md, plan.md)&lt;/td&gt;&lt;td&gt;Run the planning workflow first&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Upstream WP not done&lt;/td&gt;&lt;td&gt;Implement or review the upstream WP&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Review feedback not addressed&lt;/td&gt;&lt;td&gt;Re-implement, address feedback, move back to for_review&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Stale agent (WP stuck in doing)&lt;/td&gt;&lt;td&gt;Move WP to planned with &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;, then re-dispatch&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Circular dependencies&lt;/td&gt;&lt;td&gt;Edit WP frontmatter to break the cycle, re-run finalize-tasks&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;terminal--mission-complete&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;terminal&lt;/code&gt; — Mission complete&lt;/h3&gt;
&lt;p&gt;There are no more steps to execute. What &lt;code dir=&quot;auto&quot;&gt;terminal&lt;/code&gt; means depends on the Mission:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A software-dev Mission with a finalized work-package board, whose run is not authoritative&lt;/strong&gt;
(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 &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; with
&lt;code dir=&quot;auto&quot;&gt;MISSION_AWAITING_ACCEPTANCE&lt;/code&gt; instead.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Every other Mission&lt;/strong&gt; (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.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;What to do:&lt;/strong&gt; If the Mission is not accepted yet, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty accept --mission &amp;#x3C;slug&gt;&lt;/code&gt;. Then,
if it has not landed, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate --mission &amp;#x3C;slug&gt;&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; does not check
acceptance itself, so do not skip &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;. Then run &lt;code dir=&quot;auto&quot;&gt;/spec-kitty-mission-review&lt;/code&gt; and the
retrospective workflow. A read-only query (&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --mission &amp;#x3C;slug&gt; --json&lt;/code&gt;) names the
command to run next in &lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; once accepted). Treat that field
as the authoritative hint.&lt;/p&gt;
&lt;h2 id=&quot;a-finalized-board-is-never-rewound&quot;&gt;A Finalized Board Is Never Rewound&lt;/h2&gt;
&lt;p&gt;These rules apply to &lt;strong&gt;software-dev Missions with a finalized work-package board&lt;/strong&gt; only.
Documentation, research, plan and custom Missions keep their runtime path unchanged, because their
runtime has steps after the work packages.&lt;/p&gt;
&lt;p&gt;They also depend on whether the run is &lt;strong&gt;authoritative&lt;/strong&gt;. A run at &lt;code dir=&quot;auto&quot;&gt;analyze&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt;
or &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; is authoritative and keeps the runtime path unchanged. For example, a run at &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt;
whose last work package is approved gets the runtime &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; step. A run that is absent, untouched,
or issued at a planning step (&lt;code dir=&quot;auto&quot;&gt;discovery&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;tasks&lt;/code&gt;) is not
authoritative, because the board is further along than the run. For such a run, an advancing
&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; never sends the Mission back to an earlier step such as &lt;code dir=&quot;auto&quot;&gt;discovery&lt;/code&gt;. Two rules apply:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The board’s own answers.&lt;/strong&gt; These apply for every &lt;code dir=&quot;auto&quot;&gt;--result&lt;/code&gt; value (&lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;), when the run is absent, untouched, or issued at &lt;code dir=&quot;auto&quot;&gt;discovery&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;plan&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;tasks&lt;/code&gt;:
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A finished board&lt;/strong&gt; (every work package approved, done or canceled) that is not accepted
returns &lt;code dir=&quot;auto&quot;&gt;kind: &quot;blocked&quot;&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;error_code: &quot;MISSION_AWAITING_ACCEPTANCE&quot;&lt;/code&gt; and a
&lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt; of &lt;code dir=&quot;auto&quot;&gt;spec-kitty accept --mission &amp;#x3C;slug&gt;&lt;/code&gt;. Once you accept, the next advance
returns &lt;code dir=&quot;auto&quot;&gt;kind: &quot;terminal&quot;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Acceptance must be newer than the board.&lt;/strong&gt; The acceptance recorded in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;accepted_at&lt;/code&gt;) 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A board step that cannot be dispatched&lt;/strong&gt; (for example a work package that is claimed or in
progress) returns &lt;code dir=&quot;auto&quot;&gt;kind: &quot;blocked&quot;&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;error_code: &quot;BOARD_STEP_NOT_DISPATCHABLE&quot;&lt;/code&gt;, naming
the work package, and a &lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt; that resumes it:
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action &amp;#x3C;implement|review&gt; &amp;#x3C;WP&gt; --agent &amp;#x3C;agent&gt; --mission &amp;#x3C;slug&gt;&lt;/code&gt;. When no
work package can be named, &lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks status --mission &amp;#x3C;slug&gt;&lt;/code&gt;,
so you can inspect the board.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A board step whose work package needs &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, when &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; is missing&lt;/strong&gt;, returns
&lt;code dir=&quot;auto&quot;&gt;kind: &quot;blocked&quot;&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;error_code: &quot;LANES_MANIFEST_MISSING&quot;&lt;/code&gt;. The &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt; is the error’s own
message. &lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-tasks --mission &amp;#x3C;slug&gt;&lt;/code&gt; while
every work package is still &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor mission-state --fix --mission &amp;#x3C;slug&gt;&lt;/code&gt; once any work package has left
&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; (finalize-tasks refuses then; the doctor rebuilds &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; from the event log).
The same answer is returned when the board dispatch below meets a missing &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;These answers start no run and record no step as completed. A &lt;code dir=&quot;auto&quot;&gt;terminal&lt;/code&gt; answer carries no
&lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt; in advancing mode; a read-only query names &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; for it.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Board dispatch.&lt;/strong&gt; A claimable work package is dispatched from the board when the run is absent,
untouched, or issued at &lt;code dir=&quot;auto&quot;&gt;discovery&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;plan&lt;/code&gt;. A run at &lt;code dir=&quot;auto&quot;&gt;tasks&lt;/code&gt; is not
overridden: it advances through the runtime to &lt;code dir=&quot;auto&quot;&gt;analyze&lt;/code&gt;, its next step.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Read-only &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; uses the same finished-board verdict, so the two modes agree on a finished board: a
query names &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;, and names &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; once the acceptance is fresh.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Residuals.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;MissionRunCompleted&lt;/code&gt; and the retrospective gate are not reached through &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; for a
software-dev Mission whose run is not authoritative (its work packages were driven from the
board or outside &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;A run that an earlier release already replayed to &lt;code dir=&quot;auto&quot;&gt;analyze&lt;/code&gt; or beyond cannot be told apart
from a legitimate run, so it keeps the runtime path.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;the-agent-loop-pattern&quot;&gt;The Agent Loop Pattern&lt;/h2&gt;
&lt;p&gt;At a conceptual level, an agent running the runtime loop follows this pattern:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Call &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent &amp;#x3C;name&gt; --mission &amp;#x3C;slug&gt; --json&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Read the decision kind&lt;/li&gt;
&lt;li&gt;If &lt;strong&gt;step&lt;/strong&gt;: read the prompt file, do the work, report the result&lt;/li&gt;
&lt;li&gt;If &lt;strong&gt;decision_required&lt;/strong&gt;: answer the question (or escalate to the user)&lt;/li&gt;
&lt;li&gt;If &lt;strong&gt;blocked&lt;/strong&gt;: diagnose the blocker, attempt to resolve it&lt;/li&gt;
&lt;li&gt;If &lt;strong&gt;terminal&lt;/strong&gt;: run &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; if the Mission is not accepted, then &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; if it has not landed, and exit&lt;/li&gt;
&lt;li&gt;Report the result of the previous step with &lt;code dir=&quot;auto&quot;&gt;--result success&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Go back to step 1&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The loop continues until the runtime returns &lt;code dir=&quot;auto&quot;&gt;terminal&lt;/code&gt; or the agent hits a blocker it cannot resolve.&lt;/p&gt;
&lt;h3 id=&quot;wp-iteration-within-a-single-step&quot;&gt;WP iteration within a single step&lt;/h3&gt;
&lt;p&gt;During the implementation phase, multiple calls to &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; will return different &lt;code dir=&quot;auto&quot;&gt;wp_id&lt;/code&gt; values but the &lt;strong&gt;same &lt;code dir=&quot;auto&quot;&gt;step_id&lt;/code&gt;&lt;/strong&gt; (“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 (&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt; &lt;strong&gt;with operator provenance&lt;/strong&gt; — an operator-recorded cancellation is an acceptable ending, mirroring &lt;code dir=&quot;auto&quot;&gt;is_acceptable_ending&lt;/code&gt;; a synthetic cancellation still blocks advancement, fail-closed — #3780).&lt;/p&gt;
&lt;p&gt;This means that in a mission with WP01 through WP09, successive calls might return:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;step_id: &quot;implement&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;wp_id: &quot;WP01&quot;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;step_id: &quot;implement&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;wp_id: &quot;WP02&quot;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;step_id: &quot;implement&quot;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;wp_id: &quot;WP03&quot;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;…and so on until all WPs are accepted-ready&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The same behavior applies to the review step.&lt;/p&gt;
&lt;h3 id=&quot;reporting-results&quot;&gt;Reporting results&lt;/h3&gt;
&lt;p&gt;After completing a step, tell the runtime what happened:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# After successful work&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;next&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;name&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;slug&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--result&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;success&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# After a failure&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;next&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;name&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;slug&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--result&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;failed&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# After hitting a blocker&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;next&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;name&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;slug&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--result&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;blocked&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If &lt;code dir=&quot;auto&quot;&gt;--result&lt;/code&gt; is omitted, the command stays in read-only query mode. Query mode may still accept &lt;code dir=&quot;auto&quot;&gt;--agent&lt;/code&gt; as a compatibility form, but it does not advance mission state.&lt;/p&gt;
&lt;h2 id=&quot;things-to-be-aware-of&quot;&gt;Things to Be Aware Of&lt;/h2&gt;
&lt;h3 id=&quot;merged-missions-are-recognized-as-terminal-2947-was-335&quot;&gt;Merged missions are recognized as terminal (#2947, was #335)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Fixed (#2947).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; now resolves mission state from the
&lt;strong&gt;committed status authority&lt;/strong&gt; before it selects a coordination workspace. When a
Mission has landed — its PRIMARY &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; records &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt;, which
&lt;code dir=&quot;auto&quot;&gt;mission_has_landed&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/landing.py&lt;/code&gt;) reads — the loop recognizes it
from that committed record instead of a stale coordination worktree checkout:
advancing mode (&lt;code dir=&quot;auto&quot;&gt;--result success&lt;/code&gt;) returns &lt;code dir=&quot;auto&quot;&gt;kind: &quot;terminal&quot;&lt;/code&gt; and creates &lt;strong&gt;no&lt;/strong&gt;
runtime run; read-only query mode returns &lt;code dir=&quot;auto&quot;&gt;kind: &quot;query&quot;&lt;/code&gt; with
&lt;code dir=&quot;auto&quot;&gt;mission_state: &quot;done&quot;&lt;/code&gt; (query mode is structurally &lt;code dir=&quot;auto&quot;&gt;kind: query&lt;/code&gt;). 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 &lt;code dir=&quot;auto&quot;&gt;kind: &quot;blocked&quot;&lt;/code&gt; — never a fabricated “unstarted” step. A landed
Mission’s query envelope carries no &lt;code dir=&quot;auto&quot;&gt;next_command&lt;/code&gt;. The former
&lt;code dir=&quot;auto&quot;&gt;progress&lt;/code&gt;-field workaround is no longer required.&lt;/p&gt;
&lt;p&gt;Historically this class was tracked as #335; the committed-authority resolution
in mission &lt;code dir=&quot;auto&quot;&gt;next-committed-state-authority&lt;/code&gt; closes it via #2947.&lt;/p&gt;
&lt;h3 id=&quot;some-steps-may-return-a-null-prompt-file-336&quot;&gt;Some steps may return a null prompt file (#336)&lt;/h3&gt;
&lt;p&gt;Certain mission steps (such as &lt;code dir=&quot;auto&quot;&gt;discovery&lt;/code&gt;) do not have command templates. When the runtime reaches one of these steps, it returns a &lt;code dir=&quot;auto&quot;&gt;step&lt;/code&gt; decision with &lt;code dir=&quot;auto&quot;&gt;prompt_file: null&lt;/code&gt;. An agent that tries to read a null prompt file will fail.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Workaround:&lt;/strong&gt; Always check that &lt;code dir=&quot;auto&quot;&gt;prompt_file&lt;/code&gt; 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.&lt;/p&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/multi-agent-orchestration/&quot;&gt;Multi-Agent Orchestration&lt;/a&gt; — The coordination model for running multiple agents&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/mission-system/&quot;&gt;Mission System&lt;/a&gt; — How missions define the workflow that the runtime follows&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/mission-type-resolution/&quot;&gt;Mission-Type Resolution&lt;/a&gt; — The doctrine → charter → core seam that resolves the bundle the runtime consumes&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/kanban-workflow/&quot;&gt;Kanban Workflow&lt;/a&gt; — The lane-based status model that the runtime reads&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;p&gt;&lt;em&gt;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.&lt;/em&gt;&lt;/p&gt;</content>
</entry>
