@jualopezmo/codeforge 0.4.0

package/src/shared/scripts/claude-gate-hook.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+# claude-gate-hook.sh — Claude Code PreToolUse adapter (opt-in Tier-C hardening).
+#
+# Installed only by `install.sh --with-hooks` into .claude/settings.local.json. On a
+# Bash ship action (git commit / git push / gh pr create) it runs check-gates.sh; if
+# the ship-gate boxes are incomplete it exits 2, which Claude Code treats as a BLOCK.
+# This is the one place codeforge can HARD-block — Claude Code only, per-developer opt-in,
+# not portable. The default install stays advisory. See shared/rules/ship-gates.md.
+#
+# Reads the tool call as JSON on stdin. Fails OPEN (never blocks) if it can't verify —
+# an opt-in convenience must not brick a commit when the install is incomplete.
+set -eu
+
+input="$(cat)"
+
+# Only gate outward ship actions. Match the raw payload (escaping-robust); the
+# PreToolUse matcher already scopes this to Bash calls.
+case "$input" in
+  *'git commit'*|*'git push'*|*'gh pr create'*) : ;;
+  *) exit 0 ;;
+esac
+
+hook_dir="$(cd "$(dirname "$0")" && pwd)"
+gates="$hook_dir/check-gates.sh"
+if [ ! -f "$gates" ]; then
+  echo "codeforge gate-hook: check-gates.sh not found next to the hook; allowing (fail-open)." >&2
+  exit 0
+fi
+
+rc=0
+sh "$gates" >/dev/null 2>&1 || rc=$?
+if [ "$rc" -eq 0 ]; then exit 0; fi        # gates complete → allow
+if [ "$rc" -ne 1 ]; then                    # can't verify (e.g. no state, exit 3) → fail OPEN
+  echo "codeforge gate-hook: could not verify gates (check-gates exit $rc); allowing (fail-open)." >&2
+  exit 0
+fi
+
+# rc == 1: ship-gate incomplete → block with the detail.
+echo "codeforge gate: ship BLOCKED — ship-gate boxes are not complete." >&2
+sh "$gates" 2>&1 | sed 's/^/  /' >&2 || true
+echo "  (opt-in --with-hooks gate; Claude Code only. Finish the boxes in" >&2
+echo "   .workflow/state.md, then retry. This checks the record, not the work.)" >&2
+exit 2

package/src/shared/state.template.md

@@ -0,0 +1,33 @@
+# Workflow State — <feature-name>
+
+> Copy this file to `.workflow/state.md` when a workflow starts. It is the source of truth
+> the ship-gate reads. Keep it updated as you progress.
+
+## Active workflow
+
+- **Skill:** new-feature
+- **Profile:** standard  <!-- standard (new-feature, fix-bug) | light (quick-fix) — see shared/rules/ship-gates.md -->
+- **Feature:** <name>
+- **Branch:** <feat/...>
+- **Driver:** <claude | codex | opencode>
+- **Phase:** <brainstorm | plan | design-review | tdd | code-review | verify | ship>
+
+## Ship-gate checklist (boxes for the Profile above — see shared/rules/ship-gates.md)
+
+<!-- `standard` profile shown below; for the `light` profile (quick-fix) use its shorter list. -->
+
+- [ ] On a feature branch (not `main`)
+- [ ] Plan written and design-reviewed by the other engine — `N/A: <reason>` allowed for a simple fix-bug (see ship-gates.md)
+- [ ] Tests written (TDD) and passing
+- [ ] Code review clean — no open P0/P1/P2
+- [ ] E2E verified via verify-e2e (report: docs/e2e/reports/<...>.md)
+- [ ] State updated
+
+## Review log
+
+- Design review iteration 1 — <engine> — findings: <P0/P1/P2 counts or "clean">
+- Code review iteration 1 — <engine> — findings: <...>
+
+## Notes
+
+<decisions, assumptions, what was verified>

