SpecForge

Spec Driven Development for AI coding agents.

📚 Documentation · 🇪🇸 Documentación en Español

Installation

Claude Desktop / Claude Code

Add to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "specforge": {
      "command": "npx",
      "args": ["-y", "specforge-mcp@latest"]
    }
  }
}

Requires Node.js ≥ 22. No API keys or accounts needed — all data is stored locally.

Auto-updates: Using @latest ensures users always get the current version. Every time the MCP server starts, npx checks the npm registry and downloads any newer release automatically — no reinstall needed.

What is SpecForge?

SpecForge is an MCP (Model Context Protocol) server that brings Spec Driven Development to AI coding agents. It manages the full spec lifecycle -- from requirements clarification and spec creation to estimation, validation, and drift detection. It enforces a project Constitution (immutable architectural principles extracted from CLAUDE.md and .cursorrules), validates DoR/DoD at every lifecycle transition, generates PLAN.md execution files for implementing specs step-by-step, and detects spec versioning drift with cascading downstream impact analysis. Language and framework agnostic, it works with any stack and learns from your codebase over time.

SDD Lifecycle

clarify → create_spec → DoR check → implement (PLAN.md) → validate → drift detection → done

Each transition is gated by DoR (Definition of Ready) and DoD (Definition of Done) checklists. Constitution compliance is enforced automatically at create_spec, audit, and detect_drift. Spec versioning tracks every change and flags downstream spec impact when a dependency drifts.

Getting Started

1. Initialize your project

"Initialize my project at /Users/me/my-app with specforge"

SpecForge scans the directory and auto-detects your language, framework, package manager, and architecture style. It returns a projectId (e.g., proj_abc123) you'll use in all subsequent commands. No manual configuration needed.

2. Create your first spec

"Create a spec for adding Google OAuth authentication to my project proj_abc123"

SpecForge generates a full HU.md with acceptance criteria, a DoR checklist, database schema hints, and a step-by-step PLAN.md. All stored locally — no accounts, no cloud.

3. Implement guided by the spec

Claude uses the spec as a development contract while you code. When you're done, validate coverage:

"Validate spec SPEC-001 against the code at /Users/me/my-app/src"

4. Detect drift

As the codebase evolves, keep specs in sync:

"Check if my implementation matches SPEC-001 spec"

SpecForge reports which criteria are covered, missing, or drifted — and flags downstream specs affected by the change.

Use Cases

New feature

"Use specforge to create a spec for [feature] in project [id]"

Audit dependencies

"Audit the stack of my project [id] and suggest improvements"

Plan a migration

"Create a migration plan from Express to Fastify for project [id]"

Reverse engineer existing code

"Reverse engineer my codebase at /path/to/project and generate specs"

Detect tech debt

"Analyze tech debt in project [id]"

Features

A -- Configuration

| Tool | Description | |------|-------------| | set_locale | Change the active locale for messages and spec templates | | init_project | Initialize a project -- detects language, framework, architecture, and stores project knowledge; also detects AI-native architecture patterns (inference mode, orchestration frameworks), frontend performance setup (Core Web Vitals budgets, SSR frameworks), and K3s/Nomad workload orchestrators | | init_constitution | Generate the project constitution -- immutable architectural principles extracted from CLAUDE.md, .cursorrules; auto-enforced in create_spec, audit, and drift detection |

B -- Spec Lifecycle

| Tool | Description | |------|-------------| | clarify_requirements | Generate targeted clarification questions before creating a spec | | create_spec | Create a full SDD spec with auto-generated sections: ADR hints, DB schema, UI contracts, test plan, execution plan, DoR checklist; generates AI-native architecture criteria (latency budgets, fallback chains, prompt versioning) and frontend performance criteria (Core Web Vitals, SSR hydration, MFE boundaries) when detected | | list_specs | List all specs for a project, optionally filtering by status | | update_status | Transition a spec through its lifecycle with DoR/DoD validation at each step | | summarize_spec | Generate a concise summary of a spec | | generate_checklist | Generate a quality checklist for a spec | | reconcile_spec | Reconcile spec with implementation changes, with per-change approval and Constitution compliance check | | manage_scope | Manage the project scope definition and backlog | | detect_contradictions | Analyze all specs in a project for semantic contradictions | | check_readiness | Evaluate if a spec is ready for implementation -- completeness, criteria quality, and dependency status | | package_handoff | Generate a structured handoff package for an AI agent to implement a spec, including objective, criteria, file list, and constraints |

