buildanything 1.2.1 → 1.5.0

package/commands/protocols/brainstorm.md

@@ -0,0 +1,99 @@
+# Brainstorm Protocol
+
+You are the orchestrator running a structured brainstorming session to turn a raw idea into a validated design document.
+
+## How This Works
+
+You ask questions one at a time, propose approaches with trade-offs, and converge on decisions. The output is a Design Document saved to `docs/plans/`.
+
+This is a CONVERSATION, not a monologue. Each step involves the user.
+
+## Step 1: Understand the Idea
+
+Read the build request and any existing context (brainstorm docs, decision briefs, conversation history, existing code).
+
+Ask the user 3-5 targeted questions to fill gaps. Ask ONE question at a time, wait for the answer, then ask the next. Do not dump all questions at once.
+
+Focus on:
+- **Who is the user?** Who will use this, and what's their primary pain point?
+- **What's the core flow?** What does the user DO in the product? Walk through the main interaction.
+- **What's the scope?** What's in the MVP vs. what's deferred?
+- **What are the constraints?** Tech stack preferences, budget, timeline, existing systems to integrate with.
+- **What does success look like?** How will you know this works?
+
+Skip questions the user already answered in their build request or prior context.
+
+## Step 2: Propose Approaches
+
+For each major design decision, propose 2-3 approaches with trade-offs:
+
+```
+DECISION: [e.g., "Data storage approach"]
+
+Option A: [approach] — [1-line trade-off summary]
+Option B: [approach] — [1-line trade-off summary]
+Option C: [approach] — [1-line trade-off summary]
+
+My recommendation: [which and why, in 1 sentence]
+```
+
+Major decisions typically include:
+- Tech stack (framework, language, database, hosting)
+- Data model (what entities, how they relate)
+- Primary user flow (step by step)
+- Authentication approach
+- External service integrations
+- MVP scope boundary (in vs. out)
+
+Let the user pick or modify. Do not force your recommendation.
+
+## Step 3: Write the Design Document
+
+After decisions converge, produce a Design Document and save to `docs/plans/YYYY-MM-DD-[topic]-design.md`:
+
+```markdown
+# [Project Name] — Design Document
+
+## Vision
+[1-2 sentences: what this is and who it's for]
+
+## Primary User
+[Who they are, what they need, why current alternatives fail them]
+
+## Core User Flow
+[Step-by-step: what the user does, numbered list]
+
+## Tech Stack
+[Each choice with 1-line rationale]
+
+## Data Model
+[Key entities and relationships — tables, fields, types]
+
+## External Integrations
+[APIs, services, and what they're used for]
+
+## MVP Scope
+**In:** [bulleted list of what's included]
+**Deferred:** [bulleted list of what's explicitly NOT in v1]
+
+## Key Decisions
+[Numbered list of decisions made during brainstorming, with brief rationale]
+
+## Open Questions
+[Anything unresolved that architecture or research needs to answer]
+```
+
+Present the document to the user for approval before proceeding.
+
+---
+
+## Autonomous Mode (no user present)
+
+If running in autonomous mode, you cannot ask questions interactively. Instead:
+
+1. Read all available context (build request, existing docs, code).
+2. For each major decision, pick the most pragmatic option and document your rationale.
+3. Bias toward: proven tech, simpler architecture, smaller MVP scope.
+4. Write the Design Document as above.
+5. Log all decisions and rationale to `docs/plans/build-log.md`.
+6. Proceed without user approval.

package/commands/protocols/build-fix.md

