Spec Kitty

Contracts

command-template.md

Command Template Schema Contract

Purpose: Define the expected structure for mission-scoped command templates in the plan mission

---

Template File Structure

Each command template MUST follow this structure:

---
step_id: "string"           # Must match step ID in mission-runtime.yaml
mission: "plan"             # Mission identifier
title: "string"             # Human-readable title
description: "string"       # Brief description of this step
estimated_duration: "string" # Time estimate (optional)
---

# {Title}

## Context

[Detailed context about what this step accomplishes]

## Deliverables

- [Specific deliverable 1]
- [Specific deliverable 2]
- [Additional deliverables as needed]

## Instructions

[Step-by-step instructions or prompts for the agent]

## Success Criteria

- [Success criterion 1]
- [Success criterion 2]
- [Additional criteria as needed]

## References

[Links to related documentation, templates, or resources (optional)]

---

Field Specifications

Frontmatter (YAML)

Field	Type	Required	Description
step_id	string	YES	Must match a step ID in mission-runtime.yaml (specify, research, plan, or review)
mission	string	YES	Must be "plan"
title	string	YES	Title of the step (e.g., "Specify", "Research", "Plan", "Review")
description	string	YES	Brief description of step purpose
estimated_duration	string	NO	Approximate time to complete (e.g., "15-30 minutes")

Body Sections

Section	Type	Required	Description
Context	Markdown	YES	Explains what should be accomplished in this step, why it matters, and what the agent should focus on
Deliverables	Markdown list	YES	Specific outputs the agent should produce (use bullet points)
Instructions	Markdown	YES	Step-by-step guidance or prompts for the agent
Success Criteria	Markdown list	YES	How to validate the step is complete (use bullet points)
References	Markdown	NO	Links to related docs, templates, or external resources

---

Plan Mission Command Templates

1. specify.md

---
step_id: "specify"
mission: "plan"
title: "Specify Feature"
description: "Prepare and specify the feature definition"
estimated_duration: "15-20 minutes"
---

Purpose: Entry point; create feature specification Output: Feature spec document with clear requirements Agent Task: Ask clarifying questions, document user intent, create specification outline

2. research.md

---
step_id: "research"
mission: "plan"
title: "Research"
description: "Gather research inputs and technical context"
estimated_duration: "20-30 minutes"
---

Purpose: Investigate technical requirements and design patterns Output: Research document with findings and recommendations Agent Task: Analyze technical aspects, research patterns, identify dependencies

3. plan.md

---
step_id: "plan"
mission: "plan"
title: "Plan"
description: "Design and create planning artifacts"
estimated_duration: "30-45 minutes"
---

Purpose: Create technical design artifacts Output: Data model, API contracts, architecture diagram Agent Task: Design system, create contracts, document architecture

4. review.md

---
step_id: "review"
mission: "plan"
title: "Review"
description: "Review and validate planning artifacts"
estimated_duration: "10-15 minutes"
---

Purpose: Validate completeness and consistency Output: Validation report, approval status Agent Task: Review all artifacts, check consistency, validate feasibility

---

Template Content Guidelines

Context Section

Purpose: Set the stage for the agent

Good practices:

• Explain what this step accomplishes
• Describe inputs (what was completed in previous step)
• Describe outputs (what should be delivered)
• Call out any dependencies or prerequisites
• Be specific about the feature context

Example:

## Context

You are now in the Research phase of planning a new software feature.

**Input**: Feature specification from the Specify step (spec.md)

**What you're doing**: Investigating the technical requirements, design patterns,
and dependencies needed to build this feature.

**Output**: A research document with findings and recommendations that will
inform the design phase.

**Focus areas**:
- Technical requirements and constraints
- Existing design patterns that apply
- Third-party dependencies
- Potential risks or challenges

Deliverables Section

Purpose: Define concrete outputs

Good practices:

