@jualopezmo/codeforge 0.4.0

package/src/skills/prd/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: prd
+description: Write a product requirements doc before designing — the spec for what to build and who it's for: the problem, users, goals/non-goals, requirements, and success criteria, then hand off to plan. Use at the start of a substantial feature to spec out what a system should do, under Claude Code, Codex, or OpenCode.
+---
+
+# prd
+
+Define *what* and *why* before *how*. A PRD keeps design and implementation anchored to a
+real user outcome. Feeds the `plan` skill.
+
+Use for substantial features; skip for small changes (go straight to `plan` or
+`quick-fix`).
+
+## 1. Clarify the problem
+
+Establish who has the problem and what outcome they need. Ask the user one question at a
+time only when genuinely ambiguous; otherwise state assumptions. Avoid jumping to a
+solution — this phase is about the need, not the design.
+
+## 2. Draft the PRD
+
+Write `docs/prds/<feature>.md` with:
+
+- **Problem** — what's broken/missing and why it matters.
+- **Users / personas** — who this is for; the situation they're in.
+- **Goals** and **Non-goals** — what success includes, and what it deliberately excludes.
+- **Requirements** — the capabilities the feature must provide (user-facing, not code).
+- **Success criteria** — how you'll know it worked, observably.
+- **Open questions** — what's still undecided.
+
+## 3. Review + confirm
+
+Sanity-check with the user (and optionally the `review` skill) that the PRD captures the
+real intent. Resolve contradictions and vague requirements now — a gap here misdirects
+everything downstream.
+
+## 4. Hand off
+
+The PRD feeds `plan` (design) → `new-feature` (build). Reference it from
+`.workflow/state.md`.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "The requirements are obvious — just start designing." | The PRD anchors design to a real user outcome; skipping it lets the build drift from what the user needs. |
+| "I'll write the endpoints and tables as the requirements." | Requirements are user-facing capabilities, not code. A PRD that reads like a design doc has skipped the what/why. |
+| "Non-goals are unnecessary." | Naming what's deliberately excluded is how scope stays bounded. Omit them and scope creeps. |
+| "Success criteria can wait." | Without observable success criteria you can't tell if it worked. Define them up front. |
+
+## Red flags
+
+- The PRD names components/endpoints/tables as the goal.
+- No users/personas, or no non-goals.
+- No observable success criteria.
+- It reads like a design doc rather than a statement of need.
+
+## Verification
+
+`docs/prds/<feature>.md` exists and states the problem, users, goals/non-goals,
+requirements, and success criteria in user terms (no endpoints, tables, or code as the
+goal). A PRD that reads like a design doc has skipped the "what/why" — rewrite it.

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

