Build it out

Build It Out V2

Run the standing three-role board with mechanical evidence between roles:

Claude coordinator -> exact Codex worker -> deterministic gate -> fresh Claude reviewer
         ^                                                           |
         +------------------ concrete BAD blockers ------------------+

The coordinator owns the bounded loop but has no Edit or Write tool. Workers implement one sealed unit at a time. The semantic reviewer is a new one-shot Claude process in safe mode with only Read, Glob, and Grep; it receives canonical task/contract/gate/Git evidence rather than worker narratives.

Install once

bash ./scripts/install

From a cloned repository, use the top-level install.sh wrapper. The installer safely links this directory into both ~/.claude/skills and ~/.codex/skills, the launcher into a user command directory, and the restricted coordinator agent into ~/.claude/agents. It refuses to overwrite files or directories. Pass --replace-links only to migrate existing symlinks to this checkout. The installer restores executable modes on its own known launchers/runners because some GitHub skill downloaders do not preserve them. The launcher canonicalizes symlinks before resolving assets.

Launch

build-it-out "implement the exact task" --project /absolute/repo --trusted-task
build-it-out "inspect the proposed run" --project /absolute/repo --dry-run

Useful bounds and safety controls:

--workers 1..8                 default 3
--max-worker-attempts 1..5     default 2
--max-plan-revisions 0..5      default 2
--max-rounds 1..10             default 3
--max-units 1..32              default 12
--command-timeout 30..3600     default 600 seconds
--role-timeout 30..3600        default 1800 seconds
--run-id SAFE_LABEL            unique NTM label
--allow-dirty                  fingerprint and preserve user changes
--worktrees                    preview protocol in dry-run only; live refused
--trusted-task                 required live trust/data-flow acknowledgement
--no-user                      omit the operator pane

Bundled defaults are explicit: Codex workers use gpt-5.6-terra; coordinator and fresh critic/reviewer use fable. Override them with the three model flags or BUILD_IT_OUT_WORKER_MODEL, BUILD_IT_OUT_ORCH_MODEL, and BUILD_IT_OUT_REVIEW_MODEL. --worker-model must name a Codex-compatible model. --orch-model and --review-model must name Claude-compatible models. This launcher does not pretend a model can be routed through the wrong provider.

Safety contract

• Live runs require Git and default to a clean tree. --allow-non-git is dry-run-only because HEAD, diff, and scope cannot otherwise be proven.
• Dirty baselines require --allow-dirty. V2 records content fingerprints, so changing a file that was already dirty is still detected and attributed.
• Preflight and gates also fingerprint conservatively named protected ignored files, including .env*, local databases, keys/certificates, and common credential/secret/token files. Dependency and cache trees are pruned. This is deliberate secret protection, not a complete inventory of every ignored file.
• The immutable task must exactly match contract version 2. Contract validation rejects dependency cycles, unsafe paths, unordered overlapping scopes, prose masquerading as commands, and commit/network/install/deploy commands.
• An atomic, locked run-state ledger anchors the task, baseline, contract, and validation hashes. It creates one-shot claims for each contract-bound plan critic, checkpoint-bound unit gate, and evidence-bound semantic reviewer. Official runners atomically consume a claim before invoking Claude or running a gate, then finish it with the immutable result. Replays, parallel reuse, and prompt-only counter resets fail closed.
• Each shared-tree assignment gets a pre-dispatch checkpoint. The gate checks both cumulative scope and the current worker's delta, preventing a later worker from silently overwriting an earlier unit.
• Verification evidence records literal commands, exit codes, bounded output, HEAD, changed/untracked paths, content fingerprints, canonical diff and repository-state hashes, baseline/validation paths and SHA-256s, contract SHA-256, and any scope or mutation failure. Contract, baseline, validation, and checkpoint files are parsed from the same byte snapshots whose hashes are recorded, then rechecked after the gate. Verification commands themselves may not mutate repository paths. Checkpoint, gate, and role artifacts must live outside the project and refuse overwrite, so the evidence machinery cannot dirty the build or silently replace an earlier record.
• Mechanical green always precedes semantic review. A fresh reviewer validates the seal, evidence, current HEAD/status, canonical tracked diff, and untracked file list before judging behavior, then rechecks the repository and artifacts after Claude returns so a review-time edit invalidates the verdict.
• Reviewer suggestions are advisory. Only concrete BAD blockers may enter a repair round, and they must map to existing sealed units. No contract expansion occurs mid-run.
• Workflow policy forbids commits, pushes, deploys, publishing, dependency installation, and external-service mutation. Exhausted bounds stop as BLOCKED with artifacts.
• Verification entries are parsed as one executable plus literal arguments and launched without a shell. The validator rejects shell control/substitution and common direct wrappers, inline-code flags, network/service clients, filesystem mutators, package executors, and unsafe Git forms. This is defense-in-depth, not a complete program-behavior allowlist: unknown executables and repository-owned test programs still execute trusted code. Sensitive-looking and execution-injection environment variables are removed, stdin is closed, output is capped, and timeout cleanup targets the spawned process group. None of these controls are OS containment.

The integrity seals and official one-shot entry points protect against stale state, accidents, and protocol replay. They are not a hostile same-Unix-account security boundary. The coordinator, critic, and reviewer have restricted tools, but worker panes use the operator's NTM/Codex runtime. The launcher does not assert that an OS sandbox is active. Repository gates detect Git-visible effects after the fact; they cannot prevent or undo network calls, external-service actions, or writes outside the repository. Run trusted tasks in trusted repositories, keep deployment credentials out of scope, and inspect the retained evidence before external actions.

A live run requires --trusted-task. This acknowledges that Codex workers receive sealed task/unit context and operate with the caller's runtime permissions. The Claude coordinator receives the task and can inspect project instructions/repository content through Read/Glob/Grep and policy-constrained Bash; it is launched unattended with permission prompts bypassed. Fresh Claude critics/reviewers receive the task, contract, canonical diff, and bounded gate output and may inspect additional repository content with Read/Glob/Grep. Provider transmission, retention, and cost follow the configured Claude/Codex clients and accounts. Tool profiles and prompts are policy boundaries, not OS containment.

--worktrees is a design-preview switch for dry runs only. NTM's built-in merge/remove commands can create commits, checkout main, or force-delete work, so the proposed V2 protocol uses verified binary patches instead. The launcher refuses live worktree execution until per-worktree baseline binding and a full end-to-end swarm qualification pass. Shared-tree mode is the supported live path.

Runtime artifacts

Each live run gets a private mode-0700 directory under XDG_RUNTIME_DIR (or /tmp) containing the immutable task/baseline, plan approval, contract seal, atomic lifecycle ledger, checkpoints, exact command evidence, and structured critic/reviewer verdicts. It is retained for audit and printed at handoff. Failed partial launches kill only the exact labeled session created by that invocation. Dry-run artifacts are removed.

The detailed coordinator protocol lives in assets/orchestrator-prompt.md. Canonical role prompts and schemas live in assets/plan-critic-prompt.md, assets/reviewer-prompt.md, and adjacent JSON schemas. scripts/contract.py owns preflight, validation, checkpoints, and mechanical gates; scripts/run-readonly-role owns fresh restricted roles. scripts/run-state.py owns immutable anchors and atomic bound claims.

Verify the skill

node --test tests/build-it-out.test.mjs
python3 /path/to/skill-creator/scripts/quick_validate.py .