<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-17-1-canonical-next-command-runtime-loop/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-17-1-canonical-next-command-runtime-loop/</id>
  <title>Canonical `spec-kitty next` Command for Agent Execution Loop</title>
  <updated>2026-02-17T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-17-1-canonical-next-command-runtime-loop/"/>
  <summary>Collapses per-step agent entrypoints into a single repeatedly-called next command that returns the prompt and context for whatever the Mission needs done next.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Current agent workflow execution requires selecting command-specific entrypoints (for example &lt;code dir=&quot;auto&quot;&gt;agent workflow implement&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent workflow review&lt;/code&gt;). This increases agent-side branching logic and creates inconsistent next-step behavior.&lt;/p&gt;
&lt;p&gt;The product direction requires that agents repeatedly call one command (&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;) and receive complete prompt + context for the next action.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Deterministic execution loop for LLM agents.&lt;/li&gt;
&lt;li&gt;Reduced command-selection cognitive load.&lt;/li&gt;
&lt;li&gt;Unified behavior across missions and runtimes.&lt;/li&gt;
&lt;li&gt;Compatibility with local-first operation.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Keep command-specific entrypoints only.&lt;/li&gt;
&lt;li&gt;Add &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; as canonical loop command (chosen).&lt;/li&gt;
&lt;li&gt;Delegate step selection to SaaS only.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; Add top-level &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent &amp;#x3C;name&gt;&lt;/code&gt; as the canonical mission loop command.&lt;/p&gt;
&lt;h3 id=&quot;command-contract&quot;&gt;Command Contract&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--agent&lt;/code&gt; is required.&lt;/li&gt;
&lt;li&gt;Default behavior auto-completes previously issued step as success unless &lt;code dir=&quot;auto&quot;&gt;--result&lt;/code&gt; override is supplied.&lt;/li&gt;
&lt;li&gt;Output includes both machine JSON decision payload and human-readable prompt text.&lt;/li&gt;
&lt;li&gt;Decision kinds: &lt;code dir=&quot;auto&quot;&gt;step&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;decision_required&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;terminal&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; planning for an active run uses the frozen mission template captured at run start (not live mission file edits).&lt;/li&gt;
&lt;li&gt;If template drift is detected during active run, &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; MUST return &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; with migration-required reason.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Single command for agent execution loop.&lt;/li&gt;
&lt;li&gt;Deterministic UX across mission types.&lt;/li&gt;
&lt;li&gt;Easier integration with diverse agent runtimes.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Migration effort from legacy &lt;code dir=&quot;auto&quot;&gt;agent workflow&lt;/code&gt; command family.&lt;/li&gt;
&lt;li&gt;Need compatibility bridge and deprecation messaging.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Legacy commands remain available during migration window.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;rollout-notes&quot;&gt;Rollout Notes&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Runtime integration is gated on &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; mission-next contract publication.&lt;/li&gt;
&lt;li&gt;Do not ship CLI-side local-only mission-next event names.&lt;/li&gt;
&lt;li&gt;Implement compatibility bridge from &lt;code dir=&quot;auto&quot;&gt;agent workflow&lt;/code&gt; to runtime-backed planning semantics.&lt;/li&gt;
&lt;li&gt;Emit telemetry during migration to quantify legacy command usage.&lt;/li&gt;
&lt;li&gt;Deprecate legacy flow after adoption threshold is met.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;amendment-2026-02-18&quot;&gt;Amendment (2026-02-18)&lt;/h2&gt;
&lt;p&gt;The initial implementation left three contract gaps that are now explicitly closed:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; result handling (&lt;code dir=&quot;auto&quot;&gt;failed&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;) is runtime-driven. CLI no longer short-circuits these outcomes before runtime execution.&lt;/li&gt;
&lt;li&gt;Runtime template resolution for &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; honors deterministic discovery precedence tiers for &lt;code dir=&quot;auto&quot;&gt;mission-runtime.yaml&lt;/code&gt;, instead of selecting built-in templates first.&lt;/li&gt;
&lt;li&gt;Integration tests include a real successful decision-answer path and replay parity against canonical mission-next conformance fixtures from &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;known-limitations-locked-in&quot;&gt;Known Limitations (Locked In)&lt;/h2&gt;
&lt;p&gt;As of &lt;strong&gt;2026-02-17&lt;/strong&gt;, some mission mappings/templates for &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; are intentionally incomplete and may return &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;terminal&lt;/code&gt; before a full loop.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;plan&lt;/code&gt; mission initial state/action mapping gap.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;documentation&lt;/code&gt; mission state-machine/template parity gap for &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;These are accepted short-term constraints and MUST remain explicitly tracked via:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Per-mission tracking docs:
&lt;code dir=&quot;auto&quot;&gt;architecture/2.x/initiatives/next-mission-mappings/issue-plan-mission-next-mapping.md&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;architecture/2.x/initiatives/next-mission-mappings/issue-documentation-mission-next-mapping.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;xfail(strict=True)&lt;/code&gt; integration tests that express desired behavior and fail loudly on accidental drift/partial fixes.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;When either mission is implemented end-to-end, the corresponding tracking doc MUST be updated to closed and the &lt;code dir=&quot;auto&quot;&gt;xfail&lt;/code&gt; test MUST be converted to a normal passing test in the same PR.&lt;/p&gt;</content>
</entry>
