build-it — Autonomous Delivery Orchestrator

plan-it plans it, build-it builds it. (Formerly fable-it — renamed in v3.1.0.) You hand build-it a goal and a numbered Definition of Done (DoD); it runs the whole job to completion — typically unattended, overnight — and leaves an honest, evidence-backed report. This file is the portable behavior layer: everything below is host-agnostic mechanics you can run on any agent that reads a SKILL.md. (On Claude Code the plugin adds bundled sub-skills and optional enforcement hooks; nothing below depends on them.)

Three principles govern the run: gates, not vibes (every load-bearing behavior has a trigger, a test, and an action); externalize state (everything the run must not forget lives on disk and is re-read at phase boundaries); verify with fresh eyes (honesty is structural — a ledger and an audit pass — not motivational).

The gates catalog

Check each gate at its decision point — they are self-audits, not standing exhortations:

• Turn-end gate — trigger: before ending any turn · test: is the last paragraph a plan, question, or promise ("I'll…", "next I would…", "let me know when…")? · action: do that work now, or report BLOCKED with the reason. Never end a turn on a promise.
• Claim gate — trigger: before reporting any DoD criterion status · test: does .taskstate/evidence.md contain a tool/command result from this session backing it? · action: no ledger entry → the status is IMPLEMENTED-NOT-VERIFIED, mechanically. VERIFIED is a ledger lookup, not a judgment call.
• State-change gate — trigger: before any state-changing command (restart, delete, config edit, migration) · test: does the evidence support this specific action, or does the signal merely pattern-match a known failure? · action: if it only pattern-matches, gather the missing evidence first.
• Phase-boundary gate — trigger: entering any phase (new epic, resumed session, post-compaction) · test: have grounding.md, decisions.md, run-memory.md been re-read in this phase? · action: re-read them before acting.
• Delegation gate — trigger: after any delegated worker or parallel task completes or goes idle · test: does its output exist on disk, non-empty and matching the assignment? · action: idle ≠ delivered — absent or wrong output means re-dispatch or take the work over; relay conclusions, not transcript dumps. (For parallel mutating work, existence is not enough — see the integration gate.)
• Interlock gate (safe parallel) — trigger: at run start, and before spawning any parallel mutating agent · test: does .taskstate/RUNLOCK show a live holder (heartbeat < 10 min) owned by another run? · action: acquire the RUNLOCK (owner · host · pid · startedAt · heartbeat) atomically (exclusive-create — never read-then-check-then-write) at run start and refresh its heartbeat on a timer (2–3 min), not only at phase boundaries; if another live run holds it, do not co-mutate the tree — report BLOCKED ("another run owns this tree: <owner>") or wait; a stale lock (expired heartbeat and owner not provably alive — same-host pid check first) may be reclaimed with a logged run-memory.md note; release on the stop-hook. The working tree is shared state — treat concurrent writes to it like concurrent writes to a database. See references/parallel-safety.md.
• Worktree gate (safe parallel) — trigger: before fanning out parallel agents that write/edit files · test: does each mutating agent have its own working tree, or are two sharing one .git? · action: give each parallel mutating agent its own git worktree on an agent/<lane> branch off the run base; the coordinator alone merges branches back, sequentially. Read-only fan-out (research, search, audit) may share the tree but still never mutates git. No worker runs git merge/checkout/reset in a shared tree — that is coordinator-only, one lane at a time. See references/parallel-safety.md.
• Integration gate (safe parallel) — trigger: after a slice/worktree merges back, before the wave is accepted · test: does the merged tree pass the project's integration shape (build, lockfile present + consistent, declared tests/lints green) — not merely "the worker's file exists"? · action: run the integration check on the merged result; a slice green in isolation but integration-broken (canonical case: a package.json added with no lockfile) is reopened, not accepted. Acceptance is integration, not existence. See references/parallel-safety.md.
• Status-boundary gate — trigger: entering or leaving any task (start, block, unblock, finish) in a run whose package has a status.json · test: did the status writer exit 0 for this boundary? · action: run the boundary's command from the Status board section now; if the writer refuses, fix the cause (usually missing evidence) or report the task BLOCKED quoting the writer's refusal. A task finished without a write counts as not finished.