• Use bullet points
• Be specific (file names, document sections, etc.)
• Include format (Markdown, JSON, YAML, etc.)
• Estimate scope ("2-3 pages", "5-10 items", etc.)

Example:

## Deliverables

- research.md (Markdown document)
  - Technical Analysis section (2-3 pages)
  - Design Patterns section (1-2 pages)
  - Dependencies section (0.5-1 page)
  - Risks & Mitigations section (0.5-1 page)
  - Recommendations section (0.5 page)

- Rough architecture sketch (ASCII diagram or description)

Instructions Section

Purpose: Guide the agent through the work

Good practices:

• Use numbered steps
• Be concrete and actionable
• Include specific questions or prompts
• Reference templates or examples if available
• Break down complex tasks into subtasks

Example:

## Instructions

1. **Analyze the specification** from the previous step
   - What are the core requirements?
   - What constraints exist?
   - Who are the key users?

2. **Research technical patterns**
   - What design patterns apply to this type of feature?
   - Are there existing examples in similar projects?
   - What dependencies or libraries are commonly used?

3. **Identify risks**
   - What could go wrong?
   - What technical challenges exist?
   - Are there security or compliance concerns?

4. **Compile findings**
   - Organize your research into the research.md document
   - Include alternatives considered
   - Make recommendations for the design phase

Success Criteria Section

Purpose: Validate completion

Good practices:

• Use bullet points
• Be testable/observable
• Include both content and quality checks
• Focus on outcomes, not process

Example:

## Success Criteria

- [ ] research.md is complete with all required sections
- [ ] Technical analysis addresses all key requirements
- [ ] Design patterns are well-researched and cited
- [ ] Dependencies are clearly listed with version constraints
- [ ] Risks are identified with mitigation strategies
- [ ] Recommendations are specific and actionable
- [ ] Document is well-organized and easy to follow
- [ ] No broken links or missing references

---

Validation Rules

For each command template file:

✅ File exists in src/specify_cli/missions/plan/command-templates/{step_id}.md ✅ Frontmatter YAML parses correctly ✅ step_id matches a step in mission-runtime.yaml ✅ mission == "plan" ✅ title is provided and non-empty ✅ Body has all required sections: Context, Deliverables, Instructions, Success Criteria ✅ References section is optional but if present, all links are valid ✅ No broken references to content templates (../templates/...) ✅ No doctrine path references (2.x-safe paths only) ✅ Content is plan mission-specific (not generic)

---

Path Reference Rules

Allowed Paths

✅ Relative to command template file:

See: ../templates/research-outline.md
Link: ../data-model.md
Reference: ../../spec.md

✅ Absolute within project:

Source: src/specify_cli/missions/plan/
Docs: docs/plan-mission/

Prohibited Paths

❌ Doctrine paths (2.x compatibility violation):

NO: doctrine/prompts/
NO: .doctrine/
NO: .amazonq/prompts/  (agent-specific - use 2.x paths only)

❌ External service references:

NO: https://external-api.com/template
NO: Database queries
NO: Network calls

---

Content Template Integration

When to Reference Content Templates

If a command template needs to reuse common content:

See also: ../templates/research-outline.md

Creating Content Templates

Only create if explicitly referenced. Example:

In research.md:

Use this template: ../templates/research-outline.md

Then create: src/specify_cli/missions/plan/templates/research-outline.md

No Artificial Templates

Do NOT create templates without explicit references.

• Avoid generic helpers ("common-structure.md", "template-template.md")
• Keep templates mission-specific and focused
• Only create when solving a real referencing problem

---

Examples

Minimal Valid Template

---
step_id: "specify"
mission: "plan"
title: "Specify"
description: "Create feature specification"
---

# Specify

## Context

You are creating the initial feature specification.

## Deliverables

- spec.md with requirements

## Instructions

1. Define feature goals
2. List requirements
3. Document assumptions

## Success Criteria

- spec.md is complete
- All requirements are testable
- Assumptions are documented

Complete Template with References

