build-loop

name	build-loop
description	Drives task-by-task execution from an approved plan with quality gates between each task. Reads the plan, finds the next incomplete task, dispatches implementation, validates, updates progress, and continues. Use after a plan is approved and the user says "go", "start building", "execute the plan", or "implement the feature".
version	1.2.0
modes	["build","architect"]

Build Loop

Execute the plan, task by task, with quality gates between each one. This is the main execution engine for BUILD and ARCHITECT modes.

Core Principle: Autonomous but supervised. The agent works through tasks independently, but pauses at checkpoints and escalates when stuck. A beginner should be able to say "go" and watch tasks get completed, knowing they'll be asked before anything surprising happens.

When to Use

After a plan is approved. The user says "go", "start building", "implement", or approves the plan at the checkpoint.

Process

Step 1: Read the Plan

Load .sage/work/<active-feature>/plan.md. Parse:

• Total task count
• Which tasks are already done (checked boxes - [x])
• Which tasks are blocked (dependencies not met)
• Which task is next (first unchecked, unblocked task)

If ALL tasks are done → skip to Final Review. If NO plan exists → error: "No approved plan found. Run the plan skill first."

Step 2: Show Status and Start

Sage: Plan: [feature name] Tasks: [total] tasks in plan. Next: Task [N] — [task name].

Starting Task [N]. I'll commit after each task and check quality. Say "pause" anytime to stop between tasks.

Step 3: Execute Task

For the current task:

0. Load coding principles — read sage/core/capabilities/execution/coding-principles/SKILL.md. Apply the 7 universal principles to every line written during this task. Announce: "Loading coding principles for implementation."
1. Read the task spec from the plan (files, action, test, verify)
2. Implement using TDD (tdd skill):
   • Write failing test
   • Verify it fails for the right reason (on resume, a test the prior session already recorded as written-and-failing is not re-watched — tdd § "Inherited red")
   • Write minimal code to pass
   • Verify it passes
   • Refactor if needed
