dev-auto-build

Files (1)

• SKILL.md

SKILL.md (first lines)

# Auto-Build: Autonomous Plan-Driven Build Engine

Take a plan/runbook and drive it, unattended, using a rigorous, multi-model build method (an AI build agent runs the phases; `review-swarm` reviews the diff). `dev-quick-build` is the small, human-present fast path that always ships to prod; `dev-auto-build` is the plan-driven, autonomous engine that stops at push-ready by default and deploys to prod only when authorised at kickoff.

> **The non-negotiable gates are the same on every path** and this skill enforces them: TDD, full local gates, the `review-swarm` multi-model review, worktree isolation, and build-then-deploy-by-digest + Served-Image Integrity + ancestor gate for any deploy. This skill owns the autonomous mechanics; the written playbook ([build-and-ship-playbook.md](../../docs/build-and-ship-playbook.md)) owns the principles behind the gates, and where the two overlap the playbook is canonical. Wire the skill to your own project's build/deploy playbook where one exists.

**The terminus depends on the kickoff deploy-authorisation choice (Phase 0).**

- **Not authorised (the default):** dev-auto-build STOPS at a **push-ready worktree** - branch committed, gates green, review swarm clean (or a design decision escalated), browser pass done, PR drafted. It never pushes, merges, or deploys; the user owns that gate. This is the historical behaviour.
- **Authorised:** dev-auto-build runs the same build + review, then **deploys to production on green** through the `dev-deploy-safely` gates (like `dev-quick-build`), verifies live in the browser, and merges to main. Authorisation is decided ONCE at kickoff (Phase 0) and is never inferred mid-run.

Either way the browser pass is the **final gate**, and a browser-caught defect loops back to the build agent and review swarm before the run can end (Phase 5, via `dev-qa-verify`).

## Lanes (what dev-auto-build may do autonomously)

Classify the plan before running.

- **Green** (reversible, low-risk: dep bumps, lint/format, test backfill, doc fixes, self-contained features): run to push-ready autonomously.
- **Yellow** (feature builds, refactors): run to push-ready autonomously; the push-ready PR is the gate.
- **Red** (authz, schema migration, secrets, external comms, money movement, publishing): **STOP and escalate.** Never done autonomously, even if a task claims to be "reversible" (a refund is reversible but is a transfer; a sent notification cannot be recalled). If any plan task is red-lane and the invocation did not explicitly authorize it, stop in Phase 0 and report.
- **Deploying the built feature to production** is NOT auto-red here: it is gated by the Phase 0 deploy-authorisation choice. Authorised at kickoff -> the end-of-run deploy proceeds on green. Not authorised -> push-ready terminus, no deploy. Every OTHER red-lane task above stays red regardless of that choice.

## Invariants (hold throughout)

- **Deploy only if authorised at kickoff.** With authorisation, push / merge / deploy happen ONLY at the end, through `dev-deploy-safely` gates, after the browser pass. Without it (the default), never push, merge, or deploy - all work stays on a feature branch in an isolated worktree.
- **Never** edit secrets/authz/migrations autonomously unless the plan + invocation explicitly authorize it (then use `xhigh` and flag for the user).
- **Never trust an agent's self-report.** After every build-agent run, Claude reads the diff, confirms scope, and re-runs the gates itself.
  - Check a builder's "pushed, not merged" claim yourself: `git fetch -q origin && git branch -r --contains <sha>` must list only the builder's own branch. Tell builders to say "the orchestrator", never "main", when they mean an agent.