---
step_id: "research"
mission: "plan"
title: "Research"
description: "Research technical aspects"
estimated_duration: "20-30 minutes"
---

# Research

## Context

You are investigating technical requirements and design patterns for this feature.

**Input**: Feature specification from the Specify step
**Output**: research.md with findings and recommendations

## Deliverables

- research.md (Markdown document)
  - Technical Analysis (2-3 sections)
  - Design Patterns (3-5 patterns)
  - Dependencies (5-10 items)
  - Risks & Mitigations (3-5 items)
  - Recommendations (2-3 actionable items)

## Instructions

Use the research outline template below to structure your findings:

See: ../templates/research-outline.md

Then:
1. Analyze technical requirements
2. Research applicable design patterns
3. Identify key dependencies
4. Surface potential risks
5. Compile recommendations

## Success Criteria

- [ ] research.md follows the outline structure
- [ ] All sections are completed
- [ ] Recommendations are specific and actionable
- [ ] No broken links or references

## References

- Specification: ../spec.md
- Data Model: ../data-model.md

---

References

• Feature Spec: ../spec.md
• Data Model: ../data-model.md
• Implementation Plan: ../plan.md
• Quick Start: ../quickstart.md

mission-runtime.yaml

Mission Runtime Schema Contract

This file defines the expected structure for mission-runtime.yaml in the plan mission

mission: key: type: string value: "plan" description: "Unique identifier for this mission" required: true

title: type: string description: "Human-readable title for the mission" example: "Planning Mission" required: true

description: type: string description: "Detailed description of the mission purpose" example: "Plan and design software features through structured phases" required: true

steps: type: array[Step] description: "Ordered list of steps in the mission" minItems: 2 maxItems: 10 required: true

items: Step: id: type: string description: "Unique step identifier (lowercase, no spaces)" pattern: "^[a-z_]+$" examples: ["specify", "research", "plan", "review"] required: true

name: type: string description: "Human-readable step name" examples: ["Specify", "Research", "Plan", "Review"] required: true

description: type: string description: "What this step accomplishes" required: true

order: type: integer description: "Sequential order (1-based)" minimum: 1 required: true

depends_on: type: array[string] description: "IDs of previous steps that must complete first (empty for first step)" items: string default: [] examples: [[], ["specify"], ["research"], ["plan"]] required: false

runtime: type: object description: "Runtime execution configuration" required: true

properties: loop_type: type: string enum: ["sequential", "parallel", "conditional"] description: "How steps are executed (sequential = one at a time)" required: true

step_transition: type: string enum: ["automatic", "manual", "agent-decision"] description: "How transitions between steps occur" examples: ["manual (user calls next)", "automatic (no wait)"] required: true

prompt_template_dir: type: string description: "Relative directory containing command templates" default: "command-templates" required: true

terminal_step: type: string description: "ID of the final step that completes the mission" required: true

---

Plan Mission Concrete Schema

The src/specify_cli/missions/plan/mission-runtime.yaml file MUST match:

mission:
  key: "plan"
  title: "Planning Mission"
  description: "Plan and design software features through structured phases"

  steps:
    - id: "specify"
      name: "Specify"
      description: "Prepare and specify the feature definition"
      order: 1
      depends_on: []

    - id: "research"
      name: "Research"
      description: "Gather research inputs and technical context"
      order: 2
      depends_on: ["specify"]

    - id: "plan"
      name: "Plan"
      description: "Design and create planning artifacts"
      order: 3
      depends_on: ["research"]

    - id: "review"
      name: "Review"
      description: "Review and validate planning artifacts"
      order: 4
      depends_on: ["plan"]

  runtime:
    loop_type: "sequential"
    step_transition: "manual"
    prompt_template_dir: "command-templates"
    terminal_step: "review"

Validation Rules

The runtime bridge MUST validate:

