@jualopezmo/codeforge 0.4.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jualopezmo/codeforge",
+  "version": "0.4.0",
+  "description": "Install one cross-engine AI-coding workflow discipline (research → plan → TDD → cross-engine review → verify → ship) into a project — runs identically on Claude Code, Codex, and OpenCode. Also hosts the framework's own dev tooling (skill linter, routing evals).",
+  "bin": {
+    "codeforge": "bin/codeforge.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "install.sh",
+    "install.ps1",
+    "VERSION",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint:skills": "node tools/lint-skills.mjs",
+    "eval:routing": "node tools/run-evals.mjs",
+    "test:tools": "node --test",
+    "check": "npm run lint:skills && npm run eval:routing && npm run test:tools"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Juan-Motta/codeforge.git"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "opencode",
+    "ai-agents",
+    "agent-skills",
+    "workflow"
+  ]
+}

package/src/CLAUDE.md

@@ -0,0 +1,88 @@
+# Workflow discipline for Claude Code, Codex + OpenCode
+
+> This file is the always-on instruction set. `AGENTS.md` is a generated copy of it, so
+> **Claude Code** (reads `CLAUDE.md`), **Codex** (reads `AGENTS.md`), and **OpenCode**
+> (reads `AGENTS.md`, falls back to `CLAUDE.md`) all load the exact same discipline — no
+> symlinks, no drift. Both are generated from the codeforge source; to change the discipline,
+> edit the source there and re-run the codeforge installer against this project (don't
+> hand-edit `CLAUDE.md`/`AGENTS.md` here — a re-install overwrites them).
+
+## What this is
+
+A lightweight, **skills-and-config-only** workflow system. It's **discipline, not a hard
+gate**: you follow the instructions (advisory), plus each engine shows a **best-effort
+native prompt** on outward actions (push / PR) that the human confirms — it reads no gate
+state and is bypassable. It runs identically under Claude Code, Codex, and OpenCode.
+
+## Golden rules (always apply)
+
+- **Resume from continuity.** At the start of each session, read `CONTINUITY.md` first and
+  continue from its **Next step** before anything else; if it names an active workflow,
+  open that `.workflow/state.md` too. See `shared/rules/continuity.md`.
+- **Load project rules.** Also read `PROJECT.md` — this project's persona, info,
+  variables, and special rules. It **adds** to these global rules and **should not**
+  override the safety/ship-gate baseline (advisory — nothing enforces this). See
+  `shared/rules/project-rules.md`.
+- **Never work on `main`.** Create a branch before changing code.
+- **Pick the right workflow skill** for the task (see index below) and follow it.
+- **`.workflow/state.md` is the source of truth** for the active workflow: its checklist
+  gates shipping. Keep it updated as you progress. If it doesn't exist for the current
+  task, start from `shared/state.template.md`.
+- **Do not ship until the gates pass.** Before `git commit` / `git push` /
+  `gh pr create`, every required box in `.workflow/state.md` must be checked. See
+  `shared/rules/ship-gates.md`.
+- **Challenge, don't flatter.** Push back on weak ideas; verify claims against the code.
+- **Ground your claims.** State what you verified vs. inferred; cite `file:line`.
+- **Capture learnings.** Save reusable solutions/decisions to the repo `docs/` (portable
+  memory) — see `shared/rules/memory.md` and `shared/rules/docs-layout.md`.
+
+## Workflow skills (canonical in `skills/`, discovered by all three harnesses)
+
+- `prd` — write a product requirements doc (problem/users/goals) before designing
+- `research` — pre-design research: check current docs + prior art, write a sourced brief
+- `plan` — design step: clarify intent, compare approaches, write a reviewed plan
+- `new-feature` — full feature workflow (brainstorm → plan → cross-review → TDD → review → verify → ship)
+- `fix-bug` — bug fix with systematic debugging (reproduce → root cause → failing test → fix → review → verify → ship)
+- `quick-fix` — trivial changes (<3 files, no behavior risk); escalate if scope grows
+- `review` — cross-engine second opinion on a plan or diff (P0–P3 findings)
+- `simplify` — post-green, behavior-preserving cleanup pass (reduce complexity, tests stay green)
+- `verify-e2e` — execute API/CLI user-journey use cases, write an evidence report, and bind the E2E ship-gate box to it
+- `council` — multi-perspective decision analysis: several engines as advisors → synthesized verdict + minority report (for hard, expensive forks)
+- `adr` — record an architecture decision (context, alternatives, consequences) → `docs/adr/`
+- `finish-branch` — close out a branch: confirm gates → final verify → commit → push → PR
+- `checkpoint` — write a clean session handoff to `CONTINUITY.md` before closing / context reset
+- `index` — generate/refresh `docs/index.md`, a high-level project map for fast orientation
+
+## Discipline reference (`shared/rules/`)
+
+- `workflow.md` — when to use which skill; the phases
+- `severity.md` — P0–P3 rubric for review findings
+- `ship-gates.md` — what must be true before commit/push/PR, and how each harness gates it
+- `tdd.md` — red-green-refactor discipline
+- `research.md` — when to research and what a good brief contains
+- `approach-comparison.md` — fixed-axes table for choosing an approach
+- `memory.md` — what to save and where (repo-first, portable across engines)
+- `docs-layout.md` — where each artifact lives (`docs/prds|plans|research|solutions|adr`, `CHANGELOG.md`)
+- `continuity.md` — session handoff via `CONTINUITY.md`; how to resume on a new session
+- `models.md` — default model per role (research/review/council); reviewer ≠ driver
+- `project-rules.md` — how per-project `PROJECT.md` layers on the global baseline (precedence)
+
+## Enforcement model (read this — it's a deliberate trade)
+
+By default there is **no hard conditional block**. The skills instruct you to run the gates
+before shipping (advisory), and `finish-branch` runs `shared/scripts/check-gates.sh` — a
+deterministic check of `.workflow/state.md` that fails loudly on an unchecked box (still only
+when invoked). On top of that, each harness applies a **coarse native approval** on outward
+actions:
+
+- **Claude Code:** `git push` / `gh pr create` are `ask`-tier in `.claude/settings.json`
+  (human approves).
+- **Codex:** `approval_policy` in `.codex/config.toml` requires approval before running
+  non-trivial shell commands.
+- **OpenCode:** `permission.bash` in `opencode.json` sets `git push*` / `gh pr create*`
+  to `ask` (and force-push to `deny`).
+
+None of them read `.workflow/state.md` to decide — they always ask; you approve, after
+checking the gates (or running `check-gates.sh`). For real blocking on Claude Code,
+`install.sh --with-hooks` adds an opt-in `PreToolUse` hook that exits 2 on incomplete gates.
+A checked box is *attested*, not *verified* — see `shared/rules/ship-gates.md`.