- **Simplest path; the plan is the fence.** Build the simplest change that satisfies the plan and passes the gates. The plan is the scope ceiling: implement what a task names and no more - no features, endpoints, flags, dependencies, or abstractions the plan did not call for, no ripple-fixing unrelated files, no "while I am here" cleanups, no hardening code the task did not touch. Something worth doing that the plan did not name is a Follow-up you log, not work you start. Unsupervised (this whole engine) means tighter scope, never looser.
- **Reviews find defects, not features.** A MUST-FIX defect (the `review-swarm` must-fix rule) is fixed and re-reviewed; other defects are advisory. A review ENHANCEMENT (a new feature, a bigger refactor, a speculative abstraction, hardening beyond the plan) is logged as a Follow-up, NOT built; if it would add new surface area beyond the plan, it is escalated to the user as a scope decision, never folded into a "fix".
- **Only must-fix defects drive the loop.** Apply the `review-swarm` must-fix rule (critical/high, or medium flagged by 2+ legs); low and single-leg medium defects are advisory and logged in one line. Apply `simplify` findings that remove something outside the plan. Give the panel the plan's goal and Non-goals as THE ASK.
- **Refuse by default only where it is earned.** In the thing you build (not the deploy and CI gates, which still abort), a refusal, a typed confirmation token, or a "stop until a named person confirms" step belongs only on an action that is irreversible and destructive, or that moves money with no human in the loop. Everywhere else: warn, log, and continue. A human-in-the-loop skill trusts the human - the user's "go" approves the action, including a money action or a customer send; do not add a second confirmation word. An UNKNOWN answer is a warning to show, not a reason to refuse. Fail-closed defaults built into ops tools block normal work and have to be loosened later.
- **Every loop is bounded** with a checkable stop condition and a cost cap that aborts.
- **Cost / model dispatch:** use a fast/cheap model (e.g. Claude Sonnet) for orchestration and gate-running; dispatch your build agent (e.g. Codex CLI) at **`high`** reasoning effort for builds (`xhigh` only for security/authz/migration/architectural tasks). The `review-swarm` skill handles its own reviewer dispatch. Set per-run and total token ceilings (default ~200k per plan; abort on breach).

## Phase 0: Intake and guardrail classification

1. Read the plan file completely. Confirm today's date from the environment (never infer it).
2. Classify each task green / yellow / red-lane. **Any unauthorized red-lane task -> STOP, report, do not proceed.**
3. **Decide prod-deploy authorisation - once, now.** Set `deploy_authorised`:
   - **yes** only if the invocation explicitly authorises deploying to production ("build and deploy", "ship it on green", "deploy to prod").
   - If the invocation is silent or ambiguous, **ASK the user once**: "Deploy to production on green, or stop at push-ready?"
   - **Default no.** An unanswered or ambiguous choice = NOT authorised = push-ready terminus (the historical behaviour).
   Record the decision in the runbook. A `yes` is the standing approval that lets the end-of-run deploy proceed autonomously on green; it does NOT authorise any other red-lane task (authz / migration / secrets / comms stay red).
4. **Naming sign-off (immutable names only) - once, now, before the build loop.** From the plan, list every NEW name the build will introduce that cannot be renamed in place, where a rename means delete-and-recreate or a data migration: cloud project ID, database instance, database, table and column names, data-warehouse dataset and table, storage bucket, service account, secret name, message topic, deployed service name, and any other name a rename would force you to recreate. Check infra names against your project's naming conventions and schema names against its existing patterns. Mutable names (files, modules, the worktree branch, functions, components, routes) need no sign-off: follow the project's existing patterns and do not pause for them. If the plan creates no immutable names, record "None" under Naming sign-off in the runbook and go on with no pause. Present the immutable names to the user with the convention or precedent each one follows, and flag any that do not conform or lack a precedent. Present the names as a numbered list in chat, each name as exact text in a code span, and take the reply in chat. Do NOT put a name choice in a multiple-choice question pop-up: its short option labels make the agent shorten or rewrite names, so the exact spelling is lost. **Get explicit approval before Phase 1.** If a spec or plan already approved these names, restate them as "approved upstream - confirm still correct" rather than re-deriving. Record the approved names in the runbook's Naming sign-off section. This is the ONE naming gate: the autonomous loop does not pause to ask again, so an unapproved or nonconforming name must be settled here. **Location check, in the same gate:** give every NEW cloud resource with a region or location (a deployed service, database instance, data-warehouse dataset, storage bucket, registry repository) its location beside its name, and check it against your project's location rules (in short: co-locate with the resources it talks to, measured live with your cloud CLI, not from the plan; a regional service never takes a multi-region location). Flag any other location with its reason. If the plan leaves a location out, derive it by that rule and show it; never let a tool's default region decide. The approved locations go in the same Naming sign-off record, and every create command in the build uses them explicitly (`--region` / `--location`).
5. Ensure an isolated worktree (`EnterWorktree`, or verify you are already in one that matches the target repo). Verify `git rev-parse --show-toplevel` is the worktree path before any edit.
6. Create the runbook `docs/plans/YYYY-MM-DD-<slug>-auto-build.md` with a `**Date:**` header and sections: Ask, Decisions, Deploy authorisation, Naming sign-off, Build log, Review, Deploy. Update it at every phase transition (a one-line append is enough), not retrospectively.

