Plan Mission Runtime: Quick Start Guide

Feature: 041-enable-plan-mission-runtime-support Target Audience: Developers and agents using the plan mission in the runtime loop

Overview

The plan mission enables structured planning for software features through a 4-step runtime workflow:

specify → research → plan → review

Each step is guided by AI agents using mission-scoped command templates.

Prerequisites

  • spec-kitty 0.11.0+ on 2.x branch
  • A spec-kitty project initialized
  • Git (for branch management)

Step 1: Create a Plan Feature

Create a new feature with the plan mission:

spec-kitty specify "OAuth2 Integration Planning" --mission plan --json

Expected Output:

{
  "result": "success",
  "feature": "NNN-oauth2-integration-planning",
  "feature_dir": "/path/to/kitty-specs/NNN-oauth2-integration-planning"
}

Verification:

  • Feature directory created
  • meta.json contains "mission": "plan"
  • spec.md created with initial specification

Step 2: Start the Plan Mission Runtime Loop

Progress through the 4-step plan mission:

spec-kitty next --feature NNN-oauth2-integration-planning --agent codex --json

First Call Output:

{
  "status": "step",
  "current_step": "specify",
  "mission": "plan",
  "template": "[resolved specify.md template content]",
  "agent": "codex",
  "blocked": false
}

What Happens: 1. Runtime loads mission-runtime.yaml for plan mission 2. Runtime resolves command-templates/specify.md 3. Template is executed by the agent (Codex in this example) 4. Agent produces feature specification output

Step 3: Progress Through Research Phase

After the agent completes the specify step, call next again:

spec-kitty next --feature NNN-oauth2-integration-planning --agent codex --json

Output:

{
  "status": "step",
  "current_step": "research",
  "mission": "plan",
  "template": "[resolved research.md template content]",
  "agent": "codex",
  "blocked": false
}

What Happens: 1. Runtime transitions to step 2: research 2. Runtime resolves command-templates/research.md 3. Agent gathers research inputs and technical context 4. Agent produces research document output

Step 4: Progress Through Plan/Design Phase

Call next to move to the planning phase:

spec-kitty next --feature NNN-oauth2-integration-planning --agent codex --json

Output:

{
  "status": "step",
  "current_step": "plan",
  "mission": "plan",
  "template": "[resolved plan.md template content]",
  "agent": "codex",
  "blocked": false
}

What Happens: 1. Runtime transitions to step 3: plan 2. Runtime resolves command-templates/plan.md 3. Agent creates design artifacts (data-model.md, contracts, etc.) 4. Agent produces implementation design output

Step 5: Final Review Phase

Call next to move to the review phase:

spec-kitty next --feature NNN-oauth2-integration-planning --agent codex --json

Output:

{
  "status": "step",
  "current_step": "review",
  "mission": "plan",
  "template": "[resolved review.md template content]",
  "agent": "codex",
  "blocked": false
}

What Happens: 1. Runtime transitions to step 4: review (final step) 2. Runtime resolves command-templates/review.md 3. Agent reviews and validates all planning artifacts 4. Agent produces validation report

Step 6: Complete Planning and Generate Tasks

After review is complete, the plan mission workflow is done. Next step is to generate work packages:

spec-kitty tasks --feature NNN-oauth2-integration-planning

This generates:

  • tasks.md with work package definitions
  • tasks/WP01.md, tasks/WP02.md, etc. (individual work packages)
  • Ready for implementation phase

Expected Feature Artifacts After Planning

kitty-specs/NNN-oauth2-integration-planning/
├── spec.md                  # Feature specification (from step 1)
├── research.md              # Research findings (from step 2)
├── data-model.md            # Data model and contracts (from step 3)
├── contracts/               # API/schema contracts
├── tasks.md                 # Work packages (generated by /spec-kitty.tasks)
└── tasks/
    ├── WP01.md
    ├── WP02.md
    └── ...

Troubleshooting

Error: "Mission 'plan' not found"

Cause: mission-runtime.yaml not deployed to target environment Solution: Ensure 2.x branch is up to date with the deployed spec-kitty version