@@ -0,0 +1,60 @@
+---
+name: quick-fix
+description: Lightweight workflow for trivial changes (fewer than 3 files, no behavior risk) — branch, change, quick check, verify, ship. Use for typos, copy tweaks, small config edits under Claude Code, Codex, or OpenCode. Escalate to new-feature or fix-bug if scope grows.
+---
+
+# quick-fix
+
+For genuinely trivial changes only. If the change touches 3+ files, alters behavior, or
+turns out non-obvious, **stop and switch** to `new-feature` or `fix-bug`.
+
+## 0. Set up tracking
+
+- Confirm you are **not on `main`** — create a branch (`chore/<name>` or `fix/<name>`).
+- A full `.workflow/state.md` is optional here; still record the branch and a one-line
+  intent so the ship-gate has context. If you use state.md, set **Profile: light**.
+
+## 1. Make the change
+
+Apply the small edit. Keep it to the stated scope — no drive-by refactors.
+
+## 2. Quick check
+
+- If code with a runtime effect: add or run a relevant test.
+- If docs/config: sanity-check syntax and that nothing references the old value.
+
+## 3. Verify
+
+Exercise the changed path (or render the doc / load the config) and confirm the intended
+result. Trivial does not mean unverified.
+
+## 4. Ship
+
+Commit, then push / open PR. The native approval prompt on push/PR still applies — approve
+only if the change is truly complete and correct.
+
+> Scope guard: the moment this stops feeling trivial, abandon quick-fix and restart under
+> `new-feature` / `fix-bug` with the full discipline.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "It's one line, no need to test or run it." | A one-line change with a runtime effect still needs the changed path exercised. Trivial does not mean unverified. |
+| "It's grown to four files but I'm nearly done — I'll finish here." | 3+ files or a behavior change is the escalation trigger. Stop and restart under `fix-bug` / `new-feature`; don't finish under the light profile. |
+| "While I'm in here I'll tidy up the nearby code." | Drive-by refactors break the no-behavior-risk contract. Keep to the stated scope or escalate. |
+| "It's just a doc — nothing to check." | Confirm the doc renders and nothing still references the old value. |
+
+## Red flags
+
+- You're editing a third file, or changing behavior rather than copy/config.
+- You skipped exercising the change because it "obviously works."
+- You're reaching for a refactor "while you're here."
+- The change stopped feeling trivial two edits ago and you kept going.
+
+## Verification
+
+- [ ] Change stayed in scope (<3 files, no behavior change) — otherwise escalated to `fix-bug` / `new-feature`.
+- [ ] Changed path exercised (or doc rendered / config loaded); intended result observed.
+- [ ] Nothing still references the old value.
+- [ ] On a branch, not `main`; ship prompt approved only because the above hold.

package/src/skills/research/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: research
+description: Pre-design research — check current docs and prior art for the libraries/APIs/problems a change touches, then write a sourced brief that the plan builds on. Use before designing anything involving unfamiliar or external technology, under Claude Code, Codex, or OpenCode.
+---
+
+# research
+
+Don't design on stale, recalled-from-memory assumptions. Model knowledge has a cutoff;
+verify against current sources first. See `shared/rules/research.md` for the full standard.
+
+## When to run
+
+Before `plan` / `new-feature` design when the change touches a new or external library,
+API, protocol, third-party service, or a well-trodden problem worth learning from. Skip
+for changes fully contained in code you already understand.
+
+## 1. Scope the unknowns
+
+List exactly what you need to find out: which libraries/APIs/versions, which behaviors or
+constraints, and any "how do others do this" questions. A vague scope yields a useless
+brief.
+
+## 2. Consult current sources
+
+Use the engine's available tools (web search / fetch / docs lookup) to gather **current,
+versioned** facts. Prefer official docs over blog posts. Note the version and the date
+checked. Also look at how established tools/products solved the same problem. If you
+delegate the research to another engine, use the research model from
+`shared/rules/models.md`.
+
+## 3. Write the brief
+
+Create `docs/research/<YYYY-MM-DD>-<topic>.md` with: the questions, sourced findings
+(cite URL + date; separate verified from inferred), prior art, implications for the design,
+and open questions. Follow the shape in `shared/rules/research.md`.
+
+## 4. Hand off to design
+
+The brief feeds `plan` / `new-feature`. The resulting design must be consistent with it.
+If research surfaced a blocker or a changed assumption, say so before designing.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "I already know this library." | Model knowledge has a cutoff and APIs move. Verify the current, versioned docs before designing on memory. |
+| "The blog post is good enough." | Prefer official, versioned docs and note the date checked. A confident blog can be stale or wrong. |
+| "I'll cite the sources later." | Cite as you go, with dates, separating verified from inferred. An unsourced brief is just recalled assumptions. |
+| "No time to research — just build." | Designing on a wrong assumption costs more than the lookup. If it's genuinely known code, skip research *explicitly* — don't fake it. |
+
+## Red flags
+
+- The brief asserts version-specific behavior with no source or date.
+- Verified facts and your own inferences are mixed together.
+- You're about to design and haven't checked whether the assumption still holds.
+
+## Verification
+
+The brief exists at `docs/research/<date>-<topic>.md`, every non-obvious claim cites a
+source with a date, and inferences are labeled as such. A brief full of unsourced
+assertions is not research — redo it.

