Release history

Changelog

Rendered from CHANGELOG.md at build time. Single source of truth — no separate copy lives in this site.

#[v2.0.1] - 2026-03-22

#Features

  • Implement EPIC-072 coaching stories and multi-story dev progress

#Chores

  • remove pycache from git tracking
  • remove duplicate STORY-553 (completed version in archive/)
  • remove tgz build artifacts from repo and gitignore them
  • add NPM-Publish.md to gitignore
  • Add src/devforgeai/specs/business/ artifacts
  • Sync operational folders with src/ tree and update QA/workflow state
  • Checkpoint before STORY-536 development
  • Checkpoint before STORY-536 development WIP state from STORY-468, STORY-469, STORY-471, STORY-535, STORY-544 and related QA/workflow artifacts.

#Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

#[Unreleased]

Future v3.x changes accumulate here. Per ADR-104 D1 §"3-release rollout window": v3.0.0-beta.1 (this release, @beta dist-tag) → v3.0.0 GA (@latest) → v3.1.0 (removes --legacy per ADR-104 D2).

#[3.0.0-beta.1] - 2026-05-28

Status: First public pre-release of the v3.x installer modernization arc on the npm @beta dist-tag. The declarative install engine (ADR-100 through ADR-105) is implemented across phase PRs #155 through this PR. Tag a v3.0.0-beta.1 to publish via .github/workflows/npm-publish.yml.

