/shep-kit-plan

name: shep-kit:plan
description: Use after /shep-kit:research to create implementation plan and task breakdown. Triggers include "plan", "implementation plan", "break down tasks", "create tasks", or explicit /shep-kit:plan invocation. Part of the Shep autonomous SDLC platform — https://shep.bot
metadata:
  version: '1.0.0'
  author: Shep AI (https://shep.bot)
  homepage: https://shep.bot
  repository: https://github.com/shep-ai/shep

Create Implementation Plan

Generate a detailed implementation plan with architecture overview and task breakdown.

**Full workflow guide:** [docs/development/spec-driven-workflow.md](../../../docs/development/spec-driven-workflow.md)

Prerequisites

• Feature spec exists at `specs/NNN-feature-name/spec.yaml`
• Research completed at `specs/NNN-feature-name/research.yaml`
• On the feature branch `feat/NNN-feature-name`

GATE CHECK (Mandatory)

Before starting planning, verify:

1. **Read `research.yaml`** and check the `openQuestions` field 2. **If any items have `resolved: false`**: STOP and inform user: > Cannot proceed with planning. Open questions in research.yaml must be resolved first. > Please complete research or mark questions as resolved. 3. **Only proceed** when all open questions have `resolved: true` or the `openQuestions` array is empty

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
feature:
  lifecycle: 'implementation' # Update from "planning"

status:
  phase: 'ready-to-implement' # Update from "planning"
  progress:
    total: <count from tasks.yaml> # Count tasks[].id entries
  lastUpdated: '<timestamp>'
  lastUpdatedBy: 'shep-kit:plan'

checkpoints:
  # Add new checkpoint:
  - phase: 'plan-complete'
    completedAt: '<timestamp>'
    completedBy: 'shep-kit:plan'

**Count tasks** from the YAML array (not markdown grep):

# Count entries in tasks.yaml tasks[] array
yq '.tasks | length' specs/NNN-feature-name/tasks.yaml

**Reference:** [docs/development/feature-yaml-protocol.md](../../../docs/development/feature-yaml-protocol.md)

10. Update data-model.md (if needed)

If feature requires entity changes:

• Define new entities with TypeSpec structure
• Document modifications to existing entities
• List new enums or value objects

11. Commit

git add specs/NNN-feature-name/
git commit -m "feat(specs): add NNN-feature-name implementation plan"

12. Next Steps

Inform the user:

> Plan complete for `NNN-feature-name`! > Ready to implement. Use tasks.yaml to track progress. > > ⚠️ **MANDATORY TDD**: Each phase follows RED-GREEN-REFACTOR: > > 1. RED: Write failing test FIRST > 2. GREEN: Write minimal code to pass > 3. REFACTOR: Improve while keeping tests green > > **MANDATO