Spec-Driven Development: Specification Skill

Overview

Skill(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:

• Analyze codebase structure using Explore agents and LSP
• Design phased implementation approaches
• Create JSON specifications with task hierarchies
• Define verification steps for each phase
• Automatic AI review of specifications
• Apply review feedback as modifications
• Validate and auto-fix specifications

Integrated Workflow

This skill follows a plan-first methodology. A markdown plan is MANDATORY before JSON spec creation, with human approval required after AI review.

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│  1. Analyze    2. Create Plan    3. Plan Review   4. APPROVAL   5. Create Spec   6. Spec Review   7. Validate │
│  ──────────    ─────────────     ────────────     ───────────   ─────────────    ────────────     ──────────  │
│  Explore/LSP → plan-create   →   plan-review  →  HUMAN GATE →  spec-create  →   spec-review  →  validate-fix │
│  (understand)  (MANDATORY)       (AI feedback)   (approve)     (from plan)      (MANDATORY)     (auto-fix)   │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Flow

[x?]=decision · (GATE)=user approval · →=sequence · ↻=loop

- **Entry** → UnderstandIntent → Analyze[Explore|LSP]
- **Plan** (MANDATORY)
  - `plan action="create"` → create markdown plan
  - Fill in plan content with analysis results
- **Plan Review** → `plan action="review"`
  - [critical/high?] → Revise plan, re-review
  - ↻ Self-iterate until no critical/high issues remain
  - Present final plan + review summary to user
- **(GATE: approve plan)**
  - Present plan summary + AI review findings to user
  - User must explicitly approve via AskUserQuestion
  - [approved] → continue to spec creation
  - [revise] → ↻ back to plan editing
  - [abort] → **Exit** (no spec created)
- **Spec Creation** → `authoring action="spec-create"`
  - `authoring action="phase-add-bulk"` ↻ per phase
  - `authoring action="spec-update-frontmatter"` → mission/metadata
- **Spec Review** (MANDATORY) → `review action="spec"`
  - [critical/high?] → `review action="parse-feedback"` → fix spec → re-review
  - ↻ Self-iterate until no critical/high issues remain
  - Present final spec + review summary to user
  - (GATE: approve remaining modifications) → `spec action="apply-plan"`
- **Validate** → `spec action="validate"` ↻ [errors?] → `spec action="fix"`
- **Exit** → specs/pending/{spec-id}.json

When to Use This Skill

Use for:

• New features or significant functionality additions
• Complex refactoring across multiple files
• API integrations or external service connections
• Architecture changes or system redesigns
• Any task requiring precision and reliability

Do NOT use for:

• Simple one-file changes or bug fixes
• Trivial modifications or formatting changes
• Exploratory prototyping or spikes
• Finding next task or tracking progress (use foundry-implement)

MCP Tooling

Router	Key Actions
authoring	spec-create, spec-update-frontmatter, phase-add-bulk, phase-move, phase-update-metadata, assumption-add, assumption-list, constraint-add, constraint-list, risk-add, risk-list, question-add, question-list, success-criterion-add, success-criteria-list
spec	validate, fix, apply-plan, completeness-check, duplicate-detection, stats, analyze-deps
review	spec, parse-feedback, list-tools
task	add, remove, move, update-metadata

Critical Rule: NEVER read spec JSON files directly with Read() or shell commands.

Core Workflow

Step 1: Understand Intent

Before creating any plan:

• Core objective: What is the primary goal?
• Spec mission: Single-sentence mission for metadata.mission
• Success criteria: What defines "done"?
• Constraints: What limitations or requirements exist?

Step 2: Analyze Codebase

Use Explore subagents for large codebases (prevents context bloat), or Glob/Grep/Read for targeted lookups.

LSP-Enhanced Analysis for refactoring:

• documentSymbol - Understand file structure
• findReferences - Assess impact (count affected files)
• goToDefinition - Navigate to implementations

See references/codebase-analysis.md for detailed patterns.

Step 3: Create Phase Plan (MANDATORY)

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"

The command creates a template at specs/.plans/feature-name-YYYY-MM-DD.md (date is auto-appended). Fill in all sections:

• Mission statement (becomes metadata.mission)
• Objectives and success criteria
• Assumptions and constraints
• Phase breakdown with tasks
• Risks, dependencies, and open questions

After completing the plan:

1. Run AI review (Step 4)
2. Obtain human approval (Step 5)
3. Then proceed to JSON spec creation (Step 6)

See references/phase-authoring.md for templates and bulk macros. See references/phase-plan-template.md for the plan structure.

Step 4: Run AI Review on Plan

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-YYYY-MM-DD.md"

Review output: Saved to specs/.plan-reviews/<plan-name-YYYY-MM-DD>-review.md

Important: Use the actual plan_path returned by the create step — do not hardcode the path.

All 6 dimensions are always assessed: Completeness, Architecture, Sequencing, Feasibility, Risk, Clarity.

Self-iterate before presenting to user: Address all critical and high issues yourself:

1. Read the review feedback
2. Revise the plan to address critical/high findings
3. Re-run review
4. Repeat until no critical/high issues remain
5. Then present the clean plan + review summary at the human approval gate

See references/ai-review.md for review output format and iteration workflow.

Step 5: Human Approval Gate (MANDATORY)

Before creating the JSON spec, obtain explicit user approval.

Present to user:

1. Plan summary (mission, phases, task count)
2. What you fixed during self-iteration (critical/high issues resolved)
3. Any remaining medium/low findings for awareness
4. Any unresolved questions or risks

Use AskUserQuestion with options:

• "Approve & Create JSON Spec" - Proceed to Step 6
• "Revise Plan" - Return to Step 3 for modifications
• "Abort" - Exit without creating spec

CRITICAL: Do NOT proceed to JSON spec creation without explicit "Approve" response.

Step 6: Create JSON Specification (From Approved Plan)

mcp__plugin_foundry_foundry-mcp__authoring action="spec-create" name="feature-name" template="empty" plan_path="specs/.plans/feature-name-YYYY-MM-DD.md" plan_review_path="specs/.plan-reviews/feature-name-YYYY-MM-DD-review.md"

Important: Use the actual paths returned by the create and review steps. The date suffix is auto-generated.

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"

Step 6a: Enrich Spec Metadata (From Approved Plan)

After creating the spec, populate structured metadata extracted from the approved plan:

# Add constraints from plan
mcp__plugin_foundry_foundry-mcp__authoring action="constraint-add" spec_id="{spec-id}" text="Must maintain backward compatibility with v2 API"

# Add risks from plan
mcp__plugin_foundry_foundry-mcp__authoring action="risk-add" spec_id="{spec-id}" description="OAuth provider rate limits" likelihood="medium" impact="high" mitigation="Implement token caching"

# Add open questions from plan
mcp__plugin_foundry_foundry-mcp__authoring action="question-add" spec_id="{spec-id}" text="Which OAuth scopes are required for the admin flow?"

# Add success criteria from plan
mcp__plugin_foundry_foundry-mcp__authoring action="success-criterion-add" spec_id="{spec-id}" text="All protected endpoints return 401 without valid token"

# Add assumptions
mcp__plugin_foundry_foundry-mcp__authoring action="assumption-add" spec_id="{spec-id}" text="Single GCP project for staging and production"

See references/metadata-management.md for full action reference and workflow. See references/json-spec.md and references/task-hierarchy.md for structure details.

Step 7: Spec Review — Spec-vs-Plan Comparison (MANDATORY)

After spec creation, the spec review compares the JSON spec against its source plan:

mcp__plugin_foundry_foundry-mcp__review action="spec" spec_id="{spec-id}"

Action name: Use action="spec" (canonical). The alias "spec-review" also works but "spec" is preferred.

The spec review compares the JSON spec against its source plan to catch translation gaps — evaluating coverage, fidelity, success criteria mapping, and preservation of constraints, risks, and open questions. The response includes a verdict of aligned, deviation, or incomplete.

Prerequisites for spec review to succeed:

• The spec must already be saved to disk (completed by spec-create + phase-add-bulk)
• The spec's metadata.plan_path must point to an existing plan file (set during spec-create)
• An AI provider must be available (configured in foundry-mcp.toml or environment)

If the review returns success: false:

1. Check error_code in the response — common causes:
   • SPEC_NOT_FOUND: Verify spec_id is correct via spec action="list"
   • AI_NO_PROVIDER: Check AI provider configuration
   • AI_PROVIDER_TIMEOUT: Retry with a higher ai_timeout value
2. Do NOT retry with a different action name — "spec" and "spec-review" are identical

Self-iterate before presenting to user: Address all critical and high issues yourself:

1. Parse review findings via review action="parse-feedback"
2. Fix the spec to address critical/high findings (using authoring/task MCP tools)
3. Re-run spec review
4. Repeat until no critical/high issues remain
5. Then present the clean spec + review summary to the user

See references/plan-review-workflow.md for detailed review workflow. See references/plan-review-dimensions.md for review dimensions. See references/plan-review-consensus.md for interpreting results.

Step 8: Apply Modifications (If Needed)

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.md for detailed workflow. See references/modification-operations.md for operation formats.

Step 9: Validate Specification

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:

• 0: Valid (no errors)
• 1: Warnings only
• 2: Errors (run fix)
• 3: File error

See references/validation-workflow.md for detailed workflow. See references/validation-fixes.md for fix patterns. See references/validation-issues.md for issue types.

Phase-First Authoring

Use this approach for efficient spec creation:

Step 1: Create spec from approved plan

mcp__plugin_foundry_foundry-mcp__authoring action="spec-create" name="my-feature" template="empty" plan_path="specs/.plans/my-feature-YYYY-MM-DD.md" plan_review_path="specs/.plan-reviews/my-feature-YYYY-MM-DD-review.md"

Both plan_path and plan_review_path are required. Create these first via plan action="create" and plan action="review". Use the actual paths returned by those steps.

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="..."

File Path Policy

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.

Valid Values Reference

Spec Templates

Template	Use Case	Required Fields
empty	All specs (blank with no phases)	Add phases via phase-add-bulk

Task Categories

Category	Requires file_path
investigation	No
implementation	Yes
refactoring	Yes
decision	No
research	No

Node Types

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.md for research node patterns and blocking modes.

Verification Types

Type	Purpose
run-tests	Execute test suite
fidelity	Compare implementation to spec
manual	Manual testing checklist

Best Practice: Every phase should end with a fidelity review task (verification_type: "fidelity"). This ensures implementation matches the spec before moving to the next phase. The foundry-review skill performs this comparison.

Task Statuses

Status	Description
pending	Not yet started
in_progress	Currently being worked on
completed	Finished successfully
blocked	Cannot proceed

Size Guidelines

If >6 phases or >50 tasks, recommend splitting into multiple specs.

Output Artifacts

1. JSON spec file at specs/pending/{spec-id}.json
2. Plan review report at specs/.plan-reviews/{plan-name-YYYY-MM-DD}-review.md
3. Spec review report at specs/.spec-reviews/{spec-id}-spec-review.md
4. Validation passed with no errors

Detailed Reference

Planning:

• Investigation strategies → references/investigation.md
• Phase authoring → references/phase-authoring.md
• Phase plan template → references/phase-plan-template.md
• JSON spec structure → references/json-spec.md
• Task hierarchy → references/task-hierarchy.md
• Metadata management → references/metadata-management.md
• Codebase analysis → references/codebase-analysis.md

Review:

• Review workflow → references/plan-review-workflow.md
• Review dimensions → references/plan-review-dimensions.md
• Consensus interpretation → references/plan-review-consensus.md

Modification:

• Modification workflow → references/modification-workflow.md
• Operation formats → references/modification-operations.md

Validation:

• Validation workflow → references/validation-workflow.md
• Fix patterns → references/validation-fixes.md
• Issue types → references/validation-issues.md

General:

• AI review → references/ai-review.md
• Troubleshooting → references/troubleshooting.md