package/src/skills/review/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: review
+description: Get a cross-engine second opinion on a plan or a code diff — run the other engine as reviewer, collect severity-tagged findings (P0–P3), and report. Use during the design-review and code-review phases under Claude Code, Codex, or OpenCode.
+---
+
+# review
+
+A utility skill for the review phases of other workflows. The point is **model
+diversity**: the reviewer must be a *different* engine than the one driving.
+
+## 1. Identify the target
+
+- **Plan review** — a written plan/spec before implementation.
+- **Code review** — the current diff (uncommitted, or vs `main`).
+
+State which, and the exact scope (file paths, base ref).
+
+## 2. Pick the reviewer (must differ from the driver)
+
+- Driver Claude Code → reviewer Codex (`codex exec ...`) or OpenCode (`opencode run ...`).
+- Driver Codex → reviewer Claude (`claude -p ...`) or OpenCode.
+- Driver OpenCode → reviewer Claude or Codex.
+
+Use the reviewer model + effort from `shared/rules/models.md`. Give the reviewer the
+target + this instruction: report findings tagged by severity (`shared/rules/severity.md`)
+with location and a concrete fix.
+
+**Invoke the reviewer read-only.** It judges the diff/plan; it must not change it. Use
+read-only permissions (Codex `--sandbox read-only`; Claude/OpenCode: no write/edit tools)
+and hand it the plan/diff as text. Afterward, confirm the working-tree diff is unchanged.
+
+**Single-engine fallback.** If no second engine is available, do a delayed self-review (or
+use a human reviewer) and log a waiver in `.workflow/state.md` — see the fallback in
+`shared/rules/ship-gates.md`. Cross-engine is preferred; the waiver keeps the degradation
+explicit, not silent.
+
+## 3. Collect findings
+
+Gather the reviewer's output as P0/P1/P2/P3 items. If output is missing or unparseable,
+treat it as a failed review — re-run, do not fabricate a verdict.
+
+## 4. Act and record
+
+- Resolve all P0/P1/P2 (P3 optional). Re-run the reviewer until a pass is clean.
+- Record each iteration and its result in `.workflow/state.md` (which engine, findings).
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Same-engine review is fine." | The whole point is a *different* model's blind spots. A same-engine pass is an echo, not diversity — use the other engine or log a waiver. |
+| "The reviewer output was empty — I'll just say it passed." | Missing or unparseable output is a *failed* review; re-run it. Never fabricate a verdict. |
+| "P2s aren't worth fixing." | The loop exits only on no P0/P1/P2. P3s are optional; P2s block. |
+| "I'll let the reviewer edit the fix while it's at it." | The reviewer is read-only — it judges, it doesn't touch the diff. Confirm the working tree is unchanged afterward. |
+
+## Red flags
+
+- Reviewer engine == driver engine, with no waiver logged.
+- A "clean" verdict with no reviewer output behind it.
+- The loop has run many passes without converging — escalate, don't grind.
+- The working-tree diff changed during the review.
+
+## Verification
+
+The loop exits only when a single pass from the reviewer yields no P0/P1/P2. State that
+explicitly before returning to the calling workflow.