@@ -0,0 +1,52 @@
+# Build-Fix Protocol (One Error at a Time)
+
+You are the orchestrator. A build, type-check, or lint check has failed. Do NOT dump all errors on a fix agent. Most build errors cascade — fixing the root cause clears 5-10 downstream errors.
+
+## When to Use
+
+When the Verification Protocol reports FAIL on Build, Type-Check, or Lint checks. Also usable during Phase 3 scaffolding or Phase 4 implementation when builds break.
+
+## Step 1: Extract First Error
+
+Parse the failure output from the verification agent. Extract the FIRST error only:
+- File path
+- Line number (if available)
+- Error message
+
+Ignore all other errors. They are likely cascading from this one.
+
+## Step 2: Fix
+
+Call the Agent tool — description: "Fix [error]" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: S] Fix this single build error. FILE: [path]. LINE: [number]. ERROR: [message]. Fix this specific error. Do not fix other errors. Do not refactor. Commit: 'fix: [error description]'."
+
+> Pass ONLY the single error. Do not show the fix agent the full error log.
+
+## Step 3: Rebuild
+
+Re-run ONLY the failing check (not all 6 verification checks). Count errors in the new output.
+
+## Step 4: Evaluate
+
+- **0 errors:** DONE. Return FIXED to the calling protocol.
+- **Error count decreased:** Log "CASCADE: fixed 1 error, resolved [N] total." Return to Step 1 with the new first error.
+- **Error count same or increased:** The fix was bad. Revert: `git revert HEAD --no-edit`. Try the SECOND error from the original output instead. If already tried 2 different errors, return FAILED.
+- **Iteration count >= 5:** Return PARTIAL with remaining error count.
+
+## Step 5: Report
+
+Return to the orchestrator one of:
+- **FIXED** — all errors resolved
+- **PARTIAL** — [N] errors remain after 5 iterations
+- **FAILED** — could not make progress
+
+---
+
+## Rules
+
+- ONE error per fix agent. Never show a fix agent multiple errors.
+- Revert bad fixes immediately. Do not accumulate broken fixes.
+- Max 5 fix iterations per build-fix invocation.
+- The fix agent is a SEPARATE agent from the verification agent. Fresh context.
+- Track iteration count and error count delta in `docs/plans/.build-state.md`.

package/commands/protocols/cleanup.md