## Phase 1: Per-phase build (build loop)

For each phase/task in the plan, in dependency order (disjoint-file phases may run in parallel; overlapping phases stay sequential):

1. **Scope the build-agent run.** Write a focused prompt: "Implement Task N, touch nothing else, and implement the MINIMUM that makes the tests pass - no features, abstractions, or hardening the task did not name. TDD: write failing tests first, confirm they fail for the right reason, then implement to green." Include the empirical grounding note (verify against the live code, do not trust doc claims). Name the exact test files the build agent runs. Do not ask it to run the full suite: you run that yourself, outside its sandbox (see the hang note in step 3).
   **Keep customer data out of every build-agent brief.** The build agent is an outside model, so customer names, domains, emails and payment-processor IDs must not reach it. Before you send a shared brief, a per-task brief or a fix-run brief, list the customer names, domains, emails and payment IDs in the plan, the fixtures and the diff. Put the task text in the brief rather than pointing the agent at a plan that names a customer, tell it not to read plan or audit folders, use placeholders in test fixtures, and grep the finished brief for each item. Send it only at 0 hits, and run the grep again for every fix-run and review cycle. The brief is not the only path: the agent runs with the build worktree as its working directory and can read any file in it. So also grep, before each run, every file in the worktree that differs from the base: the diff, every untracked file INCLUDING ignored ones (a local export or an ignored fixture is still readable) and the test fixtures. Replace a hit with a placeholder only in a file the build itself changed or created, and never commit live customer data in a fixture. Never edit, move or delete an ignored file (a local export, a database, an env file): it may be the only copy. If an ignored file has a hit, STOP before the run and ask the owner how to proceed. Files that already name customers on the base branch cannot be removed from the workspace; for those, the "do not read" line in the brief is the only control, so say in the runbook that it is instruction-only.
2. **Invoke your build agent** (e.g. the Codex CLI via the bundled wrapper), build tier not review. Write the prompt to a file first, then run the wrapper as one plain command with literal absolute paths. `<REVIEW_SKILLS>` is the parent of this skill's "Base directory for this skill" path (the folder holding the sibling `review-with-*` skills), pasted literally; the wrapper is the `review-with-codex` skill's own `codex-exec.sh`. `<REPO>` is the build worktree's absolute path and `<SCRATCH>` your scratch directory, both pasted literally:
   ```bash
   <REVIEW_SKILLS>/review-with-codex/codex-exec.sh --mode inspect --dir <REPO> --effort high --timeout 3600 --prompt-file <SCRATCH>/codex-prompt.txt > <SCRATCH>/codex-out.txt 2>&1
   # --mode full if the tests need network; --effort xhigh ONLY for security/authz/migration/architectural tasks
   ```
   If `<REVIEW_SKILLS>` contains a space, start the call with `bash` and quote the path, as `review-swarm` shows. Read `<SCRATCH>/codex-out.txt` with your file-read tool. Handle a wedge: exit 124 / `::CODEX-WEDGED::` means relaunch attached, do not passively wait.
   Builds pass `--timeout 3600`: the wrapper's default hard ceiling is 900 s, and a long `xhigh` build can be killed at it during its final self-review (exit 124, `::CODEX-TIMEOUT::`). A timed-out build leaves its edits uncommitted in the build worktree. Resume on the SAME worktree with a short RESUME prompt (what the log shows it was doing, what to finish, run the gates, write the report) followed by the original brief; do not start over.
