/spec-kitty-runtime-next

name: spec-kitty-runtime-next
description: >-
  Drive the canonical spec-kitty next --mission <handle> control loop for mission
  advancement. Load agent profiles at init, apply action-scoped doctrine
  context at each step boundary, and pull specific tactics/directives on demand.
  Triggers: "run the next step", "what should runtime do next", "advance the
  mission", "what is the next task", "continue the workflow", "what step comes
  next".
  Does NOT handle: setup or repair requests, purely editorial glossary or
  doctrine maintenance, or direct code review.

spec-kitty-runtime-next

This skill teaches agents how to advance a Spec Kitty mission through the canonical runtime control loop, including doctrine-aware context loading at each step boundary.

When to Use This Skill

Use this skill when the user wants to:

• Advance a mission to its next step
• Understand what the runtime will do next
• Unblock a stalled mission
• Interpret runtime outcomes (step, blocked, decision_required, terminal)

---

How the Runtime-Next System Works

The `spec-kitty next` command is the single entry point for agent-driven mission execution. Each call returns a deterministic decision about what action the agent should take next.

Decision Algorithm

The runtime evaluates state in this order:

1. **Mission state machine** — Current phase and available transitions (from `mission-runtime.yaml` DAG) 2. **WP iteration check** — For `implement` and `review` steps, the CLI bridge manages WP-level iteration WITHOUT advancing the runtime. The runtime only advances when ALL WPs reach terminal/handoff lanes. 3. **Guard conditions** — Required artifacts, prerequisites, dependency graph 4. **Priority ordering** — Reviews before implementations, higher-priority WPs first, dependency-free WPs before dependent ones

WP Iteration Logic (Critical)

The CLI bridge (not the runtime) manages WP-level iteration:

• If current step is `implement` or `review`
• AND there are WPs in `planned` or `in_progress` lanes
• THEN return a WP-level decision **without advancing the runtime step**
• The runtime step only advances when ALL WPs are in terminal/handoff lanes

(`done`, `approved`, or `for_review`)

This means multiple calls to `spec-kitty next` during implementation will return different WP IDs but the same `step_id` (e.g., "implement") until all WPs are done.

Mission Runtime YAML Schema

Missions define steps as a DAG (directed acyclic graph) with dependencies:

mission:
  key: software-dev
  name: Software Dev Kitty
  version: "2.1.0"

steps:
  - id: discovery
    title: Discovery & Research
    depends_on: []
    prompt_template: research.md

  - id: specify
    depends_on: [discovery]
    prompt_template: specify.md

  - id: plan
    depends_on: [specify]
    prompt_template: plan.md

  - id: tasks
    depends_on: [plan]

  - id: implement
    depends_on: [tasks]
    prompt_template: implement.md

  - id: review
    depends_on: [implement]
    prompt_template: review.md

  - id: accept
    depends_on: [review]
    prompt_template: accept.md

Decision Kinds

Every call to `spec-kitty next` returns exactly one decision kind:

| Kind | Meaning | Agent Action | |---|---|---| | `step` | Normal action available | Read `prompt_file` and execute | | `query` | Read-only current-state preview | Inspect state; run `next_command` when it is set; do not execute a prompt or mark a result | | `decision_required` | Runtime needs input | Answer with `--answer` and `--decision-id` | | `blocked` | Guards failing, cannot proceed | Read `reason` + `guard_failures`; when `next_command` is set, run it (for example `MISSION_AWAITING_ACCEPTANCE` names `spec-kitty accept`) | | `terminal` | No more steps. Software-dev Mission with a finalized board and a run that is not authoritative: accepted or landed. Any other Mission: the run completed, with no acceptance check | If not accepted, run `spec-kitty accept --mission <handle>`; if not landed, run `spec-kitty consolidate --mission <handle>` (a query's `next_command` names which); then: mission review → author or verify retrospective (`retrospect create`) → surface findings (`summary` aggregates; `synthesize` reviews proposals) |

Decision Output Fields

{
  "kind": "step",
  "agent": "claude",
  "mission_slug": "042-test-mission",
  "mission": "software-dev",
  "mission_state": "implementing",
  "action": "implement",
  "wp_id": "WP02",
  "workspace_path": ".worktrees/042-test-mission-lane-b",
  "prompt_file": "/tmp/spec-kitty-next-claude-042-test-mission-implement-WP02.md",
  "reason": null,
  "guard_failures": [],
  "progress": {
    "total_wps": 5,
    "done_wps": 1,
    "approved_wps": 0,
    "in_progress_wps": 1,
    "planned_wps": 3,
    "for_review_wps": 0
  },
  "run_id": "abc123",
  "step_id": "implement",
  "decision_id": null,
  "question": null,
  "options": null
}

**Additive fields and codes (next-lifecycle-integrity).** These appear only when set, so other envelopes are unchanged:

| Field or code | Where | Meaning | |---|---|---| | `next_command` | every `query` envelope, except a pending decision on a started run and a landed Mission | The command to run next: the advance command (`spec-kitty next --agent <agent> --mission <handle> --result success`), `spec-kitty accept --mission <handle>`, or `spec-kitty consolidate --mission <handle>` | | `next_command` | `blocked` with one of the three codes below | The command that unblocks the Mission | | `error_code: MISSION_AWAITING_ACCEPTANCE` | advancing `next`, software-dev Mission with a finalized board and a run that is not authoritative | Every WP is approved, done or canceled, and the Mission is not accepted, or was accepted before the board's latest WP transition. Run `next_command` (`accept`) | | `error_code: BOARD_STEP_NOT_DISPATCHABLE` | advancing `next`, software-dev Mission with a finalized board and a run that is not authoritative | The finalized board's s