Implementation Plan: Enable Plan Mission Runtime Support on 2.x

Branch: 2.x | Date: 2026-02-22 | Spec: spec.md Input: Feature specification from /kitty-specs/041-enable-plan-mission-runtime-support/spec.md

Note: This plan is generated by the /spec-kitty.plan command for Feature 041 on the 2.x branch.

Summary

Primary Requirement: Enable the plan mission to work end-to-end in the runtime loop (spec-kitty next) by adding required runtime artifacts and mission-scoped command templates.

Current State:

  • Plan mission can be created via /spec-kitty.specify --mission plan, but next blocks with "Mission 'plan' not found"
  • Root cause: Missing mission-runtime.yaml and command templates

Technical Approach: 1. Create src/specify_cli/missions/plan/mission-runtime.yaml with runtime schema (4 steps: specify → research → plan → review) 2. Create 4 mission-scoped command templates (specify.md, research.md, plan.md, review.md) 3. Create any referenced content templates 4. Add integration + resolver tests with regression checks 5. Ensure 2.x compatibility (no doctrine paths, no mainline changes)

Technical Context

Language/Version: Python 3.11+ (existing spec-kitty codebase requirement) Primary Dependencies: typer (CLI), ruamel.yaml (YAML parsing), pathlib (filesystem), subprocess (git operations) Storage: Filesystem only (YAML configs, Markdown templates, Python code) Testing: pytest (existing test suite, Python 3.11+) Target Platform: Cross-platform CLI (Linux, macOS, Windows via WSL) Project Type: Single project (spec-kitty is monolithic Python CLI tool) Performance Goals: Not applicable (configuration artifact generation, not performance-sensitive) Constraints: 2.x-only scope; no doctrine path migration; no mainline changes; no external service dependencies Scale/Scope: Mission system scope (plan mission addition to existing runtime loop, ~4 artifacts + tests)

Constitution Check

GATE: Skipped — No .kittify/constitution.md file exists for this project.

Status: ✅ No constitutional constraints to validate against. Feature 041 scope is contained to mission system artifacts (2.x branch, existing directories, standard testing patterns).

Project Structure

Documentation (this feature)

kitty-specs/041-enable-plan-mission-runtime-support/
├── spec.md              # Feature specification (completed)
├── plan.md              # This file
├── research.md          # Phase 0 output (if needed for mission schema research)
├── data-model.md        # Phase 1 output (mission + runtime data structures)
├── quickstart.md        # Phase 1 output (how to use plan mission)
├── checklists/          # Quality validation
│   └── requirements.md  # Specification checklist (completed)
└── tasks.md             # Phase 2 output (/spec-kitty.tasks command - NOT created by /spec-kitty.plan)

Source Code Structure (existing mission system)

