build-loop

Use when coordinating build-loop with peer coding agents, checking Rally Point presence/inbox state, posting handoffs or feedback, validating the embedded Rally Point boundary, or changing the future agent-rally-point spin-out surface.

Use when listening for Rally Point changes, wiring coordination watchers, debugging watch-loop behavior, or changing the future agent-rally-watcher spin-out surface.

Use when Phase 1 Assess or Phase 5 Iterate detects a new API dependency, API config fails, or the user asks to "register this API" or "check the API registry". Consults api-registry plugin; degrades gracefully if plugin is absent. NOT for PRD strategic grounding (use `prd-bridge`) or UI verification (use `ibr-bridge`).

Apply the canonical four-layer Apache-2.0 attribution model (NOTICE, per-file SPDX, REUSE.toml, canary markers) to a repo. Triggers on 'stamp attribution', 'add NOTICE', 'license headers', 'attribution layers', a newly public repo, or a repo with .git but no NOTICE / no REUSE.toml / no CONTRIBUTING.md. Build-loop Phase 1 Assess can advise running this when shipped source files lack SPDX headers.

Use when wiring auth to a new project, debugging login errors (redirect_uri_mismatch, invalid_grant, session callback, refresh_token), or adding social/magic link flows. Covers Better Auth (Drizzle/Neon), Supabase Auth (SSR), Google OAuth, and Resend transactional email.

Passively capture a substantive decision the user just made, in real time, into build-loop-memory. Fires automatically when the user confirms a choice or states a constraint — not user-invoked. Not for findings/issues (use `auto-finding-capture`), after-the-fact review (use `recursive-retrospective`), or surfacing an unstated call the user never saw so he can reverse it (use `silent-assumptions`).

Orchestrated build loop for multi-step code work. TRIGGER on verb language ('build', 'implement', 'create', 'add', 'ship', 'wire up', 'integrate', 'refactor', 'migrate', 'rewrite', 'replace') OR symptom language ('fix', 'broken', 'doesn't work', 'isn't loading', 'not displaying', 'missing', 'should show', 'needs to', 'make it', 'show this differently') OR any task touching 2+ files, adding/removing an endpoint, crossing an architectural boundary, or attached screenshots of a bug. SKIP one-line edits, pure Q&A, conversational clarifications, status checks, and trivial typos/renames.

Build or refactor an agent using the OSS `deepagents` framework (SubAgent API, middleware, tool scoping, streaming, checkpointing). Use when the user wants a multi-agent/subagent system built with deepagents, or the code imports it. Not for `.claude/agents/*.md` definitions.

Name the LAYER a claim lives at (working tree / repository / deployed / live behavior) and check that your instrument can reach it, before stating any fact about a system. Triggers on assertion words (is / never / only / verified / cannot) and on 'does X exist', 'did X ship'. Not for grading evidence STRENGTH ([measured]/[correlated]/[reasoned]) — that is report_lint's mechanism-claim rule, which this extends with reach. A grep proves what is in one checkout; it can say nothing about what is running. Verify right-to-left: start at observed behavior, walk back toward source.

Generate accessible color systems and solve contrast, instead of guessing hex values. Use when picking or fixing colors for any UI, chart, diagram, doc, or artifact — "what colors should this use", "is this readable", "this text fails contrast", "make a dark theme", "pick an accent". Also use before shipping any palette, to PROVE contrast rather than assert it. NOT for choosing layout, typography, or component structure.

Quantify what a context/caching/model change did to token spend and dollars, from measured usage data, never estimates. Use when the user asks "how much did that cost", "did caching save money", "why did my bill spike", or "token delta". Not for choosing which model to use (use `model-tiering`) or comparing models head-to-head (use `model-bakeoff`).

Iteratively investigate and fix a live, currently-broken bug. Use when a fix didn't hold, `/build-loop:debug` is invoked, or the user wants it debugged right now. Not for checking whether this bug happened before (use `debugging-memory` first) or a post-fix blameless analysis (use `root-cause-analysis`).

Search Build Loop's native debugging memory before you investigate a bug, then store the verified fix afterward. Use when the user reports a crash, error, regression, or broken behavior — check what already failed this way before re-deriving it. Not for implementing the fix itself; use debug-loop.

Turn pending decisions — Operations Center tasks with status needs_input, a backlog of open questions, anything blocked on the user's judgment — into one interactive page the user answers inline and Claude reads back later. Not for a one-off static report with no response capture; use a plain Artifact instead. Each decision gets a card carrying the choice, why it needs the user, its impact, the options, and a recommendation. Triggers: 'show me the decisions waiting on me', 'what needs my input', 'make a decision queue', 'launch a ui for these open questions'. Not for a judgement call you already made and applied while work continued — that never blocks and belongs in `silent-assumptions`.

Walk the cross-repo proposal backlog interactively, deciding apply/reject/defer on each item; never auto-applies. Use when the user says "drain proposals" or "review the proposal backlog".

Use when the user asks to "create a custom build loop", "build a loop spec", "make a focused loop", "generate a workflow loop", "adapt a framework into a loop", or asks whether a workflow should use skill chaining. Generates declarative focused-loop specs, presets, validators, and skill-chain plans.

Compose a complete, durable build-loop handoff document from the current run state, and optionally launch a fresh session with it injected. Use when crossing a context boundary (context limit, planned restart, worktree GC). Triggers: 'hand off', 'handoff', 'new session', 'context limit', 'restart', 'fresh session', '/build-loop:compose-handoff'.