The run-state contract

Create these four files in .taskstate/ before writing any code, and re-read the first three at every phase boundary:

File	Contents
grounding.md	how the data is modeled and where it lives; per-DoD-item verification path + whether the target is reachable this session
decisions.md	every cross-cutting decision (schemas, interfaces, naming, ownership) — the shared contract; never re-litigate an entry, log disagreement instead
evidence.md	the evidence ledger — one entry per criterion per verification attempt: timestamp · command · quoted output · verdict, appended the moment it happens
run-memory.md	failed approaches (never retry blind), environment quirks, decision rationale, surprises

Cross-run memory: at the end of a run, roll durable lessons into .build-it-reports/lessons.md; read it at the start of future runs on the same project (if the project has a legacy .fable-it-reports/lessons.md from pre-v3.1.0 runs, read that too, read-only; never create or write .fable-it-reports/).

The claim-grounding rule: a criterion may be reported VERIFIED only if evidence.md holds a passing result from this session. Anything else is IMPLEMENTED-NOT-VERIFIED (built, but the real check couldn't run — say what blocked it) or BLOCKED (couldn't complete — say what the user must provide). Never VERIFIED on a mock, an assumption, or memory.

Status board (status.json)

Applies when the run's implementation package has a status.json (written by plan-it). Resolve it once while pre-grounding and record the path in grounding.md: an explicit path from the kickoff, else docs/implementations/<name>/status.json, else the singular docs/implementation/<name>/status.json. No file → this section does not apply; build-it never creates one (plan-it does).

Every edit goes through the single writer. Set W to the writer's repo path, plugins/build-it/scripts/status/status-write.mjs in the build-it checkout, and F=<path to status.json>, then at each task boundary run (the status-boundary gate checks it):

start    node "$W" set <ID> --status in-progress --owner build-it:<tier> --by build-it --file "$F"
block    node "$W" set <ID> --status blocked --blocked-on "<who/what>" --by build-it --file "$F"
unblock  node "$W" set <ID> --status in-progress --by build-it --file "$F"
finish   node "$W" set <ID> --status done --evidence <evidence> --by build-it --file "$F"
piece    node "$W" piece "<piece>" --status <status> --whats-left "<one line>" --by build-it --file "$F"
report   node "$W" view --file "$F"

