DevForgeAI

Spec-driven development for Claude Code.

DevForgeAI is a framework for Claude Code that adds the structure a senior engineer would: tests first, your tech stack, your rules — enforced by hooks at every step. It is language-agnostic, MIT-licensed, and free. There is no telemetry.

Install — pick a channel, then run the installer:

npx devforgeai install        # v2.x stable           (@latest)
npx devforgeai@beta install   # v3.0.0-beta.9 (beta)   (@beta — declarative install engine, dual-mode CLI, update channels, /spec-sprint)

npm install devforgeai (or npm install devforgeai@beta) only downloads the package into node_modules/ — nothing is set up in your project yet. You must then run the install step: npx devforgeai install from your project root, which writes .claude/, imports CLAUDE.md, and records an install manifest. More: Installation Options.

What it is, in one paragraph

DevForgeAI is an open-source workflow framework that runs on top of Anthropic's Claude Code. It defines a spec-driven pipeline — brainstorm → ideate → context → epic → story → dev → qa → release — and enforces each stage with shell hooks and CLI gates that block the AI from cutting corners. The framework ships 45 skills, 89 specialized subagents, 61 slash commands, and 6 immutable context files that lock your tech stack, code standards, and architecture constraints in place. v2.0.0 is on @latest; v3.0.0-beta.9 (declarative install engine, dual-mode CLI, update channels, issue-driven /spec-sprint) is on @beta — try it with npx devforgeai@beta install.

The Problem

You've tried coding with AI. It's fast — until it rewrites your auth system in a framework you didn't choose, skips the tests, and produces code that works today but breaks next week.

The problem isn't the AI. It's the lack of guardrails.

Without structure, AI assistants will:

• Pick technologies you didn't approve
• Skip tests because "the implementation is straightforward"
• Create inconsistent patterns across your codebase
• Make architecture decisions without asking you

What DevForgeAI Does

Your project's rules are written down. You define your approved tech stack, code standards, and patterns in 6 immutable context files (tech-stack.md, source-tree/, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md). The AI reads these before writing any code and cannot deviate without explicit user approval.

Tests come first, every time. Hook-enforced red-green-refactor. The AI writes a failing test, then minimum code to pass, then refactors. The pre-tdd-test-first hook blocks writes that violate the cycle. No shortcuts.

Quality checkpoints catch problems early. Sequential CLI gates between phases: coverage thresholds (95% business / 85% application / 80% infrastructure), security scanning, contract-spec drift, dead-code detection, anti-pattern checks. A story can't progress until each gate is green.

See It in Action

Try the interactive demo at devforgeai.com — watch the install command play out, copy it to your clipboard, and click through every screen of the v3.x wizard.

The site also hosts a static React prototype rendering all 75 v3.x wizard screens at /installer/preview.

Before & After

Get Started

Prerequisites: Claude Code, Node.js 20+, Git, Python 3.10+ (optional, for the devforgeai-validate CLI).

npx devforgeai install

That's it. The installer walks you through choosing components, detects an existing install, optionally creates a Python venv, and writes a manifest you can re-run against. Then open Claude Code in your project:

/brainstorm "I want to build a task management app"

DevForgeAI guides you through exploring your idea, locking your tech stack, decomposing it into stories, and building it with TDD — all conversationally. No config files to hand-write.

What happens next:

1. /brainstorm — explore the idea through Socratic questions
2. /create-context — lock your tech stack, standards, and patterns
3. /create-story — turn features into clear, AC-stamped specs
4. /dev STORY-001 — build it with hook-enforced TDD (red → green → refactor)
5. /qa STORY-001 — validate coverage, security, anti-patterns before you ship

You don't have to use every command. Start with /brainstorm for a vague idea, or jump straight to /dev if you already have a story.

Start from Just an Idea

The full workflow takes you from a napkin sketch to production:

/brainstorm     "I want to build..."     You explore the idea
      │
/ideate         Idea → requirements       AI asks the right questions
      │
/create-context Requirements → rules      Your tech choices get locked in
      │
/create-epic    Rules → feature plan      Big idea broken into pieces
      │
/create-story   Features → specs          Each piece gets acceptance criteria
      │
/dev            Specs → tested code       Built with TDD (tests first)
      │
/qa             Code → quality check      Coverage, security, patterns validated
      │
/release        Validated → shipped       Deploy with confidence

