@tyroneross/build-loop 0.35.0 → 0.36.0

package/README.md

@@ -2,403 +2,312 @@
 <!-- canary-end -->
 # build-loop
 
-A plugin for Claude Code that turns big code changes into a checked, repeatable workflow.
+A portable, multi-phase build loop for AI coding agents. It gives Claude Code, Codex, and any AGENTS.md-aware tool the same disciplined operating loop: assess, plan, execute, review, iterate, then learn.
 
-## What it is
+> **Summary:** build-loop helps AI coding agents and the developers who run them ship multi-step code changes by running every change through a planned, reviewed, verified loop. Best for non-trivial features, refactors, migrations, and bug hunts across more than one file. Skip it for one-line edits, pure Q&A, or status checks.
 
-Build-loop runs your code change through five phases — plan, execute, review, iterate — plus a mandatory Learn step that runs after every build. It splits the work into safe parallel chunks where it can. A critic reads the diff before tests run, so cheap checks catch the obvious mistakes first. Tests must actually pass. Every number on the page traces back to a real source. Fake data in production paths gets flagged. The build stops if what you shipped does not match what you said you would build. The plugin picks the right model for each task: a strong model to plan and review, a faster model to write code, a small model for pattern checks.
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/badge/npm-%40tyroneross%2Fbuild--loop-cb3837.svg)](https://github.com/tyroneross/build-loop/pkgs/npm/build-loop)
+[![hosts](https://img.shields.io/badge/hosts-Claude_Code_%C2%B7_Codex_%C2%B7_AGENTS.md-5b21b6.svg)](#install)
 
-## Why use it
+## Why build-loop
 
-Big changes break things. You forget an edge case. You skip the test pass. The diff drifts from the plan. The implementer makes a quiet design call you never see. Build-loop catches all of that before the change ships.
+Hand an agent a multi-step task and it tends to dive straight into edits, with no plan, no scope boundary, and no independent check that the result matches the goal. The failures compound: wrong assumptions ride into code, fixes patch symptoms, and "it compiles" gets reported as "it works."
 
-- **One source of truth.** The plan lists every design decision up front. The implementer must say which decisions it made. A lint compares the claim to the actual diff. If the two do not match, the loop stops.
-- **Speed where you can, depth where you must.** Mechanical work runs in parallel on a fast model. Work with five or more design decisions auto-routes to the strong model in one pass. Five is the cutoff measured in our testing where the fast model lost cross-decision context.
-- **Real evidence, not vibes.** Every pass or fail has a code-based grader. Every metric on a page traces back to its data source. Tests must run. Output must render. Placeholders get flagged.
-- **Less rework.** A read-only critic runs before full validation. Cheap checks catch the obvious mistakes first.
-- **A way to actually improve a number.** Run multiple tests in a single experiment using Design of Experiments and other statistical methods. You can test six variables at once instead of one. The optimize mode plans the test matrix, runs each combination, and tells you which variable actually moved the number.
+build-loop replaces that with a **structured loop every change runs through**: it assesses live repo state and memory, plans with explicit file ownership and pass/fail criteria, executes within scope, then runs an adversarial review (a critic, a fact-checker, a mock-data scanner) before iterating to green. The differentiator is portability and verification: the **same loop runs across Claude Code, Codex, and host-neutral AGENTS.md tools**, it is **multi-model by tier** (a frontier model plans and judges, a coding model executes), and **no completion claim ships without a verification step behind it**.
 
-You ship fewer regressions. You get a clean record of what changed and why. You can trust the workflow on changes that touch many files at once.
-
-## Get started
-
-Install the plugin via the RossLabs AI Toolkit marketplace (recommended) or directly from the build-loop repo.
+## The loop
 
+```mermaid
+flowchart LR
+    A[Assess] --> P[Plan]
+    P --> E[Execute]
+    E --> R[Review]
+    R -->|fail| I[Iterate]
+    I --> R
+    R -->|pass| L[Learn]
+    subgraph Review
+        direction LR
+        R1[Critic] --> R2[Validate] --> R3[Optimize] --> R4[Fact-Check] --> R5[Simplify] --> R6[Auto-Resolve] --> R7[Report]
+    end
 ```
-# Recommended — via the RossLabs AI Toolkit marketplace (includes companion plugins):
-/plugin marketplace add tyroneross/RossLabs-AI-Toolkit
-/plugin install build-loop@rosslabs-ai-toolkit
 
-# Or direct — install from the build-loop source repo alone:
-/plugin marketplace add tyroneross/build-loop
-/plugin install build-loop@build-loop
-```
+Assess → Plan → Execute → Review → Iterate (5x max) → Learn (always emits an outcome). Review runs seven ordered sub-steps; Iterate loops back to Review on failure.
 
-Run a build.
+For the **living, auto-generated diagram** of how the loop actually wires up in this repo, covering every phase, gate, agent, skill, and script and regenerated from source so it cannot drift, open [`docs/build-loop-flow-mockup.html`](docs/build-loop-flow-mockup.html) in a browser. Format spec and drift gate: [`architecture/README.md`](architecture/README.md).
 
-```
-/build-loop:run add user notification system with email and push
-```
+## Quick start
 
-Skip the loop for small fixes (under about 20 lines, single file, no new endpoint). For everything else, run it through the loop. That includes features, refactors, migrations, schema changes, and anything that crosses a file or system boundary.
+Install for all three host surfaces on macOS:
 
-Debug a failing system.
-
-```
-/build-loop:debug tests pass locally but fail in CI
+```bash
+npm install -g @tyroneross/build-loop@0.36.0
+build-loop-install --host all
 ```
 
-Detail on each phase, the model tier rules, the synthesis-decision lint, the architecture engine, and the debugger is below.
-
-## Phases
+Then, in a Claude Code session inside your project, hand the loop a task:
 
-| # | Phase | Purpose |
-|---|-------|---------|
-| 1 | **Assess** | Understand state (project type, architecture, tools, prior state) AND define goal + 3-5 scoring criteria with pass/fail conditions |
-| 2 | **Plan** | Task breakdown with dependency order and parallel-safe groups |
-| 3 | **Execute** | Build it — parallel subagents for independent work |
-| 4 | **Review** | Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Report — six ordered sub-steps, single exit point; routes to Iterate on failure |
-| 5 | **Iterate** | Fix Review failures, loop back to Review (max 5x) |
-| 6 | **Learn** *(mandatory)* | Always runs and always emits a `## Learn` outcome line in the Review-G report. Three states: `accruing` (`runs[] < 3` — detector + memory consolidation only), `deferred` (debug-only or budget-exhausted — writes a marker, skips Sonnet draft), or `full` (`runs[] >= 3` + a pattern crossed threshold — detector + Sonnet draft + Opus signoff). Reads two signal sources: `state.json.runs[]` and `proposals/enforce-from-retro/` (recurring enforce-candidates across runs). |
-
-## Supply-chain: dependency cooldown
-
-Build-loop refuses to install third-party JS packages (or version bumps) until the resolved version has been published for at least **7 days**, mitigating smash-and-grab npm compromises (a malicious version published then yanked within hours-to-days never reaches your lifecycle scripts). Defense-in-depth, three layers:
-
-1. **Native config injection** (primary gate) — Phase 1 Assess runs `scripts/inject_dependency_cooldown.py`, idempotently writing the package manager's native publish-age key: npm ≥ 11.10.0 → `.npmrc` `min-release-age` (days); pnpm → `pnpm-workspace.yaml` `minimumReleaseAge` (minutes) + `.npmrc` `minimum-release-age` for pnpm 10.x; yarn ≥ 4.10 → `.yarnrc.yml` `npmMinimalAgeGate` (numeric minutes). npm has **no** native exclude ([npm/cli#8994](https://github.com/npm/cli/issues/8994)) so the user-authored allowlist is enforced by layer 2 on npm; pnpm/yarn carry it natively.
-2. **PreToolUse backstop hook** — for ungated projects, rewrites `npm`/`yarn add` with `--before=<7d ago>` and denies `npm ci`/`pnpm add` with an actionable message. On npm **with** native config it stays engaged for the allowlist: all-allowlisted installs get a command-scoped `--min-release-age=0`; third-party installs are left to the native gate (never `--before` — npm rejects it alongside native config).
-3. **Constitution + commit-auditor** — `C-SUPPLY/dependency_cooldown` rule; advisory flag on `<7d`-old deps in lockfile diffs.
-
-User-authored scopes are exempt via a config-driven allowlist (`.build-loop/config.json` → `dependencyCooldown.allowlist`, default `["@tyroneross/*"]`). See KNOWN-ISSUES for the older-toolchain fallback caveat. pip/cargo not covered in v1.
-
-## Installation
-
-### From GitHub (recommended)
+```text
+/build-loop:run add billing settings with tests
+```
 
-Via the RossLabs AI Toolkit marketplace (includes companion plugins such as bookmark, Coding Debugger, research, etc.):
+What you observe: the agent prints a short status line per phase (`[Phase 1: Assess]`, `[Phase 2: Plan]`, `[Phase 3: Execute]`, then each Review sub-step), then ends with a scorecard marking every acceptance criterion ✅ / ⚠️ / ❓. Completed, verified work is committed automatically; the only human-confirmation gates are production push, irreversible delete, and major user-impacting decisions.
 
-```
-/plugin marketplace add tyroneross/RossLabs-AI-Toolkit
-/plugin install build-loop@rosslabs-ai-toolkit
-```
+You do not pick a mode. `/build-loop:run` auto-routes build, fix, refactor, optimize, research, and test requests to the right path.
 
-Or direct from the build-loop source repo alone (build-loop only, no companions):
+## Install
 
-```
-/plugin marketplace add tyroneross/build-loop
-/plugin install build-loop@build-loop
-```
+`build-loop-install` runs the package's helpers from the installed npm package:
 
-build-loop does not register its own MCP server. Deep debugging is native to the build-loop skills; cross-project incident memory can be supplied separately by the standalone Coding Debugger plugin when installed.
+- Syncs the Claude Code cache from the package root.
+- Syncs the Codex cache from `plugin-artifacts/codex`, the slim Codex install artifact.
+- Bootstraps the build-loop memory root with public templates.
+- Leaves publishing, GitHub releases, and production deploys to explicit release commands.
 
-### Manual (local development)
+For GitHub Packages, authenticate first and point the `@tyroneross` scope at the GitHub registry:
 
 ```bash
-git clone https://github.com/tyroneross/build-loop.git
+npm config set @tyroneross:registry https://npm.pkg.github.com
+npm login --scope=@tyroneross --registry=https://npm.pkg.github.com
+npm install -g @tyroneross/build-loop@0.36.0
+build-loop-install --host all
 ```
 
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "build-loop": {
-      "source": {
-        "source": "directory",
-        "path": "/path/to/build-loop"
-      }
-    }
-  },
-  "enabledPlugins": {
-    "build-loop@build-loop": true
-  }
-}
-```
+Installer options:
 
-### Memory setup (one-time, per machine)
+| Option | Use |
+|---|---|
+| `--host claude` | Sync only the Claude Code cache. |
+| `--host codex` | Sync only the Codex cache. |
+| `--host all` | Sync both caches. This is the default. |
+| `--project <slug>` | Ensure `projects/<slug>/raw/` exists in build-loop memory. Repeatable. |
+| `--memory-dest <path>` | Override the memory root. |
+| `--skip-memory` | Sync plugin caches only. |
+| `--dry-run` | Show cache sync actions without writing. |
+| `--json` | Emit one machine-readable result. |
 
-Build-loop's advisory judges read from the canonical `build-loop-memory` store
-(at `<memory-root>` — the neutral `~/.build-loop-memory` on a fresh install;
-see `docs/memory-setup.md` for the full resolution order). Plugin writers also
-maintain a global update ledger at `<memory-root>/indexes/updates.jsonl` for
-audit and freshness. Bootstrap with templates:
+Local development install:
 
 ```bash
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py
-```
-
-This seeds `constitution.md` + `MEMORY.md`; `indexes/updates.jsonl` is created on first memory mutation. The build-loop public repo ships only the templates — your actual lessons, constitution rules, and patterns belong in a private repo because they reference specific projects and decisions. See [`docs/memory-setup.md`](docs/memory-setup.md) for the full guide including private repos, root overrides, and repo-local ignored stores.
-
-```bash
-# Status check anytime
-python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py --check
+git clone https://github.com/tyroneross/build-loop.git
+cd build-loop
+npm install
+npm run build
+python3 scripts/sync_plugin_cache.py --source . --host claude
+npm run codex:sync-cache
+python3 scripts/install_memory.py --ensure-project build-loop
 ```
 
-## Usage
+## Commands
 
-`/build-loop:run` is the one command for any coding task — build, fix, refactor, optimize, research, or test. The orchestrator reads your goal, classifies intent, and routes to the right mode. You don't choose the mode.
+`/build-loop:run` is the only command. Describe the task in plain language — build, fix, refactor, optimize, research, debug, test, root-cause, retrospective, or plan — and the orchestrator classifies intent and routes to the right internal mode. You never pick a mode or a flag.
 
-```
-/build-loop:run [goal description]
+```text
+/build-loop:run add billing settings with tests
+/build-loop:run tests pass locally but fail in CI        # routes to deep debugging
+/build-loop:run reduce API latency                       # routes to the optimize loop
+/build-loop:run compare queue providers                  # routes to research (no commits)
+/build-loop:run self-improve against recent runs         # runs Phase 6 Learn alone
 ```
 
-Examples:
+Debugging is also auto-invoked by the loop itself on a review failure. The former mode and utility commands (`debug`, `research-run`, `test`, `self-improve`, `debugger*`, `assess`) are now internal, reached by intent rather than as separate commands.
 
-```
-/build-loop:run add user notification system with email and push
-/build-loop:run refactor auth middleware to use JWT
-/build-loop:run migrate database from SQLite to PostgreSQL
-/build-loop:run tests pass locally but fail in CI
-/build-loop:run --parallel add billing settings
-```
+## Host surfaces
 
-Skip the loop for single-file edits, config changes, or fixes under ~20 lines.
+The repo ships three agent surfaces from one source:
 
-### Advanced / direct-mode commands
+- **Claude Code plugin**: plugin metadata, commands, hooks, and `agents/*.md`.
+- **Codex plugin**: Codex metadata plus a slim public skill entrypoint (`plugin-artifacts/codex/`).
+- **Host-neutral [`AGENTS.md`](AGENTS.md)**: the same loop methodology for any AGENTS.md-aware tool (Copilot, Cursor, and others), with no Claude-specific integration required.
 
-These commands force a specific mode. Normal usage only needs `/build-loop:run`.
+Surface counts in this release: one command (`/build-loop:run`), 44 skills, 28 agents.
 
-**`/build-loop:debug <symptom>`** — force debug mode directly. `/build-loop:run` auto-routes to this on symptom language ("broken", "doesn't work", "failing", etc.), so you usually don't need it. Useful when you want to skip the full loop and go straight to causal-tree investigation.
+## Agent start protocol
 
-Examples:
+Start every build-loop repo session by checking Rally for coordination state: peers, claims, handoffs, and soft file conflicts. Rally verifies nothing on its own, so confirm code, package, version, and release truth from git, tests, manifests, registries, or GitHub directly.
 
+```bash
+rally enter --tool claude_code --json
+rally next --tool claude_code --json
+rally check before-write --tool claude_code --path README.md --strict --json
 ```
-/build-loop:debug tests pass locally but fail in CI
-/build-loop:debug login works once then breaks on refresh
-/build-loop:debug API returns wrong data intermittently
-```
-
-Runs deep iterative root-cause investigation (causal-tree analysis, fix, verify, critique — up to 5 iterations). The build orchestrator also auto-invokes `Skill("build-loop:debug-loop")` on Review-B Validate failures and Iterate retries (attempts 2 and 3) — you don't have to call it manually during a build.
-
-**`/build-loop:optimize-run [target]`** — force optimize mode. Auto-routed from `/build-loop:run` on metric-improvement language. (Renamed from `/build-loop:optimize` 2026-06-09 to clear the command↔skill namesake collision; `Skill("build-loop:optimize")` is unchanged.)
-
-**`/build-loop:research-run [topic]`** — force research mode. Auto-routed from `/build-loop:run` on evaluation/comparison language. (Renamed from `/build-loop:research` 2026-06-09; `Skill("build-loop:research")` is unchanged.)
-
-**`/build-loop:test [--strict] [test-name]`** — force plugin-test static analysis. Auto-routed from `/build-loop:run` on "test plugin"/"validate plugin" language.
 
-Quick incident-memory lookup: `/build-loop:debugger`. Multi-domain assessment: `/build-loop:assess`. Memory stats: `/build-loop:debugger-status`.
+If the Rally binary is not installed, proceed without it. Full coordination rules: [`references/coordination-rules.md`](references/coordination-rules.md).
 
-## Deployment Policy
+Codex-specific delegation is opt-in. build-loop planning language such as "parallel-safe groups" does not by itself authorize Codex subagents. Spawn them only when the user explicitly asks for parallel delegation or passes a parallel flag.
 
-Build-loop uses a repo-local policy before running push/deploy commands. If `.build-loop/config.json` is absent, the default is:
+## How it works
 
-```json
-{
-  "deploymentPolicy": {
-    "preview": "auto",
-    "testflight": "auto",
-    "production": "confirm",
-    "unknown": "confirm"
-  }
-}
-```
-
-Meaning: preview deploys and TestFlight/App Store Connect upload/export flows can run automatically after review passes; production deploys, releases, publishes, protected-branch pushes, and unknown targets require explicit confirmation. Repos can override each target with `auto`, `confirm`, or `block`.
-
-## Components
+build-loop routes work through a lead orchestrator, invokes bounded subagents with scoped context, and accepts output only after verification. It is **multi-model by tier**: each role maps to an abstract tier (Frontier / Thinking / Code / Pattern), and any model that meets the tier's benchmark contract can fill it. The Anthropic mapping is the default; equivalents from other providers substitute when their benchmarks meet the tier contract.
 
-### Intent Capability Pack
+| Phase | Agent obligation |
+|---|---|
+| Assess | Read live repo state, tooling, memory, Rally, and current docs. Define the goal and pass/fail criteria. |
+| Plan | Produce a dependency-ordered plan with MECE file ownership, validation gates, and approach tradeoffs. |
+| Execute | Implement the accepted plan. Keep edits scoped to owned files. |
+| Review | Run critic, validate, fact-check, simplify, auto-resolve, and report steps. |
+| Iterate | Fix review failures until pass or a real blocker is reached. |
+| Learn | Always emit the Learn outcome and capture durable lessons when warranted. |
 
-Build-loop captures a north star before planning: app/repo purpose, primary users, core jobs, update intent, user value, and non-goals. It writes this to `.build-loop/intent.md` and passes a compact intent packet to every subagent.
+<details>
+<summary><strong>Agent roles (full index)</strong></summary>
 
-Decision rule: prefer the simplest durable approach that creates user value. UI work should be intentional and polished in the basics: every button, option, nav item, chart, and message must have meaning and working behavior. Preview or prototype-looking surfaces must not use fake data in production/user decision paths.
+These tables index agent roles. None of them are commands you run directly. Core authority follows [`references/agent-role-taxonomy.md`](references/agent-role-taxonomy.md): an agent is **core** when a pipeline step is contingent on its verdict, regardless of whether it is top-level or expensive. Model tier follows role; it does not define authority. Deterministic judge surfaces also exist outside `agents/` (`scripts/plan_verify.py`, `scripts/judgment_gate.py`, release verifiers); the tables below are the LLM-side surfaces.
 
-### Modular Systems Pack
+Each agent declares a `(segment, tier)` role that resolves to a concrete model at dispatch. Selection runs on two axes: a work-role **segment** (Generative Reasoning, Agentic Execution, Representation/Retrieval, Governance/Evaluation, plus dormant Realtime, Perception, and Generative Media lanes) and a seven-rung **capability tier** ladder (T0 through T5, plus T-S for specialist infrastructure). Both axes are encoded as data in [`references/model-taxonomy.json`](references/model-taxonomy.json), the **index** that is the durable source of truth. The `(segment, tier)` role is the KEY into that index; an agent's `model:` frontmatter is the index-DERIVED recommended fallback for the active host, kept in sync by [`scripts/sync_agent_model_defaults.py`](scripts/sync_agent_model_defaults.py) (never hand-edited). At dispatch the orchestrator resolves the role LIVE through [`scripts/resolve_agent_model.py`](scripts/resolve_agent_model.py) and OVERRIDES the frontmatter, so the running model always reflects the current index + availability. The `Tier` column below shows the legacy token (`Frontier`, `Thinking`, `Code`, `Pattern`), which aliases onto `T1`, `T2`, `T3`, `T4`, and the concrete model is an Anthropic fresh-install default. The index is **user-editable and chat-maintainable**: a new or different-provider model is adopted by classifying it once and reordering the cell, with no agent edits. Then `sync_agent_model_defaults.py --apply` regenerates the recommended `model:` values. Full mapping: [`references/model-tier-mapping.md`](references/model-tier-mapping.md).
 
-Build-loop defaults to modular, scalable, MECE structure: high cohesion, loose coupling, stable interfaces, and one clear owner per changed file. Plans and reports use pyramid structure: governing thought first, MECE support lines second, evidence/details third.
+Resolution is availability-aware across dispatches: a model observed unavailable at dispatch (a provider outage) is recorded so the role falls back to the next host-reachable model in its tier — a frontier/judgment role degrades at most to the thinking tier, and a model the current host cannot dispatch is never offered. Outage records carry a timestamp and auto-expire after a TTL (`BUILD_LOOP_OUTAGE_TTL_SECONDS`, default 1800s), so a recovered model is picked up again without a manual clear. Recording and clearing run through [`scripts/dispatch_fallback.py`](scripts/dispatch_fallback.py); expiry is pruned on read in [`scripts/model_resolver.py`](scripts/model_resolver.py).
 
-This is a decision rule, not architecture for its own sake. When a simpler or more integrated approach is better for the use case, the plan records `MODULARITY EXCEPTION: <reason>` and explains the user, performance, clarity, or delivery benefit.
+### Lead / workflow agents
 
-### Agents
+| Agent | Description | Tier |
+|---|---|---|
+| `build-orchestrator` | Lead workflow owner for Assess → Plan → Execute → Review → Iterate → Learn; owns dispatch, phase transitions, commits, and report. | Thinking |
+| `assessment-orchestrator` | Multi-domain debugging coordinator for unclear symptoms across database, frontend, API, and performance lanes. | Thinking |
+| `optimize-runner` | Optimization-loop coordinator for metric-driven experiments, measurement, and regression handling. | Code |
 
-| Agent | Role | Model |
-|-------|------|-------|
-| **build-orchestrator** | Drives the 5-phase loop plus mandatory Phase 6 Learn, dispatches subagents | opus (overridable) |
-| **commit-auditor** | Advisory judge — chunk scope (Phase 3) + build scope (Phase 4-A, replaces retired sonnet-critic) | opus |
-| **fact-checker** | Traces rendered metrics to data sources | inherit (sonnet recommended) |
-| **mock-scanner** | Scans for placeholder/fake data in production code | haiku |
+### Judgment / review agents
 
-**Pin vs inherit philosophy**: pin when the task has a clear right tier (critic needs Sonnet, mock-scanner needs Haiku, orchestrator benefits from Opus judgment). Use `inherit` when user intent should flow through (fact-checker — recommended Sonnet, but respects main-session choice). Override an agent's pin by passing `model:` at spawn time or editing frontmatter.
+| Agent | Description | Tier |
+|---|---|---|
+| `advisor` | Frontier planning author or re-planner when Phase 2 needs deeper synthesis. | Frontier |
+| `plan-critic` | Plan critique for dependencies, scope drift, validation, ownership, alternatives, and MECE quality. | Frontier |
+| `scope-auditor` | Plan-to-Execute boundary check and public-signature caller coverage. | Frontier |
+| `independent-auditor` | Independent adversarial review for chunk and build-scope completion claims. | Frontier |
+| `fix-critique` | Root-cause and regression pressure-test after a proposed fix. | Frontier |
+| `fact-checker` | Claim, metric, and rendered-data provenance checks before completion. | Frontier |
+| `security-reviewer` | Security review for auth, secrets, trust boundaries, injection, and adjacent risks. | Frontier |
+| `overfitting-reviewer` | Optimization review for test gaming, Goodhart effects, and overfitting. | Frontier |
+| `promotion-reviewer` | Review of proposed skill, agent, or enforcement promotions before activation. | Frontier |
+| `synthesis-critic` | Advisory coherence review for synthesis-heavy outputs across multiple dimensions. | Code |
+| `alignment-checker` | Advisory queue-item alignment check against current intent, goal, and non-goals. | Code |
 
-### Model Tiering
+### Worker / specialist agents
 
-Build-loop assigns models per task, not per phase, guided by the `model-tiering` skill:
+| Agent | Description | Tier |
+|---|---|---|
+| `implementer` | Bounded coding worker for one Phase 5 fix plan or criterion-targeted implementation packet. | Code |
+| `api-assessor` | API, route, auth, rate-limit, CORS, and request/response failure assessment. | Code |
+| `database-assessor` | Query, migration, schema, connection, vector index, and data integrity failure assessment. | Code |
+| `frontend-assessor` | React, rendering, hydration, state, component, and client performance assessment. | Code |
+| `performance-assessor` | Latency, memory, CPU, timeout, and bottleneck assessment. | Code |
+| `architecture-scout` | Read-only architecture baseline, impact, rules, iterate subgraph, and learn-sync tasks. | Code |
+| `design-contract-specialist` | UI/data input-output contracts, design direction, and traceability artifacts. | Code |
+| `ui-validator` | UI behavior, state, accessibility, layout, console, and rendering evidence validation. | Code |
+| `root-cause-investigator` | Causal-tree investigation for persistent or ambiguous failures. | inherit |
+| `mock-scanner` | Production-path scan for placeholder, fake, fixture, and mock data. | Pattern |
 
-- **Opus** at boundaries: planning, final review, novel architecture, ambiguity resolution, user-visible prose
-- **Sonnet** inside: bounded code execution, adversarial critic, first-pass debugging, fact-checking
-- **Haiku** for pattern-matching only (mock scanning)
+### Learning agents
 
-Escalation triggers (mid-flow switch to Opus): 2 consecutive failures, ambiguous spec, cross-file architectural decision, critic `strong-checkpoint` finding, novel error, user-visible prose. See `skills/model-tiering/SKILL.md` and `agents/build-orchestrator.md §Escalation Triggers`.
+| Agent | Description | Tier |
+|---|---|---|
+| `recurring-pattern-detector` | Repeated run-pattern and Learn-candidate detection from run history and retro signals. | Pattern |
+| `retrospective-synthesizer` | Background post-build retrospective and enforce-candidate summary. | Code |
+| `self-improvement-architect` | Experimental skill, agent, and workflow drafts from recurring lessons. | Code |
+| `transcript-pattern-miner` | Transcript mining for repeated patterns and self-improvement candidates. | Pattern |
 
-The pattern amortizes Opus cost across many Sonnet subagents. Typical build: Opus plans once, 6 to 12 Sonnet implementer runs, 1 Sonnet critic per chunk, Opus final review. Estimated 4x cheaper than single-pass Opus end-to-end.
+</details>
 
-### Eval Methodology
+## FAQ
 
-- **Binary pass/fail only** — no partial credit, no Likert scales
-- **Code-based graders first** — test pass/fail, lint, type check, build (fast, deterministic)
-- **LLM-as-judge second** — for nuanced criteria code can't evaluate
-- **One evaluator per dimension** — no multi-dimension "God Evaluator"
-- **Pytest-collection gate at Review-B** — `scripts/pytest_collect_gate.py` runs `pytest --collect-only` (with `PYTHONPATH` stripped) on Python-bearing repos before LLM judges. The bar is collection only — db/live tests still skip at execution time via their markers — but every test module must *load*. A run can't report success while any test module fails to import. Closes the silent-coverage-loss gap where a broken import quietly removes whole modules from coverage. Skipped on library-only repos with no test paths.
+### What problem does it solve?
 
-### Iteration Rules
+Agents handed multi-step work tend to skip planning and verification, so wrong assumptions ride into code and "it compiles" gets reported as "it works." build-loop forces every change through a planned, reviewed, verified loop and refuses to claim completion without evidence behind it.
 
-- Diagnose root cause before fixing
-- Re-validate only failed criteria
-- 3 failures on same criterion with same cause → escalate to user
-- Fixing one criterion breaks another → stop, reassess
-- No improvement after 2 consecutive iterations → change strategy
-- **Hard stop at 5 iterations**
+### Who is it for, and who is it not for?
 
-### Post-build retrospective & backlog drain
+It is for developers running AI coding agents on non-trivial changes: features, refactors, migrations, and bug hunts that touch more than one file. It is not for one-line edits, pure Q&A, or status checks; those skip the loop by design.
 
-- **Post-push retrospective** — after the Phase 4 Report closing push, the `retrospective-synthesizer` agent runs non-gating in the background and writes a 9-section lessons-learned file (`.build-loop/retrospectives/<YYYY-MM-DD>/<run-id>.md`) plus a ≤5-line summary surfaced inline. Anything prompted ≥2× in the thread, or surfaced for "what should be enforced", becomes an auto-drafted enforce-candidate at `.build-loop/proposals/enforce-from-retro/` — a candidate for human review, never silently promoted. The closing run does not wait for it.
-- **Backlog auto-iterate** — product-impacting work that gets descoped during a build is triaged on capture (via `scripts/backlog/triage.py` + `assess.py`) into `.build-loop/backlog/<id>.md` using `templates/backlog-item.md` (mandatory `repo` + `branch` segmentation keys plus `classify`, `effort`, `status`). Phase 5 Iterate drains the backlog at end-of-run alongside `issues/` and `ux-queue/` by default; the durable cross-run backlog of record lives at `build-loop-memory/projects/<slug>/backlog.md`. Cross-repo items are never mixed into one tracker.
-- **Retro → Learn wiring** — `scripts/enforce_retro_signals.py` normalizes the enforce-candidates and counts recurrence across distinct run-ids; the `recurring-pattern-detector` agent reads it as a second signal source (alongside `state.json.runs[]`) and emits `enforce_recurrence` patterns when the same candidate signature appears across ≥2 runs. Delivers "anything prompted or needed repeatedly → enforce" across sessions, not just within one.
+### What is the fastest way to try it?
 
-## Native Architecture & Debugging Skills
+`npm install -g @tyroneross/build-loop@0.36.0`, then `build-loop-install --host all`, then `/build-loop:run <your task>` inside a project. See [Quick start](#quick-start).
 
-Architecture and debugging are used on nearly every build, so build-loop ships native skills under:
+### How is it different from just letting an agent code directly?
 
-- `skills/architecture/{scan,impact,trace,rules,dead,review}/` — sourced from NavGator
-- `skills/debugging/{memory,store,assess,debug-loop}/` — build-loop-native RCA, investigation, memory, and storage workflows adapted from the debugger lineage
+A direct agent edit has no scope boundary and no independent check. build-loop adds explicit file ownership, pass/fail criteria, an adversarial review pass (critic, fact-checker, mock-data scanner), and automatic iteration to green. It also runs the same loop across Claude Code, Codex, and AGENTS.md tools, and routes planning/judging to a frontier model while execution runs on a coding model.
 
-Each sourced native SKILL.md frontmatter carries `source:` (relative path from the sibling-repos root) and `source_hash:` (SHA-256 at copy time). The orchestrator calls them directly in Phase 1 Assess, Review-B Validate, Review-D Fact-Check, Review-F Report, and Phase 5 Iterate cross-layer pre-step.
+## Runtime data
 
-Deep debugging remains first-class inside build-loop: causal-tree investigation, 5 Whys, fishbone categories, fault-tree branching, Kepner-Tregoe style problem boundaries, hypothesis falsification, fix verification, scorecards, and critique all live in native skills rather than an MCP process.
+Consumer projects store run state under `.build-loop/`:
 
-Drift detection is a deliberate, opt-in pass:
-
-```bash
-python3 scripts/sync_skills.py
-# or
-Skill("build-loop:sync-skills")
+```text
+.build-loop/
+  goal.md
+  intent.md
+  config.json
+  state.json
+  feedback.md
+  evals/
+  issues/
+  backlog/
 ```
 
-The script recomputes each `source_hash` against the canonical upstream file and reports drift. Read-only — never auto-updates a SKILL.md. The legacy `skills/navgator-bridge/` and `skills/debugger-bridge/` deprecation stubs were removed in v0.10.0 — the orchestrator and downstream skills call the native skills directly.
-
-## Architecture awareness
+Add `.build-loop/` to a consumer project's `.gitignore` unless the repo intentionally tracks selected backlog or plan files.
 
-Build-loop owns native architecture awareness end-to-end. NavGator is now an optional escalation adapter, not a hard dependency.
-
-**Native engine** (`src/build_loop/architecture/`)
-Python-native scanner: `.gitignore`-aware walk, Python via `ast`, TS/JS via tree-sitter, plus Gator-style runtime edges for manifest package use, Next.js frontend API fetches, path-alias imports, and conservative service/LLM calls. Pure-function `compute_impact / trace_dataflow / check_rules / find_dead`. Output schema-parity with NavGator (component/connection JSON shapes verbatim) under `.build-loop/architecture/`.
+build-loop memory defaults to `~/.build-loop-memory` on a fresh machine, or an existing `~/dev/git-folder/build-loop-memory` when present. Bootstrap or inspect it:
 
 ```bash
-uv run python -m build_loop.architecture {scan|impact|trace|rules|dead|connections|acp|acp-slice|llm-map|schema|diagram} \
-    [--mode auto|native|navgator] [--json] [--incremental|--full]
+python3 scripts/install_memory.py
+python3 scripts/install_memory.py --check
 ```
 
-**`architecture-scout` subagent** (`agents/architecture-scout.md`)
-Sonnet, read-only, dispatched by the orchestrator at six phase points with one of five task types: `baseline`, `chunk-impact`, `review-rules`, `iterate-subgraph`, `learn-sync`. Decides native-vs-NavGator escalation per task. Returns ≤500-word JSON envelope; owns architecture-related side effects (violation capture, lessons sync).
-
-**Architecture Context Pack (ACP)** (`scripts/build_acp.py`, `scripts/slice_acp.py`)
-Compact JSON summary of current architecture state: top hotspots, recent violations, lessons-in-scope. Sliceable per file set with reverse-deps depth=1 + 4 KB cap. Embedded in subagent briefs at Phase 2 / 3 / 4 / 5.
-
-**Aggressive freshness** (`hooks/session-start-architecture.sh`, `hooks/pre-edit-architecture.sh`)
-SessionStart fires an incremental scan when manifest > 24 h old. PreToolUse Edit/Write triggers an async incremental scan when the touched file is parseable (extension allowlist: `.py .ts .tsx .js .jsx .mjs .cjs`); single-flight via `fcntl.flock`. Doc-only edits never fire scans.
-
-**Capability registry + ≤8 shortlist** (`scripts/build_capability_registry.py`, `scripts/capability_shortlist.py`, `skills/capabilities/SKILL.md`)
-116 capabilities indexed across 6 kinds (agent / skill / command / hook / mcp_tool / script) and 10 categories. Phase 1 invocation is **mandatory** — populates `state.json.activeCapabilities[<phase>]` with ≤8 relevant entries via plugin-surface collapse + trigger-aware demotion, keeping the orchestrator below the empirical tool-selection ceiling. Phase 2 / 3 dispatchers read the cache instead of re-scoring.
-
-**Memory facade** (`scripts/memory_facade.py`)
-Unified `recall(query, kind, project, limit, skip_postgres)` over file-backed and optional database surfaces — `state.json.runs[]` · canonical `<memory-root>/projects/<project>/decisions/` plus migration-mode legacy decisions · local SQLite `indexes/semantic_facts.sqlite` · optional Postgres `semantic_facts` mirror. Debugging incident recall is native and file-backed by default; standalone Coding Debugger can provide cross-project MCP-backed recall when installed separately. Graceful degradation throughout; CLI accepts both `memory_facade.py --query ...` and the compatibility form `memory_facade.py recall --query ...`, including `--skip-postgres` for the optional Postgres path.
-
-**Backend health probe** (`scripts/backend_health.py`)
-Phase 1 sub-step probes each memory backend with per-backend 5 s timeout. Output: `runs: OK N | decisions: OK <legacy> + <canonical> | semantic: ok|down | debugger: ok|down`. Envelope cached at `state.json.architecture.backendHealth`. Phase 5 Iterate consumes it to short-circuit Postgres lookups when down.
-
-**Plan-verify rules** (`scripts/plan_verify.py`)
-Now includes `schema-migration-full-chain` — flags any commit touching writer/storage/schema files without matching test fixture or reader-path co-change. Catches the recurring drift pattern where writer keys diverge from reader expectations.
-
-**Web deploy verification** (`scripts/verify_deploy.py`)
-Phase 4 Review-B gate that runs after a deploy actually executed. Detects a Vercel link (`.vercel/project.json` or `vercel.json`), resolves the latest production deployment, polls `vercel inspect` to a terminal state, then probes the prod root + each changed route. An auth-gated `401`/`403` on a protected route is treated as **healthy** (the function deployed and is running) — only a `5xx`/build-error fails. Infra trouble (CLI missing, not authed) returns `skipped` and never blocks the build. Optional preferred-tier upgrade: the remote Vercel MCP, only if the user adds it to `.mcp.json` (build-loop does not add it). Inline degraded path: `fallbacks.md#web-deploy-verify`.
-
-**Decision capture loop**
-Every architecture violation surfaced by `rules` becomes a deduplicated decision in the canonical episodic store via `scripts/capture_arch_violation.py`. Recurring violations (≥3× across runs) get promoted to project-local lessons by `scripts/promote_violation_to_lesson.py` and one-way-synced into local SQLite `semantic_facts` for cross-project recall by `scripts/sync_navgator_lessons.py`. Postgres mirroring is explicit with `--postgres-mirror`.
-
-## External Skill Dependencies
-
-These skills enhance the loop when available but are not required:
+## Codex surface
 
-| Skill | Used In | Without It |
-|-------|---------|------------|
-| `writing-plans` | Phase 2 (Plan) | Write plan directly with file paths and dependency order |
-| `subagent-driven-development` | Phase 3 (Execute) | Dispatch parallel agents manually |
-| `calm-precision` | Phase 3 (Execute, UI) | Use standard UI best practices |
-| `verification-before-completion` | Phase 4 (Review sub-step B) | Run test/build/lint and confirm output manually |
-
-## Cross-Tool Support
-
-This repo includes `AGENTS.md` — the open-standard version of the build loop methodology. If you use Codex, Copilot, Cursor, Jules, or any other AI coding tool, that file provides the same 5-phase + mandatory Phase 6 Learn workflow without Claude-specific integration.
-
-Codex-specific subagent behavior lives in `skills/build-loop/references/codex-subagents.md` and `skills/build-loop/templates/codex-worker-prompt.md`. These files are additive: Claude Code continues to use the existing `agents/*.md` runtime, while Codex maps Build Loop ownership packets to explorer/worker-style delegation only when the user explicitly authorizes subagents or parallel work.
-
-## Project Data
-
-Build loop stores runtime data in `.build-loop/` within consumer projects:
+The Codex package exposes one public entrypoint skill through the slim artifact:
 
-```
-.build-loop/
-├── goal.md          # Current build goal
-├── intent.md        # North star, update intent, user value, non-goals
-├── config.json      # Optional repo flags, including deploymentPolicy
-├── state.json       # Iteration state, including compact intent/structure summaries
-├── feedback.md      # Post-build lessons
-├── evals/           # Scorecard archives
-└── issues/          # Discovered issues
+```text
+plugin-artifacts/codex/
+  .codex-plugin/plugin.json
+  skills/build-loop/SKILL.md
 ```
 
-Add `.build-loop/` to your project's `.gitignore`.
+The full `skills/` tree still ships for Claude Code and for internal references. Codex loads helper instructions only when the public build-loop skill asks for them.
 
-## License & Attribution
+Check installed cache sync and prune stale versions:
 
-This project is licensed under the [Apache License 2.0](LICENSE).
-
-- [`LICENSE`](LICENSE) — full license text.
-- [`NOTICE`](NOTICE) — attribution notices that, per Apache 2.0 §4(d), must travel with any redistribution of this work.
-- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution conventions: per-file SPDX headers (REUSE 3.3), AI co-author trailer, signed commits, conventional commits.
+```bash
+python3 scripts/check_cache_sync.py --host codex --source plugin-artifacts/codex
+python3 scripts/check_cache_sync.py --host claude --source .
+python3 scripts/prune_plugin_cache.py --source . --host all --apply
+```
 
-Per-file `SPDX-FileCopyrightText` and `SPDX-License-Identifier` headers are required on shipped source files. Files that cannot carry inline comments (JSON, generated assets) are annotated in [`REUSE.toml`](REUSE.toml). Validate compliance locally with `uvx reuse lint`.
+## Release checklist
 
-## Codex
+For a plugin/package release, keep these version surfaces in lockstep:
 
-This package now ships an additive Codex plugin surface alongside the existing Claude Code package. The Claude package remains authoritative for Claude behavior; the Codex package adds a parallel `.codex-plugin/plugin.json` install surface without changing the Claude runtime.
+- `package.json`
+- `package-lock.json`
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `.codex-plugin/plugin.json`
+- `.agents/plugins/marketplace.json`
+- `plugin-artifacts/codex/.codex-plugin/plugin.json`
 
-Package root for Codex installs:
-- the repository root (`.`)
+Build and verify, then verify the release surface after tag/push:
 
-Primary Codex surface:
-- public entrypoint skills from `./codex-skills` when present
-- public entrypoint skill metadata only; build-loop does not expose a Codex MCP server
+```bash
+npm run build
+python3 scripts/test_plugin_manifest.py
+python3 scripts/test_agent_surface_policy.py
+npm run codex:build-artifact
+npm pack --dry-run --json
+python3 scripts/verify_release_surface.py --version v0.36.0 --branch main --remote origin --json
+```
 
-Codex adapter files:
-- `skills/build-loop/references/codex-subagents.md`
-- `skills/build-loop/templates/codex-worker-prompt.md`
+Publishing to GitHub Packages, npmjs, or GitHub Releases is a release action. Run it only when explicitly requested by the human owner.
 
-The full `./skills` tree still ships with the package for Claude Code and for
-Build Loop's internal references. Codex only exposes the compact public
-entrypoint set in `./codex-skills` so helper skills do not crowd the `#` picker.
-Claude Code keeps the full tree addressable for commands/orchestrator internals,
-but helper skills are marked `user-invocable: false`. Cursor and other
-AGENTS.md-style tools should follow [`docs/agent-surface-policy.md`](docs/agent-surface-policy.md).
+## Limitations and known issues
 
-Install the package from this package root using your current Codex plugin install flow. The Codex package is additive only: Claude-specific hooks, slash commands, and agent wiring remain unchanged for Claude Code.
+See [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md). Notably, the bare `/build-loop` command form is deprecated in favor of `/build-loop:run` because of a namesake collision with the skill of the same qualified name.
 
-To check whether an installed Codex cache is using the current source instructions:
+## Architecture
 
-```bash
-python3 scripts/check_cache_sync.py --host codex --source .
-```
+Short overview: [`ARCHITECTURE.md`](ARCHITECTURE.md). The living, auto-generated diagram and its drift gate are described under [The loop](#the-loop). Regenerate the diagram with `python3 scripts/architecture_diagram/generate.py`.
 
-To remove stale Claude Code and Codex cache versions after a marketplace
-upgrade installs the current version:
+## Contributing
 
-```bash
-python3 scripts/prune_plugin_cache.py --source . --apply
-```
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Agent build/test conventions for this repo live in [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md).
 
-Host-specific variants are also available:
+## License
 
-```bash
-python3 scripts/prune_plugin_cache.py --source . --host codex --apply
-python3 scripts/prune_plugin_cache.py --source . --host claude --apply
-```
+Apache-2.0. See [`LICENSE`](LICENSE), [`NOTICE`](NOTICE), and [`CONTRIBUTING.md`](CONTRIBUTING.md).