git checkout 2.x && git pull origin 2.x

Error: "Command template not found for step X"

Cause: command-templates/{step_id}.md not found Solution: Verify all 4 templates exist:

  • src/specify_cli/missions/plan/command-templates/specify.md
  • src/specify_cli/missions/plan/command-templates/research.md
  • src/specify_cli/missions/plan/command-templates/plan.md
  • src/specify_cli/missions/plan/command-templates/review.md

Error: "Blocked: decision_required"

Cause: Agent needs additional input or clarification Solution: Provide additional context in the next call:

spec-kitty next --feature NNN-oauth2-integration-planning --agent codex --context "additional details..." --json

Feature Stuck at a Step

Cause: Agent cannot complete the step with current template Solution: 1. Review the template context 2. Provide additional input to the agent 3. Re-run the command with more specific instructions

Agent-Specific Notes

Using with Different Agents

The plan mission works with any AI agent:

# Using Claude (default)
spec-kitty next --feature NNN-feature --agent claude --json

# Using GitHub Copilot
spec-kitty next --feature NNN-feature --agent copilot --json

# Using Cursor
spec-kitty next --feature NNN-feature --agent cursor --json

Each agent receives the same mission-scoped command templates but may produce different quality/style output.

Key Concepts

Step Progression

Plan mission is linear and sequential:

  • Step 1 (specify) must complete before step 2 (research)
  • Step 2 must complete before step 3 (plan)
  • Step 3 must complete before step 4 (review)
  • Step 4 is the terminal step

No parallel steps, no branching.

Command Templates

Each step has a dedicated command template that provides:

  • Context: What should be done in this step
  • Deliverables: What outputs are expected
  • Instructions: Step-by-step guidance for the agent
  • Success Criteria: How to validate completion

Templates are stored in:

src/specify_cli/missions/plan/command-templates/
├── specify.md
├── research.md
├── plan.md
└── review.md

Runtime Schema

The mission defines the step sequence in:

src/specify_cli/missions/plan/mission-runtime.yaml

This schema tells the runtime:

  • What steps to execute (and in what order)
  • What step comes next
  • When the mission is complete (terminal step = review)

Performance & Timing

Typical Plan Mission Duration:

  • Step 1 (specify): 5-15 minutes (agent creates specification)
  • Step 2 (research): 10-30 minutes (agent researches technical aspects)
  • Step 3 (plan): 15-45 minutes (agent creates design artifacts)
  • Step 4 (review): 5-15 minutes (agent reviews and validates)

Total: 35-105 minutes (typical feature planning)

Next Steps

After completing the plan mission:

1. Generate Work Packages: ``bash spec-kitty tasks --feature NNN-feature ``

2. Implement Work Packages: ``bash spec-kitty implement WP01 spec-kitty implement WP02 ``

3. Merge Feature: ``bash spec-kitty merge --feature NNN-feature ``

Support & Documentation

  • Full Specification: spec.md
  • Implementation Plan: plan.md
  • Data Model: data-model.md
  • Source Code: src/specify_cli/missions/plan/
  • Tests: tests/specify_cli/next/test_plan_mission_runtime.py

FAQ

Q: Can I skip the research phase? A: No, all 4 steps must complete. The linear sequence ensures thorough planning.

Q: Can I use a different agent for each step? A: Yes, you can specify different agents for each next call:

spec-kitty next --feature NNN-feature --agent codex
spec-kitty next --feature NNN-feature --agent copilot  # Different agent for step 2

Q: What if an agent produces incomplete output? A: You can re-run the step with additional context:

spec-kitty next --feature NNN-feature --agent codex --context "Please focus on..."

Q: How do I verify the plan mission is working? A: Check that spec-kitty next returns non-blocked status:

{
  "status": "step",  // or "decision_required" or "terminal"
  "blocked": false   // This must be false (not: "blocked": true)
}

Q: Can I use the plan mission on the mainline branch? A: Feature 041 is deployed on 2.x branch only. Mainline deployment would be a separate release.