/how-it-works · plan, code, review, gates, ledger

From a brief to a closed block.

The skill runs these steps for you. Each step is also a plain command that you can run and inspect. Brief mode, for one small task or a short list, skips the facts, the plan and the plan approval.

01 PIPELINE SPINE · FIVE STEPS

The five steps

STEP 01 · L0 · READ-ONLY CHECK

1. Facts.

A small model checks each claim in your brief against the repository, with a read-only command and its output. No design starts before the facts.

FACTS CHECK BEFORE DESIGN

L0 | brief claims checked against repository

mode: read-only command + output | written to plans/

Gate rule: no design starts before the facts.

STEP 02 · L3 · OWNED FILES & CLAUSES

2. Plan and harden.

A strong model splits the work into blocks with owned files and testable clauses, then asks the hard questions. You answer them. plan check must pass, and you approve the plan.

PLAN & HARDEN PLAN CHECK

L3 | blocks with owned files + testable clauses

hard questions answered → plan check passes → you approve the plan

STEP 03 · ONE CODER PER BLOCK

3. Code.

One coder for each block, at the level that the job needs. It climbs one level only on evidence: failed attempts, two review rounds at one level, a stalled review, or a review round with several warnings. A security change starts one level higher.

EVIDENCE-ONLY ESCALATION +1 LEVEL

1. failed attempts · 2. two review rounds at one level

3. a stalled review · 4. a review round with several warnings

Climbs one level only on evidence.

STEP 04 · CLOSED-BOOK REVIEW

4. Review each file.

A fresh, closed-book reviewer checks each finished file. It has an empty folder, a packet of the change, and no tools. Round 1 reviews the whole file. Later rounds check only the fix, and a file stops at four rounds by default. A stuck file gets one small patch, then a human.

REVIEW ISOLATION & BOUNDS MAX 4 REVIEW ROUNDS

reviewer: empty folder · packet of the change · no tools

round 1 full → rounds 2..4 check only the fix → one small patch (≤80 lines) → human

STEP 05 · GATE & SIGNED LEDGER ROW

5. Proof and close.

The gate runs the tests and other checks again. Each changed file needs a signed approval for its current content, or every open finding on it waived or answered. High-risk tests must fail first and then pass. Then one commit. The ledger holds the block’s rows, and code-forge report adds up its cost and time.

GATE CLOSURE SEQUENCE SIGNED

tests & checks run again · signed approval, waiver or answer for each changed file

high-risk tests: fail first → then pass

one commit + signed close row · report adds cost & time

Levels, not model names

Your config maps each level to a model. A model changes, and your workflow does not. code-forge resolve L2 shows what a level maps to on your machine.

L0 Rung 01

Facts, triage, trivial edits

L1 Rung 02

A plain feature that follows an existing pattern

L2 Rung 03

Money, dates, tenancy, migrations, concurrency, and all file reviews

L3 Rung 04

Plan, harden, judge, System 2, and one patch of at most 80 lines, once per file, when a file is stuck

Level reference table
Level	Typical work
L0	Facts, triage, trivial edits
L1	A plain feature that follows an existing pattern
L2	Money, dates, tenancy, migrations, concurrency, and all file reviews
L3	Plan, harden, judge, System 2, and one patch of at most 80 lines, once per file, when a file is stuck


                $
                code-forge resolve L2

Where the record lives

State is on disk, not in the chat. A new session can take over from the run record.

On-disk files and directories
Place	What it holds
`.code-forge.yml`	Levels, review mode, gates, and key references (not keys)
`plans/`	Brief, facts, plan, and block records
`~/.code-forge/ledger/<slug>.jsonl`	The ledger: one row per event, append-only
`~/.code-forge/runs/<run>.json`	The run record: active blocks, base sha, owned files, the pinned worker

Honest limits

LIMIT 01 · TAMPERING VS SANDBOX PROCESS BOUNDARY

Signed rows make tampering visible. They are not a sandbox. A process that runs as your own user can still forge them. For a hard boundary, run coders as a second user or in a container.
LIMIT 02 · CLOSED-BOOK REVIEW NO SHELL IN REVIEW

Codex does not review by default. Reviews run closed book with no tools, and Codex always has a shell, so code-forge refuses it unless you set review.allow_open_book_codex: true. Codex still codes.
LIMIT 03 · TEST PROOF MODEL DELIBERATE CHOICE

There is no mutation testing. Proof is exact tests plus fail-then-pass. This is a deliberate choice.

INSTALL & INITIALIZE