Existing Structure (won't change):

src/specify_cli/missions/
├── software-dev/        # Existing mission
│   ├── mission.yaml
│   ├── command-templates/
│   └── templates/
├── research/            # Existing mission
│   ├── mission.yaml
│   ├── command-templates/
│   └── templates/
└── plan/                # Target mission (expanding in this feature)
    ├── mission.yaml     # Existing planning mission definition
    ├── mission-runtime.yaml   # NEW: Runtime schema for next loop
    ├── command-templates/     # NEW: Mission-scoped command templates
    │   ├── specify.md         # Step 1 command template
    │   ├── research.md        # Step 2 command template
    │   ├── plan.md            # Step 3 command template
    │   └── review.md          # Step 4 command template
    └── templates/             # NEW: Content templates (if referenced)
        └── [created only if command templates reference them]

Test Structure:

tests/specify_cli/next/
├── existing_test_files/
└── test_plan_mission_runtime.py    # NEW: Plan mission integration + resolver tests

Structure Decision: Infrastructure feature within existing mission system. No new directories or projects required. All changes localized to src/specify_cli/missions/plan/ and corresponding tests. 2.x branch only, no cross-branch dependencies.

Phase 0: Research (if needed)

Research Tasks (Phase 0 input gathering):

Based on the specification, the following research is already complete or straightforward:

1. Runtime Schema Compatibility ✅

  • User has identified existing mission-runtime.yaml patterns in other missions (software-dev, research)
  • Task: Examine existing src/specify_cli/missions/software-dev/mission-runtime.yaml as reference
  • Deliverable: Confirm schema structure (mission.key, steps, depends_on, prompt_template)

2. Command Template Patterns ✅

  • User has identified software-dev as the reference mission
  • Task: Review src/specify_cli/missions/software-dev/command-templates/*.md as adaption source
  • Deliverable: List of template sections to adapt for plan mission

3. Runtime Bridge Integration Points ✅

  • User has pinpointed exact lines (214, 244, 302) in runtime_bridge.py
  • Task: Verify mission discovery and template resolution logic
  • Deliverable: Confirm no changes needed to bridge code (only add artifacts)

Phase 0 Status: Low research overhead. Existing patterns in software-dev and research missions serve as reference. Proceed directly to Phase 1 design.

Phase 1: Design & Contracts

Design Artifacts to Generate

1. data-model.md (Phase 1 output)

  • Runtime schema structure for mission-runtime.yaml
  • Step sequence and transitions
  • Command template structure
  • Test data model (test features, WP mockups)

2. Mission Runtime Schema (Design Reference)

  • mission.key: "plan"
  • steps: 4-step sequence (specify, research, plan, review)
  • depends_on: None (linear sequence)
  • prompt_template: Runtime invocation format

3. Command Template Structure (Design Reference)

  • Each template: Markdown with YAML frontmatter (context headers)
  • Step 1 (specify): Entry prompt for feature definition
  • Step 2 (research): Research gathering prompt
  • Step 3 (plan): Design and planning prompt
  • Step 4 (review): Review and validation prompt

4. quickstart.md (Phase 1 output)

  • How to use plan mission from CLI
  • Step-by-step spec-kitty next workflow
  • Example output from each step

5. contracts/ (Phase 1 output)

  • mission-runtime.yaml contract (YAML schema)
  • command-template.md contract (Markdown structure)
  • test-coverage.txt (integration + resolver test scope)

Agent Context Update

Task: After Phase 1 design is complete, update agent context files:

  • No new technologies introduced (Python 3.11+ already documented)
  • No new dependencies (existing: typer, ruamel.yaml, pathlib, pytest)
  • Plan mission addition noted in mission system docs

Implementation Strategy

Artifacts to Create (Derived from Spec FR1-FR4)

FR1: Runtime Mission Definition → src/specify_cli/missions/plan/mission-runtime.yaml

  • 4 steps: specify, research, plan, review
  • Standard runtime schema (no extensions)
  • Compatible with runtime bridge (lines 214, 244, 302)

FR2: Command Templates → src/specify_cli/missions/plan/command-templates/

  • specify.md (entry point)
  • research.md (research phase)
  • plan.md (design phase)
  • review.md (validation phase)
  • 2.x-compatible paths (no doctrine references)

FR3: Content Templates → src/specify_cli/missions/plan/templates/

  • Created only if command templates reference them
  • Plan-specific content (no generic helpers)

FR4: Tests → tests/specify_cli/next/test_plan_mission_runtime.py (NEW dedicated file)

  • Integration test: create feature + next command progression
  • Resolver test: 4 steps resolve successfully
  • Regression test: software-dev & research missions unaffected

Testing Plan (Derived from Spec Testing Strategy)

Unit Tests:

  • mission-runtime.yaml parsing validates against schema
  • Each command template resolves without missing references

Integration Tests:

  • Create feature with mission=plan via CLI
  • Run spec-kitty next on plan feature
  • Verify non-blocked status (no "Mission not found" error)

Resolver Tests:

  • resolve_command(mission="plan", step="specify") → valid template
  • resolve_command(mission="plan", step="research") → valid template
  • resolve_command(mission="plan", step="plan") → valid template
  • resolve_command(mission="plan", step="review") → valid template

Regression Tests:

  • software-dev mission tests still pass
  • research mission tests still pass
  • No regressions in existing runtime loop

Success Criteria (from Spec, Restated for Implementation)

✅ Specification Phase: Feature created with mission=plan in meta.json

✅ Runtime Loop Phase: spec-kitty next --feature <slug> --agent codex returns non-blocked status

✅ Command Resolution: All 4 steps (specify, research, plan, review) resolve successfully

✅ Regression Testing: Zero regressions for software-dev and research missions

✅ Scope Compliance: All changes on 2.x; no doctrine migration; no PR146 side-effects

Dependencies & Risks

Dependencies:

  • Existing mission system (software-dev, research as reference)
  • Runtime bridge (runtime_bridge.py lines 214, 244, 302)
  • Existing test infrastructure (pytest)

Risks:

  • Template schema incompatibility → Mitigated by following software-dev pattern
  • Missing file references → Mitigated by resolver tests
  • Regression in other missions → Mitigated by regression tests
  • 2.x path conflicts → Mitigated by local paths (no doctrine)

Definition of Done (for planning phase)

  • ✅ Specification complete and approved
  • ✅ Quality checklist passed
  • ✅ Planning interrogation complete (test file strategy: Option A)
  • ✅ Technical context documented
  • ✅ Constitution check completed (N/A)
  • ✅ Project structure defined
  • ✅ Implementation strategy outlined
  • □ research.md generated (Phase 0, if needed)
  • □ data-model.md generated (Phase 1)
  • □ contracts/ generated (Phase 1)
  • □ quickstart.md generated (Phase 1)
  • □ Agent context updated (Phase 1)

Ready for: /spec-kitty.tasks to generate work packages