feature-build-loop

name: feature-build-loop description: Use when modifying build loop code, debugging stats/token tracking, adding CLI features, changing iteration prompts, or understanding how spectre-build works end-to-end user-invocable: false

Build Loop (spectre-build)

Trigger: build loop, spectre-build, build iteration, validation cycle, promise tags, build stats, code review, phase awareness Confidence: high Created: 2026-02-07 Updated: 2026-02-18 Version: 3

What is Build Loop?

spectre-build is an automated task execution CLI that runs Claude Code (or Codex) in a loop, completing one parent task per iteration. The CLI handles the loop; the agent handles task tracking and progress writing. It supports recursive validation cycles that catch gaps and auto-remediate, multi-agent backends, manifest-driven configs, and a pipeline abstraction for multi-stage workflows.

Why Use It?

User Flows

Flow 1: Flag-Based Build with Code Review + Validation (Default Pipeline)

spectre-build --tasks docs/tasks.md --context docs/scope.md --validate --max-iterations 15

When --validate is used without --pipeline, the CLI routes through run_default_pipeline() which creates a 3-stage pipeline:

1. Build — Completes tasks, emits TASK_COMPLETE / PHASE_COMPLETE / BUILD_COMPLETE
2. Code Review — Reviews git diff from build, emits APPROVED / CHANGES_REQUESTED
3. Validate — Checks D!=C!=R for completed work, emits ALL_VALIDATED / VALIDATED / GAPS_FOUND

Stage lifecycle hooks (hooks.py) snapshot HEAD before build, then inject changed_files and commit_messages into context for the code review prompt.

Flow 2: Build Without Validation (Legacy Mode)

spectre-build --tasks docs/tasks.md --context docs/scope.md

Without --validate, uses run_build_validate_cycle() with validate=False — simple build loop only, no pipeline.

Flow 3: Explicit Pipeline YAML

spectre-build --pipeline .spectre/pipelines/full-feature.yaml --tasks docs/tasks.md

Uses run_pipeline() to load and execute a custom YAML pipeline definition.

Flow 4: Manifest-Driven Build

spectre-build build.md

YAML frontmatter in .md file. If validate: true, routes to default pipeline.

Flow 5: Resume Interrupted Session

spectre-build resume      # prompts for confirmation
spectre-build resume -y   # skip confirmation

Technical Design

Execution Routing (cli.py:main())

parse_args()
├─ --pipeline → run_pipeline() (load YAML, execute)
├─ --validate (no --pipeline) → run_default_pipeline() (3-stage build/review/validate)
└─ no --validate, no --pipeline → run_build_validate_cycle(validate=False) (legacy build-only)

Same routing logic applies in run_resume() and run_manifest().

Default Pipeline Flow

run_default_pipeline()
├─ create_default_pipeline() → PipelineConfig with 3 stages
├─ Build context dict (tasks_file_path, progress_file_path, etc.)
├─ Wire on_event callback for stats loop counting
├─ PipelineExecutor(config, runner, on_event, context, before_stage, after_stage)
└─ executor.run(stats)
    ├─ For each stage transition:
    │   ├─ before_stage_hook(stage_name, context)
    │   │   └─ For "build": snapshot HEAD into context["_phase_start_commit"]
    │   ├─ stage.run(context, stats)
    │   ├─ after_stage_hook(stage_name, context, result)
    │   │   ├─ For "build": collect git diff, inject changed_files/commit_messages/review_fixes_path
    │   │   └─ For "validate": track validated phases in context["_validated_phases"]
    │   ├─ context.update(result.artifacts) — propagates phase metadata from build
    │   └─ Transition based on signal → transitions map
    └─ End when signal in end_signals (ALL_VALIDATED)

Promise-Based Flow Control (Build Stage)

The agent signals completion via tags in its output text:

• [[PROMISE:TASK_COMPLETE]] → task done, loop back to build
• [[PROMISE:PHASE_COMPLETE]] → phase done, transition to code_review
• [[PROMISE:BUILD_COMPLETE]] → all tasks done, transition to code_review

Phase rules: If the tasks file has no ## Phase N: headers, never emit PHASE_COMPLETE.

Phase-Scoped Context Flow

When the build agent emits PHASE_COMPLETE or BUILD_COMPLETE, it also outputs a JSON block with phase metadata:

{"phase_completed": "Phase 1: ...", "completed_phase_tasks": "- [x] ...", "remaining_phases": "Phase 2: ..."}

PromiseCompletion(extract_artifacts=True) extracts this JSON into result.artifacts. The executor's context.update(result.artifacts) propagates these values to downstream stages. Code review and validate prompts use {phase_completed}, {completed_phase_tasks}, {remaining_phases}, and {validated_phases} to scope their work to the current phase.

Validated phases are tracked via after_stage_hook("validate") which appends completed phase names to context["_validated_phases"].

Code Review Stage

Prompt receives {changed_files} and {commit_messages} injected by after_stage_hook.

