Skip to main content
Agent skill

Shep Kit:Plan

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

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Shep Kit:Plan when an AI agent needs a reusable SKILL.md workflow for this job: 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

When not to use it

Skip Shep Kit:Plan when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/shep-kitplan
# Save SKILL.md to ~/.claude/skills/shep-kitplan/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/shep-kitplan/SKILL.md. For a shared project, commit the folder at .claude/skills/shep-kitplan/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Shep Kit:Plan skill for this task: Use Shep Kit:Plan when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
62/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# 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:**

```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):

```bash # 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

```bash 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 > > **MANDATORY Phase Completion Workflow**: > > After EACH phase: > > 1. Update tasks.yaml status fields FREQUENTLY (as you complete items, not at the end!) > 2. Commit and push: `git add . && git commit -m "feat: complete phase N" && git push` > 3. Watch CI: `gh run watch --exit-status` > 4. If CI fails: Fix → Commit → Push → Watch again (LOOP until green) > 5. Only proceed to next phase after CI passes > > **IMPORTANT:** After implementation, update all spec file statuses to "Complete"

## Key Principles

- **Gate enforcement**: Never skip the open questions check - **TDD MANDATORY**: Plans MUST follow RED-GREEN-REFACTOR cycles for all implementation phases - **Tests FIRST**: Every TDD phase starts with failing tests, never implementation first - **Incremental**: Each phase produces working, tested code - **Parallel-aware**: Mark independent tasks for concurrent execution - **Reversible**: Always have a rollback plan - **Status tracking**: Always update Phase fields before committing

## Template Locations

- Plan: `.claude/skills/shep-kit-new-feature/templates/plan.yaml` - Tasks: `.claude/skills/shep-kit-new-feature/templates/tasks.yaml` - Data Model: `.claude/skills/shep-kit-new-feature/templates/data-model.md`

## Example

See: `.claude/skills/shep-kit-plan/examples/sample-plan.md`

Intended uses

  • Use Shep Kit:Plan when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.