Skip phases on small projects. The guardrails scale down — you're not forced into enterprise ceremony.

What's Coming in v3.x

DevForgeAI v3.0.0-beta.9 shipped 2026-06-16 on the npm @beta dist-tag (see CHANGELOG.md). ADRs 100–105 are accepted. The interactive design prototype renders all 75 wizard screens. Per ADR-104, v3.x ships on @beta first, then GA on @latest. The v2 imperative installer and its --legacy flag were removed in the beta cycle (F1 / #279); the v3 declarative engine is the sole installer.

The v3.x arc spans PR #8 through #563 (300+ PRs from 2026-05-05 to 2026-06-12) and ratifies 50+ ADRs (ADR-065 through ADR-137). It's documented in full in CHANGELOG.md. The headline arcs:

Issue-driven sprints — /spec-sprint, new in beta.7. Point it at a GitHub issue and it runs a hook-enforced, resumable sprint: plan-mode research → a self-contained HTML spec with work cards → an isolated worktree → TDD per card → QA against the spec's acceptance criteria → PR. No story file required. Beta.7 also ships a deterministic audit-fs filesystem-audit engine, a /create-incident observation-to-issue pipeline, run-tests harness upgrades (--framework, Bash sub-runner, worktree PYTHONPATH), and ~40 hook fixes making enforcement workflow-aware and parallel-session-safe — see the beta.7 changelog.

Spec-driven pipeline, now five first-class skills (ADRs 065–070). Previously a single spec-driven-architecture skill; now decomposed into spec-driven-brainstorming (Business Analysis), spec-driven-ideation (Project Management), spec-driven-system-architecture, spec-driven-solution-architecture, and spec-driven-development-architecture. Each phase has its own architect role and its own output artifact.

Ceremony-to-hook conversion (ADR-076). ~12 new hooks now mechanically enforce what was previously prose-only across .claude/agents/, .claude/skills/, .claude/rules/, and ADR/manifest paths. Includes append-only ADR enforcement, tree-json read guard, audit-attempt escalation, and a single-shot marker-bypass mechanism (ADR-081).

Seven new CLI gates. validate-devarch-seed, validate-pm-plan, validate-system-architecture-output, validate-solution-architecture-output, verify-story-creation, diagnose-dod-failure, and dev-preflight (exit 4 on missing DEVARCH). Binary gates — fail loud, fail fast.

Installer modernization (ADRs 100–105).

• Declarative install engine. v2.0.0's 9-phase imperative wizard becomes a 5-layer engine (parser → validator → planner → executor → state) with rollback. Adds --dry-run, --resume, --rollback, and --verify flags. See ADR-101.
• Dual-mode CLI. Interactive wizard and silent CI mode are co-equal first-class. Silent mode emits NDJSON events with deterministic exit codes (0–12, 130). See ADR-102.
• Update channels. stable / beta / edge. Run devforgeai status --check-updates; devforgeai install --switch-channel=beta to opt in. Privacy-preserving — no phone-home, 24h cache. See ADR-105.
• Cross-platform Python. Native Windows + Linux + macOS + WSL venv management, 5 structured error codes. See ADR-103.
• Manifest schema v2. JSON Schema Draft 2020-12; v1→v2 migration on first run. See ADR-100.

Source-tree, decomposed. The source-tree.md monolith is replaced by a schema-validated JSON folder at devforgeai/specs/context/source-tree/. The spec-driven-migration skill orchestrated the conversion. ADR-071 / ADR-072.

Roadmap:

v3.0.0-beta.9  →  v3.0.0 GA  →  v3.1.0
   (shipped       ~4 weeks
   2026-06-16)

Not in v3.0.0: GUI installer (deferred to v3.1+ per ADR-009 amended). The React prototype is a static design artifact, not the shipped GUI.

How is this different from…

Each of these is a useful tool. DevForgeAI is differently scoped, not "better" — it's the spec-and-workflow layer above them.

Common Questions

Do I need to use all the commands?
No. Start with /brainstorm if you have a vague idea, or /dev STORY-001 if you already have a story file. Use as much or as little as you need.

What tech stacks does it support?
All of them. DevForgeAI is language-agnostic — Python, TypeScript, C#, Go, Rust, anything else. Your six context files declare what you're using. The framework adapts.

Is this only for big projects?
No. It works great for side projects, prototypes, and solo dev work. The quality guardrails scale down — you're not forced into enterprise ceremony.

Do I need to know TDD?
No. The framework handles the test-driven workflow for you. It writes the tests, runs them, and implements code to make them pass. You just describe what you want.

What if I just want to write code without all the process?
You can. Use /dev directly with a story file and it handles the TDD cycle. Skip brainstorming, skip epic planning — jump straight to building.

How is this different from Cursor Rules or .cursorrules?
DevForgeAI goes beyond static rules. It's an active framework with 60+ specialized AI subagents that enforce your rules at every step, not just suggest them. It manages the full journey from idea to deployment. Cursor and DevForgeAI compose well — Cursor inside your editor, DevForgeAI defining the workflow.

Does it phone home?
No. Per ADR-105, version detection in v3.x is user-initiated, cached for 24 hours, and offline-safe. There is no telemetry in any release.

What's the difference between v2.0 and v3.x?
v2.0 (on @latest) has a 9-phase imperative installer. v3.0.0-beta.9 (on @beta, shipped 2026-06-16) replaces it with a declarative engine + dual-mode CLI + update channels + cross-platform Python, and adds the issue-driven /spec-sprint workflow. Try the beta with npx devforgeai@beta install. See the "Coming in v3.x" section above.

What's Under the Hood

For the technically curious — DevForgeAI is built entirely as Claude Code extensions, all Markdown, all version-controllable:

• 45 Skills — Structured workflows for each stage (spec-driven-brainstorming, spec-driven-dev, spec-driven-qa, etc.)
• 89 Subagents — Specialized AI agents with specific jobs (test-automator writes tests, security-auditor finds vulnerabilities, code-reviewer checks quality, custody-chain-auditor traces provenance)
• 61 Slash Commands — User-facing entry points from /brainstorm to /release
• 6 Context Files — Your project's rules: tech-stack.md, source-tree/, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md
• Architecture Decision Records — Every significant choice documented in devforgeai/specs/adrs/

Installation Options

# Recommended (v2.x stable, on @latest)
npx devforgeai install

For full installation documentation — prerequisites, modes (Fresh / Update / Reinstall), components, command reference, validation, rollback, uninstallation, v3.x roadmap, 18-entry troubleshooting catalog, and FAQ — see INSTALL.md.

Try the v3.0.0-beta.9 (declarative engine + dual-mode CLI + update channels + /spec-sprint)

v3.0.0-beta.9 shipped on the npm @beta dist-tag on 2026-06-16. It's opt-in until GA — npx devforgeai install continues to give you v2.x stable.

# One-shot via npx (no global install)
npx devforgeai@beta install

# Or pin globally to the beta channel
npm install -g devforgeai@beta
devforgeai install

# Or as a project dependency — note this is TWO steps:
npm install devforgeai@beta   # step 1: downloads the package into node_modules/ (nothing is set up yet)
npx devforgeai install        # step 2: installs the framework into the project (npx resolves the local beta from node_modules/.bin)

npm install alone never sets up a project — it only downloads. The devforgeai install step is what writes .claude/ (skills, agents, commands, hooks), imports CLAUDE.md, optionally creates the Python venv for devforgeai-validate, and records the install manifest.

The v2 imperative installer and its --legacy flag were removed in the beta cycle (F1 / #279); the v3 declarative engine is the sole installer. If v3 hits an issue on your platform, use npx devforgeai install --resume (continue a partial install) or --rollback (reverse a completed one). See CHANGELOG.md for the full release notes and known limitations.

Other install paths

# Global install (v2.x stable)
npm install -g devforgeai
devforgeai install

# From source
git clone https://github.com/bankielewicz/DevForgeAI.git
cd DevForgeAI && npm install
node bin/devforgeai.js install /path/to/your-project

After installing, open Claude Code in your project and run /create-context to set up your project rules interactively.

Contributing

1. Fork the repository
2. Create a feature branch
3. Use the DevForgeAI workflow: /create-story → /dev → /qa
4. Push and open a Pull Request

See CONTRIBUTING.md for full guidelines.

Support

If DevForgeAI has helped your development workflow, consider supporting the project:

Issues, feature requests, and PRs welcome on GitHub.

License

MIT License — see LICENSE for details.

DevForgeAI — Spec-driven development for Claude Code.
_{Built with Claude Code itself.}