✅ mission.key == "plan" ✅ steps array has exactly 4 items ✅ steps are ordered 1-4 ✅ step IDs are: specify, research, plan, review ✅ step names match IDs ✅ dependencies form a linear chain (no cycles) ✅ first step has no dependencies ✅ each subsequent step depends on previous step only ✅ runtime.terminal_step == "review" ✅ runtime.loop_type == "sequential" ✅ runtime.step_transition == "manual"

References

• Data Model: ../data-model.md
• Feature Spec: ../spec.md
• Implementation Plan: ../plan.md

test-coverage.txt

Test Coverage Contract: Plan Mission Runtime Support

Feature: 041-enable-plan-mission-runtime-support Test File: tests/specify_cli/next/test_plan_mission_runtime.py Target: Python pytest

---

Test Organization

All plan mission tests are organized in a SINGLE dedicated test file:

• Location: tests/specify_cli/next/test_plan_mission_runtime.py
• Organization: test classes grouped by concern (Integration, Resolution, Regression)
• Framework: pytest (existing spec-kitty test suite)
• Fixtures: Use standard pytest fixtures and mocks

---

Test Classes & Coverage

1. Integration Tests

Class: TestPlanMissionIntegration Purpose: Verify end-to-end feature creation + runtime loop progression

Tests:

test_create_plan_feature_with_mission_yaml()
  - Create feature with mission=plan
  - Verify meta.json contains "mission": "plan"
  - Verify feature directory created
  - Expected: Success, feature ready for runtime

test_next_command_plan_feature_not_blocked()
  - Create feature with mission=plan
  - Call spec-kitty next --feature <slug>
  - Verify status != "blocked"
  - Verify no "Mission 'plan' not found" error
  - Expected: Returns "step" status (non-blocked)

test_plan_mission_all_steps_reachable()
  - Create feature with mission=plan
  - Simulate progression through all 4 steps
  - Step 1: specify → should be accessible
  - Step 2: research → should be accessible after step 1
  - Step 3: plan → should be accessible after step 2
  - Step 4: review → should be accessible after step 3
  - Expected: All 4 steps reachable sequentially

test_plan_feature_artifacts_created()
  - Create feature with mission=plan
  - Progress through steps (simulated)
  - Verify artifacts are created:
    - spec.md (from specify step)
    - research.md (from research step)
    - data-model.md (from plan step)
    - validation report (from review step)
  - Expected: All expected artifacts present

2. Command Resolution Tests

Class: TestPlanCommandResolution Purpose: Verify each step's command template resolves successfully

Tests:

test_resolve_specify_command_template()
  - Input: mission="plan", step="specify"
  - Call: resolver.resolve_command(...)
  - Verify: Template file exists
  - Verify: YAML frontmatter parses
  - Verify: Required sections present (Context, Deliverables, Instructions, Success Criteria)
  - Verify: No broken references
  - Expected: Valid template object returned

test_resolve_research_command_template()
  - Input: mission="plan", step="research"
  - Same checks as specify
  - Additional: Check for content template references
  - Expected: Valid template object returned

test_resolve_plan_command_template()
  - Input: mission="plan", step="plan"
  - Same checks as specify
  - Additional: Verify design artifact references
  - Expected: Valid template object returned

test_resolve_review_command_template()
  - Input: mission="plan", step="review"
  - Same checks as specify
  - Additional: Verify validation checklist references
  - Expected: Valid template object returned

test_resolve_all_plan_steps()
  - Loop through all 4 steps
  - Verify each resolves without error
  - Parameterized test with steps: ["specify", "research", "plan", "review"]
  - Expected: All 4 resolve successfully

test_mission_runtime_yaml_validation()
  - Load: src/specify_cli/missions/plan/mission-runtime.yaml
  - Verify: mission.key == "plan"
  - Verify: 4 steps with correct IDs (specify, research, plan, review)
  - Verify: Step sequence is ordered 1-4
  - Verify: Dependencies form linear chain
  - Verify: terminal_step == "review"
  - Expected: All validations pass