• Reads all changed files, reviews for correctness/security/quality
• Severity scale: CRITICAL/HIGH/MEDIUM/LOW
• Approval threshold: APPROVED if zero CRITICAL and zero HIGH
• If CHANGES_REQUESTED: writes remediation tasks to {review_fixes_path}, loops back to build
• Build prompt checks for {review_fixes_path} existence and addresses fixes first

Validate Stage Signals

• ALL_VALIDATED → all parent tasks [x] and verified → pipeline ends
• VALIDATED → current work verified, but unchecked tasks remain → loop back to build
• GAPS_FOUND → gaps in completed work → after_stage_hook sets context["remediation_tasks_path"] to the gaps file path, loops back to build

GAPS_FOUND → Remediation Flow

When validate returns GAPS_FOUND with a gaps_file artifact:

1. after_stage_hook("validate") injects remediation_tasks_path into context
2. Build prompt tells agent to read the remediation file and work on those tasks instead of the original tasks file
3. Agent completes remediation tasks, emits BUILD_COMPLETE
4. Pipeline cycles back through code_review → validate
5. If validate passes (VALIDATED/ALL_VALIDATED), remediation_tasks_path is cleared

Executor Hooks

PipelineExecutor accepts optional before_stage and after_stage callbacks:

before_stage: Callable[[str, dict[str, Any]], None] | None
after_stage: Callable[[str, dict[str, Any], CompletionResult], None] | None

Called in run() immediately before/after stage.run(). Errors caught and logged (don't crash pipeline).

Stats Pipeline

• BuildStats has build_loops, review_loops, validate_loops fields
• Incremented via on_event callback listening for StageCompletedEvent
• Dashboard shows LOOPS B:3 R:2 V:1 line between COMMITS and TOKENS
• Token/cost tracking from result events, model-specific pricing in _MODEL_PRICING
• Stats persistence: to_dict()/from_dict()/merge() methods on BuildStats
• Stats saved to .spectre/build-stats.json at each stage boundary via save_stats()
• On resume, previous stats loaded via load_stats() and merged into fresh stats
• Stats file cleared on successful pipeline completion via clear_stats()
• [🪳 TEMP STATS] debug logging in stream.py and stats.py for token count diagnosis

Tool Filtering

Allowed: Bash, Read, Write, Edit, Glob, Grep, LS, TodoRead, TodoWrite, Skill, Task Denied: AskUserQuestion, WebFetch, WebSearch, EnterPlanMode, NotebookEdit

Validation Principle

"Definition != Connection != Reachability"

Three levels: Defined → Connected → Reachable

Key Files

Common Tasks

Add a New Pipeline Stage

1. Create prompt template in prompts/ directory
2. Add stage config to create_default_pipeline() in loader.py
3. Define completion strategy and transitions
4. If the stage needs inter-stage context, add logic to hooks.py
5. Update YAML files in .spectre/pipelines/

Change Review/Validate Behavior

• Review criteria: edit prompts/code_review.md
• Validation criteria: edit prompts/validate.md
• Git scope injection: edit hooks.py (after_stage_hook)
• Signal routing: edit transitions in loader.py:create_default_pipeline()

Add a New Stat to the Dashboard

1. Add field to BuildStats dataclass in stats.py
2. Capture it in stream.py:process_stream_event() or via on_event callback
3. Format and display in stats.py:print_summary()

Change the Build Prompt

Edit build-loop/src/build_loop/prompts/build.md. Variables available:

• {tasks_file_path} — absolute path to tasks file
• {progress_file_path} — absolute path to progress file
• {additional_context_paths_or_none} — formatted context paths or "None"
• {review_fixes_path} — path to review remediation file (if exists)

Gotchas

• Stats from assistant events are unreliable: Only result events have authoritative totals.
• Promise overrides exit code: Non-zero exit with valid promise is NOT a failure.
• owns_stats flag: When run_build_loop() receives external stats, it does NOT print summary.
• Template variables must match exactly: Typos silently break the prompt.
• Code review needs git commits: If no commits between build start and end, review sees "No files changed."
• Phase headers are optional: If tasks file has no ## Phase N: headers, PHASE_COMPLETE is never emitted.
• Legacy path still exists: run_build_validate_cycle() is used for non-validate builds. Don't break it.
• Hooks are error-safe: before/after stage hooks catch exceptions and log warnings, never crash the pipeline.
• Model pricing is hardcoded in stats.py: Updated 2026-02-18 for Opus 4.5+/Sonnet 4.5+/Haiku 4.5 pricing. Will need updating when Anthropic changes prices.
• Subagent tokens are invisible: Task tool dispatches (e.g., clean_investigate, test_execute) create nested Claude sessions whose tokens don't flow through the parent stream parser. Stats undercount when subagents are active.
• Stats persist across resume: Stats saved to .spectre/build-stats.json at stage boundaries. Merged on resume. Cleared on successful completion.