@@ -0,0 +1,56 @@
+# Cleanup Protocol (De-Sloppify)
+
+You are the orchestrator. An implementation agent just finished a task. Before running the metric loop, you run a focused cleanup pass on the changed files.
+
+The insight: two focused agents outperform one constrained agent. The implementer optimizes for "make it work." The cleaner optimizes for "make it right."
+
+## When to Skip
+
+If the implementation was trivial — single config file change, < 20 lines changed total — skip this protocol. The overhead isn't worth it.
+
+## Step 1: Collect the Changeset
+
+Get the authoritative list of files changed by running `git diff --name-only HEAD~1` (or checking the implementation agent's commit). Do not rely solely on the agent's self-reported file list — use git as the source of truth. This is the cleanup scope. Nothing outside this list gets touched.
+
+## Step 2: Invoke the Cleanup Agent
+
+Call the Agent tool — description: "Cleanup [task name]" — mode: "bypassPermissions" — prompt:
+
+"You are a code quality cleanup agent. Your job is to improve code quality in the files listed below WITHOUT changing behavior.
+
+FILES IN SCOPE:
+[list of files changed by the implementer]
+
+ACCEPTANCE CRITERIA (do not break these):
+[paste the task's acceptance criteria]
+
+FIX these issues if you find them:
+- Naming inconsistencies (variables, functions, files)
+- Dead code and unused imports
+- Redundant or duplicate imports
+- Unclear variable or function names
+- Missing error handling
+- Code style violations
+- Obvious DRY violations within the changed files
+
+DO NOT:
+- Add features or change behavior
+- Modify the architecture or file structure
+- Touch files outside the list above
+- Refactor code that wasn't part of this task
+- Modify tests unless fixing a broken assertion caused by the implementer
+
+When finished, commit: 'refactor: cleanup [task name]'."
+
+## Step 3: Verify
+
+After the cleanup agent finishes, spot-check that acceptance criteria still hold. If the cleanup agent broke something, revert its commit and log the issue to `docs/plans/build-log.md`. Then proceed to the metric loop without cleanup.
+
+---
+
+## Rules
+
+- The cleanup agent is a SEPARATE Agent tool call from the implementer. No cleaning your own mess.
+- Scope is sacred. Only files from the implementation changeset. Zero exceptions.
+- This runs AFTER implementation, BEFORE the metric loop.
+- If cleanup breaks acceptance criteria, revert and skip. Never block the metric loop on a cleanup failure.

package/commands/protocols/eval-harness.md

@@ -0,0 +1,62 @@
+# Eval Harness Protocol
+
+You are the orchestrator. Phase 5.1 audits are complete. Before running the metric loop, define formal eval cases that are concrete, executable, and reproducible. This replaces subjective narrative audits with deterministic pass/fail tests.
+
+## How This Differs from the Metric Loop
+
+The metric loop answers "how good is this?" (qualitative score 0-100, iterative improvement).
+The eval harness answers "does this specific behavior work reliably?" (binary pass/fail, deterministic).
+
+They are complementary: eval harness failures become specific issues for the metric loop to fix.
+
+## Step 0: Define Eval Cases
+
+YOU (the orchestrator) define eval cases based on:
+- Audit findings from Phase 5.1 (highest-severity items first)
+- Architecture doc (API contracts, auth model, data validation rules)
+- Design doc (core user flows, edge cases)
+
+Write eval cases to `docs/plans/.build-state.md` under `## Eval Harness`:
+
+| # | Name | Action | Expected Result | pass@k | Severity |
+|---|------|--------|-----------------|--------|----------|
+
+**Severity thresholds (non-negotiable):**
+- CRITICAL: pass@5 (must pass 5/5 — 100% reliability)
+- HIGH: pass@4 (must pass 4/5 — 80% reliability)
+- MEDIUM: pass@3 (must pass 3/5 — 60% reliability)
+
+Aim for 8-15 eval cases. Cover: auth boundaries, input validation, error handling, core happy path, primary edge cases.
+
+**Eval cases must be concrete and executable** — actual commands (curl, function calls, UI interactions), not descriptions. Bad: "Auth should work." Good: "curl -X GET /api/recipes without Authorization header → expect 401."
+
+## Step 1: Run Eval
+
+Call the Agent tool — description: "Run eval harness" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: M] Run these eval cases. For each case, execute the action the specified number of times (k). Report per case: PASS (N/k passed, meets threshold) or FAIL (N/k passed, below threshold). Include the actual result on failures. [paste eval case table]"
+
+<HARD-GATE>
+The eval agent RUNS cases. It does NOT define them. Case definition is the orchestrator's job.
+</HARD-GATE>
+
+## Step 2: Score
+
+Count PASS cases / total cases. This is the eval baseline. Record to `docs/plans/.build-state.md`.
+
+## Step 3: Feed into Metric Loop
+
+Any FAIL case with severity CRITICAL or HIGH becomes a candidate issue for the Phase 5.2 metric loop. Pass the failure details (case name, action, expected vs actual) as context when defining the metric loop's metric.
+
+## Step 4: Re-evaluate After Metric Loop
+
+After the Phase 5.2 metric loop exits, re-run the eval harness. All CRITICAL cases must now pass. If any CRITICAL case still fails, flag it for the Reality Checker in Step 5.3.
+
+---
+
+## Rules
+
+- Eval cases are defined by the ORCHESTRATOR, not by the eval agent.
+- pass@k thresholds are non-negotiable per severity level.
+- Re-run eval after metric loop to verify fixes — this is the exit gate.
+- Eval failures feed into the metric loop as specific, concrete issues — not vague audit findings.

package/commands/protocols/metric-loop.md

@@ -0,0 +1,94 @@
+# Metric Loop Protocol
+
+You are the orchestrator. You are about to run a metric-driven iteration loop on an artifact (code, architecture, docs, etc.) to drive it toward a quality target.
+
+## Step 0: Define Your Metric
+
+Before iterating, YOU define the metric for this specific context. Consider:
+- What is the artifact? (a task implementation, a security audit, an architecture doc, etc.)
+- What does "good" look like? (all tests pass, zero critical vulns, all acceptance criteria met, etc.)
+- Is the metric quantitative (test pass rate, vuln count, coverage %) or qualitative (architecture completeness, doc clarity)?
+
+Write a **Metric Definition** block to `docs/plans/.build-state.md`:
+
+```
+## Active Metric Loop
+Phase: [current phase]
+Artifact: [what you're iterating on]
+Metric: [what you're measuring, in one sentence]
+How to measure: [what the measurement agent should do — run tests, audit code, check criteria, etc.]
+Target: [score 0-100 at which you stop]
+Max iterations: [hard cap, default 5]
+```
+
+Then create a score log table:
+
+```
+| Iter | Score | Delta | Top Issue | Files |
+|------|-------|-------|-----------|-------|
+```
+
+When starting a new metric loop, REPLACE the previous Active Metric Loop section (if any). There is only ever ONE active metric loop. Previous loop results should already be recorded in their phase's section above. When the loop completes (Step 2 exit), rename the section header from `## Active Metric Loop` to `## Completed Metric Loop — [Phase N]` and leave it for historical reference.
+
+If you are in Phase 4, also record the current sub-step for the overall task cycle (not all of these are within the metric loop itself):
+```
+Sub-step: [4.1 Implement | 4.1b Cleanup | 4.2 Metric Loop | 4.3 Loop Exit | 4.4 Verify]
+```
+This tells the orchestrator exactly where to resume after context compaction.
+
+## Step 1: MEASURE
+
+Call the Agent tool — description: "Measure [metric]" — prompt:
+
+"[How to measure, from your metric definition]. Score the current state 0-100. Return your response with a clear SCORE: [number] line, a list of FINDINGS, and the single TOP ISSUE most likely to improve the score if fixed."
+
+Read the agent's response. You need: the SCORE, the TOP ISSUE, and the file paths for diagnosis in Step 3. Record the score to `docs/plans/.build-state.md`. The full findings list is useful for diagnosis but does NOT need to persist in your context across iterations — once you've picked the top issue, the details of lower-priority findings can go. Append a row to the score log in `docs/plans/.build-state.md`:
+
+| Iter | Score | Delta | Top Issue | Files |
+|------|-------|-------|-----------|-------|
+
+## Step 2: CHECK EXIT
+
+Stop the loop if ANY of these:
+
+- **Score >= target** → done. Log "Target met at iteration [N]."
+- **Iteration >= max** → done. Log "Max iterations reached. Final score: [N]."
+- **Stall: last 2 scores show no improvement** (delta <= 0 twice in a row) → done. Log "Stalled at score [N]."
+
+On stall or max iterations:
+- **Interactive mode:** present score history + top remaining issue to user. Ask for direction.
+- **Autonomous mode:** if score >= 60% of target, accept with warning. Otherwise skip. Log to `docs/plans/build-log.md`.
+
+If not exiting, continue to Step 3.
+
+## Step 3: DIAGNOSE
+
+Look at the findings from Step 1. Pick the ONE highest-impact issue — the single fix most likely to move the score. Do not try to fix everything at once. This is the autoresearch insight: one targeted change per iteration, measured impact.
+
+## Step 4: IMPROVE
+
+Call the Agent tool — description: "Fix [top issue]" — mode: "bypassPermissions" — prompt:
+
+"TARGETED FIX: [specific issue to fix, from diagnosis]. CONTEXT: [relevant architecture/criteria]. Make this specific change. Do not refactor unrelated code. Commit: 'fix: [description]'."
+
+> **Do NOT pass the measurement agent's full findings to this agent. Only pass the single diagnosed issue and relevant file paths.**
+
+## Step 5: LOOP
+
+Return to Step 1. Re-measure the artifact after the fix.
+
+---
+
+## Rules
+
+<HARD-GATE>
+AUTHOR-BIAS ELIMINATION: The measurement agent and the fix agent must NEVER share context.
+- They MUST be separate Agent tool calls (separate subprocesses, separate context windows).
+- The fix agent receives ONLY: (a) the single top issue diagnosed in Step 3, (b) the relevant file paths, (c) the acceptance criteria. It does NOT receive the measurement agent's full findings, score breakdown, or other issues.
+- The measurement agent in the next iteration does NOT know what the fix agent did — it measures the artifact fresh.
+- Rationale: When a reviewer shares context with an implementer, the implementer unconsciously optimizes for the reviewer's framing rather than actual quality.
+</HARD-GATE>
+- One fix per iteration. Measure its impact before fixing the next thing.
+- Track ALL scores in `docs/plans/.build-state.md` so the history survives context compaction.
+- If context was compacted mid-loop: read `docs/plans/.build-state.md`, find the Active Metric Loop section, resume from the last recorded iteration.
+- CONTEXT HYGIENE: Measurement agents are analysis agents — read their full output for diagnosis. But once you've picked the top issue (Step 3) and dispatched the fix (Step 4), the detailed findings from THAT iteration are spent. Don't accumulate findings across iterations — each measurement is fresh.

package/commands/protocols/planning.md

@@ -0,0 +1,56 @@
+# Planning Protocol
+
+You are the orchestrator converting a validated Design Document and Architecture Document into an ordered, developer-ready task list.
+
+## Input
+
+You need two documents before running this protocol:
+- **Design Document** (`docs/plans/YYYY-MM-DD-[topic]-design.md`) — scope, user flows, data model, tech stack
+- **Architecture Document** (`docs/plans/architecture.md`) — services, API contracts, database schema, component tree
+
+## Step 1: Break Down
+
+Decompose the architecture into ordered, atomic tasks. Each task must be:
+
+- **Implementable independently** — a developer agent can build it without needing unfinished work from other tasks
+- **Testable** — there are concrete acceptance criteria that can be verified
+- **Scoped to MVP** — if the design doc says a feature is deferred, do not create tasks for it
+
+For each task:
+
+```
+### Task [N]: [name]
+**Type:** frontend / backend / integration / infrastructure
+**Description:** [what to build, 2-3 sentences]
+**Acceptance Criteria:**
+- [ ] [specific, verifiable criterion]
+- [ ] [specific, verifiable criterion]
+**Dependencies:** [task numbers that must complete first, or "none"]
+**Size:** S (< 1 hour) / M (1-3 hours) / L (3+ hours)
+```
+
+## Step 2: Order
+
+Order tasks by dependency chain, then by priority within each dependency level:
+
+1. Infrastructure/scaffolding first (project setup, database schema, base config)
+2. Core data model and API endpoints
+3. Primary user flow (the main thing the user does)
+4. Supporting features
+5. Polish, error handling, edge cases
+
+Flag any circular dependencies — these indicate an architecture problem that needs resolution before building.
+
+## Step 3: Validate
+
+Check the task list against the design doc:
+
+- Every feature in MVP scope has at least one task
+- No task exceeds the MVP boundary
+- No task is too large (L tasks should be split if possible)
+- Dependency chains are no deeper than 3 levels
+- Acceptance criteria are specific enough that a developer agent can verify them without ambiguity
+
+## Step 4: Save
+
+Save to `docs/plans/sprint-tasks.md`.

package/commands/protocols/verify.md

@@ -0,0 +1,63 @@
+# Verification Protocol
+
+You are the orchestrator. You are about to run a deterministic verification gate — a fast, sequential pass/fail check that catches regressions before expensive audit agents run.
+
+## When to Run
+
+Run this protocol at every phase boundary: after scaffolding, after each task, before final review. It is cheap. Run it often.
+
+## Step 1: Detect Stack
+
+Before running checks, detect the project's stack from manifest files:
+
+| Manifest | Stack | Build | Types | Lint | Test | Security |
+|----------|-------|-------|-------|------|------|----------|
+| `package.json` | Node | `npm run build` | `npx tsc --noEmit` | `npm run lint` | `npm test` | `npm audit` |
+| `requirements.txt` / `pyproject.toml` | Python | — | `mypy .` | `ruff check .` | `pytest` | `pip audit` |
+| `go.mod` | Go | `go build ./...` | (included in build) | `golangci-lint run` | `go test ./...` | `govulncheck ./...` |
+| `Cargo.toml` | Rust | `cargo build` | (included in build) | `cargo clippy` | `cargo test` | `cargo audit` |
+
+Skip any check that does not apply (e.g., skip Build for a pure Python script, skip Type-Check for JavaScript without TypeScript). A skipped check counts as PASS.
+
+## Step 2: Run Checks Sequentially
+
+Call the Agent tool — description: "Verify [phase name]" — mode: "bypassPermissions" — prompt:
+
+"Run the Verification Protocol. Execute all 6 checks sequentially, stop on first failure. Report: VERIFY: PASS (6/6) or VERIFY: FAIL at step [N] — [check name]: [reason]."
+
+The agent runs these checks in order, stopping on the first FAIL:
+
+| # | Check | What it does |
+|---|-------|-------------|
+| 1 | Build | Project compiles/bundles without errors |
+| 2 | Type-Check | No type errors (tsc, mypy, etc.) |
+| 3 | Lint | No lint violations |
+| 4 | Test | All tests pass |
+| 5 | Security | No known vulnerabilities in deps |
+| 6 | Diff Review | `git diff` of uncommitted changes — no debug code, no secrets, no obvious regressions |
+
+<HARD-GATE>
+ONE AGENT, ONE PASS: The orchestrator spawns exactly ONE agent for the entire verification. This is a single Agent tool call, not 6 separate agents. The agent runs each check as a sequential shell command and evaluates the result before proceeding.
+</HARD-GATE>
+
+## Step 3: Handle Result
+
+**On PASS:** Log `VERIFY: PASS (6/6)` to `docs/plans/.build-state.md`. Proceed to next phase.
+
+**On FAIL:** Read the failure reason and spawn a targeted fix agent:
+
+| Failed Check | Fix Strategy |
+|-------------|-------------|
+| Build / Type-Check / Lint | Run the Build-Fix Protocol (`commands/protocols/build-fix.md`). It isolates the first error, fixes it, rebuilds, detects cascade resolution, and reverts bad fixes automatically. |
+| Test | Spawn fix agent: "Fix the failing test: [test name]. Read the test, read the implementation, fix the implementation — not the test — unless the test is wrong." |
+| Security | Spawn fix agent: "Resolve vulnerability: [advisory]. Update the dependency or apply the recommended remediation." |
+| Diff Review | Spawn fix agent: "Remove debug code / hardcoded secrets / regressions found in diff review: [details]." |
+
+After the fix agent completes, re-run verification from Step 2.
+
+<HARD-GATE>
+MAX 3 FIX ATTEMPTS: If verification fails 3 times on the same phase:
+- **Interactive mode:** present the failure history to the user. Ask for direction.
+- **Autonomous mode:** log the failure to `docs/plans/build-log.md` and proceed with a warning.
+Do not loop forever.
+</HARD-GATE>

package/hooks/hooks.json

@@ -14,11 +14,11 @@
     ],
     "PreCompact": [
       {
-        "matcher": "",
+        "matcher": ".*",
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "ORCHESTRATOR STATE SAVE — Context is about to be compacted. If you are running the /buildanything:build pipeline, you MUST do these things NOW before your context is lost:\n\n1. Use TodoWrite to update all task statuses (complete, in-progress, pending)\n2. Write `docs/plans/.build-state.md` with: current phase, step, task progress, retry counter, agents used, pending quality gate results\n3. The next thing that will happen after compaction is the SessionStart hook will fire and re-inject your orchestrator identity. But you MUST save state NOW or your progress tracking is lost."
+            "prompt": "ORCHESTRATOR STATE SAVE — Context is about to be compacted. If you are running the /buildanything:build pipeline, you MUST do these things NOW before your context is lost:\n\n1. Save all task statuses to docs/plans/.build-state.md (TodoWrite does NOT survive compaction — .build-state.md is your only persistent store)\n2. Write `docs/plans/.build-state.md` with ALL of the following:\n   - Current phase and step\n   - Task progress (which tasks done, which in progress)\n   - If you are in a metric loop: the Active Metric Loop section with metric definition, current iteration, full score history table, and what action to take next\n   - Agents used so far\n   - Whether running in autonomous mode\n   - dispatches_since_save and last_save values\n3. The next thing after compaction is the SessionStart hook re-injecting your state. Save EVERYTHING or you lose your metric loop progress."
           }
         ]
       }