package/src/skills/simplify/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: simplify
+description: Post-implementation cleanup pass that reduces complexity without changing behavior — remove dead code, flatten nesting, de-duplicate, clarify names — with the test suite staying green throughout. Use after a change works (tests pass) and before shipping, under Claude Code, Codex, or OpenCode. Not for adding behavior or fixing bugs.
+---
+
+# simplify
+
+Make the code simpler without changing what it does. The refactor step is the first thing
+skipped under pressure, so this is its own pass: start from green, reduce complexity in small
+behavior-preserving steps, end greener. If it changes behavior, it isn't a simplify — it's a
+`fix-bug` or `new-feature`.
+
+## 1. Start from green
+
+The suite must pass **before** you touch anything. A simplify pass leans entirely on the tests
+to prove behavior didn't change — if they're red (or thin), stop: fix them (or the bug) first.
+
+## 2. Find the complexity
+
+Look for: dead code, deep nesting (early-return / guard-clause opportunities), duplication
+(rule of three), unclear names, and over-abstraction that costs more than it saves.
+**Chesterton's Fence:** understand *why* a piece of code exists before removing it — the reason
+may not be covered by a test.
+
+## 3. Change in small, behavior-preserving steps
+
+One simplification at a time; **re-run the tests after each**. Never fold a behavior change into
+a simplify pass — the moment you do, a green suite no longer proves you kept behavior. A
+big-bang refactor hides which step broke something.
+
+## 4. Verify behavior is identical
+
+Full suite green, and actually exercise the changed path (`shared/rules/tdd.md` refactor
+discipline). The diff should read as *same behavior, less code*: less duplication, shallower
+nesting, clearer names, no dead code.
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "While I'm here I'll also fix this small bug / add this tweak." | A simplify pass is behavior-preserving. Mixing in a change means the green suite no longer proves you broke nothing — do it as a separate `fix-bug` / `new-feature`. |
+| "This code looks pointless — I'll just delete it." | Chesterton's Fence: understand why it's there first. Tests may not cover the reason. Delete only once you know it's truly dead. |
+| "I'll do all the simplifications in one commit." | One behavior-preserving step at a time, re-running tests between. A big-bang refactor hides which step regressed. |
+| "Tests pass, so the refactor is done." | Also exercise the path — a passing suite proves the tests pass, not that behavior held where tests are thin. |
+
+## Red flags
+
+- You started from a red or thin suite.
+- The diff mixes a behavior change into the cleanup.
+- You deleted code without understanding why it existed.
+- Many simplifications landed in one step with no test run between.
+
+## Verification
+
+Started from green; the suite is green after every step and at the end. The diff is
+behavior-preserving (same inputs → same outputs) and complexity is measurably lower (less
+duplication, shallower nesting, clearer names, dead code gone). The changed path was exercised,
+not just the tests. If behavior changed at all, this was the wrong skill — revert and use
+`fix-bug` / `new-feature`.

