build-loop

Files (56)

• SKILL.md
• detect-plugins.mjs
• eval-guide.md
• fallbacks.md
• fact-check.md · phases/
• ui-validation.md · phases/
• advisor-dispatch-ladder.md · references/
• apple-native-planning.md · references/
• autonomous-and-per-commit-modes.md · references/
• autonomy-dashboard.md · references/
• capability-routing.md · references/
• codex-subagents.md · references/
• coordination.md · references/
• correction-aware-capture.md · references/
• experiment-results-template.md · references/
• independent-auditor.md · references/
• intent-capability-pack.md · references/
• intent-exploration-prompts.md · references/
• leadership.md · references/
• memory.md · references/
• modular-systems-pack.md · references/
• output-style.md · references/
• pay-it-forward-arch.md · references/
• phase-1-assess.md · references/
• phase-2-plan.md · references/
• phase-3-execute.md · references/
• phase-4-review.md · references/
• phase-5-iterate.md · references/
• phase-6-learn.md · references/
• privileged-request-broker.md · references/
• recent-design-structures.md · references/
• ASSESSMENT.md · references/refactor-history/
• STANDALONE_TEST_RUN.md · references/refactor-history/
• 01-simple-bugfix.md · references/refactor-history/scenarios/
• 02-ui-build-with-iteration.md · references/refactor-history/scenarios/
• 03-multi-failure-escalation.md · references/refactor-history/scenarios/
• 04-ui-build-ibr-absent.md · references/refactor-history/scenarios/
• 05-refactor-navgator-absent.md · references/refactor-history/scenarios/
• 06-recurring-bug-debugger-absent.md · references/refactor-history/scenarios/
• trace-comparison.md · references/refactor-history/
• research-architecture-pilot.md · references/
• resource-aware-execution.md · references/
• self-recursive-dev.md · references/
• self-review.md · references/
• share-presentation.md · references/
• status-output-format.md · references/
• system-access-once.md · references/
• targeted-acceptance.md · references/
• ui-io-contract.md · references/
• verify-dispatch.md · references/
• audit-design-rules.mjs · scanners/
• require-visual-evidence.mjs · scanners/
• backlog-item.md · templates/
• codex-worker-prompt.md · templates/
• ui-subagent-prompt.md · templates/
• ux-fix-plan.md · templates/

SKILL.md (first lines)

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
<!-- build-loop@tyroneross:canary:build-loop -->
<!-- canary-end -->

# Build Loop — Orchestrated Development

A 5-phase development loop with a mandatory Phase 6: assess state and criteria, plan, execute, review (critic/validate/fact-check/report as sub-steps), iterate on review failures. Phase 6 Learn (mandatory; always runs) detects cross-build recurring patterns and drafts experimental skills; below 3 runs it accrues; debug-only and budget-exhausted runs defer the expensive arm.

## Routing

**`/build-loop:run` is the ONLY human-facing command.** Type it with any request in plain language — or just describe what you need — and the orchestrator classifies intent and routes to the right internal mode. No flags, no picking a mode, no other commands to learn. Everything below is reached by intent, not by a separate command; agents/build-loop invoke these internally.

Intent → internal mode:

- **Build** (default): full 5-phase loop + mandatory Phase 6 Learn — implementation / fix / refactor / migrate / update / "add" / "wire up" language.
- **Debug**: deep iterative root-cause investigation — symptom language ("broken", "doesn't work", "failing"); also auto-invoked on Review-B failures.
- **Optimize**: metric-driven optimization loop — "speed up", "reduce", "improve" + a mechanical metric.
- **Research**: pre-decision analysis and a research packet — "research", "evaluate", "compare", "should I". Research-only requests end with a recommendation. An explicit request to research then implement continues through the authorized build.
- **Test**: static plugin-test suite — "test plugin", "validate plugin".
- **Root-cause analysis**: blameless RCA producing durable system levers — "root cause", "why did this fail", "post-mortem" (delegates to the `root-cause-analysis` skill).
- **Retrospective**: recursive learning retrospective on a build/project — "retrospective", "retro", "what did we learn", "review this project's trajectory" (delegates to `recursive-retrospective`). *Example: "I need a root cause and a retrospective" → run does both.*
- **Plan / spec**: "write a plan", "spec this" → spec-writing + plan-verify.
- **Repository maintenance / closeout**: repository structure, duplicate source, sibling consolidation, build artifacts, branches, worktrees, stashes, or local-main closeout → `repo-maintenance` (`repo-closeout` remains a temporary compatibility alias).
- **PRD**: "start a PRD", "spec out a new app" → prd-bridge / start-prd flow.
- **Self-improve / promote / knowledge / handoff / memory setup**: "scan recent runs", "promote this experiment", "record a decision", "hand this off", "set up memory" → the matching internal skill (self-improve, promotion-reviewer, knowledge, handoff, setup-memory).
- **Drain proposals**: "drain proposals", "review the proposal backlog", "what proposals are open" → the `drain-proposals` skill. Interactive and never auto-applies; every item needs an explicit apply / reject / defer.
- **Daydream / mine coding patterns**: "daydream", "find reusable patterns", "learn from coding sessions", or "mine transcripts for improvements" → `daydream`. Scan explicit local evidence, separate corrections from added scope and verified success, segment by recorded model/effort/harness, draft improvements, and export observational evidence to Benchmark Lab when requested. Preserve coverage gaps and the existing experiment/promotion lifecycle.

**Design intent:** one command for humans, plain-language routing, everything else agent-invoked within build-loop. If a request doesn't match a mode, run treats it as a Build task or asks one clarifying question — it never makes the user pick a command.

**Preserve the requested outcome.** This section is the canonical routing table
for both host entrypoints and the orchestrator. Classify the operation and its
object before matching an isolated word: comparing worktrees belongs to
repository maintenance; comparing external SDKs may need research. A combined
request retains both steps. Research is an assist to an already authorized build
or maintenance task, and returns control to that owner when the evidence is ready.
"Research how to build X" alone does not authorize building X. Read-only and
explicit negative instructions take precedence.

For a build or maintenance research check, run `scripts/research_trigger.py`
with `--context build` or `--context maintenance`; use `--context research` for
a research-only request. Its `continuation` field is advisory and never grants
authority. The user request and accepted plan determine what executes. Local
code comparison does not require external research merely because it says
"compare" or "latest main". Explicit research and concrete external/risk signals
still receive evidence checks. Do not start a background reconciler from these
requests.

### Parallelism config

Fan-out width is supervisor-controlled. `autonomy_supervisor.py fanout` previews capacity and live backpressure. Before concurrent dispatch, use `reserve-fanout` per `skills/build-loop/references/codex-subagents.md`; a preview alone reserves nothing. Effective width is the minimum of independent MECE work, project/request capacity, CPU headroom, cloud token budget, shared cross-session capacity, and the absolute ceiling of 150. Default project capacity remains 8.

To set a project preference, use `.build-loop/config.json`:

```json
{ "parallelism": { "maxImplementers": 8 } }
```

The preference never forces that many workers. The supervisor admits only independent chunks supported by live resource and provider telemetry. Values above 150 are clamped; local capacity also preserves two CPU cores for the orchestrator and host OS.

## Autonomous Mode + Per-Commit Mode

Both are conditional modes — their flag tables, budget/iteration caps, question-timeout rules, self-recursive detection, and the per-commit dispatch contract (incl. the GAP-1 parent-dispatch audit + E3 Learn/retro contract) load on demand from `references/autonomous-and-per-commit-modes.md`. Read it when:

