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 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?
mkdir -p ~/.claude/skills/shep-kitplan # Save SKILL.md to ~/.claude/skills/shep-kitplan/SKILL.md
- 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.
- 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.
- 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.
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.