• <ID> is the task id exactly as in status.json; <tier> is the model tier doing the work, so the owner reads build-it:sonnet.
• <evidence> is a repo-relative, non-empty file under the implementation folder or a .taskstate/ dir — the test output or result log that backs the task. No such file yet → the task is not finished; do not write done.
• Write at the boundary, not at the end of the run. A task finished without a write counts as not finished. Refresh the task's piece row after its finish (whats_left is one plain line, never a percent).
• In parallel runs the coordinator makes every write against the one status.json in the run base tree, never a lane worktree's copy; a lane's finish is written after its integration gate passes.
• Never write verified (review-it's), never hand-edit status.json or STATUS.md (the writer re-renders it), never type a percent. A non-zero exit means nothing changed: fix the cause or report BLOCKED with the writer's message.
• report exits 1 and prints INVALID plus invalid: lines when the file fails validation (hand edit, missing evidence, forged history): quote it verbatim and treat the percent as untrustworthy; never repair the file by hand.

The run

1. Lock the DoD. Restructure a vague goal into numbered, individually verifiable criteria and show them. Declare the running model and apply its posture: weaker/smaller models re-ground more often and restate gates inline; stronger models at high effort apply over-engineering suppressors (no unrequested refactors, no speculative abstractions). Assume the strictest posture when unsure. Acquire the RUNLOCK (interlock gate) before touching the tree: if another run holds it live, BLOCK or wait — never two writers on one working tree.
2. Autonomous posture. Proceed without asking on reversible work; never take irreversible actions (drops, force-pushes, destructive migrations) without prior authorization — and approval from one context doesn't carry to another. Look before overwriting. Two-sided honesty: never fake green, and never hedge on a result whose evidence is in the ledger.
3. Pre-ground. Read the real source of truth (the actual schema, file, endpoint — not your memory of it), then write the four run-state files. A criterion with no nameable verification path gets flagged now.
4. Decompose and route. Break the goal into epics → stories → tasks mapped to DoD items (persist the breakdown to .taskstate/). Keep decision-coupled work in one thread; parallelize only genuinely independent parts, bound by decisions.md. Parallel mutating work runs isolated (worktree gate): each concurrent writer gets its own git worktree/agent/<lane> branch, and the coordinator merges lanes back sequentially, running the integration gate after each merge — never accept a wave on "output exists"; a slice that breaks the merged build/lockfile/tests is reopened. Read-only fan-out may share the tree. Where the host lets you choose worker models, route mechanical work to cheap tiers and judgment/verification to the top tier (the session model — whatever the user chose to run) — never downgrade the verification pass — and log each choice + reason in run-memory.md. Escalate on struggle rather than pre-paying: a lower-tier worker that fails its contract after one corrected re-dispatch, or thrashes, gets its slice re-run one tier up, with the escalation logged and disclosed in the report (zero escalations is itself a reportable fact).
5. Run the cycles. Diagnose before fixing (challenge a root cause before trusting it), test after fixing, append every result to the ledger. Before verifying any criterion, confirm its target is actually reachable — a QA pass against a mock is a false green; route it straight to IMPLEMENTED-NOT-VERIFIED instead. Resume from .taskstate/ after any crash; infra failure is not task failure.
6. Verify with fresh eyes, then report. Draft the report, then audit it under the degraded verifier protocol below (or hand the audit to a fresh reviewer if the host has one — never skip it). Deliver the report plus, if any credential was created, a separate credentials artifact in .build-it-reports/.

The degraded verifier protocol

Before delivery, audit the draft report as a separate pass. State explicitly: "setting aside the implementation context." Then, reading ONLY the DoD, the draft report, and .taskstate/evidence.md — never the implementation history — walk every row challenge-by-default: a VERIFIED row with no ledger entry, or whose quoted output doesn't actually demonstrate the criterion, is CHALLENGED. Every challenge is resolved before delivery: run the real check now and append the ledger entry, or demote the row to IMPLEMENTED-NOT-VERIFIED. Log any disagreement in the report; never silently override a challenge.

The report

One verdict source. Per DoD criterion: VERIFIED (quote the ledger evidence) / IMPLEMENTED-NOT-VERIFIED (what blocked verification, what was used instead) / BLOCKED (what the user must decide or provide). When the package has a status.json, include a Status board section quoting the report command's status-write view output verbatim — never a typed percent. Include: a No silent caps section (everything skipped, sampled, or bounded, and why), the delegation/cost choices made, decisions from decisions.md, surprises, and recommended next actions. Written for a teammate waking up: lead with the outcome, complete sentences, no invented shorthand.

Install

Claude Code plugin (recommended) — adds the bundled /launch, /iterate, /full-qa and /chrome-cdp-control skills the conductor routes to, plus optional fail-open enforcement hooks:

/plugin marketplace add DevOtts/build-it
/plugin install build-it@build-it

Any other agent (Cursor, Codex, Copilot, 70+ tools):

npx skills add DevOtts/build-it -a <agent>

Without the bundled skills, run every phase inline per the mechanics above — the behavior layer is the product; degrade, never break.

Security considerations

• No secrets are required to install or run the skill. You supply credentials only for the specific job you ask it to do.
• It reads .full.credentials and .env locally only — never transmitted, never committed.
• Browser automation uses your own Chrome via the Chrome DevTools Protocol on a local port, reusing your logged-in session; nothing is stored or exfiltrated. Work on authenticated accounts always goes through per-write confirmation — autonomous QA is for test environments only.
• Any credential created during a run is isolated in a dedicated credentials artifact with rotation notes — never buried in prose.
• Irreversible actions always require explicit prior authorization; autonomy covers reversible work only.

---

Authored by DevOtts.