package/src/skills/verify-e2e/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: verify-e2e
+description: Execute user-journey use cases (API and CLI in v1) against the running app, classify each, and write a committed evidence report the ship-gate binds to. Use to verify a user-facing change end to end before shipping, under Claude Code, Codex, or OpenCode.
+---
+
+# verify-e2e
+
+Run **user journeys** — not unit tests — against real interfaces, then bind the result to
+the ship-gate with an evidence report. API and CLI are executed in v1; UI is deferred
+(record `E2E verified — N/A: UI journey, no v1 adapter`). The driver runs this; it is not a
+cross-engine review.
+
+## 0. Locate use cases
+
+From the active plan (`new-feature` / `fix-bug`) or, in regression mode, from
+`docs/e2e/use-cases/*.md`.
+
+## 1. Validate journey shape (before executing)
+
+Each use case MUST carry: **ID, Actor, Scenario, Interface (API|CLI), Intent, Setup, Steps
+(≥2), Verification, Persistence**. Reject a malformed UC with a reason code and stop —
+rewrite it, don't execute it:
+
+- `MISSING_ACTOR` · `MISSING_SCENARIO` · `SCENARIO_FLUFF` · `CHEAT_SETUP` (Setup performs the
+  action under test) · `THIN_VERIFICATION` (bare status/exit code) · `MISSING_PERSISTENCE` ·
+  `TOO_SHALLOW` (<2 meaningful steps) · `NOT_USER_JOURNEY` (reads as a unit/contract test) ·
+  `WRONG_INTERFACE`.
+
+## 2. ARRANGE — sanctioned setup only
+
+Public API, signup/login, app CLI, or documented seed commands. **Forbidden:** raw DB writes
+(`psql -c "INSERT"`, `mysql -e`, `mongosh --eval`), internal/undocumented endpoints,
+file-injection on disk. A broken sanctioned path is a **finding, not a fix-it-here**: report
+it (verify runs read-only) and loop the repair back through `fix-bug` / `new-feature` so the
+app change gets its own tests and review — **never route around it** and never patch app code
+inline during the verify phase. Credentials come from **env vars**, never hard-coded
+(graduated use cases are committed).
+
+## 3. Safety
+
+- Default to a **non-production** target; require explicit confirmation otherwise.
+- **Redact** secrets/tokens/PII from captured output before writing the report.
+- Quote/escape UC-provided values; never `eval` raw UC text.
+- Clean up resources you created, or note residual state in the report.
+
+## 4. ACT + VERIFY per interface
+
+- **API** — `curl`/`httpie`: assert status, body, headers, AND a follow-up request (e.g. GET
+  the resource a POST created via its `Location`).
+- **CLI** — subprocess: assert stdout/stderr + exit code, AND a second invocation that
+  observes the persisted state (e.g. `add` then `list`).
+
+No cheating in VERIFY: assert only through the interface under test.
+
+## 5. Classify + verdict
+
+| Result | Blocks ship? | Retry |
+| --- | --- | --- |
+| `PASS` | no | — |
+| `FAIL_BUG` | yes | no |
+| `FAIL_STALE` (UC references a renamed interface) | yes, until UC updated | no |
+| `FAIL_INFRA` (server down/timeout) | yes if still failing after 1 retry | once |
+| `FAIL_INVALID_UC` | yes | no |
+
+**Top-level `VERDICT: PASS` only if every required UC is `PASS`.** Anything else →
+`VERDICT: FAIL`.
+
+## 6. Write the evidence report
+
+`docs/e2e/reports/<YYYY-MM-DD>-<feature>.md` (committed). Include a header line
+(feature, branch, ISO-8601 timestamp), the top-level `VERDICT: PASS|FAIL`, and one block per
+UC (ID, classification, interface, trimmed+redacted output, persistence re-check).
+
+## 7. Graduate passing use cases
+
+Upsert each `PASS` UC by its **ID** into `docs/e2e/use-cases/<feature>.md` so later sessions
+re-run it. Then check the `E2E verified` ship-gate box (or record `— N/A: <reason>`).
+
+## Common rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Tests pass, that's enough." | Unit tests miss wiring/integration/UX. A journey exercises the real interface. |
+| "I'll assert the status code and move on." | A bare 200/exit-0 is `THIN_VERIFICATION`. Observe a real outcome + a next observable step. |
+| "I'll seed the row straight into the DB." | Raw DB writes are forbidden ARRANGE. Use the sanctioned interface; if it's broken, report it as a finding and loop through `fix-bug`. |
+| "Just check the box — the report can wait." | `check-gates` binds the box to a fresh `VERDICT: PASS` report; an empty claim fails the gate. |
+| "It's a read endpoint, skip Persistence." | Only genuinely stateless reads may use `Persistence: N/A`. |
+
+## Red flags
+
+- A use case with no Actor/Scenario, or an Intent naming endpoints/tables/components.
+- Setup that performs the very action the UC is meant to test.
+- Checking the `E2E verified` box without a committed `VERDICT: PASS` report on this branch.
+- Verifying through a back channel (DB/logs) instead of the interface under test.
+
+## Verification
+
+- [ ] Every use case validated for shape before execution.
+- [ ] API/CLI journeys executed; VERIFY only through the interface under test.
+- [ ] Report written to `docs/e2e/reports/` with a top-level verdict; secrets redacted.
+- [ ] Passing UCs graduated to `docs/e2e/use-cases/<feature>.md` by ID.
+- [ ] `E2E verified` gate box checked only with a fresh `VERDICT: PASS` report (or `N/A:`).

package/src/sync.ps1

