# DevForgeAI

[![npm version](https://img.shields.io/npm/v/devforgeai.svg?color=cyan)](https://www.npmjs.com/package/devforgeai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js >= 20](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org/)
[![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet.svg)](https://docs.anthropic.com/en/docs/claude-code)
[![npm downloads](https://img.shields.io/npm/dm/devforgeai.svg?color=success)](https://www.npmjs.com/package/devforgeai)
[![Last commit](https://img.shields.io/github/last-commit/bankielewicz/DevForgeAI.svg)](https://github.com/bankielewicz/DevForgeAI/commits/main)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

> **Spec-driven development for Claude Code.**

DevForgeAI is a framework for [Claude Code](https://docs.anthropic.com/en/docs/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:

```bash
npx devforgeai install        # v2.x stable           (@latest)
npx devforgeai@beta install   # v3.0.0-beta.5 (beta)   (@beta — declarative install engine, dual-mode CLI, update channels)
```

> `npm i devforgeai` only **downloads** the package — run an `install` command above to set up your project. More: [Installation Options](#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.5 (declarative install engine, dual-mode CLI, update channels) 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](https://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`](https://devforgeai.com/installer/preview/).

### Before & After

| Without DevForgeAI | With DevForgeAI |
|---|---|
| AI picks random libraries | AI uses only your approved stack |
| Tests skipped "to save time" | Tests written first, every feature |
| Code works but you're not sure why | Every decision traceable to an ADR |
| "It works on my machine" | Quality checkpoints before shipping |
| Vague idea → spaghetti code | Vague idea → structured spec → clean code |

---

## Get Started

**Prerequisites:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Node.js 20+, Git, Python 3.10+ (optional, for the `devforgeai-validate` CLI).

```bash
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:

```bash
/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.5 shipped 2026-06-05** on the npm `@beta` dist-tag (see [CHANGELOG.md](CHANGELOG.md#300-beta5---2026-06-05)). ADRs 100–105 are accepted. The interactive [design prototype](https://devforgeai.com/installer/preview) renders all 75 wizard screens. Per [ADR-104](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-104-backwards-compatibility-v2-to-v3.md), 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 #337 (220+ PRs from 2026-05-05 to 2026-06-05) and ratifies **50+ ADRs** (ADR-065 through ADR-137). It's documented in full in [CHANGELOG.md](CHANGELOG.md#300-beta5---2026-06-05). The headline arcs:

**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](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-101-install-engine-architecture.md).
- **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](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-102-dual-mode-ux-contract.md).
- **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](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-105-version-detection-update-channels.md).
- **Cross-platform Python.** Native Windows + Linux + macOS + WSL venv management, 5 structured error codes. See [ADR-103](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-103-python-end-to-end-ownership.md).
- **Manifest schema v2.** JSON Schema Draft 2020-12; v1→v2 migration on first run. See [ADR-100](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-100-declarative-install-manifest-schema.md).

**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.5  →  v3.0.0 GA  →  v3.1.0
   (shipped       ~4 weeks
   2026-06-05)
```

**Not in v3.0.0:** GUI installer (deferred to v3.1+ per [ADR-009](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-009-electron-gui-installer-template.md) amended). The [React prototype](https://github.com/bankielewicz/DevForgeAI/tree/main/docs/installer/preview) is a static design artifact, not the shipped GUI.

---

## How is this different from…

| Tool | DevForgeAI difference |
|---|---|
| **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** | The runtime DevForgeAI extends. Claude Code provides the AI; DevForgeAI provides the workflow, gates, and 6 immutable context files it reads from. |
| **Cursor Rules** | Cursor rules are suggested. DevForgeAI rules are enforced by hooks and CLI gates, with 60+ specialized subagents on top. Different scope of enforcement. |
| **Continue.dev** | Continue is an IDE plugin for autocomplete and chat. DevForgeAI is a workflow framework that owns the full lifecycle from brainstorm to release. |
| **Aider** | Aider does pair programming on a single change. DevForgeAI handles end-to-end: vague idea → requirements → epic → story → TDD'd code → QA → release. |
| **GitHub Copilot** | Copilot is autocomplete at the keystroke level. DevForgeAI is a different category — guardrails and structured workflow wrapping your AI. |

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](https://github.com/bankielewicz/DevForgeAI/blob/main/devforgeai/specs/adrs/ADR-105-version-detection-update-channels.md), 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.5 (on `@beta`, shipped 2026-06-05) replaces it with a declarative engine + dual-mode CLI + update channels + cross-platform Python. 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/`

| Want to learn more? | Where to look |
|---|---|
| All commands explained | [Developer Guide](docs/guides/DEVELOPER-GUIDE.md) |
| Architecture deep-dive | [Architecture Guide](docs/architecture/ARCHITECTURE.md) |
| API documentation | [API Reference](docs/api/API.md) |
| Troubleshooting | [Troubleshooting Guide](docs/guides/TROUBLESHOOTING.md) |
| Project roadmap | [Roadmap](docs/guides/ROADMAP.md) |
| v3.x design source | [`devforgeai/specs/design/installer/`](devforgeai/specs/design/installer/) |

---

## Installation Options

```bash
# 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](INSTALL.md)**.

### Try the v3.0.0-beta.5 (declarative engine + dual-mode CLI + update channels)

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

```bash
# 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
```

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](CHANGELOG.md#300-beta5---2026-06-05) for the full release notes and known limitations.

### Other install paths

```bash
# 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](CONTRIBUTING.md) for full guidelines.

---

## Support

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

<a href="https://buymeacoffee.com/devforgeai" target="_blank">
  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="40">
</a>

Issues, feature requests, and PRs welcome on [GitHub](https://github.com/bankielewicz/DevForgeAI/issues).

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

<p align="center">
  <strong>DevForgeAI</strong> — Spec-driven development for Claude Code.<br>
  <sub>Built with Claude Code itself.</sub>
</p>
