claude-foundry

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