Spec Kitty Runtime Next

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:

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
}

6 Guard Primitives

Guards block step transitions by returning failure descriptions:

Guards never raise exceptions — they return false on missing context.

Prompt File Generation

The runtime generates a temp file at: /tmp/spec-kitty-next-{agent}-{mission_slug}-{action}[-{wp_id}].md

Template actions (specify, plan, tasks): Mission context header + governance context + action-specific template content.

WP actions (implement, review): Full isolation-aware prompt containing:

1. WP header with workspace path
2. Governance context (paradigms, directives, tools)
3. WP Isolation Rules — DO only modify this WP's status, DO NOT change other WPs or react to their status changes
4. Working directory and review commands
5. WP file content (from tasks/WP##.md)
6. Completion instructions

Decision prompts: Question text, options, and the --answer command to run.

Run Persistence

Runtime state is persisted between calls:

.kittify/runtime/
├── feature-runs.json       # Index: {"mission-slug": {"run_id": "...", "run_dir": "..."}}
└── runs/
    └── <run_id>/
        └── state.json      # Runtime snapshot (current step, inputs, etc.)

Mission Detection

When --mission is omitted, the runtime detects the mission via (in order):

1. SPECIFY_MISSION environment variable
2. Git branch name (mission and lane branches both encode the mission slug)
3. Current directory path (walks up looking for ###-mission-name)
4. Single mission auto-detect (only if exactly one mission exists)
5. Error with guidance if ambiguous

NOTE: Always use --mission <slug> in multi-mission repositories.

Doctrine-Aware Step Execution

The runtime-next loop should load doctrine context iteratively — not all at once. Each step boundary is a context loading opportunity.

Agent Profile at Init

At the start of a session, resolve the active agent profile. This scopes your role, boundaries, and initialization context.

Load the profile using the Python API — do NOT read YAML files directly:

from charter.activation.doctrine_service_builder import build_activation_aware_doctrine_service

service = build_activation_aware_doctrine_service(project_root)

# resolve_profile()'s specializes_from lineage traversal is a repository
# operation, not available on the filtered `agent_profiles` dict — reach it
# through the pinned lineage/mutation accessor:
repo = service.agent_profile_repository
profile = repo.resolve_profile("<profile-id>")  # e.g. "implementer"

# Internalize identity — acknowledge this at session start
print(profile.initialization_declaration)

# Respect scope boundaries
profile.specialization.primary_focus       # What you actively do
profile.specialization.avoidance_boundary  # What you must NOT do
profile.collaboration.handoff_to           # Roles to defer to when out of scope

# Load only the directives this profile references (same `service`, gated dict)
for ref in profile.directive_references:
    directive = service.directives.get(f"DIRECTIVE_{ref.code}")

Discovery (if you don't know your profile-id):

spec-kitty agent profile list
spec-kitty agent profile show <profile-id>

Action-Scoped Context at Each Step

At each step boundary (when spec-kitty next returns a step decision), load governance context scoped to the current action — not the full doctrine:

# Load only what's relevant to this action (compact after first load)
spec-kitty charter context --action implement --json

The context system uses two depth levels:

First-load state is tracked per action in .kittify/charter/context-state.json. This means implement and review each get their own first-load bootstrap independently.

Pull Specific Doctrine On Demand

When you need governance guidance mid-step (e.g., how to structure tests, which review criteria apply), pull the specific tactic or directive by ID rather than re-loading the full context:

from charter.activation.doctrine_service_builder import build_activation_aware_doctrine_service

service = build_activation_aware_doctrine_service(project_root)

# Pull a specific tactic when it becomes relevant
tactic = service.tactics.get("tdd-red-green-refactor")

# Pull a specific directive
directive = service.directives.get("TEST_FIRST")

The action index (actions/<action>/index.yaml) tells you which doctrine artifacts are relevant to the current step. Load the index to discover what to pull:

from charter.offering.missions.action_index import load_action_index

index = load_action_index(missions_root, "software-dev", "implement")
# index.directives → ["TEST_FIRST", ...]
# index.tactics → ["tdd-red-green-refactor", ...]
# index.procedures → [...]

Anti-Pattern: Upfront Context Dump

Do NOT load all doctrine into context at session start. This wastes tokens and dilutes relevance. Instead:

1. At init: Load agent profile + initialization declaration.
2. At each step boundary: Call charter context --action <action>.
3. When stuck or need guidance: Pull specific tactic/directive by ID.
4. When reviewing: Pull review-scoped doctrine, not implement-scoped.

Step 1: Load Runtime Context

Before invoking the runtime, gather the current state.

Commands:

# Check WP status for a mission
spec-kitty agent tasks status --mission <mission-slug>

# Check current context for an action
spec-kitty agent context resolve --action implement --mission <mission-slug> --json

What to look for:

• Active mission slug and mission type
• Current WP lane status (planned, claimed, in_progress, for_review, in_review, approved, done, blocked, canceled)
• Whether there are WPs ready for implementation or review
• Any blocked WPs that need attention first

Step 2: Run the Next Command

# Run the next step
spec-kitty next --agent <agent> --mission <mission-slug> --json

# After completing a step successfully
spec-kitty next --agent <agent> --mission <mission-slug> --result success --json

# After a step failed
spec-kitty next --agent <agent> --mission <mission-slug> --result failed --json

# After a step was blocked
spec-kitty next --agent <agent> --mission <mission-slug> --result blocked --json

Note: --mission is the sole selector. The legacy --feature alias has been removed (#1060); passing --feature now exits with No such option.

The --result flag tells the runtime the outcome of the previous step. If omitted, spec-kitty next returns current state without advancing (query mode). It does not report success for the previous step.