package/src/CONTINUITY.template.md

@@ -0,0 +1,16 @@
+# Continuity — session handoff
+
+> The first thing to read on a new session (auto-loaded via `CLAUDE.md` / `AGENTS.md`).
+> Keep it current; refresh it with the `checkpoint` skill before closing a session.
+> Roles: this file = cross-session "where am I / what's next"; `.workflow/state.md` = the
+> active workflow's checklist. Non-overlapping — this points to state.md, doesn't copy it.
+
+- **Focus:** <what you're working on, one line>
+- **Next step:** <the single next action to take on resume — an action, not "continue">
+- **Blockers:** <what's stuck, or "none">
+- **Active workflow:** <path to `.workflow/state.md` if one is running, else "none">
+- **Updated:** <YYYY-MM-DD>
+
+## Handoff notes
+
+<2–4 lines: where we are, why, and the key decisions/context the next session needs>

package/src/PROJECT.template.md

@@ -0,0 +1,27 @@
+# Project rules
+
+> Project-specific rules for THIS project. Always loaded alongside the global baseline
+> (`CLAUDE.md` golden rules + `shared/rules/*`). These **add and refine** — they
+> **should not** override the global safety rules (branch safety, ship-gate) — advisory;
+> nothing enforces it. See `shared/rules/project-rules.md`.
+> Copy this file to `PROJECT.md` and fill it in.
+
+## Persona
+
+<How the agent should behave here: tone, stance, what to optimize for. One short paragraph.>
+
+## Project info
+
+<What this project is, its stack, layout, and anything an agent needs to orient. A few lines.>
+
+## Variables
+
+<Stable facts the agent should reuse: repo URL, service URLs/ports, key names, entry points.>
+
+- `<KEY>`: `<value>`
+
+## Special rules
+
+<Project-specific dos/don'ts that go beyond the global baseline. Bullet list.>
+
+- <rule>

