FAQ

FAQ & Troubleshooting

When should I use build-loop vs. just editing?

Use it for non-trivial features, refactors, migrations, and bug hunts that touch more than one file. Skip it for one-line edits, pure Q&A, status checks, and trivial typos/renames. /build-loop:run auto-routes build/fix/refactor/optimize/research/test — you don't pick a mode.

Does it commit on its own?

Yes — completed, verified work is committed automatically. The only human-confirmation gates are production push, irreversible delete, and major user-impacting decisions.

Do I run the agents directly?

No. Agents (plan-critic, fact-checker, implementer, etc.) are roles the orchestrator dispatches. You interact through commands (/build-loop:run, /build-loop:debug, …).

What models does it use?

It's multi-model by tier (Frontier / Thinking / Code / Pattern). The Anthropic mapping is the fresh-install default, but selection is data-driven via references/model-taxonomy.json and resolved live at dispatch. See Configuration → Model tiering.

---

Known issues

Skill(skill="build-loop:build-loop") returns the slash-command template

Symptom. Calling the Skill tool with build-loop:build-loop returns the slash-command body (commands/build-loop.md) instead of executing the skill at skills/build-loop/SKILL.md.

Cause (suspected). A slash command and a skill share the same qualified name (<plugin>:<name>); the Skill resolver picks the slash-command file. The same collision affects claude-code-debugger:debug-loop.

Workaround. Dispatch the build-loop:build-orchestrator agent directly, or invoke via the /build-loop:run command surface rather than the Skill tool.

Dependency cooldown — per-PM native keys

The supply-chain cooldown writes a different native key per package manager. Getting this wrong silently installs ungated packages:

PM	Key	Unit	File	Native exclude
npm ≥ 11.10	min-release-age	days	.npmrc	None (npm/cli#8994)
pnpm ≥ 11	minimumReleaseAge	minutes	pnpm-workspace.yaml	minimumReleaseAgeExclude:
pnpm 10.x	minimum-release-age	minutes	.npmrc	(carried in workspace yaml)
yarn ≥ 4.10	npmMinimalAgeGate	minutes (numeric)	.yarnrc.yml	npmPreapprovedPackages:

• On npm, the allowlist is enforced by the PreToolUse backstop hook (npm has no native exclude). The hook never adds --before when npm native config is active — npm hard-errors when both are present.
• The hook cannot rewrite lockfile-driven npm ci or pnpm installs — those are denied with an actionable message.
• pip / cargo have no native cooldown primitive and are not covered in v1.
• Inspect a cooldown resolution with npm install <pkg> --dry-run (the .npmrc in place), not npm view --before (which ignores --before for metadata reads).

Concurrent-session collisions

Two concurrent writers (e.g. a main session + a background orchestrator) on the same worktree are handled by Rally Point presence — one file per live session under the resolved channel. The legacy M4 session_registry.py mechanism was retired (2026-05-18); peer file-overlap surfaces as a soft-claim WARNING, never a block. isolation: "worktree" on Agent dispatches remains good practice for HEAD/index isolation.

Web deploy verification (Vercel)

scripts/verify_deploy.py is a Phase 4 Review-B gate that fires after a deploy runs on a Vercel-linked project. An auth-gated 401/403 on a protected route is treated as healthy (function deployed and running). Missing/unauthed CLI or transient infra → skipped, never a hard build failure.

---

Where do I report bugs?

Repo: https://github.com/tyroneross/build-loop · see KNOWN-ISSUES.md and CHANGELOG.md for the latest.