C -- Analysis and Estimation

| Tool | Description | |------|-------------| | estimate | Estimate effort, cost, and token usage for a spec using multi-agent analysis | | reverse_engineer | Analyze existing code and generate an SDD spec from it | | validate | Validate implementation against its spec -- coverage, drift, and quality | | detect_drift | Detect drift between spec and implementation -- includes Constitution compliance, downstream spec impact | | audit | Audit code for SOLID, clean code, architecture, and Constitution violations; generates quality score 0-100 | | learn_pattern | Teach the system a new pattern (architecture, convention, estimation, stack, quality) | | security_check | Analyze a spec against OWASP Top 10, scan code for insecure patterns, and generate a security score (A–F) with drift detection | | capture_learning | Capture a discovered pattern or lesson into the spec system with semantic deduplication | | paradigm_report | Detect and report the programming paradigms used in a project | | reality_check | Evaluate whether a set of requirements is feasible given the project context |

D -- Design and Planning

| Tool | Description | |------|-------------| | generate_adr | Generate Architecture Decision Records for a spec | | design_schema | Design database schema from spec requirements | | define_ui_contract | Define UI component contracts, data flow, and state management | | challenge_spec | Stress-test a spec for failures, concurrency, scale, and edge cases | | generate_execution_plan | Generate a step-by-step PLAN.md for implementing a spec -- RED/GREEN/VERIFY cycle with parallelizable steps | | generate_orchestration_script | Generate a 3-layer parallel automation script (worktrees + claude -p) for running specs concurrently | | event_contracts | Manage event-driven architecture contracts -- generate JSON Schema event contracts for producer/consumer validation |

E -- Stack and Agents

| Tool | Description | |------|-------------| | suggest_stack | Suggest a technology stack based on project requirements | | check_versions | Check dependency versions for updates, deprecations, and security issues | | generate_skill | Generate an agent skill file for a specific platform | | detect_agent | Detect the AI coding agent platform in use | | generate_sub_agent | Generate a sub-agent definition for multi-agent orchestration | | generate_rules | Generate agent rules files (.cursorrules, CLAUDE.md, etc.) |

F -- Dev Lifecycle

| Tool | Description | |------|-------------| | suggest_tooling | Assess and suggest dev lifecycle tooling (CI/CD, testing, monitoring, etc.); includes AI-native tooling recommendations (LLM observability, semantic cache, prompt management, guardrails) and frontend performance tooling (Lighthouse CI, visual regression, component libraries) | | generate_tests | Generate test plan and test files from a spec | | generate_docs | Generate documentation from specs and code | | integrate_pm | Integrate with project management tools (Jira, Linear, GitHub Issues, etc.) |

G -- Infrastructure

| Tool | Description | |------|-------------| | manage_context | Save, load, and manage persistent context notes across sessions | | manage_git | Git integration -- branches, PRs, changelogs, hooks linked to specs | | orchestrate | Multi-agent orchestration -- register agents, lock resources, distribute tasks | | consult_docs | Consult framework documentation for a specific topic | | discover_mcps | Discover MCP servers configured in the environment | | suggest_mcps | Suggest MCP servers that could benefit the project | | migrate_tech | Guide tech stack migration -- analyze source codebase, map equivalences, generate migration plan, validate functional parity, and plan DB migration | | orchestrate_agents | Declare agent capabilities, route tasks to the best agent, generate structured handoff contexts, and detect file-ownership conflicts before parallel execution | | validate_workflow | Validate developer workflow conventions: suggest the right AI model for a task, detect Git Flow violations, audit MCP tool conventions, or run a full workflow audit | | log_decision | Register, list, search, or supersede architectural and process decisions for a project | | facilitate | Entry point for users unfamiliar with SpecForge -- guides them through the SDD workflow interactively | | request_context | Generate a prompt that asks the user for reference documentation (README, PRD, architecture docs) | | contribute_context | Persist structured knowledge extracted from user-provided documents into the project knowledge base |

H -- Governance & Stack Health

| Tool | Description | |------|-------------| | data_governance | Detect PII in specs, generate retention policies, draft privacy notices, and audit GDPR/CCPA/LGPD compliance | | audit_stack | Audit all project dependencies, classify as up_to_date/outdated/vulnerable/unmaintained, and generate a StackHealthScore (0–100) | | plan_upgrade | Generate a migration plan for upgrading a specific package -- breaking changes, estimated effort, and rollback procedure | | detect_deprecations | Scan project source files for deprecated API patterns (no network) and return a deprecation report with tech-debt estimate |