package/src/configs/claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "permissions": {
+    "ask": ["Bash(git push:*)", "Bash(gh pr create:*)", "Bash(gh pr merge:*)"],
+    "deny": ["Bash(git push --force:*)", "Bash(git push -f:*)"]
+  }
+}

package/src/configs/codex/config.toml

@@ -0,0 +1,17 @@
+# Codex-native options for codeforge (no scripts/hooks).
+# Best-effort ship prompt (NOT a hard gate): on-request asks when a command crosses the
+# sandbox boundary — it does NOT fire before every command, does NOT read
+# .workflow/state.md, and is bypassable. See shared/rules/ship-gates.md. Check the gate
+# checklist yourself before approving a push/PR.
+
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+# This file is the CANONICAL source for Codex config; ./sync.sh copies it to .codex/config.toml.
+# Repo skills are generated under <repo>/.agents/skills (Codex discovers project skills there —
+# NOT under .codex/skills). Sync also writes <repo>/.claude/skills (Claude Code + OpenCode).
+# Discipline is loaded from AGENTS.md (a generated copy of CLAUDE.md) at the repo root.
+
+# To harden the ship-gate into an actual command block (still no bash script), add a
+# Codex execpolicy `.rules` file that requires approval specifically for
+# `git push` / `gh pr create`. Left out of this first cut to keep it minimal.

package/src/configs/opencode.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["PROJECT.md"],
+  "permission": {
+    "bash": {
+      "*": "allow",
+      "git push*": "ask",
+      "gh pr create*": "ask",
+      "gh pr merge*": "ask",
+      "git push --force*": "deny",
+      "git push -f*": "deny"
+    }
+  }
+}

package/src/docs/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+Notable changes to this project, newest first — one short entry (or small block) per
+shipped change. Written at ship time (the `finish-branch` skill records an entry before the
+ship commit). See `shared/rules/docs-layout.md`.
+
+## Unreleased
+
+- _Nothing shipped yet — the first change goes here._

package/src/docs/extending.md