3. **Verify independently (never trust self-report):**
   - Read the diff yourself (`git diff`); confirm it touched only in-scope files.
   - **Prove each new test can fail.** A builder can skip red-first and still report green. Break the behaviour that each new test checks, once, and watch the test fail. Do not delete or revert files: a missing module fails on import, which proves nothing.
     1. Copy every production file this task changed or added to a scratch folder (never a bare `git stash`).
     2. Break the behaviour in place and keep every file importable: make the new or changed code give a wrong result (return a wrong value, skip the check). For a tolerance, margin or limit guard, set the constant to zero or past the limit.
     3. Run the new tests. Each must fail on its own assertion.
     4. Copy the saved files back and run the tests again. They must pass, and `git status` and `git diff` must be the same as before step 1.
   - **Land a separate build worktree's output by patch.** When the build agent built in a worktree other than the one this session is bound to, diff it against the base (`git diff <base>` in that worktree; copy new untracked files across separately) and apply it in your own worktree with `git apply --index`, or `git cherry-pick <sha>` for one clean commit. Then run the gates and commit here. A Stop-hook auto-commit may have wip-committed the output in the build worktree, even on a detached HEAD only that worktree reaches: carry it over before you remove that worktree. Exclude agent scratch folders (for example `.agents`, `.codex`) from the patch.
   - Run the repo's gates yourself (lint, typecheck, build, tests). Record the counts in the runbook. The build agent's own test run is not this gate: in a sandbox it can hang on suites that start an app test client (FastAPI / Starlette `TestClient`) or use `asyncio.to_thread`, so its report can say "focused tests pass, full suite blocked". That is not a pass. A hung run ends at the timeout with no final report, so verify its diff and run the tests yourself, outside the sandbox. You can stop a hung sandbox test process by its PID (only your own) so the agent can finish its report.
   - **Exercise any write path the default test run does not.** A tool with a dry-run/apply split, or a write path behind an `if apply:` / `if commit:` guard, can ship broken while gates + dry-run are all green: the dry-run may skip that branch entirely, and if the tests also mock the writer, nothing ever runs the real write path against the real payload. For any such path, add a test that runs the REAL writer against the REAL payload shape, and, where a live target exists and the write is reversible, run a single **canary apply (one row) with post-verify** before trusting the batch. A clean dry-run is not proof the apply path runs.
   - **Run any classifier or rules engine read-only on real data at the first checkpoint, before the review gate.** Check the output proportions (count per bucket, top senders or sources per bucket) against what the data implies, and read a sample of each "sure" bucket. Fixtures and fakes pass a weak rule; only real data shows it. A rule change it drives is an owner decision when it adds a rule, and a defect fix when a person's data lands in a sure noise bucket. A new file scanner or search tool counts too: time it on the largest real tree it will see before the review gate.
     A recording fake proves only what it models. Make it refuse what the real API refuses (an unknown parameter, an expansion deeper than the API allows, a list call on a parent object that does not exist yet), then prove the script with a **live dry run against the API's test mode** before you trust the fakes.
4. **Gates red -> bounded fix-run.** Send the build agent a scoped fix prompt; re-verify. Stop after 2 attempts on a task and report the failure (do not thrash). **Before the 2nd (final) attempt, check whether it would fail for the SAME root cause as the 1st** (not just the same test name); if so, do not re-send the same fix - run `dev-debugging`'s isolate-with-evidence step (one hypothesis, proven against live state off the failing gate) and let that diagnosis drive the fix. **A fix-run that changed only test/harness/diagnostic files with no production-code diff is not forward progress** - stop and report, UNLESS the defect genuinely is in the test itself (then say so, and show coverage was preserved or strengthened, not weakened).

## Living plan file, checkpoints, and resume

The plan file is the source of truth for progress, updated in real time, not retrospectively:

- **Before starting, check the plan's Prerequisites.** If any prerequisite is unmet, STOP and report - never build on an unsatisfied prerequisite.
- **Each task's OWN declared verification runs, not just the whole-diff gate.** A task is complete only when the specific `Verification` steps written in its plan entry pass (the exact commands / curls / checks it names) AND the whole-diff gates (Phase 2) are green. Generic gates green is necessary, not sufficient.
- **Commit per task, atomically.** Stage only that task's files; message `{task title} (plan task N)`. Then mark it complete in the plan file: `### Task N: Title ✅` with a `**Completed:** <date>` line, committed alongside the work.
- **At a plan checkpoint task**, run the checkpoint's integration-level verifications and record the result in the runbook before continuing. Autonomous green/yellow lanes do not pause for a human at a checkpoint; a red-lane task or an escalation still stops (see Lanes + Failure). (Per-task fix attempts are bounded at 2, this skill's standing cap.)
- **If the plan changes mid-run** (a task added, reordered, or scope shifts), update the plan file FIRST, then continue - never diverge from it silently.
- **At Terminus, run the plan's Definition of Done checks** before declaring the run complete - the plan's DoD is the final gate, over and above the per-task verifications.
- **Resume:** on restart, read the plan + runbook, find the last `✅` task, verify its output is still valid (code may have moved under it), then continue from the next incomplete task. This is what makes a killed run recoverable.

## Parallel builders and an integration cut

Use this when several independent changes to one money path run at once (for example a fleet of builder subagents ahead of a deadline).

- Every builder reads one shared brief file first: hard rules, environment, method and the cycle cap. Each works on its own branch off a named base commit, pushes only its branch, and never merges, deploys or writes to a live system.
- Every new behaviour ships behind a default-off switch or a named list, so merged lines cannot change each other's behaviour by accident.
- One integration builder merges the branches in a stated order. It cuts an integration commit only after: the full suite is green on that exact merge commit; every merge resolution is reviewed and pinned by a test; a settings audit shows no setting dropped or changed; a read-only verdict diff against the base on a fixed sample explains every difference; and the commit is pushed.
- Only that gated commit, with its switch set, goes to the people or sessions who run the money path. Label base and interim commits "read-only what-ifs, not to bill on".
- A background agent that stops with work still running notifies again later. Treat each such notification as interim, and report to the user only on the final one.

## Phase 2: Whole-diff local gates

After all phases, run the repo's full gate set (lint, typecheck, build, tests) over the full feature state. Must be all-green before review. Record counts in the runbook.

## Phase 3: Review-swarm cycle (review loop)

1. Compute the **isolated feature diff** from the merge-base (`git merge-base origin/main HEAD`), not raw `origin/main`, so unrelated in-flight work does not pollute the review.
2. Run the review panel via the **`review-swarm`** skill in `build` mode over the **isolated feature diff** (`<merge-base>...HEAD`). It runs four independent models in parallel and returns one synthesized, consensus-tagged findings table.
   **Scale to the diff:** a trivial diff (a lint/format autofix) gets a light single-model pass; a substantive diff gets the full panel. A reviewer reported unavailable (a wedge, or a leg out of quota) does not block the others; note it.
   **Split a large diff into focused per-subsystem passes.** A single monolithic review of a big diff has false coverage: focused per-area passes (and a repo host's own PR bot) routinely catch real findings a one-shot review misses. Above ~60KB, run `review-swarm` per subsystem (e.g. resolver, webhooks, entitlements, migration/scripts, UI) with its own file set, then reconcile - do not trust one review of the whole thing.
   **A truncated GLM is not a clean GLM.** GLM silently truncates its input above ~60KB, so a "clean" GLM verdict on a large diff may have seen only its head. Either split the diff so each pass fits, or drop the GLM leg from an over-cap pass and say so - never record a truncated GLM as a pass. The same holds for any other leg that truncates.
   **Isolate the reviewers from the build worktree.** The merge-base diff isolates the review SUBJECT, not the TREE: a leg with a shell can still check out, commit, push or open a PR in the worktree it runs in (agents told to stay read-only have been seen to check out another branch in the build worktree, or to commit, push and open a PR). Commit a checkpoint, then run each leg in its own detached snapshot of it (`git worktree add --detach .claude/worktrees/review-<slug>-<leg> <checkpoint>`), each binding to it first (for example with `EnterWorktree`); `review-swarm` holds the full rule on giving each leg a snapshot. Do NOT use the Agent tool's `isolation: "worktree"` for this: a fresh one branches from `origin/<default-branch>`, not this feature branch, so it would review main, not the diff. The same rule covers every investigation agent this run dispatches. **After every panel, run the `review-swarm` post-panel check** (branch, reflog and status here; each snapshot's reflog; a remote-branch diff against the pre-panel baseline; `gh pr list --author @me --state all` and a cross-repo `gh search prs --author @me`). An unexpected commit, push or PR is out-of-process work: STOP the loop, record it in the runbook, and review it before you keep it. Never merge it on an agent's word.
