build-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- sage-metadata
cost-tier: sonnet
activation: auto
tags: [execution, orchestration, build, loop]
inputs: [plan, codebase-context, constitution]
outputs: [implementation, test-suite, updated-plan]
requires: [implement, tdd, coding-principles, quality-review, spec-review, verify-completion, scope-guard]
-->

# 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.

From xoai/sage, MIT.

More from xoai/sage