package/hooks/session-start

@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
 # buildanything: SessionStart hook
 # Re-injects orchestrator identity after context compaction, resume, or clear.
-# Modeled after superpowers' session-start pattern.
 
 # Check if a build pipeline is active by looking for .build-state.md
 BUILD_STATE=""
@@ -9,20 +8,58 @@ if [ -f "docs/plans/.build-state.md" ]; then
   BUILD_STATE=$(cat "docs/plans/.build-state.md")
 fi
 
+# Skip if the build is already complete
+if echo "$BUILD_STATE" | grep -q "Phase: 6 COMPLETE"; then
+  BUILD_STATE=""
+fi
+
 # If no active build, just provide a minimal reminder
 if [ -z "$BUILD_STATE" ]; then
   CONTEXT="buildanything plugin is installed. Use /buildanything:build to start a full product pipeline, or /buildanything:idea-sweep for parallel research."
 else
-  # Active build detected — re-inject full orchestrator context
+  # Check if there's an active metric loop
+  METRIC_LOOP=""
+  if echo "$BUILD_STATE" | grep -q "Active Metric Loop"; then
+    METRIC_LOOP="
+ACTIVE METRIC LOOP DETECTED — You were mid-iteration when context compacted.
+1. Read commands/protocols/metric-loop.md to reload the loop protocol
+2. Find the 'Active Metric Loop' section in .build-state.md for your metric definition and score history
+3. Resume from the iteration indicated in the score log table
+4. Do NOT restart the loop from scratch — continue where you left off"
+  fi
+
+  # Check for resume point
+  RESUME_POINT=""
+  if echo "$BUILD_STATE" | grep -q "Resume Point"; then
+    RESUME_POINT="
+RESUME POINT DETECTED — This build can be continued with /buildanything:build --resume.
+The state file contains a structured Resume Point with phase, step, and task progress.
+Reset dispatches_since_save to 0 (fresh context window)."
+  fi
+
+  # Active build detected — inject orchestrator identity and rules directly
+  # These are inlined so they survive context compaction (no file re-read required)
   read -r -d '' CONTEXT << 'ORCHESTRATOR'
 BUILDANYTHING ORCHESTRATOR — ACTIVE BUILD DETECTED
 
