An engineering harness for disciplined software building — powered by two coding agents.
Quick Start · Commands · Workflow · Philosophy · Troubleshooting · Changelog
Claude Codex Forge combines Claude Code and OpenAI's Codex into a single workflow. Two agents beat one: Claude designs, Codex independently reviews, and the Engineering Council adjudicates when they disagree. What started as a set of workflow templates has grown — through continuous iteration — into a full engineering harness.
- Dual-agent review —
/codex review(independent second opinion) +/council(5-advisor panel with Codex chairman, see explainer) catch issues one agent alone would miss; two separately-trained models flag different concerns — disagreement is the signal. And Codex isn't limited to reading code: Investigate mode gives it real, sandboxed hands on your live systems (query a DB, hit a cloud API, reproduce a bug) when a question can't be answered from source alone — repo-confined, read-only, every finding cross-verified. - Autonomous goal mode — write a sharp PRD, then paste one
/goalcommand and the agent drives the entire feature — plan → review → implement → review → verify → E2E → PR — on its own, escalating hard calls to the Council instead of stopping to ask. Optional and PRD-gated; you watch and steer any time by typing in the prompt, and PR creation is the one gate that always waits for your yes. See explainer. - Discipline by construction — workflow commands bake in TDD, research-before-design, and E2E testing. Hooks block dangerous Bash, enforce state updates, and gate commit/push/PR on explicit quality markers.
- Continuous memory — auto-memory persists locally across sessions and compaction (rescued by the
PreCompacthook);docs/adr/,docs/CHANGELOG.md, anddocs/solutions/travel with the repo so every architecture decision, root cause, and pattern compounds across weeks and teammates via git. Per-developer Workflow / Done / Now / Next state lives in gitignored.claude/local/state.md— read by hooks on demand, kept out of Claude's auto-loaded context. - Team-scale by default — one GitHub repo becomes the hub. Multiple developers run parallel Claude sessions via auto-created git worktrees, each isolated but with full project context.
Prerequisites: Claude Code · Node.js 22+ · Git 2.23+ · a ChatGPT Plus/Pro/Business plan or OpenAI API key for Codex CLI.
# 1. Clone this harness repo (once per machine)
git clone https://github.com/pablomarin/claude-codex-forge.git ~/claude-codex-forge
chmod +x ~/claude-codex-forge/setup.sh
# 2. Global setup once per machine (installs the memory system)
~/claude-codex-forge/setup.sh --global
# 3. Install Codex CLI + authenticate (required for dual-agent review)
npm install -g @openai/codex # or: brew install --cask codex
codex login
# 4. Per-project setup
cd /path/to/your/project
~/claude-codex-forge/setup.sh -p "My Project"
# 5. Start Claude Code, install the Superpowers plugin, restart
claude
> /plugin install superpowers@claude-plugins-official
# 6. Restart Claude Code, then kick off your first workflow
> /new-feature my-featureFull walkthrough with platform-specific (Windows/macOS/Linux) instructions, the "no Codex" fallback, and troubleshooting: Getting Started →
Windows users: PowerShell instructions.
setup.sh is safe to re-run. Three modes:
| Command | Use case |
|---|---|
setup.sh -p "Name" (no flags) |
First install on a new project. Also safe to re-run later to fill in missing template files without disturbing anything that already exists. |
setup.sh --upgrade |
Routine template updates on an existing project. Refreshes hooks, commands, rules, and agents. Merges .claude/settings.json and .mcp.json so your customizations (permissions, plugins, extra MCP servers) are preserved. Creates a timestamped .bak before merging. |
setup.sh -f |
Reset to template verbatim. Overwrites .claude/settings.json and .mcp.json — wipes your customizations. No backup. Use only if your setup is corrupted or you've never customized anything. |
CLAUDE.md, .claude/local/state.md, and docs/CHANGELOG.md are always preserved — the template initializes them on first install and never touches them afterward, regardless of flags. If you upgrade from a pre-5.15 install, your legacy state file is preserved too; run setup.sh --migrate when ready to split it into the three new artifacts.
Full flag reference: Upgrading guide →
The Forge commits .claude/ so your whole team shares the same workflow, rules, and gates. The catch: setup.sh --upgrade/-f regenerates that committed machinery, so if two developers run different Forge versions you get merge conflicts on those files every push. Keep it simple:
One Forge version per project. One designated upgrader. Upgrades land as their own PR.
Everyone else just uses what's committed and never runs --upgrade in that repo. When it's time to move up, the designated upgrader runs setup.sh --upgrade and opens a dedicated chore: forge X.YZ PR; once it merges, everyone pulls.
To keep that convention from drifting silently, the Forge stamps the project's version into a committed .claude/.forge-version file and warns you (advisory only — it never blocks):
- At
setup.shtime: running-f/--upgradewhen your Forge version differs from the project's pin prints a heads-up that you're about to up/downgrade it. - At session start: if your installed Forge differs from the project's pin, Claude is told once — just the facts, your call (e.g. "this project pins Forge 5.50; you're on 5.40 — the project is on a newer Forge, so you may want to upgrade yours to match").
Both are fail-open and purely informational. (If you'd rather the Forge be a personal tool than a team standard, the alternative is to gitignore .claude/ and install locally — but that gives up the shared, committed workflow discipline that's the point of committing it.)
./setup.sh --upgrade # picks up new files; preserves your existing CONTINUITY.md byte-for-byte
./setup.sh --migrate # splits CONTINUITY.md into CLAUDE.md durable + docs/adr/ decisions + .claude/local/state.md volatileSee docs/guides/upgrading.md for the full walkthrough including verifying the migration and removing the legacy @CONTINUITY.md import.
One feature goes from idea to merged PR across 14 enforced phases — from PRD through research, dual-reviewer design loops, TDD execution, parallel code review, simplify + verify + E2E, compound learnings, and PR reviewer handling.
See the full workflow diagram for the complete view, or jump straight to:
- Why a harness, not a template — the two-agent design, discipline by construction, continuous memory
- Autonomous goal mode — paste one
/goal, the agent drives PRD→PR; you watch and steer - Codex Investigate mode — give Codex real hands on live systems, safely
- Commands reference — every slash command and subagent
- Hooks reference — seven hook events that keep discipline structural
| Topic | What's inside |
|---|---|
| Getting Started | Prerequisites, 6-step install, verify setup |
| Setup Scenarios | New project · existing project · upgrade |
| Customize Your Project | CLAUDE.md · .claude/local/state.md · optional MCPs · automated PR reviews |
| Upgrading | --upgrade mode, merge behavior, fresh-install alternative |
| Parallel Development | Multiple sessions via git worktrees |
| Playwright CI Bridge | --with-playwright scaffold for deterministic E2E in CI |
| Commands Reference | All slash commands and subagents |
| Hooks Reference | Seven hook events + how they interact |
| Permissions & Security | Deny / ask / skip rules |
| File Structure | What setup creates and where |
| Creating Skills | Author your own slash commands |
| Cheatsheet | Copy-paste daily-workflow card |
| Workflow (full) | 14-phase diagram with rationale |
| Autonomous Goal Mode | /goal PRD→PR autonomy — optional, PRD-gated, watch-and-steer |
| Codex Investigate Mode | Give Codex live-system access (DB/cloud/API) safely; works inside /goal |
| Harness Philosophy | Why dual-agent, why discipline, why continuous memory |
| Memory Architecture | Global + project + auto-memory layers |
| Troubleshooting | Memory · hooks · permissions · MCP · plugins · Codex |
The pillars above cash out in specific, repo-verifiable behavior:
- Compaction rescue —
PreCompacthook flushes session learnings to auto-memory before context compression, so nothing is dropped silently - Review ordering enforced —
/codex reviewruns first as an independent pass, then/pr-review-toolkit:review-pr(6 deep agents), then/simplify, then post-PR/review-pr-comments. Commits are blocked until quality markers are present. - Worktree isolation —
/new-featureand/fix-bugauto-create git worktrees so parallel Claude sessions never share filesystem state - E2E for user-facing changes —
verify-e2esubagent replaystests/e2e/use-cases/*.mdas a growing regression suite; optional--with-playwrightscaffolds deterministic.spec.tsfor contributor PRs in CI
Recent releases:
| Version | Date | Highlights |
|---|---|---|
| 5.56 | 2026-07-12 | Stop /goal stalling on a Bash-read of state.md + skip prettier on markdown. Field hit (actbl-he): the agent improvised sed … .claude/local/state.md to peek at its status file; Bash isn't a read-only tool, so CC's sensitive-file prompt fired and the autonomous loop silently hung. Fix: a rules/workflow.md rule ("read state.md with the Read tool, never Bash") + a check-bash-safety.{sh,ps1} guardrail (check #8) that blocks a read-utility targeting .claude/local/state.md inline — per-line match, so the sanctioned extract_foldable/fold-back flows (which read via a shell variable) and the review-breaker diagnostic are structurally exempt; filename terminator spares state.md.bak; .ps1 uses valid .NET (?m)…[^\r\n]* (no POSIX class). Framed as a targeted guardrail, not a guarantee (variable-indirected reads intentionally allowed). Bundled (review-surfaced): post-tool-format.{sh,ps1} no longer runs prettier on .md — prettier 3.x corrupts the harness's escaped-backtick, byte-pinned markdown (reproduced on HEAD). New test-bash-safety.sh (17) + contracts (390); downstream smoke vs ../actbl-he clean. |
| 5.55 | 2026-07-12 | Bump Codex CLI model gpt-5.5 → gpt-5.6-sol. OpenAI shipped the GPT-5.6 family; gpt-5.6-sol is the flagship tier and Codex CLI's default "Power" model. All Codex invocations in /codex (5 strings + config-table row) and /council (peer-review-protocol.md, 3 strings) now pin it explicitly. Verified via Claude WebFetch + a Codex live-docs check (agreeing): gpt-5.6-sol is the canonical -m identifier, needs no allowlist/extra config beyond normal auth, and model_reasoning_effort="xhigh" is still the correct CLI token (UI label "Extra High"). Repo-wide grep confirmed no other model pin; historical CHANGELOG/README rows keep their old references. |
| 5.54 | 2026-06-06 | Convergence breaker for the code-review loop. Field hit (msai-v2 PR #89): a both-engines-certified, merge-authorized branch hit a docs-only merge conflict; the HEAD move re-opened FULL-scope review and ground from iteration 15 to 25 with no stopping rule. Now: after the first both-engines-clean iteration (certification), more than POST_CERT_REVIEW_ROUND_LIMIT=3 further rounds hook-blocks all ship actions (the check precedes the docs-only carve-out — no N/A or docs-commit bypass; counter-erasure N/A trips fail-closed) until a HUMAN records the head-bound Post-certification tail adjudicated by human line — the agent never writes it, and /goal halts for the human, never /council. New tiny helper hooks/lib/review-breaker.sh/.ps1 (state.md reader, no git diffing); pr_ready suppressed while tripped+unadjudicated. A full scoped-certification engine (scope grammar, patch-id delta classification, mechanical re-stamps, deep pass) was built, certified, then deliberately deferred after a community-value council returned NO-as-is — preserved at ece4eae with reactivation conditions in ADR 0009. |
| 5.53 | 2026-06-04 | Stop benign cache deletes from stalling autonomous runs. Field hit (msai-v2): a subagent's rm -rf .mypy_cache tripped the Forge-shipped ask rule Bash(rm -rf:*) mid-/goal — the loop silently hung on a human permission prompt for a routine cache clear (a /goal loop can't self-approve ask-tier commands, by design). Two-layer fix: rules/python-style.md "cache resets — use tool flags, never rm -rf" table (mypy --no-incremental, pytest --cache-clear, ruff check --no-cache) + rules/workflow.md "Ask-tier commands stall autonomous runs" rule; and both settings templates add three exact-match allows (rm -rf .mypy_cache/.pytest_cache/.ruff_cache) — exact, not prefix, so trailing args can't ride through. The rm -rf:* ask rail stays, contract-pinned (Contract 3c). Quick-fix; propagates via setup.sh --upgrade (permission entries merge). |
| 5.52 | 2026-06-02 | State continuity round-trips through main — your Done/Now/Next/Deferred story now survives worktree teardown. Was: /new-feature made a blank worktree state.md and /finish-branch deleted it (gitignored) while only clearing main's ## Workflow, so the narrative died at every merge and main went stale (hit on msai-v2 — a confirmed "KV apply done" fact was lost, then re-proposed). Now: seed-on-create copies main's foldable narrative (Done/Next/Deferred + Open Questions + Blockers) verbatim with Now cleared + writes a .claude/local/.state-seed-snapshot.md; guarded fold-back (/finish-branch step 2.2b, before git worktree remove) deterministically replaces main's foldable sections with the worktree's only if main is unchanged since seed, else loud safe-stop (no overwrite). Gate sections never travel; state stays gitignored (ADR 0001 preserved). 5-advisor /council chose guarded deterministic replace over the literal "smart LLM merge" ask (seed-forward invariant makes replace correct + testable; snapshot guard prevents silent overwrite); LLM merge deferred. ADR 0008. Codex 4 plan-review iters to clean; EXTRACT-FOLDABLE pinned byte-identical across 3 command files. Built by dogfooding /new-feature→/goal. 341+ contracts green. |
| 5.51 | 2026-06-02 | Forge version stamp + advisory drift warning — stop cross-version .claude/ merge conflicts on teams (who commit .claude/). setup.sh/.ps1 write .claude/.forge-version (project pin) + ~/.claude/.forge-version (this machine), read from the CHANGELOG top line; a -f/--upgrade version mismatch prints a direction-aware advisory (names the up/downgrade + that other clones will pull the change — facts, not a directive); session-start.sh/.ps1 add a one-line drift heads-up. All advisory, never blocks, fail-open; the pin can't lie (written only after machinery is (re)written, gated on a settings sentinel). Council-ratified (D + cheap detector; rejected gitignoring .claude/, merge=union, global-runtime/lockfile/forge doctor). README documents the one-updater/upgrade-by-PR flow. Codex 4 plan-review iters to clean; behavioral + parity tests; 11-suite green. Keeps committing .claude/ (team-standard model). |
| 5.50 | 2026-06-02 | Sharpen plan-stage severity: spec-loss omissions are P1, not P2. At Gate 1 (plan review), an omission that could build the wrong feature — missing required behavior, missing edge-case handling, a missing disambiguating acceptance criterion, or a missing test stub for a known-important behavior — is now explicitly P1. Rationale: subagents build FROM the plan, so a plan gap propagates and Gate 2 only sees code internally consistent with the incomplete plan (spec-loss invisible downstream). Pure smell stays P2. Classification only — the gate is NOT relaxed (still exits on no P0/P1/P2). In rules/workflow.md + both commands' Phase 3.3, pinned by a parity contract that also guards the strict exit. Came out of a 5-advisor /council on whether to relax Gate 1 to a P0/P1 exit for speed; the maintainer shipped only this pure-upside rubric half and deferred the gate relaxation. Docs + 1 contract; 319 contracts + 31 lint green. |
| 5.49 | 2026-06-01 | Make /finish-branch worktree-safe. gh pr merge --squash --delete-branch errored with fatal: 'main' is already used by worktree when run from a worktree (the -d local-branch delete forces a checkout switch to the base branch, which main's primary worktree already holds) — the server-side merge succeeded but the command exited non-zero (hit on PR #836 + msai-v2 #85). commands/finish-branch.md 1.4 drops --delete-branch (Phase 2 already removes the worktree + deletes local & remote branches) and adds "verify state == MERGED, don't retry" guidance. Also de-chained Phase 2.6's git push --delete … || echo … (a compound git push the Forge's own gate hook blocks) into a git ls-remote check + a bare push. Command-doc only; no code/hook/.ps1 change. 318 contracts + 31 lint green. |
| 5.48 | 2026-06-01 | Stop setup.sh --upgrade nagging "run --migrate" forever after a repo already migrated. --migrate preserves CONTINUITY.md byte-for-byte (idempotent via a <!-- forge:migrated DATE --> sentinel), but the banner keyed only on the file existing — so every later --upgrade re-printed an unsatisfiable "run --migrate" (re-running is a no-op). Confirmed live on mcpgateway. setup.sh/setup.ps1 now detect the sentinel and point at removal instead: gate on the CLAUDE.md sentinel only (a state.md-only marker → still prompts --migrate), key the flag on the bare prefix (date-less markers still recognized), and say "remove once you've confirmed its content landed" (NOT unconditional "safe to delete" — --migrate can stamp the sentinel yet skip content). Tests 8b/8c/8d + contracts. Codex 4 iters (caught partial-migration data-loss, PS case-insensitivity, malformed-date splice, prefix-only miss) + pr-toolkit + /simplify; 804 green. Installer-message only. |
| 5.47 | 2026-06-01 | Stop /codex dumping multi-MB Codex stdout into Claude's context. The Code Review / Design Review / General modes now use the council two-file pattern — --output-last-message for the clean verdict + > /tmp/codex_response_full.txt 2>&1 so the full transcript goes to a forensic log Claude never reads (Step 3 reads the OLM file; falls back to the log only if it's absent/empty). Each clears the stale OLM with : > (not rm -f /tmp/..., which check-bash-safety blocks). Prereq bumped to Codex v0.124.0+ (OLM stability). Contract assertions pin per-mode OLM capture + exact redirect + no blocked rm -f. Codex-reviewed 4 iters (it caught that the flag alone doesn't stop the stream, a stale-OLM race, prereq drift, grep gaps) + pr-toolkit; 774 green. Surfaced on msai-v2 (1.9 MB review dump). |
| 5.46 | 2026-06-01 | Developer Briefing + Developer Demo at the two human control gates — using the Forge now feels like a dev team briefing & demoing to a product owner. Gate 1: a lean ## Developer Briefing in the plan file (optional Mermaid, planned/inferred labels). Gate 2: the PR body is a structured Developer Demo via --body-file — what changed / how it works + one Mermaid diagram / code tour / mechanically-generated file map / verification / an Evidence table citing a real file:line per diagram edge. Demo template inlined byte-identically into both commands (pinned by test-contracts.sh); honesty enforced by review (unsupported Gate-2 diagram edge = P1), not a new hook (council Option A). No new shipped file, no setup change. Designed via Codex consult + 5-advisor council; this PR carries the first real Demo. |
| 5.45 | 2026-06-01 | Fix setup.sh/setup.ps1 silently aborting when run in-place (forge dogfooding via ./setup.sh --upgrade in the repo). copy_file/Copy-TemplateFile had no same-file guard, so in-place runs (SCRIPT_DIR == repo root) hit cp X X on the docs/adr seed copies → "are identical" non-zero exit → set -e aborted the installer before the rules sync. Adds a self-copy guard to the shared copy helper (bash -ef inode identity; PowerShell Resolve-Path … -ceq), placed before the force/exists branches. TDD regression test (extract real copy_file, self-copy under set -e) + pwsh-gated PS parity test. Codex (2 iters) + pr-toolkit; 771 tests green. |
| 5.44 | 2026-06-01 | Add a "Ground Your Claims" behavioral non-negotiable (anti-hallucination): state verified-vs-inferred, cite file:line before asserting about code, say "I haven't checked X" instead of guessing — "Confident guessing is a defect, the same caliber as a known bug left behind." Ships across rules/critical-rules.md (caps bullet, sibling of CHALLENGE ME / NO BUGS LEFT BEHIND), a ## Ground Your Claims Policy headline in CLAUDE.template.md, and a ## Ground Your Claims global default — mirroring the No Bugs Left Behind pattern. A test-contracts.sh parity contract binds the three copies so an edit to one fails CI until the others follow. Docs + 1 assertion; 775 tests green. |
| 5.43 | 2026-05-28 | Close the workflow-gate integrity hole: a no-code carve-out lets a docs-only git commit skip the code-quality gates without marking them N/A (gates stay armed for the real-code ship), killing the "N/A dance" that permanently satisfied them. Fail-safe (any code path / -a/--amend/-p/-i/-o → enforce), commit-only (push/PR always enforce). + 4 sibling fixes: PASS-before-N/A ordering, malformed-loop-line blocking, PowerShell E2E-scan parity, and stdin-cwd+toplevel repo-context resolution. Hardens the compound guard against newline-separated ship chains. Codex-reviewed (5 iterations) + pr-toolkit; 731 tests green. Companion to the anchored-unchecked-probe hotfix (PR #779). |
| 5.42 | 2026-05-27 | Document how /codex picks a mode (developer FAQ): Claude routes, not Codex — hermetic modes are keyword-routed, Investigate is capability-routed (never silently escalates). Improves existing commands.md + codex-investigate.md; no new files. Docs-only. |
| 5.41 | 2026-05-27 | Document autonomous goal mode and Codex Investigate mode as first-class features (were version-history-only): two "What you get" bullets, "How it works" links, Documentation-table rows, two new explainer docs (autonomous-goal.md, codex-investigate.md), and a /codex modes table + autonomous-/goal section in the commands reference. Docs-only. |
| 5.40 | 2026-05-27 | Codex Investigate mode (/codex Section D) + /council live-state fact-finding: Claude provisions Codex with the project's real read-only creds + network to dig into live systems (DB/cloud/API), repo-confined sandbox, no user prompt (autonomous-/goal-safe), cross-verified. Capability-gated, sandbox-enforced. ADR 0007. |
| 5.39 | 2026-05-26 | Hook enforcement of per-iter clean evidence on Plan + Code review loop PASS checkboxes (plan_sha + HEAD binding); closes the v5.38 msai-v2 same-iter-clean shortcut. |
| 5.38 | 2026-05-25 | Whole-UC NOT_USER_JOURNEY trigger + stale-text cleanup. Codex final-pass on v5.34–v5.37 demonstrated a real escape route: an old UC with decent Intent prose ("Customer creates an order through the API") could slide through regression if its Steps were a single curl + Verification was bare status + Persistence was N/A — each individual hard gate is skipped in regression mode, but the combination is "this isn't a journey at all." Step 2b judgment-call #7 now has TWO triggers: Intent shape (existing) AND whole-UC shape (new) — when Steps shallow + Verification bare + Persistence absent all combine, fires NOT_USER_JOURNEY in any mode. Plus three stale-text fixes: rules/testing.md Failure Classification table now lists all 9 reason codes (was out of sync); NOT_USER_JOURNEY no longer claims missing-Persistence (that's MISSING_PERSISTENCE); commands/fix-bug.md:819 simple-fix parenthetical now lists all 8 fields. 392 assertions. |
| 5.37 | 2026-05-25 | Reframe: legacy-UC bounce-back is intentional design, not residual risk. v5.36 surfaced NOT_USER_JOURNEY firing in regression mode as a side effect. Pablo confirmed the opposite: that's the intent — when the regression suite catches old code-shaped UCs from before v5.34, they SHOULD be flagged so the team rewrites them to the new user-journey standard. Phase 5.4b in both commands now splits FAIL_INVALID_USE_CASE into a Hard-SHAPE bucket (skipped in regression by v5.35) and a Judgment-call bucket (NOT_USER_JOURNEY / WRONG_INTERFACE — DO fire in regression mode by design). agents/verify-e2e.md Step 2b mode-gating note gains a mirror sentence. Wording only; no behavior change. 378 assertions. |
| 5.36 | 2026-05-25 | Codex review fixes to v5.34/v5.35. Five concrete tightening edits: (1) replaced stale 6-field intro lines in both workflow commands that contradicted the new 8-field shape; (2) dropped "in this order" rigidity from the required-shape headings; (3) narrowed Persistence: N/A to a whitelisted stateless-outcome exception (any UC whose Steps create/update/delete/transition state gets MISSING_PERSISTENCE regardless of justification); (4) softened the "objective" claim about hard gates with a Mechanical-vs-policy-gates split (SCENARIO_FLUFF / CHEAT_SETUP / non-bare THIN_VERIFICATION require judgment but still block); (5) Phase 5.4b regression promise now says "hard SHAPE gates" so NOT_USER_JOURNEY is explicitly carved out as still firing on legacy UCs. 372 assertions. |
| 5.35 | 2026-05-25 | Step 2b hard gates gated to feature mode only. v5.34's new hard gates were mode-agnostic, retroactively breaking regression suites because UCs graduated under v5.31/v5.33 lacked the required Actor: / Scenario: fields and would fail every regression run. Mirrors v5.33's Step 2c mode-gating: hard gates run in feature mode only; regression/smoke modes fall back to the prefer-valid bias. New UCs going through Phase 3.2b/6.2b authoring still get the strict shape. Contract test locks the gating across agents/verify-e2e.md + both Phase 5.4b blocks. 360 assertions. |
| 5.34 | 2026-05-25 | E2E UC shape — Actor + Scenario + surface-specific Verification. Pablo flagged that v5.31/v5.33 prose said "be specific" but the canonical GOOD examples still modeled generic "User creates…" phrasing. Codex pinned the root cause + rewrote the design. v5.34 adds required Actor field (rejects bare "user" as MISSING_ACTOR) + required Scenario field (1-2 sentences, no biography fluff → SCENARIO_FLUFF) + surface-specific Verification rubric (UI: sees/appears/shows; CLI: stdout shows/next invocation lists; API: receives/follow-up returns — bare status / bare exit / single element-visible → THIN_VERIFICATION) + Setup-cheat detection (CHEAT_SETUP). Step 2b split into hard gates (objective, no judgment) and judgment calls (prefer-valid bias preserved). All three canonical GOOD examples in rules/testing.md rewritten end-to-end. 355 assertions. |
| 5.33 | 2026-05-18 | Multi-surface E2E coverage audit (surfaced during /forge-goal soak when the user asked "did E2E cover UI, CLI, and API?" and the agent admitted it had skipped CLI even though the project's CLI exposed the same capability area). rules/testing.md gains "Multi-surface coverage" subsection distinguishing capability area from implementation diff; commands/{new-feature,fix-bug}.md Phase 3.2b + simple-fix Step 0 add a REQUIRED Surface coverage audit checklist with a Surface coverage decision sub-block (every exposed interface declared as Covered or N/A — <substantive justification>; "no CLI changes in my diff" is canonical disqualifying example). agents/verify-e2e.md adds Step 2c that emits SURFACE_COVERAGE_WARNING as a backstop. 316 assertions. |
| 5.32 | 2026-05-18 | Worktree CWD fix + split build-evidence into its own Stop hook (surfaced during /forge-goal soak in msai-v2). Two coupled bugs: (1) evidence reported session_nonce:null from worktrees because build-evidence read state.md relative to $CLAUDE_PROJECT_DIR (the parent project) instead of the worktree — would have skipped the PR-create authorization gate; fixed by parsing cwd from the Stop hook stdin JSON. (2) Pre-PR Stop hook noise: evidence dump was labeled "Stop hook error" every turn because check-state-updated ran build-evidence inline then exited 2; now build-evidence is its own Stop hook (always exit 0). merge-settings.py gains deep-merge so the upgrade path adds new commands to existing matcher-blocks IN TEMPLATE ORDER. 303 assertions across 4 hot-path suites. |
| 5.31 | 2026-05-18 | E2E user-journey enforcement (surfaced during /forge-goal soak). rules/testing.md gains GOOD-vs-BAD worked examples per UI/API/CLI, an Intent smell test, and a feature-surface-driven interface model (the feature determines the UC interface; project type is only the capability envelope). New per-UC classification FAIL_INVALID_USE_CASE (NOT_USER_JOURNEY / WRONG_INTERFACE) — verify-e2e validates UC shape BEFORE health check, bounces non-journey or wrong-interface UCs back to the main agent for rewrite. New cross-file contract test enforces caller handling for every FAIL_* label. |
| 5.30 | 2026-05-18 | Fix surfaced during /forge-goal soak: check-state-updated.{sh,ps1} CHANGELOG threshold gate downgrades from blocking (exit 2) to advisory (exit 0) when an OPEN PR already exists for the branch. Removes the per-turn "Stop hook error: FORGE_GOAL_EVIDENCE_BEGIN..." dump during CI wait. Also fixes wording: "files changed this session" → "files changed on branch vs <default-branch>". |
| 5.29 | 2026-05-16 | /forge-goal autonomous PRD-to-PR-ready workflow (Layers 1 + 2). After PRD or plan approval, type ONE /goal command; the agent drives plan → implement → review → E2E → PR-ready autonomously. Adds build-evidence.{sh,ps1} (evidence primitive), PRD-Complete + Plan-Approved checkpoints in workflow commands, council-during-/goal rule, PR-create authorization guard, and stuck-detection soft warning. |
| 5.27 | 2026-05-12 | /council chairman synthesis no longer misreports "exited without producing analysis" when codex actually succeeded. Adds --output-last-message <FILE> to all four codex call sites (advisor / chairman / contrarian gate); response captured to a clean file, full stdout kept as diagnostic fallback. PTY shim still load-bearing. |
| 5.26 | 2026-05-10 | rules/database.md gains a "Migrations — additive-only discipline" section: ✅/❌ patterns matrix + 3-release expand-contract pattern for destructive changes + escape-hatch language. Closes a real gap (forge previously had zero migration guidance for teams running rolling deploys). |
| 5.25 | 2026-05-10 | STATE-INIT diagnoses downstream-gitignored .claude/ — emits new STATE_TEMPLATE_DOWNSTREAM_GITIGNORED sentinel pointing at the actual fix (edit .gitignore, commit .claude/) instead of misleading "re-run setup". Bonus: anchors AC-2 redirect regex to fix prose-scan false positives. |
| 5.24 | 2026-05-09 | State-init via Write tool — /new-feature & /fix-bug zero prompts on the state-init path. STATE-INIT block now truly read-only; agent uses Read+Write tools (auto-approved by v5.21 hook, Write creates missing parents per ADR 0006) |
| 5.23 | 2026-05-07 | Switch superpowers identity to superpowers@claude-plugins-official (Anthropic's marketplace, since 2026-01-15) — one-step install, avoids the obra/superpowers-marketplace#11 name-conflict bug |
| 5.22 | 2026-05-07 | Codex PTY shim — .claude/hooks/lib/codex-pty.{sh,ps1} works around openai/codex#19945 (silent empty exit when codex exec runs without a TTY); migrated /codex + /council callsites |
| 5.21 | 2026-04-30 | PermissionRequest hook auto-approves writes to .claude/local/** (workaround for CC v2.1.80+ regression on path-scoped rules) |
| 5.20 | 2026-04-29 | Bump Codex CLI model gpt-5.4 → gpt-5.5 in /codex and /council (OpenAI released GPT-5.5 on 2026-04-23) |
| 5.19 | 2026-04-29 | Allow Write/Edit on .claude/local/** without prompting (workaround for Claude Code v2.1.80+ bare-tool regression) |
| 5.18 | 2026-04-28 | Tighten reconcile prompt — enumerate all CONTINUITY reference types (tree diagrams, prose pointers, labels) |
| 5.17 | 2026-04-28 | Drop per-file template-drift cry-wolf hint; soft "ask Claude to reconcile" tip |
| 5.16 | 2026-04-28 | Migration UX — consolidated "ask Claude" reconcile message; dropped cry-wolf drift hint |
| 5.15 | 2026-04-28 | CONTINUITY split — durable facts to CLAUDE.md, decisions to docs/adr/, volatile state to gitignored .claude/local/state.md |
| 5.14 | 2026-04-27 | Drift hygiene — SessionStart git fetch warning + worktree from origin/<default> |
| 5.13 | 2026-04-21 | Phase 4 task-DAG dispatch with file-conflict constraints |
| 5.12 | 2026-04-21 | Template-drift notice on setup.sh -f / --upgrade |
| 5.11 | 2026-04-20 | ARRANGE rule — close the E2E actor-boundary gap via text layer |
| 5.10 | 2026-04-18 | Evidence-based E2E gate — checkbox claims bound to tests/e2e/reports/ artifact |
| 5.9 | 2026-04-18 | E2E verified gate — close the silent-skip loophole |
| 5.8 | 2026-04-18 | Multi-project interpreter preflight + isolation guide |
| 5.7 | 2026-04-18 | Template self-test suite (4 bash suites, ~5s) |
| 5.6 | 2026-04-17 | Template monorepo support + Playwright security fixes |
| 5.5 | 2026-04-17 | verify-e2e agent (#449) · Playwright CI bridge (#450) · research-first (#472) · repo rename |
| 5.4 | 2026-03-31 | Engineering Council — 5 advisors with Codex chairman (explainer) |
| 5.3 | 2026-03-01 | Silent SessionStart context injection via JSON hookSpecificOutput |
| 5.2 | 2026-02-20 | Frontend design plugin + rules/frontend-design.md |
| 5.1 | 2026-02-19 | CLAUDE.md split — slim file + auto-loaded .claude/rules/ |
| 5.0 | 2026-02-19 | Removed Compound Engineering, replaced with built-in quality gates |
Full history: docs/CHANGELOG.md
Started from Boris Cherny's workflow (Claude Code's creator), Anthropic's official best practices, and OpenClaw's pre-compaction memory patterns — evolved into a dual-agent harness through ongoing iteration.
- Claude Code Docs
- Memory Management
- Hooks Reference
- Skills & Commands
- Anthropic Best Practices
- Subagents Guide
See LICENSE.