Claude Foundry - Spec-Driven Development for Claude Code

Plan before you code. Verify against the spec. Ship with confidence.

Overview

Ad-hoc coding with AI assistants often leads to unclear requirements, untracked progress, and implementation drift. Claude Foundry brings structure to AI-assisted development through spec-driven development (SDD): you create a detailed specification first, then implement against it with granular task tracking and AI-powered verification.

Who it's for: Developers using Claude Code who want traceable, auditable AI-assisted development with clear requirements and verifiable outcomes.

Table of Contents

• Key Features
• Prerequisites
• Installation
• Quick Start
• Example Workflow
• How It Works
• Skills Reference
• Configuration
• Scope and Limitations
• Documentation
• Support
• License

Key Features

• Spec-Driven Methodology - Plan before code with mandatory human approval gates. Specs define requirements, phases, tasks, and verification steps.
• Fidelity Verification - AI compares implementation to spec requirements. Catches drift between what was planned and what was built.
• Task Dependencies & Tracking - Granular task states with automatic next-task recommendations. Know what's done, blocked, or ready.
• Auditable Decision Journals - Every task completion logs decisions made. Full traceability of why changes happened.
• Context Flow to PRs - PR descriptions generated from spec + journals + git history. Reviewers understand the "why", not just the "what".
• Multi-Model Research - Query multiple AI models for consensus, deep research, or structured ideation before planning.

Prerequisites

Requirement	Version	Notes
Python	3.10+	Required for foundry-mcp server
Claude Code	Latest	The CLI tool from Anthropic
foundry-mcp	Latest	MCP server (installed via pip)

Installation

1. Install foundry-mcp

pip install foundry-mcp

Or with pipx for isolated installation:

pipx install foundry-mcp

Verify installation:

python -m foundry_mcp.server --help

2. Install the plugin

From within Claude Code:

/plugin marketplace add foundry-works/claude-foundry
/plugin install foundry@claude-foundry

Restart Claude Code and trust the repository when prompted.

Note: The MCP server is automatically registered when you install the plugin. Do not manually add it with claude mcp add.

Quick Start

1. Run setup - Ask Claude to configure permissions and verify installation:

   Please run foundry-setup to configure the workspace.
   

2. Research (optional) - Ask Claude to explore the codebase or research best practices:

   Research how authentication is currently handled in this codebase.
   Do deep research on current best practices for JWT refresh tokens.
   

3. Describe what you want - Tell Claude what you want to build:

   I want to add user authentication with JWT tokens.
   

   Claude creates a spec with phases, tasks, and verification steps.

4. Implement - Ask Claude to work through tasks (verification is built into the spec):

   Let's implement the next task from the spec.
   

5. Ship - Create a PR when the spec is complete:

   Create a pull request for this completed spec.
   

Example Workflow

A complete spec-driven development cycle:

# 1. Research (optional): Understand existing patterns
"Research how the current API handles errors"
# Single-model chat, multi-model consensus, or deep web research

# 2. Describe your feature: Claude creates the spec
"I want to add rate limiting to the API endpoints"
# Claude invokes foundry-spec, asks clarifying questions, creates spec
# Spec saved to specs/pending/, then activated after your approval

# 3. Implement: Work through tasks
"Let's implement the next task"
# Shows next task, you implement it, verification tasks auto-dispatch
# When foundry-implement hits a verify task, it runs foundry-review or tests

# 4. Ship: Create PR when spec is complete
"Create a PR for this spec"
# Generates PR from spec metadata, journals, and git history

How It Works

research → describe intent → implement → (auto-verify) → create PR
    │             │               │              │             │
    ▼             ▼               ▼              ▼             ▼
 Explore      Claude          Work on       Verify tasks    Create PR
 codebase     creates         tasks via     auto-dispatch   with full
 or web       spec            dependency    to review       context
                              order         or tests

Step	What happens
Research	Optional first step to explore the codebase or research best practices via web search.
Describe intent	Tell Claude what you want to build. Claude creates a spec with phases, tasks, and verification steps.
Implement	Ask Claude to implement - it finds next task by dependency order. You implement, it tracks progress.
Auto-verify	Specs include verify tasks. When implementation hits one, it auto-dispatches to foundry-review or runs tests directly.
Ship	Ask to create PR - generates from spec metadata, journals, and commit history.

Skill Architecture

Under the hood, these skills power the workflow:

foundry-research → foundry-spec → foundry-implement → [CODE] → foundry-review
        │              │                │               │            │
        ▼              ▼                ▼               ▼            ▼
     Explore        Create          Find next        Write        Verify
     codebase        spec            task            code         against
     or web                          and                          spec
                                    track

Skills Reference

Skills are invoked by Claude based on your intent. Describe what you want, and Claude selects the appropriate skill.

Skill	When Claude uses it
foundry-spec	You describe a feature or ask to plan something
foundry-implement	You ask to work on tasks or implement features
foundry-review	Verify task in spec, or you ask to check implementation
foundry-research	You ask to research or investigate something
foundry-setup	First-time setup and permissions configuration

Configuration

The plugin stores configuration in foundry-mcp.toml. Key settings:

Setting	Default	Description
workspace	Current directory	Working directory for specs
specs_dir	specs/	Where specs are stored
providers	System default	AI providers for research workflows

Specs are organized by status:

specs/
├── pending/    # Specs in planning phase
├── active/     # Specs being implemented
└── completed/  # Finished specs (archived)

Scope and Limitations

Best for:

• Feature development with clear requirements
• Bug fixes that benefit from structured investigation
• Multi-phase projects where progress tracking matters
• Work that needs auditable history (journals, specs)

Not for:

• One-line fixes or trivial changes
• Exploratory prototyping without clear goals
• Tasks where overhead exceeds benefit

Documentation

Guide	Description
Quick Start	Get started in 5 minutes
Core Concepts	Understand specs, phases, tasks
Workflow Guide	The complete SDD workflow
Tutorial	Build a feature from start to finish
Command Reference	All commands and options
Troubleshooting	Common issues and solutions

Support

• Issues: GitHub Issues
• Bugs: Open an issue with steps to reproduce
• Features: Open an issue describing the use case

License

MIT