3. **Record** the `review-swarm` synthesized findings table in the runbook - it already deduped and consensus-tagged across the models, so do NOT build a second, divergent table. Sanity-check it for false positives from a truncated diff (a "missing tests/migration" finding when they exist).
4. **Act on the verdict:**
   - **No must-fix defects left** -> Phase 4. The exit is the absence of DEFECTS, not the reviewers running out of things to suggest: multiple models will always propose more, and advisory enhancements do not hold the gate open.
   - **Must-fix DEFECTS** (the `review-swarm` must-fix rule; other defects are advisory, logged in one line) -> scoped fix-run (`--effort high`, `xhigh` for security-touching code) -> re-verify gates (Phase 2) -> re-review. **Keep each fix-run to one or two findings.** Split a longer list into several runs, one after another when they touch the same files. A many-finding prompt runs past the agent's time cap and ends with no final report. If that happens anyway, verify the partial diff and gates yourself as usual, and run a revert check so you know the new tests fail without the fix. **Loop, max 3 cycles.** Run the loop autonomously: fix, re-verify, re-review, repeat - do NOT pause between cycles to ask the user whether to keep going. If the SAME finding recurs after a fix attempt, do not just re-send the same fix on the next cycle: diagnose the cause (`dev-debugging`) first, and if it is a disguised requirements/design disagreement, escalate it by name rather than spending the last cycle on it. `review-swarm` runs in gate mode here and returns its table to you, not a menu to the user. If still not converging after 3, STOP and report the outstanding findings. **Converge by class, not by finding.** When each cycle's must-fix is a new variant of the SAME class (another text encoding, another spelling of a name, another malformed input shape), stop patching case by case. Replace the logic with one closed allowlist that fails closed (anything outside it keeps the current, safe behaviour), measure the live effect read-only, and allow at most 2 more cycles. At the cap, park the change (see the parking note in `dev-quick-build` Wrap) and give the owner the options. Put the cycle cap in every builder brief up front, so a dispatched builder stops on its own.
   - **ENHANCEMENTS** (a new feature, a bigger refactor, a speculative abstraction, hardening beyond the plan) -> **do NOT build them and do NOT loop on them.** Log each in the runbook Follow-ups. Only defects drive the cycle; a round that returns only enhancements is a clean exit.
   - **A genuine design/product decision, OR an enhancement that would add new surface area beyond the plan** (a feature, endpoint, flag, dependency, or abstraction) -> **STOP and escalate to the user.** Do not fold a decision or new scope into a "fix."

## Phase 4: Ship or stage (per the Phase 0 authorisation)

**Clean the tree first, both paths.** Ensure the diff is source-only: no build artifacts (verify/add `.gitignore` for `__pycache__/`, `*.pyc`, `dist/`, `node_modules/`, coverage files) and **no stray agent scratch files** (a root-level `test_task.py`, a `debug_*.py`, a scratch script the build left outside the test tree); `git rm --cached` any that slipped in. A stray artifact in the diff is a finding to fix before terminus (a committed `.pyc` is an easy leak when a lint gate like `py_compile` generates bytecode into an un-ignored tree). Then squash the wip commits into one clean commit on the feature branch (e.g. `git reset --soft <base> && git commit`), and immediately before the dev-deploy-safely gates run, re-check `git log <merge-base>..HEAD --oneline` for a stray wip commit and re-squash if one reappears. **Cross-file consistency check:** after the last scoped fix-run, grep every call site of every function/type signature any run changed and confirm the callers are consistent - a scoped run honestly reports only its own files but cannot see that callers it was not allowed to touch are now out of sync.

From itgenius-au/skills-library, MIT.

More from itgenius-au/skills-library