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
- 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
-
Run setup - Ask Claude to configure permissions and verify installation:
Please run foundry-setup to configure the workspace.
-
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.
-
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.
-
Implement - Ask Claude to work through tasks (verification is built into the spec):
Let's implement the next task from the spec.
-
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
foundry-works