#Highlights (Phase 10 — Integration + Release Prep)

  • v3.x engine arc is COMPLETE. Schemas (Phase 2, PR #155), parser/validator (Phase 3, PR #156), engine core (Phase 4, PR #157), 8 handlers (Phases 5-6, PRs #158-#159), migration + back-compat (Phase 7, PR #160), channel detection (Phase 8, PR #163), dual-mode UX (Phase 9, PR #165), and integration + release prep (Phase 10, this PR).
  • 5 end-to-end integration tests cover the full install flow: golden-install, resume-flow, rollback-flow, verify-flow, legacy-equivalence-final (per ADR-101 §Verification).
  • CI enforces 90% coverage on src/cli/v3/** (all 4 metrics: statements / branches / functions / lines) per ADR-101 D8.
  • STORY-048 Python contract runs on every PR (closes the PR #148 closeout addendum gap).
  • Cross-platform CI matrix (Linux + macOS + native Windows) exercises the python-venv-install handler (ADR-103 §Verification).
  • npm-publish workflow ships v3.x-beta.* tag pushes to the @beta dist-tag (stricter regex per ADR-104 D1).
  • Tarball slimming — deleted src/claude/skills/spec-driven-web-scraper-seo/web-scraper-seo-workspace/ (~26 MB scraped fixtures) and tightened package.json files to exclude deprecated docs/Optimization/, docs/assets/, docs/demo.html, docs/index.html, docs/stories/. Tarball delta vs v2.0.2 baseline: -254 KB (within ADR-100 §Verification ≤ +200 KB budget).
  • Capability flag wiring closed — Phase 10 wires the previously unwired --rollback, --resume, and --verify flags from install.js to the orchestrator entry points; replaces Phase 7 E_NOT_IMPLEMENTED stubs with real implementations honoring ADR-101 D2 + ADR-101 D10 + ADR-102 §"Exit code contract" codes 6 / 7 / 8 / 5.

#Highlights (Phase 9 — Dual-mode UX, PR #165)

  • First-class --silent with NDJSON event stream (ADR-102 §"NDJSON event envelope" schema_version "3.0").
  • First-class --interactive with bicameral 10-step footer (ADR-102 D1).
  • Step 7 Pre-flight Summary confirm gate (ADR-102 D3).
  • Per-component deterministic events (copy.start / copy.complete regardless of duration per ADR-102 D12).
  • 30-second heartbeat cadence on long-running phases with 60-second liveness invariant (ADR-102 D13).
  • 14-code exit contract (codes 0-12 + 130 SIGINT per ADR-102).
  • Curated help-text style guide (ADR-102 D7): MODE / INPUT / CAPABILITY / PYTHON / UPDATE / OUTPUT / DEPRECATED ordering.
  • One-time -y/--yes deprecation overlay (ADR-102 D8; removal v4.0).
  • One-time -q/--quiet deprecation overlay (ADR-104 D8; removal v4.0).

#Highlights (Phase 8 — Channel detection, PR #163)

  • version-detector module querying npm registry + GitHub releases + GitHub main HEAD with 24h cache + offline-safe fallback (ADR-105 §"Decision").
  • channel-switcher handler orchestrates npm install -g devforgeai@<channel> + .venv/ rebuild on channel transitions (ADR-105 D9).
  • 8 new install flags + 3 new status flags + standalone check-updates command surface (ADR-105 §Implementation).
  • Exit code 12 (UPDATE_AVAILABLE) emitted by devforgeai status --check-updates --silent when install is stale (ADR-105 D8).
  • 3 channels: stable (npm @latest), beta (npm @beta), edge (GitHub main HEAD) per ADR-105 D1.
  • Privacy-first — no phone-home; checks happen only on explicit user command (ADR-105 D4).

#Highlights (Phase 7 — Migration + back-compat, PR #160)

  • install-legacy.js — verbatim v2 imperative installer preserved behind --legacy (ADR-104 D2).
  • install.js shim routes default path to v3 engine, --legacy path to v2 imperative.
  • manifest-migrate-v1-to-v2 handler (9th handler) — runs early on FIRST v3 invocation against v2 consumers; backs up v2 manifest to .devforgeai-manifest.v1.backup.json, writes v3 schema with manifest_schema_version: 2, channel: "stable", source: "npm", channel_history: [], installed_at_v2: true (ADR-104 §Decision).
  • engines.node bumped to ≥20.0.0, engines.npm to ≥9.0.0 (ADR-104 D7).
  • --legacy flag emits one-time [DEPRECATED] warning per process; removed in v3.1.0 (ADR-104 D2).

#Highlights (Phases 5-6 — Handlers, PRs #158-#159)

  • 8 handlers implementing the 4-method contract (plan / execute / verify / rollback) per ADR-101 D2:
    • file-copy (streaming-aware for >1 MB files including tree.json)
    • template-substitute ({{KEY}} substitution)
    • directory-create
    • settings-merge (wraps existing SettingsMerger; consumer-wins on conflicts)
    • claude-md-import (wraps existing claude-md-installer)
    • python-venv-install (per ADR-103: cross-platform path resolution, 5 structured error codes, python.mode: venv|global switch)
    • pre-commit-hook-install
    • manifest-write (v3 schema with all new fields)

#Highlights (Phase 4 — Engine core, PR #157)

  • 5-layer engine architecture (Parser → Validator → Planner → Executor → State Manager) + Rollback engine per ADR-101 §Decision.
  • State journal at tmp/devforgeai-install-${SESSION_ID}/state.json (project-scoped per operational-safety Rule 2).
  • Pre-flight write-probe catches sandbox EROFS BEFORE handler.execute() runs (ADR-101 D12).
  • Topological sort by depends_on (ADR-101 D5).
  • Failure policy per component (required → fail-fast; non-required → handler's failure_policy per ADR-101 D11).

#Highlights (Phases 2-3 — Schemas + parser, PRs #155-#156)

  • JSON Schema Draft 2020-12 framework manifest at src/cli/manifests/install-manifest.json + _schema/install-manifest.schema.json (ADR-100).
  • schema_version: "1.0" strict equality enforced via Ajv const: "1.0" (ADR-100 D2; ports ADR-086/087 policy).
  • additionalProperties: false at every object level (ADR-100 D3).
  • YAML user-facing install config at .devforgeai-install.yaml (ADR-100 D1).
  • Cross-reference validator detects cycles, missing handlers, immutable-path double-claims (ADR-101).
  • NPM dependency count: 7 — added ajv@^8.x (~120 KB) + js-yaml@^4.x (~30 KB) per ADR-100 D10. Previously 5 (chalk, ora, cli-progress, inquirer, commander).

#Highlights (existing arc, unchanged)

(Unchanged from the prior "Unreleased (Proposed)" entry below — preserved for completeness.)

Earlier-arc status: This release covers PR #8 through PR #138 (2026-05-05 → 2026-05-25), the broader v3.x modernization arc covering Spec-Driven Pipeline + ceremony-to-hook conversion + source-tree decomposition. v3.0.0 will ship as v3.0.0-beta.1 on the npm @beta dist-tag, then GA on @latest. The installer engine rewrite (ADR-100 through ADR-105) is now IMPLEMENTED across PRs #155 through this PR (vs "in design" at the time the original entry was written).

#Highlights

  • Spec-Driven Pipeline broken into 5 first-class skills — spec-driven-brainstorming (Business Analysis), spec-driven-ideation (Project Management), spec-driven-system-architecture, spec-driven-solution-architecture, spec-driven-development-architecture (ADRs 065-070).
  • Ceremony-to-Hook conversion — ADR-076 codified the policy; ~12 new hooks now enforce what was previously prose-only across .claude/agents/, .claude/skills/, .claude/rules/, and ADR/manifest paths.
  • v3.x Installer Modernization (in design) — Declarative install engine, dual-mode UX (interactive ↔ silent NDJSON), update channels (stable/beta/edge), cross-platform Python venv ownership. Documented in ADR-100 through ADR-105; not yet implemented.
  • Source-tree as decomposed JSON artifact — source-tree.md monolith replaced by devforgeai/specs/context/source-tree/ (schema-validated JSON folder; ADR-071/072).
  • 40+ new ADRs ratifying architectural decisions across ADR-065 through ADR-105.

#Added

#v3.x Installer Modernization (Design Only — Not Yet Implemented)

  • Declarative install manifest schema (ADR-100) — JSON + JSON Schema Draft 2020-12 framework manifest at src/cli/manifests/install-manifest.json; YAML user-facing install config; Ajv + js-yaml dependency proposal.
  • 5-layer install engine architecture (ADR-101) — Parser → Validator → Planner → Executor → State Manager + Rollback engine + 8 built-in handlers. 90% coverage target on src/cli/v3/.
  • Dual-mode UX contract (ADR-102) — Interactive wizard and silent CI mode as co-equal first-class use cases; NDJSON event stream with schema_version: "3.0"; 14-code exit contract (0-12, 130); bicameral 10-step footer + 13-screen design catalog.
  • Python end-to-end ownership (ADR-103) — Cross-platform venv management (POSIX bin/ + Windows Scripts/); 5 structured error codes (E_PYTHON_MISSING, E_PYTHON_VERSION, E_VENV_CREATE, E_PIP_INSTALL, E_ENTRY_POINT); python.mode: "venv" | "global" switch.
  • Backwards compatibility & migration v2→v3 (ADR-104) — manifest_schema_version field, v1→v2 migration handler, --legacy flag with one-minor-cycle deprecation, engines.node bump from ≥18 to ≥20.
  • Version detection & update channels (ADR-105) — Three channels (stable / beta / edge); version-detector module querying npm registry + GitHub releases + GitHub main HEAD; 24h cache at ~/.config/devforgeai/version-cache.json; offline-safe fallback; exit code 12 UPDATE_AVAILABLE; no-phone-home privacy guarantee.
  • Design source-of-truth at devforgeai/specs/design/installer/ — 5 markdown files (260 KB) covering foundation tokens, 13 happy-path screens, 32 recovery/edge-case screens, 14 status/help layouts, NDJSON event sequences.
  • Interactive visual prototype at docs/installer/preview/ — React/Babel canvas rendering all 75 designed screens with three rendering variants (default color, NO_COLOR=1, TERM=dumb ASCII fallback).
  • Hand-off prompts at .claude/prompts/installer-wizard-design-*.md (5 design briefs) + .claude/prompts/installer-modernization-continuation-2026-05-26.md + .claude/prompts/website-readme-redesign-2026-05-26.md.

#Spec-Driven Pipeline Skills (PRs #55-#67)

  • spec-driven-brainstorming rewritten as 11-phase Business Analysis skill (#55, ADR-065).
  • spec-driven-ideation modernized into the Project Management phase (#57, ADR-066).
  • spec-driven-system-architecture (#59, ADR-067) — System Architect skill producing the System Architecture Document + 6 constitutional context files.
  • spec-driven-solution-architecture (#60, ADR-068) — Solution Architect skill producing feature decomposition.
  • spec-driven-development-architecture (#61, ADR-069) — Development Architect skill producing DEVARCH documents whose paths populate story source_devarch frontmatter.
  • test-plan.ai.yaml wired through system-architecture generation and QA validation (#62, STORY-634).
  • DEVARCH story seeds wired through /create-story + backend-architect (#63, FU-1 / FU-2).
  • Brainstorming Stream C methodology — Z14-Z18 additions (#29).

#Hooks & Enforcement

  • Pattern A marker-file bypass mechanism for pre-dual-path-write-guard.sh (#85, #87, #90, #97, #112, #138; ADR-081). Single-shot, < 30s fresh, consumed on bypass, audit-logged to devforgeai/logs/post-edit-write.log.
  • pre-tree-json-read-guard.sh — blocks wholesale Read of multi-megabyte source-tree/tree.json (#113, ADR-092).
  • pre-tmp-path-block.sh — blocks writes to system /tmp/ (#115, ADR-093).
  • pre-phase-record-reference-check.sh — phase-record reference validation hook (#105, #114, #129, ADR-091).
  • pre-adr-append-only-guard.sh — blocks Edit/Write to existing ADRs without tmp/_adr-status-update.marker bypass (#122, ADR-096).
  • post-audit-attempt-counter.sh — C11 audit-attempt escalation hook mechanizing diagnosis-before-fix.md item 5 (#125, ADR-098).
  • pre-qa-recommendations-fidelity hook (#79, ADR-075).
  • 3 enforcement hooks + git-ops completion — rules → deterministic gates (#52).
  • SessionStart sandbox-state verifier hook (#19, RCA-067 REC-4 / Issue #12).
  • Conviction-gate bypass user-approval gate (#21, RCA-067 REC-6).
  • Single-line canonical JSON contract for evidence-log writers (#18, RCA-067 REC-3 / Issue #11).
  • Conviction worklog Rule-16 validator (#88, ADR-083 PR-B).
  • Hook test harness CI workflow + closes pre-dual-path-write-guard test gap (#133).
  • Hook infrastructure refactoring — find_repo_root_for() extracted to lib/repo-root-helpers.sh (#134); 5 inline find_project_root copies migrated to phase-helpers.sh (#135); shared parse_flag + find_repo_root_for adoption (#136); ADR-081 marker-bypass extracted to lib/marker-bypass-helpers.sh (#137).
  • Phase helpers infrastructure (phase-helpers.sh) + AI companion regeneration (#26).

#CLI Validators

  • validate-devarch-seed CLI gate — H5 / ADR-082 — replaces prose-only Phase 01 structural validation in spec-driven-stories (#84).
  • Architecture CLI gates — validate-pm-plan + validate-system-architecture-output + validate-solution-architecture-output + _schema_check.py helper (#92, ADR-084).
  • H5 harmonization — devarch_seed_validator composed into _schema_check helper + schema_version == "1.0" strict equality (#96, ADR-086).
  • CLI validator schema_version audit — closure-only audit, 0 in-scope drift (#99, ADR-087).
  • verify-story-creation subcommand (#118, ADR-094).
  • diagnose-dod-failure subcommand v1 (#120, ADR-095).
  • dev-preflight exit 4 — source_devarch validation per B2 (#128, ADR-099).

#RCA & Feedback Modernization

  • /rca + spec-driven-rca modernized with hook-backed enforcement (#75, ADR-074).
  • rca-document-composer subagent for spec-driven-rca phases 04-07 (#47, OPP-8).
  • github-incident-from-rca + create-stories-from-rca aligned with ADR-074 contract (#78).
  • github-incident-from-feedback added; spec-driven-feedback modernized (#76, ADR-074).
  • QA recommendations fidelity — /create-incident-from-recommendations + generator fidelity fix (#22, ADR-075); silently-blocked Edit replaced with posting-manifest link-back (#81); SKILL.md doc tables aligned with manifest pattern (#83).
  • /recommendations-triage retired; /create-incident-from-queue added (recs → GitHub issues, not stories) (#98).
  • /feedback-export-data folded into /DF:feedback export-data subcommand (#91).
  • ADR-074 RCA traceability markers rendered into story Provenance (#80).

#Documentation Modernization (Coaching Entrepreneur Stream)

Original [Unreleased] content from prior CHANGELOG state:

  • Coaching Entrepreneur — Emotional State Tracking (STORY-468)

    • Updated docs/api/API.md (session log schema, tone mapping, business rules BR-004/BR-005)
    • Updated docs/architecture/ARCHITECTURE.md (data flow, check-in flow diagram, design decisions)
    • Updated docs/guides/DEVELOPER-GUIDE.md (session log schema, extension points, STORY-468 tests)
    • Added troubleshooting entries 21-24 in docs/guides/TROUBLESHOOTING.md (session log, tone adaptation, override, enum validation)
    • Added roadmap section in docs/guides/ROADMAP.md (3 feature items)
    • Updated README.md module blurb with new doc links

  • Coaching Entrepreneur (STORY-467) — API, architecture, developer guide, and module blurb updates.

  • Assessing Entrepreneur (STORY-465, STORY-466) — 6 module docs covering README, API, architecture, developer guide, troubleshooting, roadmap; updated for adaptive profile generation, /assess-me command, recalibration support, and business rules.

  • Hook-Based Phase Enforcement (EPIC-086, Sprint 22) — Phase Steps Registry (STORY-525), SubagentStop hook (STORY-526), TaskCompleted hook (STORY-527). Eliminates undetected phase skipping through automated validation.

#Source-Tree & Migration

  • source-tree.md monolith replaced by devforgeai/specs/context/source-tree/ AI-optimized decomposed folder artifact (#68, ADR-071 / ADR-072).
  • spec-driven-migration skill + 2 terminal-worker subagents (#69, ADR-073). Reference-sweep migration workflow.
  • spec-driven-migration dogfood + sweep of source-tree.md residuals (#70).
  • spec-driven-migration vacuous-pass dry-run pattern (#71).
  • source-tree.md → source-tree/ via spec-driven-migration (#72).
  • source-tree decomposed artifact regeneration — drift 1642 → 0 (#94); drift 324 → 0 (#104).
  • migration-cluster-worker tool-whitelist expansion (#95, ADR-085).

#Subagents

  • 8 reference-file frontmatter name: fixes (#30, Wave 1).
  • Wave 2: qa-executor + spec-driven-rca + dead-code-detector + REF-002 hook (#32).
  • Wave 3: readonly-fs-scanner + audit-orphans/budget + F07 documentation-writer reuse (#33).
  • Wave 4a: mockup-extractor terminal subagent + phase-02a refactor (#35).
  • Wave 4b: story-self-validator terminal subagent + phase-07 refactor (#36).
  • Wave 4c: custody-chain-auditor terminal subagent + validate-stories refactor (#38).
  • Wave 5: MISSING-004 + MISSING-005 placeholder renames (#39).
  • story-requirements-analyst modernized (597 → 169 lines; #43, pilot).
  • custody-chain-auditor trimmed under 600-line CI gate (655 → 572; #44).
  • 4 pseudocode-dominant subagents modernized (2181 → 508 lines; #45).

#Other Skills

  • spec-driven-qa prose reduction (~11%) matching sibling pattern (#74).
  • spec-driven-ui PR-A modernization — canonical form + Phase 00 inline + /create-ui slim (#73, ADR-074).
  • spec-driven-stories SKILL.md + 8 phase files modernized (#77, PR-A).
  • spec-driven-stories honest C-1 prose audit (#101, ADR-088, closes ADR-080 §FU#3).
  • spec-driven-stories references investigation (#102, ADR-089, closes ADR-080 §FU#1).
  • spec-driven-stories defensive-wrappers investigation — H8-CLI ship + 7 drops (#103, ADR-090).
  • spec-driven-dev ADR-076 ceremony-to-hook modernization (#106).

#Research

  • RESEARCH-011 — fresh AI file-format evaluation, post-2026-05-20 evidence only (#89).
  • RESEARCH-007 committed as superseded by RESEARCH-011 (#93).

#Other

  • STORY-667 genesis epoch support for evidence chain verification (#16).
  • PyYAML permitted for CLI use (#124, ADR-097).
  • GitHub Workflow for Claude Code (#8).
  • Template-version detection + spec-driven-remediation template upgrade (#25).
  • Test-plan-generation thesis codified (#119, ADR-094); subagent-based implementation (#127).

#Changed

  • Plan-file-archive policy + ADR-064 amendment (#24).
  • DevForgeAI.md extracted as framework steering + installer auto-import (#31).
  • Always-loaded session context reduced 41.7K → 19.2K (-54%) (#54).
  • Operational-safety.md Rule 4 expanded — sandbox policy (#20, RCA-067 REC-5 / Issue #13).
  • DEVARCH seed prerequisite documented for /dev (#117, PR #106 B2).
  • coverage-analyzer + contract-spec load thresholds from test-plan.ai.yaml; document test_plan_subset (#121).
  • Settings.json sync (#107 / #108 attempted CLAUDE_CODE_WORKFLOWS=1 then reverted — env var removed by Anthropic).
  • Rules-hooks modernization — hook hygiene chunks 1-2 of 4 (#49); chunks 3-4 of 4 (#50); plan archived (#51).
  • test-folder-protection.md HALT ceremony trimmed to hook pointer (#53).

#Deprecated

  • spec-driven-architecture skill — superseded by 3 sibling skills (system / solution / development architecture) (#64, ADR-070).
  • /recommendations-triage command — superseded by /create-incident-from-queue (recs → GitHub issues, not stories) (#98).
  • /feedback-export-data standalone command — folded into /DF:feedback export-data subcommand (#91).
  • source-tree.md monolith — replaced by source-tree/ decomposed JSON folder (#68, ADR-071).
  • -y/--yes and -q/--quiet installer flags — aliased to --silent / --output=text --verbose=0 respectively in proposed v3.x; removal scheduled for v4.0 (ADR-102 D8, ADR-104 D8).
  • Imperative src/cli/commands/install.js 9-phase wizard — proposed v3.x replaces with declarative engine; retained behind --legacy flag in proposed v3.0.0; removal scheduled for v3.1.0 (ADR-104 D2).

#Removed

  • __pycache__ from git tracking.
  • Duplicate STORY-553 completed version in archive (preserved before v2.0.1).
  • devforgeai_cli.egg-info/ pre-existing .gitignore violation (#28).
  • .claude/memory/Constitution/ deprecated mirrors (#41).
  • Ephemeral STORY-*-session.md remnants untracked + gitignored (#37).
  • Orphan internet-sleuth-integration/ completing ADR-045 (#40).
  • .claude/memory/ files pruned 25 → 4 (#48).
  • Dead Registry Drift block from pre-commit hook (#34).
  • Retired skill/command references in research skill + framework context files (#67).
  • Repointed retired spec-driven-architecture skill + command references (#66).

#Fixed

  • spec-driven-ui validate_context.py — source-tree migration + path bug + folder handling + dual-path repo-root detection (#110).
  • spec-driven-system-architecture phase-03 — source-tree generation + obsolete template retirement + noun-swap residuals (#116).
  • Multi-match-safe hook flag parser implementation plan (#17 → impl across hook PRs).
  • Pattern A marker repo-root resolution from editing file's path (#112) — closes the $CLAUDE_PROJECT_DIR env-propagation gap.
  • pre-dual-path-write-guard.sh — removed silent DEVFORGEAI_DUAL_PATH_GUARD_ENFORCE gate that didn't propagate into hook subshells (#109); follow-up housekeeping (#111).
  • PR-#114 diagnostic tracer — stripped after mystery closed (#129).
  • spec-driven-cc-guide reference files — typo filenames + orphan duplicates (#56).
  • subagent-size-check — set -e bug + orphan-audit tracking (#46).
  • ADR-074/075/076 collisions renumbered to ADR-077/078/079/080 + ADR-081 bypass-mechanism proposal (#82).
  • ADR-097 audit-attempt-hook renumbered to ADR-098 (collision with PR #124 PyYAML ADR) (#126).
  • ADR-094 status flipped to Accepted post-merge (#123).

#Security

  • Conviction-gate bypass requires user approval (#21, RCA-067 REC-6).
  • Single-line canonical JSON contract for evidence-log writers — prevents log corruption / injection (#18, RCA-067 REC-3).
  • SessionStart sandbox-state verifier — detects partial-state at boot and emits recovery commands (#19, RCA-067 REC-4).
  • ADR append-only enforcement — pre-adr-append-only-guard.sh blocks ADR mutation without marker bypass (#122, ADR-096).
  • No-phone-home guarantee in proposed v3.x version detection (ADR-100 + ADR-105) — user-initiated checks only, 24h cache, offline-safe.

#Architecture Decision Records

40+ ADRs ratified during this arc. Notable clusters:

Cluster ADRs Subject
Spec-Driven Pipeline (Stream A) ADR-065 to ADR-070, ADR-074 5 first-class architecture skills + RCA modernization
Source-Tree Decomposition ADR-071, ADR-072, ADR-073 source-tree.md → JSON folder + migration skill
Ceremony-to-Hook Policy ADR-076, ADR-081, ADR-091, ADR-092, ADR-093, ADR-096, ADR-098 Convert prose enforcement to hooks
CLI Validator Family ADR-082, ADR-084, ADR-086, ADR-087, ADR-094, ADR-095, ADR-099 Binary-gated workflow validation
Operational Safety ADR-081, ADR-085, ADR-090, ADR-097 Marker bypass + tool whitelist + PyYAML permission
v3.x Installer Modernization (Proposed) ADR-100 to ADR-105 + ADR-004/009 amendments (later reverted) Declarative engine, dual-mode UX, channels

See devforgeai/specs/adrs/ for the full ADR set.

#Notes & Open Items

  • v3.0.0 ships as v3.0.0-beta on npm @beta dist-tag first, then GA on @latest. Beta window: ~4 weeks (per ADR-104 D1).
  • The release/v2.5.0 branch was merged to main but never tagged or documented — intermediate state folded into this v3.0.0 entry.
  • ADR-004 and ADR-009 received in-flight amendments during the v3.x design session (2026-05-26) that were subsequently reverted by user direction. The amendments documented post-publication discoveries (Python venv ownership, pre-commit hook auto-install, undocumented status/uninstall commands, the context-files AS-IS gap). These discoveries are still planned for documentation in the forthcoming INSTALL.md (PR-1 of v3.x docs work).
  • Three v3.x installer ADRs (ADR-100 through ADR-105) remain in Proposed status pending implementation. Status flips will occur as implementation phases ship.

#1.0.0 - 2026-03-03

#Added

  • Core Framework

    • 44 specialized subagents for architecture, testing, QA, security, documentation, and more
    • 26 inline skills covering the full software development lifecycle
    • 46 slash commands from /brainstorm through /release
    • 6 constitutional context files (tech-stack, source-tree, dependencies, coding-standards, architecture-constraints, anti-patterns)
    • 4 sequential quality gates blocking progression until standards are met

  • TDD Workflow (/dev)

    • 10-phase development cycle with mandatory Red-Green-Refactor
    • Phase 04.5 and 05.5 AC compliance verification
    • Test folder write protection (only authorized agents in designated phases)
    • Coverage thresholds: 95% business logic, 85% application, 80% infrastructure

  • Configuration Layer Alignment Protocol (CLAP)

    • 15 validation checks across contradiction, completeness, and ADR propagation categories
    • /audit-alignment command for on-demand validation

  • Hook-Based Phase Enforcement (EPIC-086, Sprint 22)

    • STORY-525: Phase Steps Registry with 72 steps across 12 phases
    • STORY-526: SubagentStop hook for automatic invocation tracking
    • STORY-527: TaskCompleted hook for step validation gates
    • Eliminates undetected phase skipping through automated validation

  • Root Cause Analysis System

    • /rca command with 5 Whys methodology
    • diagnostic-analyst subagent for cross-reference investigation
    • /create-stories-from-rca for converting findings into actionable stories

  • Feedback System

    • 7 commands for capture, search, export, import, and reindex
    • AI analysis and observation extraction from subagent outputs

  • Sprint Planning

    • /create-sprint with automated story selection and capacity planning
    • Dependency graph analysis with cycle detection

  • Cross-AI Collaboration

    • /collaborate generates portable documents for sharing with external LLMs

  • CLI Validation Tools

    • devforgeai-validate Python CLI for phase management, DoD validation, and story checks
    • Pre-commit hook integration for commit-time validation

  • Documentation

    • API reference (docs/api/API.md)
    • Architecture guide (docs/architecture/ARCHITECTURE.md)
    • Troubleshooting guide (docs/guides/TROUBLESHOOTING.md)
    • Developer guide (DEVELOPER.md)