Skip to Content
IntegrationsClaude Code

Claude Code

Connect SpecForge to Claude Code with MCP tools and Agent Teams for autonomous parallel implementation.

Claude Code is SpecForge’s deepest integration. The CLI generates not just MCP configuration, but specialized agents, operational skills, and Agent Teams orchestration — everything Claude Code needs to plan, implement, and validate a specification autonomously.

Other agents get MCP access. Claude Code gets the full stack.

Quick Setup

From the root of your repository:

specforge init

The CLI detects Claude Code and generates:

FilePurpose
.mcp.jsonRegisters the SpecForge MCP server — 22 tools available
CLAUDE.mdAnchors the project context — which SpecForge project and specification this repo is connected to
.claude/skills/Operational skills that teach Claude Code how to use SpecForge MCP tools for planning, implementation, and validation
.claude/agents/Specialized agent definitions for orchestrated parallel implementation via Agent Teams
.specforge/config.jsonProject and specification IDs, Agent Teams configuration

If you already have a .mcp.json with other servers, specforge init merges the SpecForge entry without touching your existing configuration.

✅ Run specforge scaffold --target claude-code to regenerate only the Claude Code files without going through the full init flow.

MCP Configuration

The generated .mcp.json:

{
  "mcpServers": {
    "specforge": {
      "command": "npx",
      "args": ["-y", "@specforge/cli@latest"],
      "env": {
        "SPECFORGE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code detects this on next startup. All 22 SpecForge tools become available in conversation.

Available Tools

Once connected, Claude Code has access to the full SpecForge toolkit:

  • Planning — Create and manage specifications, epics, tickets, dependencies, and blueprints
  • Queries — Fetch tickets, get dependency trees, find blockers, view critical paths
  • Implementation — Start work sessions, link commits and PRs, review implementations
  • Reports — Generate progress reports, validate specification completeness

All tools are callable naturally in conversation. Tell Claude Code what you want, and it picks the right tool.

What Makes Claude Code Different

Agents

The .claude/agents/ directory contains agent definitions that Claude Code loads automatically. These aren’t generic instructions — they’re specialized roles designed around the SpecForge workflow:

  • Planning agents guide you through specification refinement, asking the right questions about goals, constraints, edge cases, and acceptance criteria
  • Implementation agents know how to pick up tickets, follow implementation steps, report progress, and complete work sessions
  • Validation agents check completed work against acceptance criteria and report findings

Skills

The .claude/skills/ directory contains operational skills — step-by-step protocols for using SpecForge MCP tools correctly. Skills encode the workflow so Claude Code doesn’t need to figure out tool sequencing from scratch:

  • How to start a planning session and iterate through decomposition
  • How to claim a ticket, implement it, and close the work session
  • How to run reviews and address findings
  • How to handle blocks and discoveries during implementation

Agent Teams

This is the headline capability. With Agent Teams enabled, Claude Code can coordinate multiple parallel workers implementing your specification simultaneously.

Set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Run specforge init (or re-run with --force if already initialized). The CLI generates Agent Teams orchestration files:

FileRole
orchestrator.mdReads the specification, analyzes the dependency graph, assigns tickets to workers, monitors progress
worker.mdImplements a single ticket — reads context, writes code, runs tests, reports results
validator.mdReviews completed work — checks acceptance criteria, runs test suites, flags issues
conventions.mdShared rules for code style, commit messages, branch naming, PR structure

Then start Claude Code and say:

Implement the active SpecForge specification

The orchestrator reads your spec, identifies actionable tickets (all dependencies satisfied), spawns workers per epic, and coordinates parallel execution. Validators check each completed ticket. The dependency graph ensures workers never collide.

ℹ️ Agent Teams is a Claude Code feature (Opus 4.6+, experimental). SpecForge doesn’t build its own orchestration on top of Claude Code — it generates the configuration that makes Agent Teams work with your dependency graph out of the box.

Workflow: Planning + Implementation

A typical workflow using Claude Code with SpecForge:

Planning (conversational):

  1. “Create a new specification for user authentication”
  2. Claude Code calls create_specification
  3. “Decompose this into epics and tickets”
  4. Claude Code runs the planning session, creates structure, links dependencies
  5. “Run the planning review”
  6. Claude Code calls review_planning, shows the score and findings
  7. You refine based on feedback, re-run until the gate passes

Implementation (autonomous):

  1. “Implement the active specification”
  2. Claude Code (with Agent Teams) spawns workers, implements in parallel
  3. You monitor from the dashboard or with specforge status
  4. After all tickets complete, Claude Code runs the implementation review
  5. Address any findings, re-run if needed

The transition from planning to implementation is seamless — same tool, same session, same MCP connection.

Manual Configuration

If you prefer to configure manually instead of using specforge init:

# Generate only Claude Code files
specforge scaffold --target claude-code

This creates the MCP config, CLAUDE.md, agents, and skills without the interactive project selection flow.

Next Steps

BlueprintsClaude Desktop