package/src/skills/adr/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: adr
+description: Record an architecture decision as an ADR (`docs/adr/<NNN>-<slug>.md`) — capture the context, the decision, the alternatives considered, and the consequences, so the reasoning survives. Use after making a significant, hard-to-reverse choice (a dependency, a boundary, a data model, a protocol) under Claude Code, Codex, or OpenCode.
+---
+
+# adr
+
+Write down *why*, not just *what*. An Architecture Decision Record captures a significant
+choice and the reasoning behind it so the next session — or the next engine, or a teammate —
+doesn't re-litigate a settled question or undo it without knowing the cost. This records a
+decision already made (by `plan`, `council`, or you); it doesn't make one.
+
+## 1. Decide if it warrants an ADR
+
+Write one when the choice is **significant and hard to reverse**: a framework/dependency, a
+module boundary, a data model, an API/protocol, a security or migration strategy. Skip it for
+reversible, local, or obvious choices — an ADR for those is noise.
+
+## 2. Number and name it
+
+Find the highest existing `docs/adr/<NNN>-*.md` and use the next sequential number. Name it
+`docs/adr/<NNN>-<slug>.md` (`shared/rules/docs-layout.md`), slug after the decision
+(`012-event-sourcing-for-orders.md`).
+
+## 3. Write it
+
+Keep it short and specific:
+
+- **Status** — `accepted` (or `proposed` / `superseded by NNN`).
+- **Context** — the forces at play: constraints, requirements, what made this a real fork.
+- **Decision** — what you're doing, in active voice ("We will …").
+- **Alternatives considered** — the other real options and **why each lost**. This is the part
+  that stops a future re-litigation.
+- **Consequences** — the trade-offs: what becomes easier, what becomes harder, what you accept.
+
+## 4. Link it
+
+Reference the ADR from the plan and/or `.workflow/state.md` so it's discoverable. If it
+replaces an earlier decision, mark the old ADR `superseded by <NNN>` and link both ways —
+ADRs are append-only history, never rewritten.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "The decision is obvious — no need to write it down." | It's obvious *today*. The ADR is for whoever asks "why is it this way?" six months from now with none of today's context. |
+| "I'll just capture it in the commit message." | Commit messages aren't browsable as decisions. ADRs live in `docs/adr/` where the next session actually looks. |
+| "I'll state the decision but skip the alternatives." | The alternatives and why they lost are the most valuable part — without them the ADR can't defend itself when someone wants to reverse it. |
+| "We changed our mind — I'll edit the old ADR." | ADRs are append-only. Supersede the old one and write a new one; don't rewrite the past. |
+
+## Red flags
+
+- The ADR states the decision but not the context/forces that drove it.
+- No alternatives, or alternatives with no reason they lost.
+- You edited a prior ADR's decision instead of superseding it.
+- It's recording a trivial, easily-reversed choice (ADR overkill).
+
+## Verification
+
+`docs/adr/<NNN>-<slug>.md` exists with the next sequential number and states Status, Context,
+Decision, Alternatives (with why each lost), and Consequences. If it replaces an earlier
+decision, that ADR is marked superseded and linked. The record is referenced from the plan or
+`.workflow/state.md`. An ADR missing its alternatives or consequences is incomplete — finish it.

package/src/skills/checkpoint/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: checkpoint
+description: Write a clean session handoff to CONTINUITY.md before closing a session or resetting context, so the next session knows the current state and the exact next step. Use when wrapping up under Claude Code, Codex, or OpenCode.
+---
+
+# checkpoint
+
+Capture enough that a fresh session (or a different engine) can pick up without you
+re-explaining. See `shared/rules/continuity.md`.
+
+## 1. Assess current state
+
+In one pass, determine: what's done, what's in progress, the **single next action** to
+take on resume, and any blocker. Be concrete — "continue the feature" is useless; "write
+the failing test for the empty-cart case in `cart_test`" is a handoff.
+
+## 2. Update CONTINUITY.md
+
+Write `CONTINUITY.md` at the repo root (create it from `CONTINUITY.template.md` if
+missing) with: Focus, Next step, Blockers, Active-workflow pointer, Updated date, and 2–4
+handoff notes (where we are, why, key context/decisions). Keep it tiny.
+
+## 3. Sync the workflow pointer
+
+If a workflow is active, make sure `.workflow/state.md` is current too, and that
+`CONTINUITY.md`'s "Active workflow" points to it. Don't copy state.md's content into
+`CONTINUITY.md` — just point.
+
+## 4. Confirm
+
+State a one-line summary of what the next session will pick up.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "'Continue the feature' is a fine next step." | A vague handoff defeats the purpose. The Next step must be a specific action ("write the failing test for the empty-cart case"). |
+| "I'll copy state.md into CONTINUITY.md." | Point at state.md, don't duplicate it — two copies drift. Keep CONTINUITY.md tiny. |
+| "No need to note the blocker." | The next session inherits the blocker blind if you don't record it. |
+
+## Red flags
+
+- The Next step is generic ("keep going", "finish it").
+- CONTINUITY.md duplicates state.md instead of pointing at it.
+- No Updated date, or it isn't today's.
+
+## Verification
+
+`CONTINUITY.md` exists with a **concrete Next step** (a specific action, not "continue")
+and an Updated date of today. A vague handoff defeats the purpose — rewrite it.

