<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/changelog/2x/runtime-and-missions/">
  <id>https://docs.spec-kitty.ai/changelog/2x/runtime-and-missions/</id>
  <title>2.x Runtime, Mission Types, and Missions</title>
  <updated>2026-06-03T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/changelog/2x/runtime-and-missions/"/>
  <summary>Historical Spec Kitty 2.x archive page for 2.x Runtime, Mission Types, and Missions; use Spec Kitty 3.2 docs for current Charter-era workflows.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Archive notice: This page documents historical Spec Kitty behavior and is not the current 3.2 workflow. Start with &lt;a href=&quot;/context/&quot;&gt;Spec Kitty 3.2&lt;/a&gt; for current docs.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;span id=&quot;2x-runtime-mission-types-and-missions&quot;&gt;&lt;/span&gt;
&lt;p&gt;Spec Kitty’s mission system lets you choose a workflow blueprint optimized for your type of work. Each mission type defines the phases, required artifacts, validation guards, and agent context for a specific work type. You select a mission type when creating a mission, and it governs that mission for its entire lifecycle.&lt;/p&gt;
&lt;p&gt;Terminology note:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Mission Type&lt;/code&gt; = reusable workflow blueprint&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Mission&lt;/code&gt; = concrete tracked item in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission-slug&gt;/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Mission Run&lt;/code&gt; = runtime/session instance&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Feature&lt;/code&gt; = compatibility alias for a software-dev mission&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The runtime is the engine that drives mission execution. It resolves which mission-type assets to load, determines what the next action should be, and enforces guard conditions before transitions.&lt;/p&gt;
&lt;h2 id=&quot;the-4-built-in-mission-types&quot;&gt;The 4 Built-In Mission Types&lt;/h2&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Mission&lt;/th&gt;&lt;th&gt;Purpose&lt;/th&gt;&lt;th&gt;Key Phases&lt;/th&gt;&lt;th&gt;Default?&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;software-dev&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Full development lifecycle&lt;/td&gt;&lt;td&gt;specify, plan, tasks, implement, review, accept&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;research&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Systematic evidence-gated investigation&lt;/td&gt;&lt;td&gt;scoping, methodology, gathering, synthesis, output&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;plan&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Goal-oriented strategic planning&lt;/td&gt;&lt;td&gt;discovery, specify, plan, refine&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;documentation&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Divio-based documentation creation&lt;/td&gt;&lt;td&gt;specify, plan, audit, create, validate&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Each mission type defines its own step DAG (directed acyclic graph of actions), its own required artifacts, and its own guard conditions for action transitions.&lt;/p&gt;
&lt;h2 id=&quot;mission-type-assets&quot;&gt;Mission-Type Assets&lt;/h2&gt;
&lt;p&gt;Packaged mission defaults for 2.x live under doctrine:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/software-dev/&lt;/code&gt; — software development workflow&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/plan/&lt;/code&gt; — planning workflow&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/research/&lt;/code&gt; — research workflow&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/documentation/&lt;/code&gt; — documentation workflow&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Each mission-type directory contains a &lt;code dir=&quot;auto&quot;&gt;mission-runtime.yaml&lt;/code&gt; (step DAG, guards, artifacts) and a set of command templates that are deployed to agent directories.&lt;/p&gt;
&lt;h2 id=&quot;the-hierarchy-mission-type-mission-work-package-execution-workspace&quot;&gt;The Hierarchy: Mission Type, Mission, work package, Execution Workspace&lt;/h2&gt;
&lt;p&gt;Understanding how the pieces nest is key to understanding Spec Kitty:&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;Mission Type (reusable workflow blueprint, e.g. software-dev)&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;+-- Mission (concrete tracked item, in kitty-specs/###-name/)&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;+-- Work Package (one parallelizable slice, tasks/WP01.md)&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;+-- Execution Workspace (isolated git worktree, usually .worktrees/###-name-lane-a/)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Mission Type&lt;/strong&gt; — selected when the mission is created; determines actions, artifacts, and guards.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission&lt;/strong&gt; — stored in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/###-name/&lt;/code&gt;; linked to its mission type via &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Feature&lt;/strong&gt; — legacy software-dev alias for a mission.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;work package&lt;/strong&gt; — one unit of implementable work; has its own status on the kanban board and its own dependencies.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Execution Workspace&lt;/strong&gt; — the git worktree resolved for implementation. The runtime creates exactly one worktree per execution lane, and sequential WPs in the same lane reuse that worktree.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Different missions in the same project can use different mission types simultaneously.&lt;/p&gt;
&lt;h2 id=&quot;canonical-agent-loop-spec-kitty-next&quot;&gt;Canonical Agent Loop: &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;2.x treats &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent &amp;#x3C;name&gt;&lt;/code&gt; as the canonical loop entrypoint for agent execution. The command inspects the current mission’s action state and WP statuses, then returns exactly one actionable instruction: which mission action to advance, which WP to implement, or what is blocking progress.&lt;/p&gt;
&lt;p&gt;The loop works with two orthogonal state machines:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Mission action state&lt;/strong&gt; — which outer lifecycle action are we in? (&lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;, …)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WP status&lt;/strong&gt; — where is each work package in its lifecycle? (planned, claimed, in_progress, for_review, in_review, approved, done)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Together they determine the next action. For example: “We are in the implement phase, WP01 is approved, WP02 is in_progress, WP03 is planned — your next action is implement WP03.”&lt;/p&gt;
&lt;p&gt;Agents call &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; in a loop, executing whatever it returns until the mission is complete. This keeps agent behavior deterministic and auditable — the runtime decides what happens next, not the agent.&lt;/p&gt;
&lt;p&gt;ADR reference: &lt;code dir=&quot;auto&quot;&gt;docs/adr/2.x/2026-02-17-1-canonical-next-command-runtime-loop.md&lt;/code&gt;&lt;/p&gt;
&lt;h2 id=&quot;mission-discovery-and-loading&quot;&gt;Mission Discovery and Loading&lt;/h2&gt;
&lt;p&gt;Mission-type discovery and loading are runtime-owned and resolved through explicit precedence rather than duplicated ad-hoc loaders.&lt;/p&gt;
&lt;p&gt;The resolution order is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Project override (&lt;code dir=&quot;auto&quot;&gt;.kittify/missions/&amp;#x3C;name&gt;/&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Project legacy location&lt;/li&gt;
&lt;li&gt;User-global mission-specific location (&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/missions/&amp;#x3C;name&gt;/&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;User-global location (&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Packaged doctrine mission defaults&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;ADR reference: &lt;code dir=&quot;auto&quot;&gt;docs/adr/2.x/2026-02-17-2-runtime-owned-mission-discovery-loading.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;Implementation references:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/runtime/home.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/runtime/resolver.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;status-and-event-model&quot;&gt;Status and Event Model&lt;/h2&gt;
&lt;p&gt;2.x status behavior is event-driven with canonical transition semantics and reducer materialization. Every lane transition is an immutable event appended to &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;. The reducer deterministically produces a snapshot from the event log.&lt;/p&gt;
&lt;p&gt;The 9-lane state machine:&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;planned --&gt; claimed --&gt; in_progress --&gt; for_review --&gt; in_review --&gt; approved --&gt; done&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Plus &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; (reachable from planned/claimed/in_progress/for_review/in_review/approved) and &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt; (reachable from all non-terminal lanes). Alias: &lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;ADR references:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/2.x/2026-02-09-1-canonical-wp-status-model.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/2.x/2026-02-09-2-wp-lifecycle-state-machine.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/2.x/2026-02-09-3-event-log-merge-semantics.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/2.x/2026-02-09-4-cross-repo-evidence-completion.md&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;external-orchestration-boundary&quot;&gt;External Orchestration Boundary&lt;/h2&gt;
&lt;p&gt;2.x orchestration automation is externalized behind &lt;code dir=&quot;auto&quot;&gt;spec-kitty orchestrator-api&lt;/code&gt;.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Host state and transition rules remain in &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;External providers (for example &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt;) call the host API contract.&lt;/li&gt;
&lt;li&gt;Provider implementations should not directly mutate lane/frontmatter state files.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;See &lt;a href=&quot;/changelog/2x/orchestration-and-api/&quot;&gt;Orchestration and API Boundary&lt;/a&gt; for operator and provider guidance.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;learn-more&quot;&gt;Learn More&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Deep dive on missions&lt;/strong&gt;: &lt;a href=&quot;/architecture/mission-system/&quot;&gt;The Mission System Explained&lt;/a&gt; — why missions exist, how they shape your experience, detailed comparison of all four built-in missions&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Kanban workflow&lt;/strong&gt;: &lt;a href=&quot;/architecture/kanban-workflow/&quot;&gt;Kanban Workflow Explained&lt;/a&gt; — how lanes work and what happens when work moves between them&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Workspace model&lt;/strong&gt;: &lt;a href=&quot;/architecture/execution-lanes/&quot;&gt;Execution Workspace Model&lt;/a&gt; — lane-based worktrees only&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CLI reference&lt;/strong&gt;: &lt;a href=&quot;/api/cli-commands/&quot;&gt;CLI Commands Reference&lt;/a&gt; — complete &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; subcommand details&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