test_command_template_frontmatter_valid()
  - For each template file (specify.md, research.md, plan.md, review.md)
  - Load YAML frontmatter
  - Verify: step_id matches filename
  - Verify: mission == "plan"
  - Verify: title is non-empty
  - Verify: description is non-empty
  - Expected: All frontmatter valid

test_command_template_body_sections_present()
  - For each template file
  - Parse Markdown body
  - Verify: Context section present
  - Verify: Deliverables section present
  - Verify: Instructions section present
  - Verify: Success Criteria section present
  - Expected: All required sections present in all templates

3. Regression Tests

Class: TestPlanMissionRegressions Purpose: Ensure no regressions in other missions

Tests:

test_software_dev_mission_still_resolves()
  - Create feature with mission="software-dev"
  - Verify mission resolves
  - Verify all software-dev steps resolve (research, design, implement, test, review)
  - Expected: No regressions, software-dev works as before

test_research_mission_still_resolves()
  - Create feature with mission="research"
  - Verify mission resolves
  - Verify all research steps resolve (question, methodology, gather, analyze, synthesize, publish)
  - Expected: No regressions, research works as before

test_runtime_bridge_backward_compatibility()
  - Verify runtime bridge still handles software-dev and research missions
  - Call: runtime_bridge.discover_mission("software-dev")
  - Call: runtime_bridge.discover_mission("research")
  - Call: runtime_bridge.discover_mission("plan")
  - Expected: All 3 missions discoverable, no errors

test_command_resolver_backward_compatibility()
  - Verify existing command resolver still works
  - Test resolving commands for software-dev and research
  - No changes to resolver API or behavior
  - Expected: Backward compatible

---

Test Fixtures & Mocks

Fixtures Required

@pytest.fixture
def temp_project(tmp_path):
    """Create temporary spec-kitty project for testing"""
    # Setup: minimal project structure
    # Teardown: cleanup
    # Yields: Path to project root

@pytest.fixture
def plan_feature(temp_project):
    """Create a test feature with mission=plan"""
    # Setup: create feature via CLI
    # Yields: Feature slug and paths
    # Teardown: cleanup

@pytest.fixture
def mock_runtime_bridge():
    """Mock the runtime bridge for unit tests"""
    # Returns: MagicMock with expected methods
    # Methods: discover_mission(), resolve_command()

Mocks Required

@patch('specify_cli.next.runtime_bridge.discover_mission')
@patch('specify_cli.next.command_resolver.resolve_command')
@patch('specify_cli.core.feature_detection.load_feature')

---

Test Data

Feature Creation Test Data

TEST_PLAN_FEATURE = {
    "slug": "test-plan-feature",
    "mission": "plan",
    "description": "Test feature for plan mission runtime verification"
}

Command Template Test Data

EXPECTED_STEPS = ["specify", "research", "plan", "review"]

EXPECTED_FRONTMATTER = {
    "specify": {"step_id": "specify", "mission": "plan", "title": "Specify"},
    "research": {"step_id": "research", "mission": "plan", "title": "Research"},
    "plan": {"step_id": "plan", "mission": "plan", "title": "Plan"},
    "review": {"step_id": "review", "mission": "plan", "title": "Review"}
}

EXPECTED_BODY_SECTIONS = [
    "Context",
    "Deliverables",
    "Instructions",
    "Success Criteria"
]

---

Test Execution

Run All Plan Mission Tests

pytest tests/specify_cli/next/test_plan_mission_runtime.py -v

Run Specific Test Class

# Integration tests only
pytest tests/specify_cli/next/test_plan_mission_runtime.py::TestPlanMissionIntegration -v

# Resolution tests only
pytest tests/specify_cli/next/test_plan_mission_runtime.py::TestPlanCommandResolution -v

# Regression tests only
pytest tests/specify_cli/next/test_plan_mission_runtime.py::TestPlanMissionRegressions -v

Run with Coverage