@@ -0,0 +1,69 @@
+#!/usr/bin/env pwsh
+#
+# codeforge sync (Windows / PowerShell) — generate each engine's config + skills from the
+# neutral source. No symlinks.
+#
+#   pwsh ./sync.ps1 [-Out <dir>]
+#
+# Inputs are read from this script's own project (the neutral source); outputs are written
+# to -Out (default: in place). The installer uses -Out to generate straight into a target
+# project without copying the source or this script there (thin install).
+#
+# Neutral source layout (read from the script's dir):
+#   CLAUDE.md                     -> instructions (also copied to AGENTS.md)
+#   skills\<name>\SKILL.md        -> skills, copied into each engine's discovery dir
+#   configs\claude\settings.json  -> .claude\settings.json
+#   configs\codex\config.toml     -> .codex\config.toml
+#   configs\opencode.json         -> opencode.json (OpenCode reads it from the root)
+#
+# Skill discovery differs per engine: Claude Code -> .claude\skills; Codex -> .agents\skills;
+# OpenCode -> any of .opencode/.claude/.agents. So .claude\skills + .agents\skills covers all.
+#
+# GENERATED (do NOT hand-edit): AGENTS.md, opencode.json, .claude, .agents, .codex (in the
+# output dir). Edit the neutral source above, then re-run this script.
+#
+param(
+  [string]$Out
+)
+$ErrorActionPreference = 'Stop'
+$SrcRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$OutRoot = if ($Out) { $Out } else { $SrcRoot }
+
+# validate required inputs BEFORE mutating anything
+if (-not (Test-Path (Join-Path $SrcRoot 'skills'))) {
+  Write-Host "error: no skills\ base found in $SrcRoot"; exit 2
+}
+$claude = Join-Path $SrcRoot 'CLAUDE.md'
+if (-not (Test-Path $claude)) {
+  Write-Host "error: no CLAUDE.md found in $SrcRoot"; exit 2
+}
+
+New-Item -ItemType Directory -Force -Path $OutRoot | Out-Null
+$OutRoot = (Resolve-Path $OutRoot).Path
+
+# instructions: CLAUDE.md -> AGENTS.md
+Copy-Item $claude (Join-Path $OutRoot 'AGENTS.md') -Force
+
+# skills -> each engine's discovery dir (full mirror: replace so deletions propagate).
+# .claude\skills = Claude Code (+ OpenCode); .agents\skills = Codex (+ OpenCode).
+foreach ($dir in '.claude', '.agents') {
+  $dirPath = Join-Path $OutRoot $dir
+  New-Item -ItemType Directory -Force -Path $dirPath | Out-Null
+  $skillsPath = Join-Path $dirPath 'skills'
+  if (Test-Path $skillsPath) { Remove-Item -Recurse -Force $skillsPath }
+  Copy-Item -Recurse (Join-Path $SrcRoot 'skills') $skillsPath
+  # ownership marker: lets the installer tell a forge-generated dir from the user's own,
+  # so it never wipes a user's skills (even one coincidentally named new-feature).
+  Set-Content -Path (Join-Path $skillsPath '.forge-generated') -Value 'generated by codeforge sync — do not edit; edit the codeforge source instead'
+}
+
+# per-engine config, placed where each engine looks for it
+New-Item -ItemType Directory -Force -Path (Join-Path $OutRoot '.claude'), (Join-Path $OutRoot '.codex') | Out-Null
+$cClaude = Join-Path $SrcRoot 'configs\claude\settings.json'
+if (Test-Path $cClaude) { Copy-Item $cClaude (Join-Path $OutRoot '.claude\settings.json') -Force }
+$cCodex = Join-Path $SrcRoot 'configs\codex\config.toml'
+if (Test-Path $cCodex) { Copy-Item $cCodex (Join-Path $OutRoot '.codex\config.toml') -Force }
+$cOpen = Join-Path $SrcRoot 'configs\opencode.json'
+if (Test-Path $cOpen) { Copy-Item $cOpen (Join-Path $OutRoot 'opencode.json') -Force }
+
+Write-Host "codeforge sync: generated AGENTS.md, opencode.json, .claude/ (settings + skills), .agents/skills, and .codex/config.toml into $OutRoot"