Use when the user asks to "add logging", "add tracing", "improve observability", "OpenTelemetry", "structured logging", or reports silent failures or no runtime visibility. Generates stack-appropriate logging with optional OTel.

Build, package, or debug an MCP server and its tools. Use when the user is adding MCP tools, or working on `.mcp.json`, transport, or bundling. Not for scaffolding the plugin around it (use `plugin-builder`; pair the two when a plugin exposes MCP tools).

Run the same bounded change across multiple models in parallel, then deterministically score and merge the best result. Use when the user says "bake-off", "compare models on this task", "which model is best at", or "A/B test these models". Not for picking a single model tier for one agent (use `model-tiering`).

Recommend which model tier (e.g. Opus/Sonnet/Haiku) to use for a subagent or task. Use when the user asks "which model should I use", "is Sonnet enough or do I need Opus", or sets a segment+tier in agent frontmatter. Not for running multiple models head-to-head and scoring them (use `model-bakeoff`).

Use when the user says "optimize this", "optimization", "make X faster", "reduce <metric>", or "speed up my app". Runs a Design of Experiments test matrix — up to 6 variables in one pass — to find which variable actually moves the number. Falls back to one-at-a-time loop for single variables.

Use when build-loop Phase 2 wraps plan drafting, the user runs `/build-loop:verify-plan`, asks to "verify the plan" or "lint the plan", or any plan markdown change touches evidence, synthesis-density, risk_reason, or modifies_api fields. Runs deterministic plan-verify rules and emits findings JSON.

Create, scaffold, or migrate a Claude Code plugin — manifest, directory layout, hooks, agents, distribution. Use when the user asks to create/build/scaffold/convert a plugin, or needs plugin.json/layout guidance. Not for building the MCP server itself once the shell exists (use `mcp-builder`; pair the two).

Static-analysis test harness for Claude Code plugins. Triggers on "test plugin", "validate plugin", "check skill resolution", "run plugin tests", "lint plugin", "verify manifest", "namesake collision", "MCP registration check". Runs Python stdlib pytest scripts that catch namesake collisions, manifest drift, MCP misregistration, trigger-phrase coverage gaps, bridge pre-flight gaps, agent-surface drift, and cache-prune regressions. Routed as build-loop's 4th orchestrator mode (Build / Optimize / Research / Test).

Deliberate retrospective on one project's full trajectory — decide preserve/refine/redirect/reset and encode lessons into memory, agents, skills, evals, and gates. Use when the user asks to review a project's history after a substantial build, or convert a session into durable improvement. Not for the automatic cross-run pattern scan (use `self-improve`).

Compatibility alias for Repository Maintenance. Use when an existing prompt or workflow invokes repo-closeout; route all repository structure, artifact, branch, worktree, sibling consolidation, and local-main maintenance work to repo-maintenance. Deprecated: prefer repo-maintenance for new work.

Audit and evolve repository structure — topology, module boundaries, artifact retention, branch/worktree hygiene, and open-source readiness. Use when the user asks how a repo should be structured, why it has duplicate source, wants generated artifacts cleaned, or wants a repo readied to open-source. Never pushes, deletes unique source, or rewrites history without explicit authorization.

Generate a repo-grounded pre-decision research packet — risk, best path, confidence, next action — before deciding whether/how to build something in this repo. Use when the user asks to research/investigate/evaluate options for an imminent build decision here. Not for open-ended general research unconnected to a build in this repo — use the separate `research` plugin for that.

Root-cause analysis run AFTER a bug is already fixed — explains why it existed and why it escaped controls, then lands a durable system fix, not a code patch. Use when the user asks "why did this keep happening", "root cause", wants a postmortem/RCA/"5 whys", or after a regression once the immediate fix lands. Not for fixing the bug live (use `debug-loop`) or searching/storing past incidents (use `debugging-memory`).

Use in Phase 4/5 (Validate/Iterate) for ANY change to a user-visible flow — web, macOS, iOS, agent, or CLI/TUI — before claiming "done". Verifies the RUNNING app's core flow by cross-checking the rendered/queryable UI against the backing source-of-truth (DB/API/daemon/tool-state), screen-independently. Triggers — "verify it works", "confirm the fix", "does X actually work", "nothing happens when I…", "not showing", "shows empty/wrong data", uiTarget != null, or any "action does nothing / data not displaying / stale projection" symptom. Compile-green and a passing unit test do NOT satisfy this; neither does a screenshot alone.

Write a build-loop-compatible plan/spec. Walks the completeness checklist before drafting; runs plan-critic on output. Triggers when build-loop Phase 2 starts OR when the user says "write a plan", "write a spec", "draft a plan for X", "spec out a feature".

Use when adding observability/telemetry to an app, instrumenting traces/metrics/logs, wiring LLM/agent tracing, choosing a monitoring vendor, or auditing an app for missing telemetry. Triggers — "add telemetry", "add observability", "instrument this", "tracing", "OpenTelemetry/OTel", "LLM observability", "LangChain tracing", "Phoenix/Langfuse/LangSmith", "Crashlytics/Sentry/mobile telemetry", "why is this slow in prod", "no visibility into". OpenTelemetry-first, vendor-neutral.

Use when build-loop needs UI design direction, visual style selection, UI guidance inventory, a .build-loop/app-contract/ui.md design contract, or non-trivial web/mobile/native UI planning. Build-loop-owned design route for design-contract-specialist; selects from project tokens, recent structures, UI Guidance, IBR artifacts, Mockup Gallery, and research based on product/workflow/data/platform fit.