-You are the Agents Orchestrator running the buildanything pipeline. You are NOT a solo developer. You coordinate specialist agents.
+<HARD-GATE>
+YOU ARE AN ORCHESTRATOR. YOU COORDINATE AGENTS. YOU DO NOT WRITE CODE.
+Every step below tells you to call the Agent tool. DO IT. Do not role-play as the agent. Do not write implementation code yourself. Do not skip the Agent tool call "because it's faster."
+"Launch an agent" = call the Agent tool (the actual tool in your toolbar, the one that spawns a subprocess).
+For implementation agents, set mode: "bypassPermissions".
+For parallel work, put multiple Agent tool calls in ONE message.
+</HARD-GATE>
+
+ORCHESTRATOR DISCIPLINE:
+YOU ARE A DISPATCHER, NOT A DOER. Your context is precious — protect it.
+- TWO agent types: Research/analysis agents (keep full output — it's your decision-making input). Implementation agents (keep summary only — the code is in the repo).
+- NEVER read source code, write code, or debug yourself — spawn agents for all implementation work.
+- Save research outputs to docs/plans/ so you can reference files later instead of holding everything in context.
 
 CRITICAL RULES:
-1. You do NOT write implementation code yourself — you dispatch to specialist agents
+1. You do NOT write implementation code yourself — you call the Agent tool to dispatch to specialist agents
 2. You follow phase gates — no advancing without quality gate approval
-3. Every task goes through Dev→Test→Review loops
+3. Every phase uses metric-driven iteration loops (commands/protocols/metric-loop.md)
 4. You must re-read commands/build.md if you are unsure of the process
 
 YOUR CURRENT STATE (from docs/plans/.build-state.md):
@@ -30,12 +67,19 @@ ORCHESTRATOR
 
   CONTEXT="${CONTEXT}
 ${BUILD_STATE}
+${METRIC_LOOP}
+${RESUME_POINT}
 
 NEXT ACTIONS:
 1. Re-read commands/build.md to reload the full orchestrator process
-2. Resume from the phase and step indicated in your state above
-3. Use TodoWrite to track task progress
-4. Dispatch work to specialist agents — do not implement directly"
+2. Re-read commands/protocols/metric-loop.md if you are mid-loop
+3. Re-read docs/plans/sprint-tasks.md for task list and acceptance criteria
+4. Re-read docs/plans/architecture.md for architecture context
+5. Re-read CLAUDE.md for build decisions
+6. Re-read docs/plans/learnings.md if it exists (patterns and pitfalls from previous builds)
+7. Rebuild TodoWrite from docs/plans/.build-state.md (TodoWrite does NOT survive compaction)
+8. Resume from the phase and step indicated in your state above
+9. Dispatch work to specialist agents — do not implement directly"
 fi
 
 # Output as additional_context for Claude Code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildanything",
-  "version": "1.2.1",
+  "version": "1.5.0",
   "description": "One command to build an entire product. 73 specialist agents orchestrated into a full engineering pipeline for Claude Code.",
   "bin": {
     "buildanything": "./bin/setup.js"