pytest tests/specify_cli/next/test_plan_mission_runtime.py \
  --cov=src/specify_cli/missions/plan \
  --cov=src/specify_cli/next \
  --cov-report=html

---

Coverage Targets

Code Coverage

• src/specify_cli/missions/plan/mission-runtime.yaml: 100% (schema validation)
• src/specify_cli/missions/plan/command-templates/*.md: 100% (resolution tests)
• src/specify_cli/next/runtime_bridge.py: No new changes, existing coverage applies

Scenario Coverage

• ✅ Feature creation with mission=plan
• ✅ Runtime discovery of plan mission
• ✅ Command template resolution for all 4 steps
• ✅ End-to-end progression through plan mission
• ✅ Regression verification for other missions
• ✅ Error handling (missing files, invalid schemas)

---

CI Integration

Test Requirements for CI

# .github/workflows/test.yml (example)
plan-mission-tests:
  runs-on: ubuntu-latest
  python-version: "3.11"
  steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v4
      with:
        python-version: "3.11"
    - run: pip install -e .
    - run: pytest tests/specify_cli/next/test_plan_mission_runtime.py -v
    - run: pytest tests/specify_cli/next/test_plan_mission_runtime.py --cov=src/specify_cli/missions/plan

# Failure threshold
minimum-coverage: 85%
allowed-test-failures: 0

---

Determinism & Isolation

Requirements for CI

✅ No external service calls (no API calls, no network requests) ✅ No timing-dependent assertions (no sleep(), no timing checks) ✅ No random data (all test data deterministic) ✅ Isolated filesystem (use tmp_path fixtures) ✅ Isolated processes (no cross-test contamination) ✅ Consistent ordering (no reliance on dict ordering, list order)

Non-Deterministic Tests Prohibited

❌ Tests that depend on current time/date ❌ Tests that mock random number generators ❌ Tests with flaky timing windows ❌ Tests that assume specific file ordering ❌ Tests that depend on environment variables

---

Test Success Criteria

All tests must:

✅ Pass consistently in CI (100% pass rate) ✅ Pass with and without coverage instrumentation ✅ Pass on multiple Python versions (3.11+) ✅ Complete in < 60 seconds total ✅ Use < 100MB RAM ✅ Not leave artifacts in /tmp or project directory ✅ Not modify git state (repo must remain clean after tests)

---

Known Test Limitations

Not Tested (out of scope)

• Agent-specific behavior (each agent produces different outputs)
• Actual AI model responses (mocked in tests)
• Live runtime loop (simulated with fixtures)
• Cross-platform file encoding (assume UTF-8 only)

Accepted Tradeoffs

• Mock runtime bridge instead of full integration (faster tests)
• Simulate step progression instead of actual agent calls (deterministic)
• Unit-level template validation instead of runtime execution (catches issues early)

---

Test File Structure

# tests/specify_cli/next/test_plan_mission_runtime.py

import pytest
from pathlib import Path
from unittest.mock import patch, MagicMock

class TestPlanMissionIntegration:
    """Integration tests for plan mission feature creation and runtime"""

    def test_create_plan_feature_with_mission_yaml(self, temp_project):
        """..."""

    def test_next_command_plan_feature_not_blocked(self, plan_feature):
        """..."""

    # ... more tests

class TestPlanCommandResolution:
    """Resolution tests for plan mission command templates"""

    def test_resolve_specify_command_template(self):
        """..."""

    def test_resolve_all_plan_steps(self):
        """..."""

    # ... more tests

class TestPlanMissionRegressions:
    """Regression tests ensuring no impacts to other missions"""

    def test_software_dev_mission_still_resolves(self):
        """..."""

    def test_research_mission_still_resolves(self):
        """..."""

    # ... more tests

# Fixtures and helpers at end of file

---

References

• Feature Spec: ../spec.md
• Data Model: ../data-model.md
• Implementation Plan: ../plan.md
• Quick Start: ../quickstart.md