- the invocation carries `--long` / `--budget` / `--autonomous=false` / `--no-regrets`, or the goal text matches a long-running keyword (`overnight`, `large-scale`, `multi-day`, …) → **Autonomous Mode** detail;
- `state.json.selfRecursive.enabled` is true, or the invocation carries `--per-commit` / `--no-per-commit` → **Per-Commit Mode** detail.

Default behavior: complete Phase 1–6 and required fixes autonomously within a 2h budget. Additional eligible queue/backlog pickup is on unless no-regrets is explicitly disabled; see `references/keep-going-policy.md`.

## Scope Check

Before starting the loop, assess whether the task warrants it. If the task is a single file edit, a config change, or a fix under ~20 lines — skip the loop and just do it. The loop is for multi-step work where planning and validation add value. `/build-loop:run` applies this same check before it loads this skill, so a skipped task never pays for this file; the check here covers direct skill loads.

## RossLabs LSP at component boundaries

Before changing cross-file symbols, use RossLabs LSP definitions/references rather
than assume text matches are semantic references. Before changing an interaction
between languages, terminals/PTYs, protocols, schemas, tools or runtime versions,
query `rosslabs-lsp compat <registry.json>` using the applicable registry from
workspace context. Inspect version/snapshot limits; empty coverage is unknown.
Run diagnostics and targeted behavioral tests after edits. Record new compatibility
evidence and link local Build Loop memory during Learn. The required Learn checker
executes RossLabs LSP for `updated` and `no-change` reviews and blocks on unavailable
or rejected validation. See `references/phase-6-learn.md` for the packet contract.
In Easy Terminal, `et tools --json` exposes the shared native tool index.

## Fast repository search

Scan content with code before broad file reads. Start with
`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/repo_search.py query --workdir "$PWD"
--query "<terms>" --kind content --json`; this searches live files with `rg`
and reads only selected matches. Narrow to `--kind change|run|decision|structure`
when the question calls for history or architecture. Metadata queries maintain
the rebuildable `.build-loop/search/index.json`; the canonical Git, run,
decision, and architecture sources stay authoritative. An LLM interprets
selected evidence rather than scanning every file. See
`references/repo-search.md` for freshness, coverage, and optional annotation
rules.

Phase 1 automatically retrieves relevant decisions from canonical memory and
the project's private `.build-loop/plans/DECISION-LOG.md`, including when Git
ignores the local log. Phase 2 records which prior decision applies, was
superseded, or could not be verified. Phase 6 appends substantive new decisions
with evidence through `scripts/decision_log.py`; do not edit old entries away.

## Keep going until done

Once the user accepts the plan, every phase is authorized scope. The orchestrator does not stop and ask the user between phases. Status updates are fine. Permission requests are not.

Completed, validated, authorized work commits automatically. Asking "should I commit?" or "want me to commit this?" is a workflow violation — committing validated work is a non-gated action (`scripts/autonomy_gate.py` classifies a plain `git commit` as `auto`, exit 0). This applies in both interactive and autonomous mode. The only commit-adjacent stops are autonomy-gate verdicts of `confirm` or `block` on a *push or deploy* command — never on the commit itself.

When build-loop manages a commit or push, official authorship stays human or service-owned. Do not set the git author, committer, GitHub author, push actor, release actor, or equivalent platform actor to `Claude Code`, `Codex`, or any other agent identity. Agent involvement can be recorded in commit-body notes, `.build-loop` run context, judge decisions, or other auxiliary metadata, but those records must not replace the official author or actor fields.

Issues found mid-build (failing tests, attestation drift, critic flags, discoverability gaps) route to Iterate. That is the loop's job. The default is to fix and continue.

The only valid reasons to stop and surface to the user:

- **An action whose autonomy verdict is `confirm` or `block`** (per `python3 scripts/autonomy_gate.py`). The gate is the single source of truth for what counts as "destructive or irreversible action not in the accepted plan." Do not introduce ad-hoc asks outside the gate.
- A destructive or irreversible action that was not in the accepted plan.

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop