Shipit Kit Plan

Cannot proceed with planning. Open questions in research.yaml must be resolved first. Please complete research or mark questions as resolved.

Workflow

1. Review Spec & Research

Read both YAML source files to understand:

• Requirements and success criteria (spec.yaml)
• Technical decisions and constraints (research.yaml)
• Affected areas and dependencies

2. Design Architecture

Create high-level architecture:

• Component diagram (ASCII or Mermaid)
• Data flow between components
• Integration points with existing code

3. Define Implementation Phases (MANDATORY TDD STRUCTURE)

CRITICAL: Plans MUST follow Test-Driven Development (TDD) with RED-GREEN-REFACTOR cycles.

Break implementation into phases following TDD:

• Foundational phases (no tests): Build pipeline, TypeSpec models, configuration
• TDD Cycle phases: For each layer (Domain, Application, Infrastructure):
  • RED: Write failing tests first
  • GREEN: Write minimal code to pass tests
  • REFACTOR: Clean up while keeping tests green
• Each phase should be independently testable
• Order by dependencies (foundational first)
• Identify parallelizable work

4. Identify Files to Create/Modify

For each phase, list:

• New files: Path and purpose
• Modified files: Path and changes needed

5. Define Testing Strategy (TDD: Tests FIRST)

MANDATORY: Define what tests to write FIRST in each TDD cycle.

For each layer, specify tests to write BEFORE implementation:

• Unit tests (RED first): Domain logic, use cases with mocks
• Integration tests (RED first): Repositories, migrations, database operations
• E2E tests (RED first): User-facing features, CLI commands

Each TDD phase MUST follow:

1. RED: Write failing test
2. GREEN: Write minimal code to pass
3. REFACTOR: Improve code while keeping tests green

6. Document Risks & Rollback

• Identify potential risks
• Define mitigation strategies
• Document rollback plan if needed

7. Create Task Breakdown

Convert phases into actionable tasks:

• Each task should be completable in one session
• Mark parallelizable tasks with [P]
• Include acceptance checklist

8. Write plan.yaml and tasks.yaml

Write structured YAML source files (the source of truth):

• specs/NNN-feature-name/plan.yaml - Architecture and strategy
• specs/NNN-feature-name/tasks.yaml - Detailed task list

NO DUPLICATION between files:

• plan.yaml content: Architecture overview, implementation strategy walkthrough, file tables, testing strategy, risks. NO task-by-task listing (that's in tasks.yaml).
• tasks.yaml content: Brief summary (scope + counts) and acceptance checklist ONLY. Individual task details live exclusively in the tasks[] structured array.
• tasks.yaml tasks[]: The single source of truth for all task details (title, description, TDD cycles, acceptance criteria, dependencies, effort).

9. Update Status Fields & feature.yaml

CRITICAL: Update status in YAML source files AND feature.yaml:

Update the status field in each YAML source file:

• spec.yaml → set status.phase: planning (was research)
• research.yaml → set status.phase: planning (was research)
• plan.yaml → set status.phase: planning, status.updatedAt: <today's date>
• tasks.yaml → set status.phase: implementation, status.updatedAt: <today's date>

Update feature.yaml:

# specs/NNN-feature-name/feature.yaml