@@ -0,0 +1,134 @@
+# Extending codeforge
+
+How to add capability while keeping the project simple and interoperable across
+**Claude Code, Codex, and OpenCode**.
+
+## The rule of thumb
+
+> A **skill** can express anything the agent *should do* (an instruction). A
+> **script/hook** is needed only when something must *happen regardless* — block an
+> action, run outside the agent's turn, or compute deterministically without relying on
+> the model to comply.
+
+Prefer the lowest tier that does the job. Higher tiers add power but cost simplicity and
+portability.
+
+---
+
+## Tier A — Skills only (advisory, fully portable)
+
+Anything that is a *procedure or criterion*. Add these freely — no config changes; after a
+`./sync.sh` all three engines pick them up automatically.
+
+Examples:
+
+- New workflow skills (any command/flow).
+- A research step before designing ("investigate and write the brief").
+- Cross-engine review ("have the other engine review this plan/diff").
+- Severity rubric, TDD sequence, approach comparison, PR-description format.
+- "Verify by exercising it."
+- A lightweight multi-engine council (a skill that orchestrates calling several engines
+  and synthesizing).
+- Checklists and keeping `.workflow/state.md` updated.
+
+**Cost:** the agent does it *because instructed*. Nothing prevents non-compliance.
+
+### How to add a skill
+
+1. `mkdir skills/<name>` — the directory name must be lowercase, hyphen-separated.
+2. Create `skills/<name>/SKILL.md` (uppercase filename) with frontmatter:
+   ```
+   ---
+   name: <name>          # must equal the directory name
+   description: <1–1024 chars; when to use it>
+   ---
+   ```
+   then the steps, referencing `shared/rules/*` and `.workflow/state.md`.
+3. Run `./sync.sh` (or `sync.ps1` on Windows). It regenerates `.claude/skills` (Claude Code +
+   OpenCode) and `.agents/skills` (Codex + OpenCode) from `skills/` — a full mirror (deletions
+   propagate), so every engine discovers the skill. No further config.
+
+**Framework vs project-own skills:** `skills/` holds both. The installer's `--upgrade`
+refreshes only the **framework's own** skills (by name) and never deletes the rest — so a
+skill you add here survives upgrades. (Same for `shared/rules/`.) Give your own skills
+names distinct from the framework's, or an upgrade will overwrite the collision.
+
+---
+
+## Tier B — Skills + agent-invoked scripts (deterministic, still advisory)
+
+No hooks. A skill tells the agent to run a helper script (e.g. `scripts/check-gates.sh`).
+You gain determinism and reuse; a single POSIX script serves all three engines. But it
+runs **only when the agent chooses to call it**.
+
+Good fits:
+
+- A `.workflow/state.md` validator (are the required boxes checked?).
+- A reproducible git/drift check.
+- An artifact checker that *reports* (not blocks) whether a brief/evidence file exists.
+
+**Cost:** deterministic, but still skippable — the agent may not invoke it.
+
+Convention: keep such scripts in `scripts/`, POSIX `sh`, no engine-specific assumptions,
+and have the relevant skill name the exact command to run.
+
+---
+
+## Tier C — Hooks (automatic, blocking, or out-of-turn) — NOT portable
+
+Needed only when something must be *guaranteed* — it cannot be expressed as an
+instruction. This is where interoperability breaks: each engine has a different mechanism,
+so it means maintaining up to three implementations.
+
+Capabilities that require this tier:
+
+- **Conditional blocking** of commit/push/PR based on `.workflow/state.md` (the native
+  `permission` gates only do "always ask", not "block *if* gates are unmet").
+- **Unbypassable evidence gate** / per-iteration clean evidence / a convergence breaker.
+- **A mandatory research gate** (cannot start design until the brief exists).
+- **Out-of-turn events:** per-turn phase reminder, dynamic session-start injection,
+  pre-compaction save, post-edit auto-format, auto-approve of local writes.
+
+Per-engine mechanism (all can block):
+
+| Engine | Mechanism | Block signal |
+| --- | --- | --- |
+| Claude Code | hooks in `.claude/settings.json` | `PreToolUse` exit code 2 |
+| Codex | `hooks.json` (`$CODEX_HOME` or `<repo>/.codex/hooks.json`) | `PreToolUse` exit code 2 |
+| OpenCode | plugin with `tool.execute.before` | throw to abort |
+
+**Trade:** three separate implementations to keep in sync, plus per-engine trust/merge
+concerns. Reach for it only when a real guarantee is worth that cost — and start with a single
+engine. **A reference adapter ships opt-in:** `install.sh --with-hooks` (Claude Code only)
+installs a `PreToolUse` hook (`shared/scripts/claude-gate-hook.sh`) that runs the same
+`check-gates.sh` and exits 2 to block a ship on incomplete gates. It stays off the default
+install (per-developer, gitignored `.claude/settings.local.json`) so the portable core is
+unchanged; Codex/OpenCode adapters are not built yet.
+
+---
+
+## verify-e2e roadmap (v2)
+
+Planned extensions to the `verify-e2e` skill — each is a skill/config change, no hooks
+needed:
+
+- **Playwright `.spec.ts` regression bridge:** graduate passing use cases into
+  deterministic, replayable spec files for CI, alongside the markdown use cases.
+- **UI interface adapter:** drive browser-based use cases (today's skill covers API/CLI).
+- **Automatic multi-surface coverage audit:** flag when a feature exposes UI/API/CLI
+  surfaces but use cases only cover a subset.
+
+---
+
+## Decision checklist
+
+Before adding something, ask in order:
+
+1. Is it a procedure the agent should follow? → **Tier A** (a skill).
+2. Does it need deterministic, repeatable computation, but only when asked? → **Tier B**
+   (a skill that invokes a `scripts/` helper).
+3. Must it be enforced/automatic even if the agent doesn't cooperate, or run outside a
+   turn? → **Tier C** (hooks, per engine) — accept the portability cost, or scope to one
+   engine.
+
+Default to the lowest tier that works. Most new functionality is Tier A.

package/src/shared/rules/approach-comparison.md

@@ -0,0 +1,29 @@
+# Approach Comparison
+
+Before committing to a design, compare 2–3 real alternatives on fixed axes. This forces
+the tradeoffs into the open instead of defaulting to the first idea.
+
+## Fixed axes
+
+Score each candidate approach (Low / Med / High, with a one-line why):
+
+| Axis | Question |
+| --- | --- |
+| **Complexity** | How many moving parts / how much new code? |
+| **Blast radius** | What breaks if it's wrong? How much does it touch? |
+| **Reversibility** | How hard is it to undo or change later? |
+| **Time to validate** | How fast can you prove it works (or fails)? |
+| **Correctness/User risk** | Likelihood of a wrong result or bad UX? |
+
+## How to use it
+
+1. List 2–3 genuinely different approaches (not variations of one).
+2. Fill the table; add a one-line rationale per cell.
+3. Name the **default winner** and why. Prefer the simplest option that meets the bar
+   (low complexity + low blast radius + high reversibility).
+4. **Validate the default with a second opinion** (the `review` or `council` skill) before
+   locking it in — do not self-certify the choice.
+5. If the cheapest falsifying test is quick (say, under ~30 min), **spike it first** and
+   let evidence decide.
+
+Record the table and the chosen approach in the plan / `.workflow/state.md`.

package/src/shared/rules/continuity.md

@@ -0,0 +1,32 @@
+# Continuity
+
+`CONTINUITY.md` (repo root) is the **session handoff anchor** — always present, so it's
+the reliable "read this first" on any new session or after a context reset.
+
+## Roles (non-overlapping — no drift)
+
+- **`CONTINUITY.md`** — cross-session state: current focus, the single Next step,
+  blockers, and a pointer to the active workflow. Small (a handful of lines).
+- **`.workflow/state.md`** — the active workflow's checklist/gates. Only exists while a
+  workflow runs.
+
+`CONTINUITY.md` **points to** `state.md`; it never duplicates it.
+
+## On session start
+
+Read `CONTINUITY.md` first and resume from **Next step** before doing anything else. If it
+names an active workflow, open that `.workflow/state.md` too and continue there.
+
+## Keeping it current
+
+- Update it as the situation changes — especially the Next step.
+- Before closing a session, or when context is getting tight, run the `checkpoint` skill to
+  write a clean handoff.
+- Keep it tiny: focus, next step, blockers, pointer, date + a few handoff lines. Details
+  live in the workflow/docs, not here.
+
+## Caveat
+
+Saving the handoff **automatically** right before an unexpected context compaction needs a
+hook (Tier C) and is not covered here. Keep `CONTINUITY.md` current manually so any reset
+point already reflects reality.

package/src/shared/rules/docs-layout.md

@@ -0,0 +1,23 @@
+# Docs Layout
+
+Where each artifact lives. The workflow skills write to these paths so knowledge is
+findable and portable across all three engines.
+
+| Path | Holds | Written by |
+| --- | --- | --- |
+| `docs/prds/<feature>.md` | Product requirements (problem, users, goals, criteria) | `prd` |
+| `docs/plans/<feature>.md` | Design plan (approach, files, tests, acceptance) | `plan`, `new-feature` |
+| `docs/research/<YYYY-MM-DD>-<topic>.md` | Sourced research brief | `research` |
+| `docs/solutions/<slug>.md` | Solved-bug knowledge base (symptom→cause→fix) | `fix-bug` |
+| `docs/adr/<NNN>-<slug>.md` | Architecture decision records | `adr` (from `plan` / `council`) |
+| `docs/e2e/reports/` | verify-e2e evidence reports (committed; the ship-gate binds to these) | `verify-e2e` |
+| `docs/e2e/use-cases/` | Graduated user-journey use cases (committed regression suite) | `verify-e2e` / `new-feature` / `fix-bug` |
+| `docs/CHANGELOG.md` | Human-readable history of notable changes | `finish-branch` / ship |
+| `docs/index.md` | High-level project map (structure, entry points, conventions) | `index` |
+
+## Rules
+
+- Create the file under the right folder; the folder already exists (`.gitkeep`).
+- One artifact per file; name it after the feature/topic so it's greppable.
+- These are the **portable memory** of the project — see `shared/rules/memory.md`.
+- Keep `docs/CHANGELOG.md` newest-first, one line or short block per shipped change.

package/src/shared/rules/memory.md

@@ -0,0 +1,34 @@
+# Memory & Learning
+
+Capture what's worth reusing so the next session (or the next engine) doesn't relearn it.
+
+## What to save
+
+When you solve a tricky bug, discover a project pattern/convention, or learn a durable
+preference or constraint — write it down. Ask yourself before finishing a task:
+**"Did I learn anything worth remembering?"** If yes, save it.
+
+## Where to save it (portable-first)
+
+Memory has two homes; the **repo** is the portable one that all three engines share:
+
+1. **Durable project knowledge → the repo** (source of truth, works everywhere):
+   - Solved bugs → `docs/solutions/<slug>.md` (symptom, root cause, fix, how verified).
+   - Architecture decisions → `docs/adr/<NNN>-<slug>.md`.
+   - Notable changes → `docs/CHANGELOG.md`.
+2. **Personal / cross-session recall → the engine's own memory, where it has one**
+   (Claude Code has a persistent memory; other engines vary — do NOT assume it exists).
+   Use it for preferences and session continuity, but never as the *only* copy of
+   something the team needs.
+
+**Save solutions twice:** a reusable fix goes to `docs/solutions/` (portable) AND the
+engine's personal memory if available.
+
+## Rules
+
+- Prefer the repo for anything another person or engine would need — it's the one place
+  all three read.
+- Keep entries concise and findable (clear title, one problem each).
+- Don't duplicate what the code or git history already records; save the non-obvious
+  *why*.
+- Never store secrets in memory or docs.

package/src/shared/rules/models.md

@@ -0,0 +1,59 @@
+# Models
+
+Default model + effort per engine for the cross-engine roles (research, review, council).
+Maintained by hand — edit this table to change defaults; the skills read from here so
+model IDs live in one place, not scattered across skills.
+
+**Principle:** the reviewer/advisor must run on a **different engine than the driver**
+(model diversity is the point). The driver's own model is whatever you opened the CLI
+with — not pinned by this project.
+
+## Per-engine defaults
+
+| Engine | Model | Effort | Invocation |
+| --- | --- | --- | --- |
+| **Codex** | `gpt-5.6-sol` | `xhigh` | `codex exec -m gpt-5.6-sol -c model_reasoning_effort="xhigh" --sandbox read-only "<prompt>" < /dev/null` |
+| **Claude** | `opus` | `high` | `claude -p --model opus --effort high "<prompt>"` |
+| **OpenCode** | `opencode-go/glm-5.2` | default | `opencode run -m opencode-go/glm-5.2 "<prompt>"` |
+
+Same model/effort per engine regardless of role — the role only decides **which
+engine(s)** to use:
+
+| Role | Engine(s) |
+| --- | --- |
+| **Driver** (implementation / TDD) | the CLI you open (not pinned) |
+| **Reviewer** (design + code review) | the non-driver engine |
+| **Research** (when delegated) | a non-driver, web/synthesis-capable engine |
+| **Council advisors** | all three (max diversity) |
+
+## Running these from an agent (non-interactive)
+
+When an **agent** (not a human at a terminal) runs these invocations through a shell tool,
+stdio is not attached to a TTY. Two consequences, both fixed with flags — no wrapper or shim
+needed (this stays skills + config):
+
+- **`codex exec` blocks on stdin.** Even with the prompt passed as an argument, it prints
+  `Reading additional input from stdin...` and waits forever. Always redirect **`< /dev/null`**
+  (shown in the table) so it reads no input and proceeds.
+- **A detached `codex exec` can drop its streamed stdout** ([openai/codex#19945](https://github.com/openai/codex/issues/19945)),
+  so the agent sees an empty result even though the run succeeded. Capture the final message to
+  a file with **`--output-last-message <file>`** and read that file instead of relying on
+  stdout. Give each parallel advisor its **own** file (e.g. `/tmp/council-<advisor>.txt`) so
+  concurrent `council` runs don't clobber each other.
+
+Claude (`claude -p`) and OpenCode (`opencode run`) return their output normally in
+non-interactive mode and need neither workaround.
+
+## Read-only for reviewers / advisors
+
+A reviewer (`review`) or council advisor must not modify the working tree it's judging.
+Invoke it read-only: Codex `--sandbox read-only`; for Claude/OpenCode restrict to
+read-only (no write/edit tools). Hand it the diff/plan as text and confirm the
+working-tree diff is unchanged afterward.
+
+## Cost note
+
+These are quality-first defaults (top models, high effort) because review/council
+decisions are where being wrong is expensive. If cost matters, downgrade here — e.g.
+Codex `gpt-5.4-mini`, OpenCode `opencode-go/deepseek-v4-flash`, or a lower `--effort` /
+`model_reasoning_effort` — and the skills follow automatically.

package/src/shared/rules/project-rules.md

@@ -0,0 +1,31 @@
+# Project Rules (layering)
+
+Two layers of rules apply to every session, both always-on:
+
+1. **Global baseline** — `CLAUDE.md` golden rules + `shared/rules/*`. The framework's
+   discipline. Applies **always, without exception**.
+2. **Project rules** — `PROJECT.md` at the repo root (from `PROJECT.template.md`):
+   **Persona · Project info · Variables · Special rules**. Project-specific and editable.
+
+## Load order
+
+Read `PROJECT.md` alongside the global rules at session start (golden rule). All three
+engines auto-load `CLAUDE.md`/`AGENTS.md`, which points here; OpenCode also force-loads
+`PROJECT.md` via `opencode.json` `instructions`.
+
+## Precedence (important)
+
+- The **global safety baseline** — branch safety, the ship-gate, and anything that
+  prevents data loss or an unreviewed ship — **should not** be overridden by `PROJECT.md`.
+  Note: this is **advisory** — nothing physically enforces it, so review your own
+  `PROJECT.md` against `ship-gates.md` and don't write project rules that weaken safety.
+- `PROJECT.md` **adds and refines**: persona/tone, project context, variables, and
+  special behavior.
+- On a genuine conflict, treat the global safety baseline as winning; surface the conflict
+  rather than silently following the weaker rule.
+
+## Adding project rules
+
+Copy `PROJECT.template.md` → `PROJECT.md`, fill the four sections, commit it. That's the
+whole mechanism — no per-engine config needed (the golden rule + `instructions` handle
+loading).

package/src/shared/rules/research.md

@@ -0,0 +1,30 @@
+# Research
+
+Model knowledge has a cutoff. Before designing anything that touches an external library,
+API, protocol, or a problem others have already solved, **check current sources first** —
+don't build on stale assumptions.
+
+## When research is needed
+
+- A new or unfamiliar library / framework / API / CLI is involved.
+- The behavior depends on a spec, protocol, or third-party service.
+- The problem is a well-trodden one worth learning from prior art before reinventing it.
+
+Skip it only for changes fully contained in code you already understand.
+
+## What a good brief contains
+
+Write the brief to `docs/research/<YYYY-MM-DD>-<topic>.md`:
+
+1. **Question(s)** — what you needed to find out.
+2. **Findings** — current, sourced facts (cite the doc/URL and the date checked).
+   Separate verified facts from inference.
+3. **Prior art** — how established tools/products solved this, and what to borrow or avoid.
+4. **Implications for the design** — what the findings change about the approach.
+5. **Open questions** — what remains unverified and how to close it.
+
+## Rules
+
+- Cite sources; never present recalled-from-memory API details as current fact.
+- Prefer official docs over blog posts; note the version/date.
+- The brief feeds the plan — the design must be consistent with it.

package/src/shared/rules/severity.md

@@ -0,0 +1,17 @@
+# Severity Rubric
+
+Tag every review finding with a severity. P0/P1/P2 must be fixed before shipping; P3 is
+optional.
+
+| Level | Meaning | Action |
+| --- | --- | --- |
+| **P0** | Broken — will crash, lose data, or create a security hole | Fix before proceeding |
+| **P1** | Wrong — incorrect behavior, logic error, missing required case | Fix before proceeding |
+| **P2** | Poor — code smell, maintainability, unclear intent, missing test | Fix before proceeding |
+| **P3** | Nit — style, naming, minor suggestion | May fix; does not block |
+
+**Plan-stage note:** at the plan stage, an omission that would cause the *wrong thing to
+be built* (missing required behavior or acceptance criterion) is a **P1**, not a P2.
+
+**Review loop:** run reviewers, collect findings, fix P0/P1/P2, repeat. Exit only when a
+single pass yields no P0/P1/P2 from all reviewers.