Spec-first development methodology that creates detailed specifications before coding. Creates structured specs with phases, file-level details, and verification steps. Includes automatic AI review, modification application, and validation.
Creates detailed JSON specifications with phased implementation plans and automatic AI review.
/plugin marketplace add foundry-works/claude-foundry/plugin install foundry-works-foundry@foundry-works/claude-foundryThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/ai-review.mdreferences/codebase-analysis.mdreferences/investigation.mdreferences/json-spec.mdreferences/modification-operations.mdreferences/modification-workflow.mdreferences/phase-authoring.mdreferences/phase-plan-template.mdreferences/plan-review-consensus.mdreferences/plan-review-dimensions.mdreferences/plan-review-workflow.mdreferences/task-hierarchy.mdreferences/troubleshooting.mdreferences/validation-fixes.mdreferences/validation-issues.mdreferences/validation-workflow.mdSkill(foundry:foundry-spec) creates detailed JSON specifications before any code is written. It analyzes the codebase, designs a phased implementation approach, produces structured task hierarchies, and runs automatic quality checks including AI review.
Core capabilities:
This skill follows a plan-first methodology. A markdown plan is MANDATORY before JSON spec creation, with human approval required after AI review.
See the flow below for the NBS version of the workflow.
[x?]=decision ·(GATE)=user approval ·→=sequence ·↻=loop
- **Entry** → Understand intent → Analyze
- [LSP available?] → LSP analysis
- [else] → Explore analysis
- **Plan** → `plan action="create"` → Fill plan content
- **Plan Review** → `plan action="review"`
- [findings?] → Revise plan → ↻ back to Plan Review
- (GATE: approve plan)
- [approved] → **Spec Creation** → `authoring action="spec-create"`
- `authoring action="phase-add-bulk"` → Add phases
- `authoring action="spec-update-frontmatter"` → Update mission/metadata
- **Spec Review** → `review action="spec-review"`
- [findings?] → `review action="parse-feedback"`
- (GATE: approve modifications) → `spec action="apply-plan"`
- **Validate** → `spec action="validate"`
- [errors?] → `spec action="fix"` → ↻ back to Validate
- **Exit** → specs/pending/{spec-id}.json
- [revise] → ↻ back to Plan
- [abort] → **Exit**: no spec created
Use for:
Do NOT use for:
foundry-implement)| Router | Key Actions |
|---|---|
authoring | spec-create, spec-update-frontmatter, phase-add-bulk, phase-template, phase-move, phase-update-metadata, assumption-add, assumption-list |
spec | validate, fix, apply-plan, completeness-check, duplicate-detection, stats, analyze-deps |
review | spec-review, parse-feedback, list-tools |
task | add, remove, move, update-metadata |
Critical Rule: NEVER read spec JSON files directly with Read() or shell commands.
Before creating any plan:
metadata.missionUse Explore subagents for large codebases (prevents context bloat), or Glob/Grep/Read for targeted lookups.
LSP-Enhanced Analysis for refactoring:
documentSymbol - Understand file structurefindReferences - Assess impact (count affected files)goToDefinition - Navigate to implementationsSee
references/codebase-analysis.mdfor detailed patterns.
This step is REQUIRED. All specifications must begin as markdown plans before JSON conversion.
mcp__plugin_foundry_foundry-mcp__plan action="create" name="Feature Name" template="detailed"
The command creates a template at specs/.plans/feature-name.md. Fill in all sections:
metadata.mission)After completing the plan:
See
references/phase-authoring.mdfor templates and bulk macros. Seereferences/phase-plan-template.mdfor the plan structure.
After completing the markdown plan, run AI review to catch issues before JSON conversion:
mcp__plugin_foundry_foundry-mcp__plan action="review" plan_path="specs/.plans/feature-name.md" review_type="full"
Review types for plans:
| Type | Focus | Use When |
|---|---|---|
quick | Critical blockers only | Simple plans |
full | All dimensions | Complex features |
security | Auth, data handling | Security-sensitive |
feasibility | Estimates, dependencies | Tight deadlines |
Review output: Saved to specs/.plan-reviews/<plan-name>-<review-type>.md
Iterate if needed: If the review identifies issues:
See
references/ai-review.mdfor review output format and iteration workflow.
Before creating the JSON spec, obtain explicit user approval.
Present to user:
Use AskUserQuestion with options:
CRITICAL: Do NOT proceed to JSON spec creation without explicit "Approve" response.
mcp__plugin_foundry_foundry-mcp__authoring action="spec-create" name="feature-name" template="empty"
Add phases with tasks:
mcp__plugin_foundry_foundry-mcp__authoring action="phase-add-bulk" spec_id="{spec-id}" phase='{"title": "Implementation", "description": "Core work"}' tasks='[{"type": "task", "title": "Build core logic", "task_category": "implementation", "file_path": "src/core.py", "acceptance_criteria": ["Workflow works"]}]'
Update metadata:
mcp__plugin_foundry_foundry-mcp__authoring action="spec-update-frontmatter" spec_id="{spec-id}" key="mission" value="Single-sentence objective"
Add assumptions:
mcp__plugin_foundry_foundry-mcp__authoring action="assumption-add" spec_id="{spec-id}" text="Single GCP project for staging and production"
mcp__plugin_foundry_foundry-mcp__authoring action="assumption-add" spec_id="{spec-id}" text="Shared Redis with key prefix isolation" assumption_type="constraint"
List assumptions:
mcp__plugin_foundry_foundry-mcp__authoring action="assumption-list" spec_id="{spec-id}"
See
references/json-spec.mdandreferences/task-hierarchy.mdfor structure details.
After spec creation, AI review runs automatically:
mcp__plugin_foundry_foundry-mcp__review action="spec-review" spec_id="{spec-id}" review_type="full"
Review types:
| Type | Models | Focus | Use When |
|---|---|---|---|
quick | 2 | Completeness, Clarity | Simple specs |
full | 3-4 | All 6 dimensions | Complex specs |
security | 2-3 | Risk Management | Auth, data handling |
feasibility | 2-3 | Estimates, Dependencies | Tight deadlines |
See
references/plan-review-workflow.mdfor detailed review workflow. Seereferences/plan-review-dimensions.mdfor review dimensions. Seereferences/plan-review-consensus.mdfor interpreting results.
If review finds issues, parse and apply feedback:
# Parse review feedback into modifications
mcp__plugin_foundry_foundry-mcp__review action="parse-feedback" spec_id="{spec-id}" review_path="path/to/review.md"
# Preview changes (always preview first!)
mcp__plugin_foundry_foundry-mcp__spec action="apply-plan" spec_id="{spec-id}" modifications_file="suggestions.json" dry_run=true
# Apply changes (backup created automatically)
mcp__plugin_foundry_foundry-mcp__spec action="apply-plan" spec_id="{spec-id}" modifications_file="suggestions.json"
See
references/modification-workflow.mdfor detailed workflow. Seereferences/modification-operations.mdfor operation formats.
Validate and auto-fix the specification:
# Validate
mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id="{spec-id}"
# Auto-fix common issues
mcp__plugin_foundry_foundry-mcp__spec action="fix" spec_id="{spec-id}"
# Re-validate until clean
mcp__plugin_foundry_foundry-mcp__spec action="validate" spec_id="{spec-id}"
Exit codes:
See
references/validation-workflow.mdfor detailed workflow. Seereferences/validation-fixes.mdfor fix patterns. Seereferences/validation-issues.mdfor issue types.
Use this approach for efficient spec creation:
Step 1: Create spec from template
mcp__plugin_foundry_foundry-mcp__authoring action="spec-create" name="my-feature" template="empty"
Step 2: Add phases with bulk macro
mcp__plugin_foundry_foundry-mcp__authoring action="phase-add-bulk" spec_id="{spec-id}" phase='{"title": "Phase 1"}' tasks='[...]'
Step 3: Fine-tune tasks Use modification operations to adjust individual tasks.
Step 4: Update frontmatter
mcp__plugin_foundry_foundry-mcp__authoring action="spec-update-frontmatter" spec_id="{spec-id}" key="mission" value="..."
For implementation or refactoring tasks, set metadata.file_path to a real repo-relative path. Do not guess or use placeholders. If unclear, use task_category: "investigation" first.
| Template | Use Case | Required Fields |
|---|---|---|
simple | Small tasks | Basic fields only |
medium | Standard features | mission, description, acceptance_criteria, task_category |
complex | Large features | All medium + detailed metadata |
security | Security-sensitive | All complex + security review |
| Category | Requires file_path |
|---|---|
investigation | No |
implementation | Yes |
refactoring | Yes |
decision | No |
research | No |
| Node Type | type Value | Key Fields |
|---|---|---|
| Task | "task" | task_category, file_path |
| Research | "research" | research_type, blocking_mode, query |
| Verification | "verify" | verification_type |
See
references/task-hierarchy.mdfor research node patterns and blocking modes.
| Type | Purpose |
|---|---|
run-tests | Execute test suite |
fidelity | Compare implementation to spec |
manual | Manual testing checklist |
| Status | Description |
|---|---|
pending | Not yet started |
in_progress | Currently being worked on |
completed | Finished successfully |
blocked | Cannot proceed |
If >6 phases or >50 tasks, recommend splitting into multiple specs.
specs/pending/{spec-id}.jsonspecs/.plan-reviews/{spec-id}-review-{type}.mdPlanning:
references/investigation.mdreferences/phase-authoring.mdreferences/phase-plan-template.mdreferences/json-spec.mdreferences/task-hierarchy.mdreferences/codebase-analysis.mdReview:
references/plan-review-workflow.mdreferences/plan-review-dimensions.mdreferences/plan-review-consensus.mdModification:
references/modification-workflow.mdreferences/modification-operations.mdValidation:
references/validation-workflow.mdreferences/validation-fixes.mdreferences/validation-issues.mdGeneral:
references/ai-review.mdreferences/troubleshooting.mdActivates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Activates when the user asks about Agent Skills, wants to find reusable AI capabilities, needs to install skills, or mentions skills for Claude. Use for discovering, retrieving, and installing skills.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.