package/src/sync.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# codeforge sync — generate each engine's config + skills from the neutral source.
+#
+#   ./sync.sh [--out <dir>]
+#
+# No symlinks (Windows-safe; use sync.ps1 on Windows). Inputs are read from this script's
+# own project (the neutral source); outputs are written to --out (default: in place).
+#
+#   --out <dir>   write the generated engine artifacts into <dir> instead of alongside the
+#                 source. The installer uses this to generate straight into a target project
+#                 without copying the source or this script there (thin install).
+#
+# Neutral source layout (read from the script's dir):
+#   CLAUDE.md                     → instructions (also copied to AGENTS.md)
+#   skills/<name>/SKILL.md        → skills, copied into each engine's discovery dir
+#   configs/claude/settings.json  → .claude/settings.json
+#   configs/codex/config.toml     → .codex/config.toml
+#   configs/opencode.json         → opencode.json (OpenCode reads it from the root)
+#   shared/rules/*.md             → discipline (read in place by the agent; not copied here)
+#
+# Skill discovery paths differ per engine (verified against each CLI's docs):
+#   Claude Code → .claude/skills   |   Codex → .agents/skills   |   OpenCode → any of
+#   .opencode/.claude/.agents. So .claude/skills + .agents/skills covers all three.
+#
+# GENERATED (do NOT hand-edit — regenerated on every run): AGENTS.md, opencode.json,
+# .claude/, .agents/, .codex/ (in the output dir). Edit the neutral source, then re-run.
+#
+set -euo pipefail
+SRC_ROOT="$(cd "$(dirname "$0")" && pwd)"
+OUT_ROOT="$SRC_ROOT"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --out)   shift; OUT_ROOT="${1:-}"; [ -n "$OUT_ROOT" ] || { echo "error: --out requires a directory" >&2; exit 2; } ;;
+    --out=*) OUT_ROOT="${1#--out=}" ;;
+    *)       echo "usage: $0 [--out <dir>]  (unknown arg: $1)" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+# validate required inputs BEFORE mutating anything
+[ -d "$SRC_ROOT/skills" ]    || { echo "error: no skills/ base found in $SRC_ROOT" >&2; exit 2; }
+[ -f "$SRC_ROOT/CLAUDE.md" ] || { echo "error: no CLAUDE.md found in $SRC_ROOT" >&2; exit 2; }
+
+mkdir -p "$OUT_ROOT"
+OUT_ROOT="$(cd "$OUT_ROOT" && pwd)"
+
+# instructions: CLAUDE.md -> AGENTS.md (Codex + OpenCode read AGENTS.md)
+cp "$SRC_ROOT/CLAUDE.md" "$OUT_ROOT/AGENTS.md"
+
+# skills -> each engine's discovery dir (full mirror: replace so deletions propagate).
+# .claude/skills = Claude Code (+ OpenCode); .agents/skills = Codex (+ OpenCode).
+for dir in .claude .agents; do
+  mkdir -p "$OUT_ROOT/$dir"
+  rm -rf "$OUT_ROOT/$dir/skills"
+  cp -R "$SRC_ROOT/skills" "$OUT_ROOT/$dir/skills"
+  # ownership marker: lets the installer tell a forge-generated dir from the user's own,
+  # so it never wipes a user's skills (even one coincidentally named new-feature).
+  printf 'generated by codeforge sync — do not edit; edit the codeforge source instead\n' > "$OUT_ROOT/$dir/skills/.forge-generated"
+done
+
+# per-engine config, placed where each engine looks for it
+mkdir -p "$OUT_ROOT/.claude" "$OUT_ROOT/.codex"
+[ -f "$SRC_ROOT/configs/claude/settings.json" ] && cp "$SRC_ROOT/configs/claude/settings.json" "$OUT_ROOT/.claude/settings.json"
+[ -f "$SRC_ROOT/configs/codex/config.toml" ]    && cp "$SRC_ROOT/configs/codex/config.toml"    "$OUT_ROOT/.codex/config.toml"
+[ -f "$SRC_ROOT/configs/opencode.json" ]        && cp "$SRC_ROOT/configs/opencode.json"        "$OUT_ROOT/opencode.json"
+
+echo "codeforge sync: generated AGENTS.md, opencode.json, .claude/ (settings + skills), .agents/skills, and .codex/config.toml into $OUT_ROOT"