build-it-out

Build It Out

A hardened multi-agent implementation board for Claude Code and Codex, coordinated through NTM.

Build It Out turns a substantial coding task into a sealed plan, gives each implementation unit to an exactly addressed Codex worker, checks the resulting repository state mechanically, and then asks a fresh capability-restricted Claude reviewer to judge the evidence. Repairs are bounded and must stay inside the original contract.

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

The current package release is 0.1.0. The contract and run-state protocol is version 2; package versions and protocol versions are intentionally separate.

What it protects

• Immutable task, baseline, contract, and validation hashes
• Minimal per-unit write scopes and dependency-aware execution waves
• Exact NTM pane addressing instead of worker broadcasts
• Checkpoint-bound worker attempts with one-shot replay protection
• Git-derived changed paths, fingerprints, diffs, command exits, and evidence
• Fresh read-only plan criticism and semantic review
• Bounded planning revisions, worker attempts, and repair rounds
• Existing dirty work when explicitly accepted with --allow-dirty
• Common ignored secret files such as .env, keys, and local databases

The full protocol and its fail-closed rules are in skills/build-it-out/SKILL.md.

Requirements

Runtime:

• A POSIX host; CI currently qualifies Linux
• Bash, Git, tmux, and Python 3.10+
• NTM 1.12.1 or a compatible release
• Authenticated claude and codex command-line clients
• Claude and Codex model aliases available to those clients

Development tests additionally require Node.js 20+.

The bundled model defaults are:

These aliases may be account-specific. Override them once in your shell:

export BUILD_IT_OUT_ORCH_MODEL="your-claude-model"
export BUILD_IT_OUT_WORKER_MODEL="your-codex-model"
export BUILD_IT_OUT_REVIEW_MODEL="your-claude-model"

Equivalent command-line flags are --orch-model, --worker-model, and --review-model.

Install

Clone to a stable path, then run the safe installer:

git clone https://github.com/SubliminalCoding/build-it-out.git ~/build-it-out
cd ~/build-it-out
./doctor.sh
./install.sh

If an agent skill manager downloaded only skills/build-it-out/, invoke its installer explicitly with Bash because archive downloads may not preserve file modes:

bash /path/to/installed/build-it-out/scripts/install

That installer restores executable mode only on its own known launcher and runners before creating discovery links.

The installer creates discovery links in ~/.claude/skills and ~/.codex/skills, installs the restricted Claude coordinator agent, and exposes the build-it-out command through ~/.local/bin when that directory is already on PATH, otherwise ~/bin.

It never replaces a regular file or directory. To migrate links from another checkout, inspect the proposed change first:

./install.sh --replace-links --dry-run
./install.sh --replace-links

Directory destinations can be customized with CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, CLAUDE_AGENTS_DIR, and BUILD_IT_OUT_BIN_DIR.

Run

Inspect the exact board and coordinator prompt without spawning anything:

build-it-out "implement the exact task" \
  --project /absolute/path/to/repository \
  --dry-run

Start a live shared-tree board:

build-it-out "implement the exact task" \
  --project /absolute/path/to/repository \
  --trusted-task

Attach to the printed session with ntm attach <session>. The launcher prints the private runtime directory containing task, contract, checkpoint, gate, and review artifacts. build-it-out --help lists every bound and safety control.

Live worktree mode is deliberately refused. --worktrees --dry-run previews the qualified integration design without using NTM's destructive merge/remove operations.

Trust boundary

This is an evidence and policy system, not an operating-system security sandbox. The coordinator and fresh reviewers are capability-restricted, but Codex worker panes run with the permissions of the operator's NTM/Codex runtime. Repository gates detect Git-visible effects after they occur; they cannot undo network calls, external-service actions, or writes outside the repository.

Use trusted tasks in trusted repositories, keep deployment credentials out of scope, and inspect retained evidence before any commit, push, deploy, publish, or other external action. See SECURITY.md for the complete boundary.

The required --trusted-task flag acknowledges this boundary and the complete model data flow. Codex workers receive sealed task/unit context and inherit the caller's runtime permissions. The Claude coordinator is launched unattended with permission prompts bypassed; it receives the task and can inspect project instructions and repository content with Read/Glob/Grep plus policy-constrained Bash. Fresh Claude critics/reviewers receive the task, contract, canonical diff, and bounded verification output and can inspect additional repository content with Read/Glob/Grep. Provider transmission, retention, and cost follow the configured CLI accounts. Tool profiles and prompts are policy boundaries, not OS containment.

Gate commands receive a reduced environment and run as direct argument vectors, not through 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 not a complete program-behavior allowlist: unknown executables and repository-owned tests still execute trusted code. Output and runtime are bounded, stdin is closed, and timeout cleanup targets the spawned process group, but escaped descendants are outside this portable policy layer. These controls are defense in depth rather than containment.

Update or uninstall

cd ~/build-it-out
git pull --ff-only
./install.sh --replace-links

# Remove only links owned by this checkout; keep the clone.
./install.sh --uninstall

Develop and verify

python3 scripts/validate-package.py
bash -n install.sh doctor.sh skills/build-it-out/bin/build-it-out \
  skills/build-it-out/scripts/install
python3 -m py_compile skills/build-it-out/scripts/*.py
node --test skills/build-it-out/tests/build-it-out.test.mjs

CI runs the package validator and the complete behavioral suite on supported Python/Node combinations. See CHANGELOG.md for releases.

License

MIT