buildanything 1.2.1 → 1.6.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 4 scaffolding or Phase 5 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/design.md

@@ -0,0 +1,287 @@
+# Design & Visual Identity Protocol
+
+You are the orchestrator. Phase 2 (Architecture) is complete. Before building anything, you must establish a research-backed visual design system. This phase is a FULL PEER to Architecture and Build — not a footnote.
+
+## Why This Phase Exists
+
+UI/UX is the first thing a user experiences. A structurally sound app with ugly UI fails. A beautiful app with minor bugs succeeds. Design is not decoration — it is the product.
+
+Top design firms (Pentagram, Work & Co, Clay, Metalab) treat design as its own phase with its own research, iteration, and quality gates. This protocol replicates that process: Discovery → Direction → Prototyping → Visual QA.
+
+---
+
+## Step 3.1 — Design Research (2 agents, parallel, both use Playwright)
+
+Launch 2 agents in ONE message. Both MUST use Playwright to capture real screenshots — text descriptions of competitor sites are insufficient. Downstream agents need visual references.
+
+**Agent 1: "Competitive visual audit"**
+
+```
+You are a senior visual design researcher. Find the top 5-8 competitors or analogues for: [product description from design doc].
+
+For each competitor:
+1. Use Playwright to navigate to their site
+2. Take full-page screenshots (desktop 1920x1080 + mobile 375x812)
+3. Screenshot standout components: hero sections, cards, forms, navigation, CTAs, footer
+4. Save all screenshots to docs/plans/design-references/competitors/[site-name]/
+
+Analyze each site's visual language:
+- Color palette (extract dominant colors)
+- Typography choices (font families, scale, weight usage)
+- Spacing rhythm (generous vs compact, section padding)
+- Component style (shadows, borders, radius, elevation)
+- What makes it feel premium or cheap?
+- What would you steal vs avoid?
+
+Output: Ranked analysis by visual quality and relevance. Include screenshot paths.
+```
+
+**Agent 2: "Design inspiration mining"**
+
+```
+You are a senior visual design researcher. Search Awwwards.com, Godly.website, and SiteInspire for award-winning sites in the category: [product category — SaaS, developer tool, e-commerce, marketplace, etc.].
+
+For the top 5-8 results:
+1. Use Playwright to navigate and take full-page screenshots (desktop + mobile)
+2. Screenshot standout components and interactions worth referencing
+3. Save all screenshots to docs/plans/design-references/inspiration/[site-name]/
+
+Identify cross-cutting patterns:
+- What do the best-in-class sites have in common?
+- What visual trends dominate this category right now?
+- What separates "Awwwards worthy" from "generic template"?
+- What specific techniques create the premium feel? (spacing, typography, animation, color)
+
+Output: Trend analysis with specific adoptable patterns and anti-patterns to avoid. Include screenshot paths.
+```
+
+After both return, synthesize a **Design Research Brief** saved to `docs/plans/design-research.md`. Include all screenshot paths for downstream agent reference.
+
+---
+
+## Step 3.2 — Design Direction (2 agents, sequential)
+
+The UI Designer makes ALL decisions autonomously. No "Direction A vs B" presentations. Pick the best based on the research.
+
+**Agent 1: UX Architect**
+
+```
+You are the UX Architect. Create the structural design foundation.
+
+INPUTS:
+- Architecture doc (frontend section): [paste]
+- Design Research Brief: [paste from docs/plans/design-research.md]
+- Reference screenshots: [list paths from docs/plans/design-references/]
+- User persona from Phase 1 research: [paste relevant section]
+
+OUTPUT a UX Foundation document:
+1. Information architecture and content hierarchy
+2. User flow diagrams for core interactions
+3. Layout strategy — which pages use which layout patterns, informed by what worked in the research
+4. Component hierarchy — what components exist, how they compose
+5. Responsive breakpoint strategy (mobile-first)
+6. Navigation patterns
+7. Interaction patterns: hover, focus, loading, error, empty, success states
+
+Base layout and flow decisions on what performed best in the competitive analysis — not generic patterns.
+```
+
+**Agent 2: UI Designer**
+
+```
+You are the UI Designer. Create the Visual Design Spec.
+
+INPUTS:
+- UX Foundation from UX Architect: [paste full output]
+- Design Research Brief: [paste from docs/plans/design-research.md]
+- Reference screenshots: [list paths from docs/plans/design-references/]
+- User persona: [paste relevant section]
+
+Make AUTONOMOUS decisions. Do not present options. Pick the single best direction based on the research.
+
+OUTPUT a Visual Design Spec covering:
+
+1. **Color System** — Primary, secondary, accent, semantic (success/warning/error/info), neutral palette. Full hex values for light AND dark themes. Rationale tied to research: "competitor X uses muted blues; we differentiate with warm neutrals because our persona values approachability."
+
+2. **Typography System** — Font families (from Google Fonts or system fonts), size scale using a mathematical ratio (Major Third 1.25 or Perfect Fourth 1.333), weights, line heights (body: 1.5-1.6x, headings: 1.1-1.3x), letter spacing adjustments. MAX 2 font families.
+
+3. **Spacing System** — 8px base unit. Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128px. Rule: internal component padding MUST be less than external margin between components (Gestalt proximity principle).
+
+4. **Shadow & Elevation** — Layered shadow system using tinted shadows (NOT pure black — e.g., rgba(0,0,50,0.08) instead of rgba(0,0,0,0.1)). Ambient shadow + key shadow per elevation level. Levels: flat, raised (cards), elevated (dropdowns), overlay (modals), top (tooltips).
+
+5. **Border Radius** — ONE primary radius for the entire app (pick 4px, 6px, 8px, or 12px and justify). Pill radius for tags/badges only.
+
+6. **Animation & Motion** — Easing functions (ease-out for entrances, ease-in for exits, ease-in-out for transitions). Duration scale: micro 150ms, normal 300ms, emphasis 500ms. Stagger timing for lists: 30-50ms between items. Respect prefers-reduced-motion.
+
+7. **Component Styles** — For each component (buttons, inputs, cards, badges, navigation, modals, alerts, tables):
+   - ALL states: default, hover, active, focus-visible, disabled, loading
+   - Exact CSS properties: background, color, border, shadow, padding, font-size, font-weight, border-radius, transition
+
+8. **Design Rationale** — For EVERY major decision, cite the research. "The top 3 Awwwards sites in this category use geometric sans-serifs with high x-heights. Competitor Y uses Inter which is ubiquitous. We chose Space Grotesk to differentiate while maintaining the same readability characteristics."
+
+ANTI-AI-TEMPLATE RULES:
+Your design MUST NOT fall into the generic AI aesthetic. Penalize yourself if 3+ of these appear together:
+- Purple-to-blue or purple-to-pink gradient hero backgrounds
+- Floating mesh/blob gradient decorative elements
+- Inter or Plus Jakarta Sans as the font choice (unless research specifically justifies it)
+- 3-column icon + heading + paragraph feature grids as the primary content pattern
+- Glassmorphism/frosted glass as the primary design language
+- Bento grid as default layout
+- Dark mode + neon accents as the "premium" look
+- Generic illustration pack imagery (Undraw, Humaaans style)
+- Perfect symmetry everywhere with no visual tension or personality
+
+ONE or two of these in isolation is fine IF the research supports it. THREE or more together = AI template smell. Every visual choice must be JUSTIFIED by the research, not by framework defaults.
+
+Save output to docs/plans/visual-design-spec.md.
+```
+
+---
+
+## Step 3.3 — Proof Screens (1 implementation agent)
+
+```
+[COMPLEXITY: L] Implement 2-3 proof screens — the most visually demanding pages in this product:
+
+1. Landing page / hero section (the first impression)
+2. Main app view (dashboard, feed, workspace — the core experience)
+3. A form or interactive component (sign up, settings, creation flow)
+
+INPUTS:
+- Visual Design Spec: [paste from docs/plans/visual-design-spec.md]
+- UX Foundation: [paste relevant layout and component sections]
+- Reference screenshots: [list paths from docs/plans/design-references/ — these are your visual targets]
+
+REQUIREMENTS:
+- Real, styled, responsive pages. NOT wireframes or skeletons.
+- Use the EXACT colors, fonts, spacing, shadows from the Visual Design Spec. Do not deviate.
+- Include hover states, focus states, transitions, loading states.
+- Mobile-responsive at 375px, 768px, 1024px, 1280px breakpoints.
+- These screens PROVE the design system works. They must look like they belong next to the Awwwards references from the research.
+
+Commit: 'feat: proof screens for design validation'
+```
+
+---
+
+## Step 3.4 — Visual QA Loop (Playwright + Metric Loop)
+
+Run the Metric Loop Protocol (`commands/protocols/metric-loop.md`).
+
+**Metric definition for `.build-state.md`:**
+
+```
+## Active Metric Loop
+Phase: 3
+Artifact: Proof screens (landing page, main app view, form/interaction)
+Metric: Visual design quality — implementation fidelity to Visual Design Spec + competitive quality relative to Awwwards/competitor references
+How to measure: Playwright screenshots of proof screens (desktop 1920x1080 + mobile 375x812), scored by design critic agent across 6 dimensions
+Target: 80
+Max iterations: 5
+```
+
+**Measurement agent prompt:**
+
+```
+You are a senior design critic at a top-tier agency (Pentagram, Work & Co). You are reviewing a product's visual implementation for quality.
+
+INPUTS:
+- Screenshots of current proof screens: [Playwright captures — desktop + mobile]
+- The Visual Design Spec the implementation should follow: [paste from docs/plans/visual-design-spec.md]
+- Reference screenshots from competitors and Awwwards winners: [paths in docs/plans/design-references/]
+
+Score 0-100 across these 6 dimensions (weight equally, average for final score):
+
+1. **Spacing & Alignment (0-100)**
+   - Is the 8px grid respected consistently?
+   - Do elements breathe? Generous whitespace between sections (hero padding 120-200px, not 40px)?
+   - Internal component padding < external margin between components (Gestalt proximity)?
+   - Visual grouping through whitespace, not just borders?
+
+2. **Typography Hierarchy (0-100)**
+   - Clear 3-4 levels of visual hierarchy?
+   - Consistent type scale from the spec applied?
+   - Proper line heights (body: 1.5-1.6x, headings: 1.1-1.3x)?
+   - Font weight contrast used effectively (not just size)?
+   - Letter spacing appropriate for context?
+
+3. **Color Harmony (0-100)**
+   - Cohesive palette matching the spec?
+   - 60-30-10 rule (60% neutral, 30% secondary, 10% accent)?
+   - WCAG AA contrast ratios (4.5:1 body, 3:1 large text)?
+   - Shadows tinted not pure black?
+   - Colors slightly desaturated (refined, not garish)?
+
+4. **Component Polish (0-100)**
+   - Hover states present and smooth?
+   - Focus-visible indicators for keyboard nav?
+   - Consistent border radius throughout?
+   - Shadow/elevation system applied per spec?
+   - Transitions feel intentional (not instant, not sluggish)?
+   - Loading/empty states considered?
+
+5. **Responsive Quality (0-100)**
+   - Mobile layout functional and readable at 375px?
+   - No horizontal scroll on any breakpoint?
+   - Touch targets 44px+ on mobile?
+   - Layout ADAPTS (not just stacks) — different patterns per breakpoint?
+   - Images and media scale properly?
+
+6. **Originality (0-100)**
+   - Does this look DESIGNED or GENERATED?
+   - Penalize heavily if 3+ of these appear together:
+     * Purple/blue gradient hero background
+     * Floating blob/mesh gradient decorations
+     * Inter or Plus Jakarta Sans as the only font
+     * 3-column icon+heading+paragraph feature grids
+     * Glassmorphism cards as primary style
+     * Bento grid as default layout
+     * Dark mode + neon accents aesthetic
+     * Generic illustration pack imagery
+     * Perfect symmetry everywhere, no visual tension
+   - One or two in isolation is fine. Three+ together = "AI template" smell.
+   - The test: would a human designer say "this was made by AI"?
+   - Does the design have personality and point of view?
+
+Return format:
+SCORE: [average of 6 dimensions, rounded to nearest integer]
+DIMENSION SCORES: [list each dimension with its score]
+TOP ISSUE: [the single highest-impact change that would most improve the overall score]
+FINDINGS: [detailed list of specific issues, each with the file path and line/component where the fix should happen]
+```
+
+**Fix agent receives:** ONLY the top issue + relevant file paths + the relevant Visual Design Spec section. One fix per iteration. Commit each fix.
+
+**Exit conditions (from metric-loop protocol):**
+- Score >= 80 → proceed to Phase 4
+- Stall (2 consecutive delta <= 0) → accept if score >= 65, log warning below 65
+- Max 5 iterations → accept if score >= 65, log warning below 65
+
+---
+
+## Step 3.5 — Autonomous Quality Gate
+
+Log to `docs/plans/build-log.md`:
+- Final proof screen screenshot paths
+- Score history table from the metric loop
+- Key design decisions and their research rationale
+- Anti-AI-template dimension score
+
+No user pause. Proceed to Phase 4 (Foundation).
+
+---
+
+## Rules
+
+<HARD-GATE>
+DESIGN RESEARCH IS NOT OPTIONAL. Step 3.1 agents MUST use Playwright to capture real screenshots of real competitor and inspiration sites. Text-only descriptions of "what their site looks like" are INSUFFICIENT — downstream agents need visual references to make informed decisions and the Visual QA measurement agent needs them for comparison.
+
+If Playwright is unavailable: log as blocker, use web search to find and describe competitors in maximum visual detail, proceed with degraded quality. But TRY Playwright first.
+</HARD-GATE>
+
+- The UI Designer agent makes ALL visual decisions autonomously. No "pick A or B" presentations. The research provides the evidence; the agent makes the call.
+- The Visual Design Spec MUST include research rationale for every major decision. Unjustified defaults are a design failure.
+- The anti-AI-template checklist is a SCORING DIMENSION (Originality), not a hard blocker. The goal is awareness and intentional differentiation, not rigid prohibition of any single element.
+- Proof screens are REAL implementations with real CSS/components, not mockups or wireframes. They must work responsively.
+- The Visual QA loop is the primary quality control — no human reviews the design. The 80/100 threshold IS the taste arbiter. Treat it seriously.
+- Screenshot data stays in measurement agents' context (separate subprocess). Do NOT load screenshots into the orchestrator's context — receive only the SCORE and TOP ISSUE as text.

package/commands/protocols/eval-harness.md

@@ -0,0 +1,62 @@
+# Eval Harness Protocol
+
+You are the orchestrator. Phase 6.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 6.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 6.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 6.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 6.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 5, also record the current sub-step for the overall task cycle (not all of these are within the metric loop itself):
+```
+Sub-step: [5.1 Implement | 5.1b Cleanup | 5.2 Metric Loop | 5.3 Loop Exit | 5.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.