Plan-first development methodology that creates detailed specifications before coding. Use when building features, refactoring code, or implementing complex changes. Creates structured plans with phases, file-level details, and verification steps to prevent drift and ensure production-ready code.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
reference.mdSkill(foundry:sdd-plan) creates detailed JSON specifications before any code is written. It analyzes the codebase, designs a phased implementation approach, and produces structured task hierarchies with verification steps. The skill enforces staged planning for complex features - first creating a high-level phase plan for user approval, then expanding into detailed tasks.
Core capabilities:
Use this skill when building new features, performing complex refactoring, or implementing changes that span multiple files.
This skill is part of the Spec-Driven Development workflow:
sdd-plan (this skill) --> sdd-plan-review --> sdd-modify --> sdd-next --> Implementation --> sdd-update
After creating a spec, use Skill(foundry:sdd-plan-review) for AI-powered review or proceed directly to Skill(foundry:sdd-next) for task execution.
Use Skill(foundry:sdd-plan) for:
Do NOT use for:
Skill(foundry:sdd-update))Skill(foundry:sdd-next))This skill operates entirely through the Foundry MCP server (foundry-mcp). Tools use the router+action pattern: mcp__plugin_foundry_foundry-mcp__<router> with action="<action>".
| Router | Actions | Purpose |
|---|---|---|
| code | find-class, find-function, trace-calls, impact-analysis | Understand existing code structure |
| plan | create, list, review | Create, list, and review markdown plans |
| authoring | spec-create | Generate specification files |
| spec | validate, validate-fix, list, get, get-hierarchy, schema-export | Validation and querying |
Critical Rules:
Read() or shell commandsGlob/Grep/Read only when documentation is unavailableBefore creating any plan, deeply understand what needs to be accomplished:
Check if documentation exists:
mcp__plugin_foundry_foundry-mcp__code action="doc-stats"
If documentation available, use for analysis:
mcp__plugin_foundry_foundry-mcp__code action="find-class" - Find existing class implementationsmcp__plugin_foundry_foundry-mcp__code action="find-function" - Find function implementationsmcp__plugin_foundry_foundry-mcp__code action="trace-calls" - Trace call graphsmcp__plugin_foundry_foundry-mcp__code action="impact-analysis" - Analyze change impactIf documentation unavailable, fall back to Glob, Grep, and Read.
For large or unfamiliar codebases, use Claude Code's built-in subagents for efficient parallel exploration:
| Scenario | Subagent | Thoroughness |
|---|---|---|
| Initial file structure discovery | Explore | quick |
| Understanding existing patterns | Explore | medium |
| Complex dependency analysis | Explore | very thorough |
| Multi-area architectural research | general-purpose | N/A |
Example: Parallel Exploration
Use the Explore agent (medium thoroughness) to find:
- All files matching the feature area pattern
- Existing implementations of similar functionality
- Test coverage for affected modules
- Related configuration files
Benefits:
For detailed exploration patterns, see
reference.md#parallel-investigation-strategies
For complex features (3+ phases expected), first create a phase-only markdown plan and present to the user for approval before detailed planning.
Option A: Create plan with MCP tool (recommended)
mcp__plugin_foundry_foundry-mcp__plan action="create" name="Feature Name" template="detailed"
This creates specs/.plans/feature-name.md with a structured template.
Option B: Create plan manually
Create a markdown file directly in specs/.plans/ following the phase plan template.
For phase plan template, see
reference.md#phase-plan-template
After creating the plan template, read and fill in the placeholders with your actual plan content (objectives, phases, tasks, risks, success criteria).
Before converting your markdown plan to a formal JSON spec, get AI-powered feedback to catch issues early:
mcp__plugin_foundry_foundry-mcp__plan action="review" plan_path="specs/.plans/feature-name.md" review_type="full"
Review Types:
| Type | Focus |
|---|---|
full | Comprehensive 6-dimension review (completeness, architecture, sequencing, feasibility, risk, clarity) |
quick | Critical blockers and questions only |
security | Security-focused analysis |
feasibility | Technical complexity and risk assessment |
Review → Revise → Repeat:
plan action="create" (creates template in specs/.plans/)plan action="review"specs/.plan-reviews/<plan-name>-<review-type>.mdAI review is required for all specs created with this skill. It catches issues early before they become expensive to fix during implementation.
For review output format and iteration examples, see
reference.md#ai-plan-review
After phase approval, get the spec schema and create the JSON spec:
mcp__plugin_foundry_foundry-mcp__spec action="schema-export"
mcp__plugin_foundry_foundry-mcp__authoring action="spec-create" name="feature-name" template="medium"
The spec file is created at specs/pending/{spec-id}.json.
For JSON specification structure details, see
reference.md#json-specification-structure
Use Skill(foundry:sdd-validate) to validate and auto-fix the specification:
mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id="{spec-id}"
mcp__plugin_foundry_foundry-mcp__spec action="validate-fix" spec_id="{spec-id}" auto_fix=true
| Complexity | Phases | Tasks | Verification Coverage |
|---|---|---|---|
| Short (<5 files) | 1-2 | 3-8 | 20% minimum |
| Medium (5-15 files) | 2-4 | 10-25 | 30-40% |
| Large (>15 files) | 4-6 | 25-50 | 40-50% |
Splitting recommendation: If >6 phases or >50 tasks, recommend splitting into multiple specs.
For task hierarchy details, categories, and dependency tracking, see
reference.md#task-hierarchy
specs/pending/{spec-id}.jsonThe spec file contains the full task hierarchy including phases, tasks, subtasks, and verification steps.
For comprehensive documentation including:
See reference.md