forge-plugin
A Claude Code plugin that helps cooperative Claude and Codex agents follow a
reviewable workflow, avoid common mistakes, and understand why a step refused.
Generating code has become cheap. Verifying it, understanding it, and being able
to say honestly what was checked has not. forge-plugin is built around that
asymmetry: agent output is treated as a claim, and nearly everything durable in
the system exists to test claims rather than to produce more of them.
It merges two systems — forge (gate chains, an adversarial review
constitution, worktree discipline, a kill-switch, eval regressions) and
codex-orchestrator (append-only execution logging and headless-agent tools) —
into one arrangement for the Claude + Codex pair. The Claude main session
orchestrates and verifies; fresh agents implement and review on routes resolved for each execution. The
shipped defaults use Codex for implementation and first-pass review and Claude for
the binding verdict. Support for other harnesses is deliberately out of scope.
Forge assumes that agents cooperate with the documented workflow. Its hooks,
checks, and refusal messages make the intended sequence easier to follow and
mistakes easier to diagnose; they are not a tamper-proof boundary against a process
with the operator's OS authority.
How it works
Separate the author from the judge, and record the route. Implementers and
reviewers use distinct fresh sessions, and the binding reviewer remains distinct
from the author. A run freezes each role's resolved Claude-or-Codex route, and Forge
records the actual provider, model, and effort. Codex reviewers are OS-sandboxed
read-only; Claude reviewers are instruction-bounded and execution-capable. Cross-model
separation can reduce correlated mistakes when the routes differ, but it is recorded
evidence rather than guaranteed by construction; a same-model binding review is
surfaced as a historical-routing finding by tests/test_repo_conformance.py::check_run
(routing-design decision 12).
Trust nothing that was merely reported. Agent handoffs are claims, not
evidence. Within a Forge workflow, the orchestrator re-runs each required gate in
its own environment before authorizing a commit. A run's history records what was
actually observed — command output, exit codes, SHAs read from git rather than
remembered.
Fail closed. Gates are unconfigured until /forge:init fills them, and an
unconfigured gate refuses rather than passes. For recognized direct Git commands,
a Claude Code PreToolUse guard helps a cooperative agent avoid committing without
the expected review-backed authorization. It is a mistake-prevention backstop, not
a security boundary.
Exercise the mechanical controls. Load-bearing mechanical controls ship with
tests designed to fail when the control is disabled. A test that still passes with
its control removed is treated as a defect, not as coverage. Prompt-text checks are
described separately because instruction presence is not model compliance.
Requirements
- Claude Code ≥ 2.x
- Python ≥ 3.10 is the intended runtime target (standard library only — no
packages, no build step)
- OpenAI Codex CLI on
PATH (codex --version), authenticated
- bash on Linux or macOS (BSD userland) is the intended shell target.
Reintegration locking needs no
flock binary: the worktree-merge skill holds
the portable Git-common-dir arbiter
through the Forge CLI (common-lock hold), which takes its optional kernel
layer through Python's fcntl. Only the commit-lock helper pair
(acquire-commit-lock.sh and release-commit-lock.sh, which also guard the
decision-event lock) needs flock or lockf.
Repository CI currently proves Ubuntu with Python 3.13. macOS and the broader
Python 3.10+ matrix are intended but currently unproven; portability fixes are
tracked separately.
Install
The repository is its own plugin marketplace. From any Claude Code session:
/plugin marketplace add nixlim/forge-plugin
/plugin install forge@forge
/reload-plugins
(For a local checkout, pass the absolute path to the repo instead of the GitHub
slug.) Restart the session afterwards so the skills and hooks load. You should see
seven skills:
| Skill | Purpose |
|---|
/forge:init | Install or refresh the per-repo layer (region file, AGENTS.md splice, .codex/, evals) |
/forge:workflow | Run a full orchestration lifecycle (plan → tasks → close → report) |
/forge:orchestrate | One focused Codex-agent execution, review, or verification cycle |
/forge:report | Author the final report from the run log and chain evidence |
/forge:commit | The five-step fail-closed commit gate chain |
/forge:worktree-merge | The four-gate merge chain with locked-rebase reintegration |
/forge:drift | Mechanical drift sensing, then an operator-invoked periodic semantic review |
Installing also registers a PreToolUse mistake-prevention guard for recognized
direct Git invocations, an advisory PostToolUse invariant guard, a Stop
union that independently runs telemetry aggregation and the drift-staleness
nudge, and a SessionStart nudge. Every Stop and SessionStart member is silent
and inert outside a forge-initialized repository.
Per-repository setup
In the repository you want to govern:
/forge:init
Init confirms the project name and default branch; installs forge-project.md
(with its configuration regions rendered into both CLAUDE.md and AGENTS.md), the
.codex/ layer (agent routing plus an execpolicy deny-list), the gitignore block,
and .forge/ state directories; mines your CI configuration and git history to
propose gate commands; seeds and baselines the eval suite; then presents the whole
install diff for your explicit approval. It never commits on its own.
Until the regions are filled, gates fail closed — a merge stops with
forge: gate1-test-command not configured — run /forge:init.
If the repository already carries an older non-plugin forge installation, init
detects it and migrates: regions are salvaged byte-identically from their original
locations, eval fixtures are imported with their committed baselines rather than
re-recorded (re-minting would launder an existing reviewer regression into a
fresh "correct" result), and everything left behind is enumerated in a committed
migration report.
What gets verified
Each layer answers a different question, and each is configured per repository
rather than assumed.
| Layer | Question it answers |
|---|
| Gate 1 / Gate 2 | Do the project's own tests, linters and type checks pass? |
| Invariants | Do the repository's declared structural rules still hold? Every declared invariant must be an executable command; one that cannot be scripted is moved to a review bullet explicitly. |
| Assertion sensor | Does this test actually assert anything? Blocks confidently assertion-free Python tests; advisory where it cannot resolve the delegation. |
| Scoped mutation | Do the tests detect a deliberately broken implementation? Runs on changed files after Gate 1, advisory, with a documented path to becoming blocking once its cost and baseline are known. |
| Adversarial review | Does the change do what was intended, and what did the last reviewer miss? Eight baseline lenses plus a per-artefact profile; binary PASS/BLOCK, no hedging. |
| Risk tiers | How much scrutiny does this diff deserve? Derived from the diff at gate time against committed policy, promote-only, with a non-narrowable floor for control-class paths. |
| Drift sensing | Has anything decayed since the last change? Evals, gates on a clean tree, invariants, full mutation, category coverage, region staleness, telemetry. |
Both the commit chain and the merge chain end in a binding review, and the merge
chain's final gate is mandatory even when every constituent commit took the fast
tier.
Operator controls
- Kill-switch — create
AGENT_HALT (or scoped AGENT_HALT_commit) at the
main checkout root. The Claude Code PreToolUse guard parses recognized direct
git invocations and selected environment-prefix forms while the sentinel is
present. It inspects but never executes the submitted command; bash -c
wrappers, command git, and Git alias configurations are outside its coverage
by design. The guard assumes cooperative agents and prevents mistakes rather
than providing tamper-proof enforcement. Agents are instructed never to create
or clear sentinels.
- Control-class changes — within the Forge workflow, gates, the constitution,
agent routing, hooks, evals and
forge-project.md route to the binding reviewer
and wait for your explicit approval.
- Audit — guard denials and halt detections append to
.forge/tmp/halt-audit.log; full orchestration history lives in the run journal
under .codex-orchestrator/runs/<run-id>/.
- Dead merge-lock owner — a reintegration holder killed outright leaves its
arbiter owner record (
agent-rebase.lockdir and agent-rebase.lock.intent
in the Git common directory) and later entrants refuse until it is cleared.
Forge instructions reserve clearing it for you after proving the recorded host
and PID dead.
The run record
The append-only run journal records executions and decisions. The final report
draws on that record and the chain evidence. Existing committed run archives
remain readable history; Forge does not generate or require new ones.
Evals
Golden control regressions live in .forge/evals/tasks/. Gate-output and
verdict-derived fixtures take the exact prompt as their Input and cite chain ID,
candidate and evidence references as provenance; the committed .result is the
accepted verdict baseline. Routing,
reviewer, constitution or other control-class changes require a strict run:
STRICT=1 scripts/forge/run-evals.sh
An empty suite exits non-zero. A gate that no fixture exercises is not satisfied
by having no fixtures.
Scheduled mechanical drift sensing
Point scheduled CI at the mechanical checker, with CLAUDE_PLUGIN_ROOT set to
the installed plugin root. It runs only the mechanical checker and does not invoke an
LLM. Scheduled CI never launches semantic review or any model; the semantic half
is operator-invoked:
on:
schedule:
- cron: "17 4 * * 1"
jobs:
forge-drift-mechanical:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
path: project
- uses: actions/checkout@v4
with:
repository: nixlim/forge-plugin
path: forge-plugin
- name: Run Forge mechanical drift checks
working-directory: project
env:
CLAUDE_PLUGIN_ROOT: ${{ github.workspace }}/forge-plugin
run: '"${CLAUDE_PLUGIN_ROOT}/scripts/forge/drift-check.sh"'
When the Stop or SessionStart nudge reports a stale drift report, invoke
/forge:drift interactively for the semantic half. A CRITICAL drift finding
writes a block that refuses new runs until you clear it.
Concurrency
Several agents can work in one repository. Per-commit authorization is
content-addressed by the staged diff, so two chains can hold authorization at once
and, for commands the guard evaluates, one candidate's marker cannot admit
another. Journals record an owner and refuse an append from a live foreign owner.
Runs are admitted by declared file scope rather than refused outright, and
overlapping scopes are named on refusal. Reintegrations serialize through one
arbiter in the Git common directory, so worktrees using that common directory
contend on the same lock.
Decision-event emission is designed for lossless concurrent appends on local POSIX
filesystems. Current CI evidence covers Ubuntu; macOS is an intended but unproven
target. NFS and SMB are unsupported, and Windows is out of scope.
Development
python3 -m unittest discover -s tests
The plain command above is the sequential developer form. The committed gate-1
cell in forge-project.md discovers the same modules and runs them as a work queue
inside one cell: each module is its own unittest process, pulled longest-first by
max(1, min(8, os.cpu_count() or 1)) workers, after taking the host gate slot
(/dev/shm/agents-sem/gate/slot-0.lock) and waiting out CPU pressure for at most
300 seconds; both guards are no-ops where those paths do not exist. Measured on the
shared twelve-core host at load 3 to 5: 102 modules, 2,031 tests, 335 to 350 seconds
wall; it is not a promised speedup. A candidate whose every classified path is
docs-class records a gate-1 skip instead of running the cell; the docs-contract stack validation
still runs the prose-contract modules for it.
The Python entry point scripts/forge/cli.py is a compatibility shim over the
implementation modules under scripts/forge/forge_cli/.
The suite is stdlib only; the work-queue discovery finds 2,031 tests. Its
prose-contract tests are instruction-presence and textual-consistency checks: they
verify that required instructions exist, not that a model follows them. The release
end-to-end test checks plumbing with scripted verdicts, including a literal PASS;
it does not run a live reviewer. UPSTREAM records both vendored upstream SHAs and
every deliberate deviation.
Upstreams (assessed cherry-pick, no automatic sync):
Licence
MIT. See LICENSE.
