Auto Build

Auto Build

Overview

Collapse plan → build into a single approved, autonomous pass that implements every task the disciplined way — test-first, integrated, reviewed, individually committed — while the DAG guarantees nothing is built before its dependencies land and the checkpoint guarantees a stop is always resumable. It removes the human stepping between tasks, not the verification: every task still earns a passing test and its own commit.

Phase 0: Preflight — plan, clean baseline, working branch

• Resolve the plan ($plan, or newest .ulpi/plans/*) and its independent Phase-0 intake snapshot (<stateDir>/intake/<run>.json from the active run config/checkpoint), then run the deterministic gate: node <auto-plan-dir>/scripts/validate-plan.mjs <plan.json> --intake <absolute-snapshot.json> — a non-zero exit is disqualifying (the same structural judge auto-plan and the pipeline preflight run; mechanically checked, never prose-only). No plan → route to auto-plan. No intake snapshot → STOP and route to pipeline intake; the plan cannot establish its own scope authority. Malformed/cyclic plan → STOP (it would build on a broken base).
• Confirm root is a git work tree with a committed workingBranch; never build on a protected branch without explicit confirmation.
• Require a CLEAN baseline: git status --porcelain shows only expected planning artifacts (.ulpi/spec/*, .ulpi/plans/*). Anything else → stop and ask the user to commit/stash.
• Fold the prior-run lessons from your loaded context into the engineer briefs — auto-learn routes them into CLAUDE.md / .claude/rules (auto-loaded for you), but a subagent engineer starts fresh, so a lesson the machine already paid for (a flaky service, a validate footgun, a boundary that bites) must be copied into its brief to reach the agent doing the work.
• Declare the run's budget/caps with budget-guard (max fix iterations per task, concurrency cap, token/wall-clock ceiling). Create the checkpoint-resume file with one unit per task. On resume, load the existing checkpoint and skip done tasks.

Success criteria: a valid plan, a clean git baseline on a confirmed branch, budget + checkpoint set.

Phase 1: One approval gate

Present the full plan (tasks, layers, what each touches). Wait for an UNAMBIGUOUS affirmative ("approve", "go", "yes"); treat hedges ("looks reasonable", "I guess") as NOT approved. This is the single human gate. If the plan was just generated, commit it as one preparatory commit so it doesn't bleed into task 1.

Success criteria: explicit approval recorded; planning artifacts committed separately.

Phase 2: Walk the DAG — layer by layer

For each layer in topological order (barrier between layers), build its tasks — in parallel across worktrees, capped by fan-out-work. When the plan assigned a task a specialist (agent/skill/ reviewer — auto-plan matched it to an INSTALLED agent/skill by description), spawn the engineer and reviewer as those specialists and have the engineer invoke the domain skill first; a missing name degrades to a general engineer and is recorded, never a hard failure. Per task, run the build contract (references/build-contract.md):

1. Gate on deps — all dependsOn integrated? else dep_blocked (point at the root), skip.
2. Implement (isolated) — a fresh worktree + task branch; RED (a failing test for the behavior) → GREEN (minimal code) → REFACTOR; stay inside the task's write scope.
3. Integrate — a serialized merge of the task branch onto the working branch, removing the merged worktree. Integration is merge-only; it does not run the whole-workspace validate.
4. Review — adversarial-verify the integrated slice against ITS acceptance criteria (slice-scoped: an unmet whole-codebase invariant a LATER task owns is an observation, not a block on this slice). Skippable only if the user disabled per-task review.
5. Fix loop — converge-loop (bounded, MAX_FIX≈3) on findings inside the task's write scope until the slice's validate is green; else mark blocked with the reason (don't spin).
6. Commit + checkpoint — one commit for the task's files + its status; mark the unit done.

Update the checkpoint as each task reaches its terminal state.

Success criteria: every task in the layer is done, blocked, or dep_blocked — each integrated task test-passing and individually committed; the barrier holds before the next layer.

Phase 3: Stop-and-ask triggers (throughout)

Halt the autonomous pass and ask the user — do not push through — when:

• a task's test/build won't go green without an obvious fix (surface the failure + diagnosis);
• the spec is ambiguous or a task needs a decision the spec doesn't cover;
• a task is high-risk/irreversible (see rule 6) — get explicit sign-off before continuing.

After the user resolves it, re-invoke to resume from the next pending task.

Success criteria: risky/ambiguous/unfixable situations reach the user, not a guessed-through commit.

Phase 4: Final validate + report

Once the DAG is walked, run the whole-workspace validate ONCE on the integrated tree — the load-bearing end-state gate (slices can each pass yet break the merged tree). Then report per Output Contract: tasks done/blocked/dep_blocked, tests added, commits, the final validate result, and anything escalated. Fail closed: a red final validate is never reported as a clean build.

Success criteria: the integrated tree's validate result is known and reported honestly; the checkpoint reflects the final state.

Common Rationalizations

Red Flags

• A task marked done with a red slice validate, or with a test skipped/weakened to pass.
• git add -A / commits mixing multiple tasks' files.
• A task built while a dependsOn is still pending/blocked.
• An irreversible action taken inside the pass with no stop-and-ask.
• Two agents writing the working tree without worktree isolation.
• A resume that rebuilt already-integrated tasks (checkpoint ignored/overwritten).
• A red final workspace validate reported as a clean build.

Enforcement (deterministic, not prose)

While this skill is active, a skill-scoped PreToolUse hook runs scripts/guard-git-hygiene.sh on every Bash call: bulk staging (git add/stage -A/./--all and whole-repo pathspecs like :/), commit -a/--all, plain git push --force (non-lease), reset --hard, and clean -f are BLOCKED at the tool layer (token-parsed — --amend and commit-message contents never false-positive). The clean-rollback contract is enforced by machinery, not by asking nicely. Rules 2–3 above are therefore not aspirational.

Guardrails

• One human gate (plan approval); everything irreversible/ambiguous/unfixable still escalates.
• Clean baseline required; one commit per task; stage only that task's files.
• Follow the DAG; never build on un-integrated dependencies; never ship/mark-done on a red validate.
• Test-driven every task; never weaken/skip tests to go green.
• Isolate parallel writers; serialize integration; prune merged worktrees.
• Durable resume: skip done, never overwrite the checkpoint.
• Fail closed on the final validate.

When To Load References

• references/build-contract.md — the per-task contract: worktree/branch, RED→GREEN→REFACTOR, integrate (merge + worktree removal), slice-scoped review, the bounded fix loop, and the task-exit gate.
• converge-loop (skill) — the bounded per-task fix loop.
• adversarial-verify (skill) — the per-task slice review.
• fan-out-work (skill) — parallel, capped, isolated per-layer task execution.
• checkpoint-resume (skill) — durable per-task state + skip-done resume.
• budget-guard (skill) — the run-level caps and escalation contract.

Output Contract

Report:

1. plan built + working branch; the single approval recorded
2. per task: done / blocked / dep_blocked (with reasons), tests added, the commit
3. the final whole-workspace validate result (green/red — honest)
4. anything escalated to the user (unfixable / ambiguous / irreversible)
5. checkpoint file path (durable, resumable record)