Quick Setup

pnpm install
pnpm build

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "specforge": {
      "command": "node",
      "args": ["/absolute/path/to/specforge/dist/index.js"],
      "env": {
        "SDD_DATA_DIR": "/absolute/path/to/specforge/data",
        "SDD_HOURLY_RATE": "50",
        "SDD_LOCALE": "en"
      }
    }
  }
}

Claude Code

claude mcp add specforge node /absolute/path/to/specforge/dist/index.js

Architecture

src/
├── index.ts          # MCP server entry point
├── tools/            # MCP tool handlers (58 tools, 8 streams A-H)
├── resources/        # MCP resources (read-only)
├── engine/           # Business logic (estimator, analyzer, validator)
├── storage/          # JSON persistence layer
├── types/            # TypeScript interfaces (16 domain files)
├── config/           # Extensible registries and signatures
└── i18n/             # Internationalization (en, es, pt)

Data is stored as JSON files in data/ (gitignored):

data/
├── projects/{hash}/  # Per-project: specs, metrics, patterns, knowledge
└── global/           # Shared: templates, pricing

Configuration

| Variable | Description | Default | |----------|-------------|---------| | SDD_DATA_DIR | Path to data storage directory | ./data | | SDD_HOURLY_RATE | Developer hourly rate (USD) for cost estimation | 50 | | SDD_LOCALE | Default locale (en, es, pt) | en |

Control Panel

SpecForge ships with a cross-platform interactive launcher and a parallel spec execution system.

Launchers

| Platform | How to run | |----------|-----------| | macOS | Double-click sdd.command or bash sdd.sh | | Linux / WSL | bash sdd.sh | | Windows | Double-click sdd.bat (requires WSL or Git Bash) | | Makefile | make watch / make status / make auto / make batch SPECS="..." |

The menu provides: real-time worker dashboard, system status, automatic batch detection, explicit spec batches, tests, lint, and cleanup.

Parallel Spec Execution

Specs are implemented by autonomous claude -p workers running in isolated git worktrees. Resource allocation is dynamic -- computed at runtime from the machine's physical cores and available RAM.

bash scripts/parallel-specs.sh --status    # show spec readiness and worker state
bash scripts/parallel-specs.sh --auto      # detect and launch next ready batch
bash scripts/parallel-specs.sh SPEC-014a SPEC-021   # launch specific specs
bash scripts/watch-workers.sh 10           # real-time dashboard, refresh every 10s

Worker limits are computed as min(phys_cores / 2, (avail_ram - 3 GB) / 0.35 GB) and capped at 10. A background health monitor warns on high swap and kills the highest-memory worker if swap exceeds 3 GB.

Development

| Command | Description | |---------|-------------| | pnpm build | Compile TypeScript | | pnpm dev | Watch mode | | pnpm lint | Lint with ESLint (zero warnings) | | pnpm lint:fix | Lint and auto-fix | | pnpm test | Run tests with Vitest | | pnpm format | Format with Prettier | | pnpm format:check | Check formatting | | pnpm typecheck | Type-check without emitting | | pnpm check | Run typecheck + lint + format check |

Pre-commit hooks (Husky + lint-staged) run automatically: typecheck, eslint, prettier, commitlint, and secretlint.

Releasing a New Version

Releases are automated via GitHub Actions (.github/workflows/publish.yml). When a commit lands on main with a version bump in package.json, the workflow publishes to npm automatically — no manual npm publish needed.

One-time setup: NPM_TOKEN secret

The workflow requires an NPM_TOKEN secret configured in GitHub:

1. Go to npmjs.com → your account → Access Tokens → Generate New Token
2. Select type Automation (scoped to publish)
3. Copy the token
4. Go to your GitHub repo → Settings → Secrets and variables → Actions → New repository secret
5. Name: NPM_TOKEN — Value: the token from step 3

How to cut a release

# 1. Bump version in package.json (e.g. 0.1.1 → 0.1.2)
# 2. Commit and push to develop
git add package.json && git commit -m "chore(release): bump version to 0.1.2"
git push origin develop

# 3. Merge develop → main (triggers auto-publish)
git checkout main && git merge --ff-only develop && git push origin main

The workflow checks if the version in package.json already exists on npm. If not, it publishes. If yes, it skips silently.

Contributing

See CONTRIBUTING.md for the GitFlow strategy, branch naming, commit conventions, and PR process.

License

MIT