package/src/skills/council/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: council
+description: Multi-perspective decision analysis — consult two or more engines (Claude, Codex, OpenCode) as independent advisors on one hard, expensive decision, then synthesize a verdict with a mandatory minority report. Use for architecture choices, approach forks, or any fork-in-the-road where being wrong is costly. Not for routine choices with an obvious default.
+---
+
+# council
+
+Turn an expensive, hard-to-reverse decision into a diverse, auditable vote. The value is
+**model diversity**: independent advisors from *different* engines, synthesized by the
+driver acting as chairman.
+
+## When to use
+
+- Architecture decisions, approach forks, tech/tradeoff choices where being wrong is
+  costly or hard to undo.
+
+**Do NOT use** for routine choices with an obvious default — that's just the driver
+deciding. Council is for genuine ambiguity with real stakes.
+
+## 1. Frame the question
+
+Write ONE decision-shaped question with the concrete options and the constraints that
+matter. Not "how do I do X" — rather "should we do A or B, given C, D?". List the options
+explicitly. A vague prompt produces vague advice.
+
+## 2. Pick the advisors (must span engines)
+
+Choose **at least two distinct engines** as advisors; the more model diversity, the
+better. The driver may include itself as one voice, but the panel must not be a single
+engine talking to itself. Optionally assign each advisor a different lens so they don't
+all reason the same way, e.g.:
+
+- **Simplicity** — the least-moving-parts option.
+- **Blast radius / risk** — what breaks, how reversible.
+- **Longevity** — maintainability and cost over time.
+
+## 3. Consult each advisor independently
+
+Send each advisor the **same framed question** (plus its lens), and do it
+**independently** — an advisor must not see another's answer, or you lose the diversity.
+Use each engine's **non-interactive** mode (Codex `codex exec`, Claude `claude -p`, OpenCode
+`opencode run`), spanning all three engines for max diversity. The exact **model IDs, effort,
+and read-only invocation** for each engine live in one place — `shared/rules/models.md` —
+so use them from there; do not hard-code them here. Advisors must run **read-only** (they
+advise, they don't edit) per the read-only invocation in `models.md`.
+
+Capture from each: its position, key reasoning, and a one-line recommendation. If an
+advisor's output is missing or unparseable, re-run it — do not invent a position for it.
+
+## 4. Synthesize (chairman)
+
+As the driver, produce the verdict:
+
+- **Agreement** — where advisors converge (the strongest signal).
+- **Divergence** — where and why they differ.
+- **Verdict** — the recommended decision and the reason.
+- **Minority report (mandatory)** — the strongest dissenting view, stated fairly. If every
+  advisor agreed, say so explicitly and note the biggest residual risk. Never drop this —
+  it is the guard against groupthink.
+
+## 5. Record
+
+Write the framed question, each advisor's one-line position, the verdict, and the minority
+report into `.workflow/state.md` (or the relevant plan/decision doc), so the decision is
+auditable later.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "I'll ask one engine twice for the two views." | A panel of one engine is groupthink. Advisors must span ≥2 distinct engines or it isn't a council. |
+| "Let the advisors see each other's answers to build on them." | Independence is the whole point — shared answers collapse the diversity into one view. Consult each blind. |
+| "They all agreed, so I'll drop the minority report." | The minority report is mandatory. If all agreed, state the biggest residual risk — it's the guard against groupthink. |
+| "This is a routine call — run a council to be safe." | Council is for expensive, hard-to-reverse forks. For an obvious default, just decide; don't burn the ceremony. |
+
+## Red flags
+
+- All advisors are the same engine.
+- Advisors saw each other's positions before answering.
+- The verdict has no minority report / residual-risk note.
+- You convened a council for a decision that had an obvious default.
+
+## Verification
+
+Before returning, confirm the output contains: the framed question, ≥2 distinct-engine
+advisor positions, a verdict, and a non-empty minority report. Missing any of these means
+the council did not actually run — redo it rather than presenting a thin verdict.

package/src/skills/finish-branch/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: finish-branch
+description: Wrap up a completed branch — confirm the ship-gate profile is green, do a final verify, record durable docs, then commit, push, and open the PR. Use to close out work under Claude Code, Codex, or OpenCode after the feature/fix workflow is done.
+---
+
+# finish-branch
+
+Close out a branch cleanly. This does not replace the feature/fix workflow — it's the
+final step after one.
+
+## 1. Confirm the gates
+
+Run the deterministic checker — don't just eyeball the file:
+
+```sh
+sh shared/scripts/check-gates.sh        # pwsh shared/scripts/check-gates.ps1 on Windows
+```
+
+It reads `.workflow/state.md`, confirms **every box for the active profile** is checked (or
+N/A), and exits non-zero listing any that aren't (`shared/rules/ship-gates.md`). If it fails,
+go back and finish those boxes — do not ship.
+
+This is **Tier B**: it verifies the *record*, not the work. A checked box is an
+*attestation* (you claimed it), not independent proof — so also spot-confirm the underlying
+work is real (tests actually ran, the change was actually exercised). See the
+Verified / Attested / Advisory distinction in `shared/rules/ship-gates.md`.
+
+`check-gates` now also enforces the `E2E verified` marker — if it's checked (not `N/A:`),
+a fresh `VERDICT: PASS` report must exist under `docs/e2e/reports/`. finish-branch relies on
+the report produced during the workflow; it does not re-run the journeys.
+
+## 2. Final verify
+
+Run the test suite and exercise the change once more end-to-end. Confirm the working tree
+is otherwise clean and the branch is up to date.
+
+## 3. Record durable docs — BEFORE shipping
+
+Do this **before** the ship commit so the documentation ships *with* the change (not left
+uncommitted, and never as a second unreviewed commit):
+
+- Add a newest-first entry to `docs/CHANGELOG.md` (`shared/rules/docs-layout.md`).
+- Save any reusable learning per `shared/rules/memory.md` (solved bugs → `docs/solutions/`,
+  decisions → `docs/adr/`).
+
+## 4. Commit
+
+Commit all intended changes **including the docs from step 3** with a clear message.
+Nothing uncommitted, no stray files.
+
+## 5. Push + open PR
+
+Push the branch and open the PR. Both hit the **native prompt** (a commit-confirmation, not
+a gate — `shared/rules/ship-gates.md`) — approve only because you just confirmed the gates
+in step 1. Write a PR description stating what changed, why, and how it was verified.
+
+## 6. Update transient state
+
+Only now — after shipping — record the PR link / merge outcome in `.workflow/state.md` so
+the workflow state reflects reality. (This is the one thing that legitimately comes after
+the ship commit.)
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "The gates are basically green — ship it." | "Basically" isn't checked. Any open required box means go back and finish it; the native prompt is not the gate. |
+| "I'll add the changelog / ADR in a follow-up commit." | Docs ship *with* the change, in the same commit. A second unreviewed commit is exactly how they get lost. |
+| "The push prompt appeared, so I'm cleared to ship." | The prompt is a commit-confirmation that reads no gate state (`shared/rules/ship-gates.md`). It proves nothing — you are the gate. |
+| "I'll record the PR outcome later." | Update `.workflow/state.md` with the PR link / merge outcome now, so the workflow reflects reality. |
+
+## Red flags
+
+- An open box in `.workflow/state.md` and you're pushing anyway.
+- The CHANGELOG / ADR is uncommitted or slated for "later."
+- You approved the push prompt without re-confirming the gates in step 1.
+- Stray or unintended files in the working tree at commit time.
+
+## Verification
+
+- [ ] Every required box for the active profile is checked in `.workflow/state.md`.
+- [ ] Full suite run and the change exercised end-to-end once more.
+- [ ] CHANGELOG entry (+ ADR / solution where applicable) committed *with* the change.
+- [ ] Working tree clean — nothing stray, nothing uncommitted.
+- [ ] PR opened stating what changed, why, and how it was verified; outcome recorded in state.

package/src/skills/fix-bug/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: fix-bug
+description: Bug-fix workflow with systematic debugging — reproduce with a failing test, isolate root cause, fix minimally, cross-review, verify, and ship behind the ship-gate. Use when correcting incorrect behavior under Claude Code, Codex, or OpenCode.
+---
+
+# fix-bug
+
+Fix a defect with evidence, not guesses. Works identically under all three engines.
+
+## 0. Set up tracking
+
+- Confirm you are **not on `main`** — create a branch (`fix/<name>`).
+- Copy `shared/state.template.md` to `.workflow/state.md`; set skill = `fix-bug`, **Profile:
+  standard**, feature/bug name, branch, and driver.
+
+## 1. Reproduce
+
+Reproduce the bug deterministically. Capture the exact input, expected vs actual, and the
+smallest failing case. Do not propose a fix until you can trigger it on demand.
+
+## 2. Root cause (systematic debugging)
+
+Form a hypothesis, add logging/assertions to test it, and confirm the actual cause before
+touching the fix. Read the relevant code and cite `file:line`. Distinguish what you
+verified from what you infer.
+
+## 3. Failing test first (TDD)
+
+Write a test that fails **because of the bug** (red) — see `shared/rules/tdd.md`. This
+proves the repro and prevents regression. For a high-impact surface, also design-review
+the fix approach with the `review` skill (a different engine) before implementing.
+
+## 4. Fix minimally
+
+Make the smallest change that turns the test green. Refactor only if it clarifies. Fix
+the real cause, not the symptom.
+
+## 5. Code review (cross-engine)
+
+Review the diff with the **other** engine (`review` skill; models per
+`shared/rules/models.md`) + a self-pass; resolve all P0/P1/P2 (`shared/rules/severity.md`).
+Record iterations in `.workflow/state.md`.
+
+## 6. Verify
+
+Exercise the original repro and confirm it's gone; check you didn't break neighbors.
+Note what you observed. Then run the `verify-e2e` skill to confirm the fix through the
+user-facing interface (API/CLI). Internal-only fixes record
+`E2E verified — N/A: <reason>`. Record the fix (symptom → root cause → fix → how
+verified) in `docs/solutions/<slug>.md` (`shared/rules/memory.md`).
+
+## 7. Ship
+
+Only when every required box in `.workflow/state.md` is checked
+(`shared/rules/ship-gates.md`). Commit, then push / open PR — approve the native prompt
+only if the gates are green.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "The cause is obvious — I'll just fix it." | A fix without a reproduced failing test is a guess. Reproduce first; read the code and cite `file:line`. |
+| "A failing test is overkill for this bug." | The failing test proves the repro and blocks regression — it *is* the fix's evidence. Red before green. |
+| "It's late / the lead said skip the regression test." | Time and authority pressure don't change that an unproven fix regresses. The failing test is non-negotiable. |
+| "The suite passes, so it's verified." | Re-exercise the *original* repro and check neighbors. Green tests ≠ the user's bug is gone. |
+| "This patch makes the symptom go away." | Fix the root cause, not the symptom, or it comes back. |
+
+## Red flags
+
+- You're writing the fix before you can trigger the bug on demand.
+- No test fails *because of the bug*.
+- You changed code you haven't read (no `file:line` cited).
+- You're patching the symptom, not the cause.
+- You skipped the cross-engine review to "save time."
+
+## Verification
+
+- [ ] Bug reproduced deterministically before any fix.
+- [ ] A test failed because of the bug (red) and passes after (green).
+- [ ] Root cause identified and cited (`file:line`) — not the symptom.
+- [ ] Cross-engine review clean; all P0/P1/P2 resolved.
+- [ ] Original repro re-exercised and gone; neighbors intact.
+- [ ] Fix recorded (symptom → root cause → fix → how verified) in `docs/solutions/`.
+- [ ] Every required ship-gate box checked.

package/src/skills/index/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: index
+description: Generate or refresh docs/index.md — a high-level project map (structure, key locations, entry points, conventions) so an agent orients fast without re-scanning the whole tree. Use when onboarding to a project or after a significant structural change, under Claude Code, Codex, or OpenCode.
+---
+
+# index
+
+Give the agent a curated map instead of re-scanning the tree every session. Keep it
+**high-level** so it stays fresh — structure and conventions change slowly; line-level
+detail churns and goes stale fast.
+
+## 1. Scan the shape
+
+List the top-level layout, the key directories, and the notable files. Identify the
+**entry points** (how you run / build / test / install it) and the main modules or areas.
+
+## 2. Find the conventions
+
+Note the conventions an agent must know to work here: naming, where each kind of thing
+lives, patterns, and gotchas. Pull them from `PROJECT.md`, `README.md`, and the code —
+don't invent them.
+
+## 3. Write docs/index.md
+
+Write a concise map: what the project is (one line + link to `README.md`), entry points, a
+"where things live" table (directory → purpose), the key files, and the conventions. Do
+**not** enumerate every file or go line-level — that is what goes stale.
+
+## 4. Note freshness
+
+Add an `Updated:` date. Refresh after a **significant structural change** (a new top-level
+area, moved/renamed modules) — not on every edit.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "I'll list every file so the map is complete." | Line-level detail goes stale fast. Keep the map high-level — structure and conventions, not an inventory. |
+| "I'll infer the conventions." | Pull conventions from `PROJECT.md` / `README.md` / the code — don't invent them. |
+| "No need to check the paths are real." | An index that lists paths that don't exist is worse than none. Spot-check they exist. |
+
+## Red flags
+
+- The map enumerates individual files or drops to line-level detail.
+- Conventions are asserted with no source in the repo.
+- Listed paths don't exist, or there's no `Updated:` date.
+
+## Verification
+
+`docs/index.md` names **real, current** top-level paths and entry points (spot-check they
+exist), stays high-level, and carries an `Updated:` date. If it lists paths that don't
+exist, it's stale — regenerate it.

package/src/skills/new-feature/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: new-feature
+description: Full feature workflow — research, plan, cross-engine design review, TDD, code review, verify, and ship behind the ship-gate. Use when starting or implementing any new feature or behavior change — build it end to end with tests and review — under Claude Code, Codex, or OpenCode.
+---
+
+# new-feature
+
+Drive a feature from idea to shipped change with cross-engine review discipline. Works
+identically under Claude Code, Codex, and OpenCode.
+
+## 0. Set up tracking
+
+- Confirm you are **not on `main`** — create a branch (`feat/<name>`).
+- Copy `shared/state.template.md` to `.workflow/state.md`; set **Profile: standard**, the feature name, and branch.
+
+## 1. Research (when external tech is involved)
+
+If the feature touches an unfamiliar or external library/API/protocol, run the `research`
+skill first and write a sourced brief (`shared/rules/research.md`). Skip only for changes
+fully contained in code you already understand.
+
+## 2. Plan
+
+Clarify intent, then compare 2–3 approaches and pick one — use the `plan` skill and the
+fixed axes in `shared/rules/approach-comparison.md`. Capture the goal, chosen approach,
+files/units to touch, edge cases, the test plan, and acceptance criteria. Keep units
+small. Do not write implementation code yet.
+
+## 3. Design review (cross-engine)
+
+Validate the plan with the `review` skill (a *different* engine reviews) — or `council`
+for a hard fork. Reviewer/advisor models come from `shared/rules/models.md`. Collect
+findings by severity (`shared/rules/severity.md`); resolve P0/P1/P2; record the iteration
+in `.workflow/state.md`.
+
+## 4. TDD
+
+Red → green → refactor (`shared/rules/tdd.md`). Write the failing test first, make it pass
+minimally, then refactor. Never write implementation before a failing test exists.
+
+## 5. Code review (cross-engine)
+
+Review the diff with the `review` skill (the other engine) + a self-pass. Fix all
+P0/P1/P2. Repeat until a single pass is clean. Record iterations in `.workflow/state.md`.
+Then run `simplify` for a behavior-preserving cleanup pass while the suite is green.
+
+## 6. Verify
+
+Run the `verify-e2e` skill: design/execute API & CLI user-journey use cases, and let it
+write the evidence report the ship-gate checks. For purely internal or UI-only changes,
+record `E2E verified — N/A: <reason>` in `.workflow/state.md`.
+
+## 7. Ship
+
+Only when every required box in `.workflow/state.md` is checked (`shared/rules/ship-gates.md`).
+Commit, then push / open PR — approve the native prompt **only if the gates are green**.
+Record the change in `docs/CHANGELOG.md` and save any reusable learning
+(`shared/rules/memory.md`). Or run `finish-branch` to do the wrap-up.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "I understand this — skip the plan." | Even familiar work benefits from comparing approaches and a written plan the reviewer can check. A plan gap that builds the wrong thing is a P1 (`shared/rules/severity.md`). |
+| "I'll write the tests after the code." | TDD is red → green → refactor. Implementation before a failing test isn't TDD and silently skips cases. |
+| "The reviewer is just another AI — its findings don't count." | The whole point is a second, differently-trained model catching what you miss. Resolve P0/P1/P2 before shipping. |
+| "I'll do the design review after I've built it." | Reviewing after implementation only sees code consistent with an *unreviewed* plan. Review the plan first, where the cheap fixes are. |
+| "Tests pass, no need to actually run it." | Exercise the real change — tests alone miss integration, wiring, and UX defects. |
+
+## Red flags
+
+- No plan file, or a plan with a single approach and no comparison.
+- Implementation code exists before any failing test.
+- You reviewed with the same engine that wrote the code (no cross-engine pass).
+- You're about to ship on green tests without exercising the change end-to-end.
+
+## Verification
+
+- [ ] Plan written with a compared, chosen approach + acceptance criteria.
+- [ ] Design reviewed cross-engine; P0/P1/P2 resolved.
+- [ ] TDD followed — a failing test preceded each piece of implementation.
+- [ ] Code review clean on a single pass (cross-engine + self-pass).
+- [ ] Change exercised for real; outcome observed and noted.
+- [ ] Every required ship-gate box checked; `docs/CHANGELOG.md` updated.

package/src/skills/plan/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: plan
+description: Turn an idea into a reviewed design — clarify intent, compare 2–3 approaches on fixed axes, pick one with rationale, and write a plan the implementation follows. Use before building a non-trivial change under Claude Code, Codex, or OpenCode. Feeds new-feature / fix-bug.
+---
+
+# plan
+
+Design before you build. Produces a written plan that `new-feature` / `fix-bug`
+implements against. Pairs with `research` (run it first when external tech is involved).
+
+## 1. Clarify intent
+
+Pin down purpose, constraints, and success criteria. Ask the user one question at a time
+only when something is genuinely ambiguous; otherwise state your assumptions and proceed.
+Do not write implementation code in this phase.
+
+## 2. Compare approaches
+
+List **2–3 genuinely different** approaches and score them on the fixed axes in
+`shared/rules/approach-comparison.md` (complexity, blast radius, reversibility, time to
+validate, correctness/user risk). Name the default winner and why — prefer the simplest
+option that clears the bar.
+
+## 3. Validate the choice (don't self-certify)
+
+Run `review` or `council` on the chosen approach before locking it in. If the cheapest
+falsifying experiment is quick, spike it first and let evidence decide. Resolve any
+P0/P1/P2 the reviewer raises (`shared/rules/severity.md`).
+
+## 4. Write the plan
+
+Capture: the goal, the chosen approach + the comparison table, the files/units to touch,
+edge cases, the tests that will prove it (TDD — `shared/rules/tdd.md`), and acceptance
+criteria. Keep units small and single-purpose. Save to `docs/plans/<feature>.md`
+(`shared/rules/docs-layout.md`) and reference it from `.workflow/state.md`. Record any
+significant architecture decision as an ADR (the `adr` skill) in `docs/adr/`.
+
+## 5. Hand off to implementation
+
+`new-feature` / `fix-bug` build from this plan. A gap here propagates downstream, so a
+missing required behavior or acceptance criterion is a P1, not a nit.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "I already know the best approach — skip the comparison." | Comparing 2–3 genuinely different options is how you catch the cheaper one you didn't consider, and it gives the reviewer something to check. |
+| "One approach is enough to write down." | A plan with a single option and no trade-offs is a decision with no audit trail. Name the alternatives and why they lost. |
+| "I'll validate the choice by just building it." | Self-certifying skips the cross-engine check where design flaws are cheapest to fix. Review the choice (or spike it) before locking in. |
+| "The acceptance criteria are obvious — leave them out." | Implementation builds from the plan; a missing criterion becomes the wrong feature. Spec-loss is a P1, not a nit. |
+
+## Red flags
+
+- The plan lists one approach, or "alternatives" that aren't genuinely different.
+- You picked the most complex option without justifying it over the simplest.
+- No test plan or acceptance criteria.
+- You locked the choice with no second-engine review and no spike evidence.
+
+## Verification
+
+The plan states the goal, a compared-and-chosen approach (with rationale), the test plan,
+and acceptance criteria; the choice was reviewed by another engine. Missing any of these
+means it's not ready to implement.