3. Self-review using the implement skill's checklist
4. Commit with semantic message — on the initiative branch (git-discipline: created at the workflow's Branch Setup step; commits never land on the default branch unless the user declined branching there)

The scope-guard skill monitors throughout — flags if implementation drifts beyond the task spec.

Step 4: Run Quality Gates

The deterministic script gates run after EVERY task. This is NOT optional. Do not skip them because:

• "The change was small"
• "I already verified during implementation"
• "The tests pass, so gates aren't needed"
• "This is just a refactor" Script gates run. Every task. No exceptions.

After each task, run the quality gate sub-workflow:

Gate 1: spec-review → Does implementation match the task spec? Gate 2: constitution → Does it violate any project principles? Gate 3: quality-review → Clean code, security, maintainability? Gate 4: hallucination → All imports, APIs, versions real and correct? Gate 5: verification → Tests pass? Feature works as expected?

The judgment gates (1–3) reach their independent verdict via one combined reviewer by default (gate_review); the script gates (1-script, 4, 5) run --quiet. See sage/core/workflows/sub-workflows/quality-gates.workflow.md.

On a RESUMED cycle's close-out (this session started from manifest.py resume), follow the resume close-out economy (sage/core/workflows/_shared/cycle-protocol.md § "Resume close-out economy"): run the deterministic script gates per remaining task for fast failure, but defer the adversarial sub-agent review to ONE combined review over the whole cycle diff at close-out — the first session already reviewed everything it built; re-running per-task adversarial dispatches over a small delta is the cost the profile targeted. On a first-session build, run the full per-task sequence below.

If gates pass: Move to next task. Plan checkboxes updated in bulk at the completion checkpoint (Rule 7).

If a gate fails:

• Minor issue (1 gate, fixable): Fix it, re-run that gate, continue.

• Major issue (multiple gates, design problem): Stop and report. When changing approach, log it in the initiative's scratch notes:

  Append to .sage/work/[initiative]/scratch.md:

  approach-[N]: [what was tried] — [why it failed]
  

  If scratch.md has 3+ approaches for the same task, this is a gotcha trigger — the sage-self-learning skill MUST store the finding with WHEN/CHECK/BECAUSE format before continuing.

Sage: Task [N] failed quality gates: Gate 3: Security — SQL injection risk in [file] Gate 5: Verification — test_user_create fails

[1] Fix and continue [2] Discuss the approach

• Repeated failure (3x on same gate): Escalate to human:

Sage: Task [N] has failed Gate [X] three times. The task spec may be ambiguous or contradictory.

Issue: [specific problem]

[1] Revise the task spec and retry [2] Skip this task and continue with others [3] Pause and discuss the approach

Step 5: Inter-Task Checkpoint

After every task (or every 3 tasks for long plans), show brief progress:

Sage: Task [N] complete. Continuing to Task [N+1] — [name]. Say "pause" to stop.

Batch the bookkeeping (batch_bookkeeping, default true): defer memory writes and non-essential prose to the completion/session-break checkpoint rather than emitting them per task — and when that checkpoint arrives, apply ALL of it with one command, not incremental edits:

python3 sage/runtime/tools/manifest.py close-out <manifest.md> \
  --summary "..." --next-step "..." --decision "..." --complete-task N

gate_state and updated: are mechanical (the sync hook and every advance/sync/close-out write own them — never hand-edit either). Keep the one-line progress note above; everything else waits for the close-out command. The manifest bridge at an [N]/context-budget break is NOT bookkeeping and is never deferred (cycle-protocol.md § Session-break contract) — write it with the same one command.

On a resume close-out, two more of the economy's levers apply here (see cycle-protocol.md § Resume close-out economy): with resume_memory: skip (default) the memory store/search is skipped — the brief already carries the context and L2 measured its value at this horizon as null; and with resume_test_cadence: lean (default) each step's GREEN runs the targeted test, with the full suite run once at close-out (Gate 5) rather than per task.

For tasks marked [P] (parallelizable), note: "Tasks [N] and [M] are marked parallel-safe. Running sequentially — concurrent dispatch happens ONLY through --subagents --parallel lanes (subagent-execution sub-workflow), never ad-hoc from the inline loop: lanes bring the scheduler, worktrees, caps, and single-writer bookkeeping that ad-hoc concurrency lacks."

Step 6: Final Review

After all tasks complete:

1. Run full quality gates on the COMPLETE implementation (integration check)
2. Verify all tests pass together (not just individually)
3. Check for any TODO/FIXME markers that shouldn't be there

Present the result:

Sage: Implementation complete.

Feature: [name] Tests: [count] passing Commits: [count] Quality: All 5 gates passed on final review.

[A] Approve — accept the work; branch stays unmerged [M] Merge to [default] — user-gated merge per git-discipline [R] Revise — needs changes [P] PR — create a pull request

🔒 MANDATORY CHECKPOINT: Wait for human decision.

[M] is the ONLY merge path — [A] never merges. Omit [M] when not a git repository or no initiative branch exists.

Step 7: Wrap Up

Based on human's choice:

• Merge ([M] only): apply the merge protocol from sage/core/capabilities/execution/git-discipline/SKILL.md — preconditions, the merge itself, conflict handling, and the deletion offer all live there; do not restate them here. Omit [M] when not a git repository or no initiative branch exists.
• PR: Create a pull request with the spec as description
• Keep working: Note what needs to change, update plan
• Discard: Revert and clean up

Update the initiative's decisions.md (.sage/work/[initiative]/decisions.md) if significant — cross-initiative decisions go to the global .sage/decisions.md:

# Progress

Mode: idle
Feature: [YYYYMMDD-slug] (completed)
Phase: done
Next: "Tell me what to build next"
Updated: <timestamp>

Fallbacks

Situation	Action
Implementation fails to compile	Run systematic-debug, fix, retry
Test can't be written (untestable design)	Flag to human, suggest interface simplification
Task is larger than expected	Report: "Task [N] is bigger than planned. Split into [A] and [B]?"
Discovered bug in existing code	Report: "Found unrelated bug in [X]. Note for later or fix now?"
Context window getting full	Commit current work, save state, suggest new session
All tasks done but integration broken	Create an "integration fix" task, add to plan, execute

Rules

MUST (violation = lost work or broken trust):

• MUST NOT skip quality gates. They are mandatory, not suggestions. Consolidating the adversarial review into one combined dispatch on resume close-out is not skipping — the deterministic script gates still run every task and the whole-change independent review still happens; what stops is re-reviewing, from scratch, work a prior session already reviewed.
• MUST NOT implement multiple tasks without committing between them.
• MUST NOT continue past a mandatory checkpoint without human approval.
• MUST update plan checkboxes in bulk at the completion checkpoint (Rule 7).
• MUST commit current work immediately if the user says "pause" or "stop."

SHOULD (violation = suboptimal experience):

• SHOULD show progress between tasks — the user should never wonder what's happening.
• SHOULD proactively save and suggest a new session if context is getting full.
• SHOULD present brief inter-task status every 1-3 tasks, not after every line of code.

MAY (context-dependent):

• MAY skip the final review (step 6) if the plan had only 1-2 tasks, since per-task review already covered everything.
• MUST NOT run tasks concurrently from this loop — [P] is honored only by the --parallel lane machinery (opt-in, code-scheduled).

Failure Modes

• Plan file is missing or corrupted: Ask the user if a plan exists. If a spec exists, offer to regenerate the plan from it. If neither exists, suggest starting with elicitation.
• Context window fills before all tasks complete: Commit current work, write a session bridge note, save the plan with current progress, and suggest a new session. Never lose work to context limits.
• Task produces unexpected scope: If a task turns out to be much larger than planned, STOP. Report to the user: "Task N is bigger than expected. Split into subtasks?" Don't silently expand scope.
• Gate fails repeatedly on the same task: After 2 failed attempts, stop and report: "Gate [X] keeps failing on task [N]. The issue is [description]. Should I try a different approach or skip this gate with your approval?"
• User goes silent mid-loop: After completing a task that requires approval, wait. Don't proceed to the next task. The checkpoint exists for human verification.