Why v3

v2 enforced rules through prose conventions. v3.x enforces them through hooks and CLI gates. Where v2's spec-driven-architecture skill was a single monolith, v3.x splits it into five architect roles, each with its own output artifact and a gate guarding the transition. The installer modernization (ADRs 100–105) is the most visible change for end users; the pipeline reorganization is the deeper one.

What's coming

• Spec-driven pipeline, now five skills — brainstorming → ideation → system architecture → solution architecture → development architecture, with the DEVARCH document seeding story frontmatter (ADRs 065–070).
• Ceremony-to-hook conversion — ~12 new hooks mechanically enforce what was prose-only: append-only ADR guard, phase-record reference check, tree-json read guard, tmp-path block, audit-attempt escalation, Pattern A marker-file bypass (ADR-076 + companions).
• Seven new CLI gates — validate-devarch-seed, validate-pm-plan, validate-system-architecture-output, validate-solution-architecture-output, the _schema_check.py helper, verify-story-creation, diagnose-dod-failure, dev-preflight exit 4.
• Declarative install engine — 5-layer (parser → validator → planner → executor → state) with rollback, dry-run, resume, verify. Replaces the v2 9-phase imperative installer.
• Dual-mode CLI — interactive wizard ↔ silent NDJSON CI mode. Same 13-screen design catalog you can preview at /installer-preview.
• Update channels — stable / beta / edge with user-initiated, 24h-cached, offline-safe version detection.

The six ADRs

Phasing

• v3.0.0-beta — ships first on npm @beta. Beta window ~4 weeks.
• v3.0.0 GA — promoted to npm @latest after beta.
• v3.1.0 — --legacy flag removed; the v2 imperative installer is no longer reachable.

Beta access

# When v3.0.0-beta tags:
npx devforgeai@beta install

# Or, switch an existing v2 install:
devforgeai install --switch-channel=beta

Full changelog in /changelog. Six ADR direct links above; the broader 40+ ADR set lives at devforgeai/specs/adrs/.

DevForgeAI v3.0.0 is in design across 40+ architecture decision records ratified between PR #8 and PR #138 (2026-05-05 to 2026-05-25). The release reorganizes the spec-driven pipeline into five first-class architecture skills (brainstorming, ideation, system architecture, solution architecture, development architecture), converts ~12 prose conventions into mechanical shell hooks, adds seven new CLI gates that block phase progression on failure, and replaces the v2 nine-phase imperative installer with a five-layer declarative engine. The installer change is the most visible (six ADRs, 75 designed screens, dual-mode interactive ↔ silent NDJSON CLI, three update channels stable / beta / edge with privacy-preserving version detection); the pipeline reorganization is the structural one. v3.0.0 ships first as v3.0.0-beta on the npm @beta dist-tag, then GA on @latest. The v2 imperative installer is retained behind a --legacy flag for one minor cycle.