buildanything 1.5.0 → 1.6.0

package/agents/design-ui-designer.md

@@ -223,6 +223,34 @@ You are **UI Designer**, an expert user interface designer who creates beautiful
 }
 ```
 
+## Anti-AI-Template Design Rules
+
+<HARD-GATE>
+Your design must demonstrate intentional, research-backed choices — not framework defaults. Penalize yourself if 3+ of these appear together in your output:
+
+- 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 competitive 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 pattern
+- Dark mode + neon accents as the "premium" aesthetic
+- Generic illustration pack imagery (Undraw, Humaaans style)
+- Perfect symmetry everywhere with no visual tension or personality
+
+ONE or two in isolation is fine IF research supports it. THREE or more together = AI template smell.
+
+Every visual choice must be JUSTIFIED by competitive research or design inspiration analysis. "I chose X because..." not "X is the default."
+</HARD-GATE>
+
+## Research-Driven Design
+
+When provided with a Design Research Brief and reference screenshots:
+- Study the competitor and inspiration screenshots BEFORE making any visual decisions
+- Cite specific references in your rationale: "The top 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 readability."
+- Differentiate from competitors — don't copy them. Use the research to understand the visual landscape, then find your own position within it.
+- The goal: a human designer would NOT say "this was generated by AI."
+
 ## 🔄 Your Workflow Process
 
 ### Step 1: Design System Foundation

package/agents/design-ux-architect.md

@@ -292,6 +292,16 @@ document.addEventListener('DOMContentLoaded', () => {
 - **Cards**: Subtle hover effects, clear clickable areas
 ```
 
+## Research-Driven Architecture
+
+When provided with a Design Research Brief and competitor/inspiration screenshots:
+- Study reference screenshots BEFORE making structural decisions
+- Base layout strategy on what performed best in the competitive analysis — not generic patterns
+- If the top competitors all use a specific navigation pattern or layout approach, acknowledge it and either adopt (with justification) or consciously differentiate
+- Information architecture should reflect how the best sites in this category organize content
+- Component hierarchy should consider what components the reference sites use effectively
+- Your structural decisions directly influence the visual quality downstream — poor IA creates ugly interfaces regardless of visual polish
+
 ## 🔄 Your Workflow Process
 
 ### Step 1: Analyze Project Requirements

package/commands/build.md

@@ -91,7 +91,7 @@ When spawning agents in sequence (e.g., architect → implementer → reviewer),
 2. **Previous agent's output** — what the upstream agent produced (if any)
 3. **Acceptance criteria** — what "done" looks like for THIS agent
 
-For implementation agents (Phase 4+): Do NOT paste the entire Design Document or Architecture Document. Extract the relevant sections only. For research and architecture agents (Phases 1-2): pass the full document — these agents need complete context to do their analysis.
+For implementation agents (Phase 5+): Do NOT paste the entire Design Document or Architecture Document. Extract the relevant sections only. For research and architecture agents (Phases 1-2): pass the full document — these agents need complete context to do their analysis.
 
 ### Complexity Routing (Advisory)
 
@@ -169,7 +169,7 @@ Autonomous mode: Log checklist to `docs/plans/build-log.md`. Create `.env.exampl
 ### Step 0.3 — Initialize
 
 0. Create `docs/plans/` directory if it doesn't exist (greenfield projects won't have it).
-1. Create a TodoWrite checklist with Phases 0-6.
+1. Create a TodoWrite checklist with Phases 0-7.
 2. Create `docs/plans/.build-state.md` as a single write with ALL of the following: phase and step (`Phase: 0 — Starting`), input (`[build request]`), context level (`[classification]`), prerequisites (`[status]`), dispatch counter (`dispatches_since_save: 0, last_save: Phase 0`), and a `## Resume Point` section with: phase, step, autonomous mode flag, completed tasks (none), git branch name.
 3. Go to Phase 1 (or Phase 2 if context level is "Full design").
 
@@ -294,21 +294,79 @@ Update TodoWrite and `docs/plans/.build-state.md`.
 
 ---
 
-## Phase 3: Foundation
+## Phase 3: Design & Visual Identity
 
-### Step 3.1 — Scaffolding
+**Goal**: Transform architecture into a research-backed visual design system, proven with Playwright screenshots. Fully autonomous — agents research, decide, and iterate without user input.
+
+**Skip if** the project has no user-facing frontend (CLI tools, pure APIs, backend services).
+
+<HARD-GATE>
+UI/UX IS THE PRODUCT. This phase is a full peer to Architecture and Build — not a footnote, not an afterthought, not a "nice to have." Do NOT skip, compress, or rush this phase for any reason. The agents must research real competitors and award-winning sites, make deliberate visual choices backed by that research, build proof screens, and iterate with Playwright-verified visual QA before a single line of product code is written.
+
+Phase 4 (Foundation) WILL NOT START without `docs/plans/visual-design-spec.md`. If it does not exist, return here.
+</HARD-GATE>
+
+### Step 3.1 — Design Research (2 agents, parallel, both use Playwright)
+
+Follow the Design Protocol (`commands/protocols/design.md`), Step 3.1.
+
+Call the Agent tool 2 times in one message:
+
+1. Description: "Competitive visual audit" — Prompt: "Research the top 5-8 competitors/analogues for: [product description]. Use Playwright to screenshot each site (desktop 1920x1080 + mobile 375x812). Screenshot standout components (hero, cards, forms, nav, CTAs). Save to docs/plans/design-references/competitors/. Analyze visual language: colors, typography, spacing, what feels premium vs cheap. Rank by visual quality. DESIGN DOC: [paste]."
+
+2. Description: "Design inspiration mining" — Prompt: "Search Awwwards.com, Godly.website, SiteInspire for award-winning sites in category: [product category]. Use Playwright to screenshot top 5-8 results + standout components. Save to docs/plans/design-references/inspiration/. Identify visual trends, what separates best-in-class from generic. DESIGN DOC: [paste]."
+
+After both return, synthesize a **Design Research Brief** to `docs/plans/design-research.md`. Include all screenshot paths.
+
+### Step 3.2 — Design Direction (2 agents, sequential)
+
+Follow the Design Protocol (`commands/protocols/design.md`), Step 3.2.
+
+1. Call the Agent tool — description: "UX architecture" — Prompt: "Create structural design foundation. INPUTS: frontend architecture section from architecture.md [paste], Design Research Brief [paste], reference screenshot paths [list], user persona [paste]. OUTPUT: information architecture, layout strategy, component hierarchy, responsive approach, interaction patterns. Base decisions on competitive research, not generic patterns."
+
+2. Call the Agent tool — description: "Visual design spec" — Prompt: "Create the Visual Design Spec with AUTONOMOUS decisions — pick the single best direction, do not present options. INPUTS: UX foundation [paste previous output], Design Research Brief [paste], reference screenshot paths [list], user persona [paste]. OUTPUT: color system (with hex, light+dark), typography (Google Fonts, mathematical scale), 8px spacing system, tinted shadow system, border radius, animation/motion, component styles with ALL states. Every choice must cite the research. Apply anti-AI-template rules from the Design Protocol. Save to docs/plans/visual-design-spec.md."
+
+### Step 3.3 — Proof Screens (1 implementation agent)
+
+Call the Agent tool — description: "Build proof screens" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: L] Implement 2-3 proof screens (landing/hero, main app view, key form). INPUTS: Visual Design Spec [paste], UX foundation [paste relevant sections], reference screenshots [list paths — these are your visual targets]. Use EXACT colors, fonts, spacing from spec. Real styled responsive pages, not wireframes. Include hover/focus states, transitions. 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`) using the measurement criteria from the Design Protocol (`commands/protocols/design.md`, Step 3.4).
+
+Measurement: Playwright screenshots of proof screens (desktop + mobile). Design critic agent scores 0-100 across 6 dimensions: spacing/alignment, typography hierarchy, color harmony, component polish, responsive quality, originality (anti-AI-template check). Receives screenshots + Visual Design Spec + reference screenshots.
+
+**Target: 80. Max 5 iterations.** On stall: accept if >= 65, log warning below 65.
+
+### Step 3.5 — Autonomous Quality Gate
+
+Log to `docs/plans/build-log.md`: final screenshot paths, score history table, design decisions, originality score. No user pause. Proceed to Phase 4.
+
+**Compaction checkpoint:** Check `dispatches_since_save` in `docs/plans/.build-state.md`. If >= 8: save ALL state (current phase, task statuses, metric loop scores, decisions) to `docs/plans/.build-state.md`. Reset `dispatches_since_save` to 0. TodoWrite does NOT survive compaction — rebuild it from this state file on resume.
+
+---
+
+## Phase 4: Foundation
+
+<HARD-GATE>
+Before starting Phase 4: Phase 2 must be approved AND Phase 3 must have produced `docs/plans/visual-design-spec.md`.
+If visual-design-spec.md does not exist, DO NOT PROCEED. Return to Phase 3.
+Step 4.2 (Design System) MUST implement from visual-design-spec.md — not generic architecture tokens.
+</HARD-GATE>
+
+### Step 4.1 — Scaffolding
 
 Call the Agent tool — description: "Project scaffolding" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: M] Set up the project from this architecture: [paste]. Create directory structure, dependencies, build tooling, linting config, test framework with one passing test, .gitignore, .env.example. Commit: 'feat: initial scaffolding'."
 
-### Step 3.2 — Design System (frontend only)
+### Step 4.2 — Design System (frontend only)
 
-Call the Agent tool — description: "Design system setup" — mode: "bypassPermissions" — prompt: "Implement design system foundation from this architecture: [paste frontend section]. Create CSS tokens, base layout components, core UI primitives. Commit: 'feat: design system'."
+Call the Agent tool — description: "Design system setup" — mode: "bypassPermissions" — prompt: "Implement the design system from the Visual Design Spec: [paste from docs/plans/visual-design-spec.md]. Create CSS tokens matching the spec's color system, typography scale, spacing system, shadow/elevation tokens, and base layout components. Reference the proof screens from Phase 3 as implementation targets. Commit: 'feat: design system'."
 
-### Step 3.3 — Metric Loop: Scaffold Health
+### Step 4.3 — Metric Loop: Scaffold Health
 
 Run the Metric Loop Protocol. Define a metric: builds clean, tests pass, lint clean, structure matches architecture. Max 3 iterations.
 
-### Step 3.4 — Verification Gate
+### Step 4.4 — Verification Gate
 
 Run the Verification Protocol (`commands/protocols/verify.md`). Critical rules (survive compaction):
 - ONE agent runs all 6 checks sequentially: Build → Type-Check → Lint → Test → Security → Diff Review. Stop on first FAIL.
@@ -318,7 +376,7 @@ Run the Verification Protocol (`commands/protocols/verify.md`). Critical rules (
 
 Call the Agent tool — description: "Verify scaffolding" — mode: "bypassPermissions" — prompt: "Run the Verification Protocol. Execute all 6 checks sequentially, stop on first failure. Report: VERIFY: PASS or VERIFY: FAIL with details."
 
-Do not proceed to Phase 4 until verification passes.
+Do not proceed to Phase 5 until verification passes.
 
 Update TodoWrite and state.
 
@@ -326,23 +384,23 @@ Update TodoWrite and state.
 
 ---
 
-## Phase 4: Build — Metric-Driven Dev Loops
+## Phase 5: Build — Metric-Driven Dev Loops
 
 <HARD-GATE>
-Before starting: Phase 2 must be approved, Phase 3 must pass. You MUST call the Agent tool for EVERY task. No exceptions.
+Before starting: Phase 2 must be approved, Phase 3 must produce docs/plans/visual-design-spec.md, Phase 4 must pass. You MUST call the Agent tool for EVERY task. No exceptions.
 </HARD-GATE>
 
 Expand TodoWrite with each sprint task.
 
 **For EACH task:**
 
-### Step 4.1 — Implement
+### Step 5.1 — Implement
 
 Call the Agent tool — description: "[task name]" — mode: "bypassPermissions" — prompt: "TASK: [task description + acceptance criteria]. HANDOFF — Architecture section: [paste ONLY the relevant section from architecture.md]. Design section: [paste ONLY the relevant section from the design doc]. Previous task output: [what the last completed task produced, if relevant]. Implement fully with real code and tests. Commit: 'feat: [task]'. Report what you built, files changed, and test results."
 
 Pick the right developer framing: frontend, backend, AI, etc. Set `[COMPLEXITY: S/M/L]` based on the task's Size from sprint-tasks.md.
 
-### Step 4.1b — Cleanup (De-Sloppify)
+### Step 5.1b — Cleanup (De-Sloppify)
 
 Follow the Cleanup Protocol (`commands/protocols/cleanup.md`). Critical rules (survive compaction):
 [COMPLEXITY: S]
@@ -354,11 +412,11 @@ Follow the Cleanup Protocol (`commands/protocols/cleanup.md`). Critical rules (s
 
 Call the Agent tool — description: "Cleanup [task name]" — mode: "bypassPermissions" — with the list of files changed and the task's acceptance criteria.
 
-### Step 4.2 — Metric Loop: Task Quality
+### Step 5.2 — Metric Loop: Task Quality
 
 Run the Metric Loop Protocol on the task implementation. Define a metric based on the task's acceptance criteria. Max 5 iterations.
 
-### Step 4.3 — Loop Exit
+### Step 5.3 — Loop Exit
 
 On target met: mark task complete in TodoWrite, report "Task X/N: [name] — COMPLETE (score: [final], iterations: [count])".
 
@@ -368,7 +426,7 @@ On stall or max iterations:
 
 After each task: update TodoWrite and `docs/plans/.build-state.md`.
 
-### Step 4.4 — Post-Task Verification
+### Step 5.4 — Post-Task Verification
 
 Run the Verification Protocol (`commands/protocols/verify.md`) to catch regressions. If FAIL, fix before starting the next task.
 
@@ -376,13 +434,13 @@ Run the Verification Protocol (`commands/protocols/verify.md`) to catch regressi
 
 ---
 
-## Phase 5: Harden — Metric-Driven Hardening
+## Phase 6: Harden — Metric-Driven Hardening
 
-### Step 5.0 — Pre-Hardening Verification
+### Step 6.0 — Pre-Hardening Verification
 
 Run the Verification Protocol (`commands/protocols/verify.md`). ONE agent, 6 sequential checks (Build → Type → Lint → Test → Security → Diff), stop on first FAIL. Max 3 fix attempts. All checks must pass before starting expensive audit agents — do not waste audit agents on code that doesn't build or pass tests.
 
-### Step 5.1 — Initial Audit (4 agents in parallel, ONE message)
+### Step 6.1 — Initial Audit (4 agents in parallel, ONE message)
 
 Call the Agent tool 4 times in one message:
 
@@ -394,23 +452,108 @@ Call the Agent tool 4 times in one message:
 
 4. Description: "Security audit" — Prompt: "Security review: auth, input validation, data exposure, dependency vulnerabilities. Report findings with severity."
 
-### Step 5.1b — Eval Harness
+### Step 6.1b — Eval Harness
 
-Run the Eval Harness Protocol (`commands/protocols/eval-harness.md`). Define 8-15 concrete, executable eval cases from the audit findings and architecture doc. Run the eval agent. Record baseline pass rate. CRITICAL and HIGH failures feed into the metric loop in Step 5.2 as specific issues to fix.
+Run the Eval Harness Protocol (`commands/protocols/eval-harness.md`). Define 8-15 concrete, executable eval cases from the audit findings and architecture doc. Run the eval agent. Record baseline pass rate. CRITICAL and HIGH failures feed into the metric loop in Step 6.2 as specific issues to fix.
 
-### Step 5.2 — Metric Loop: Hardening Quality
+### Step 6.2 — Metric Loop: Hardening Quality
 
 Run the Metric Loop Protocol on the full codebase using audit findings as initial input. Define a composite metric based on what this project needs. Max 4 iterations.
 
 When fixing, dispatch to the RIGHT specialist. Security → security agent. Accessibility → frontend agent. Don't send everything to one agent.
 
-### Step 5.2b — Eval Re-run
+### Step 6.2b — Eval Re-run
 
 Re-run the Eval Harness after the metric loop exits. All CRITICAL eval cases must now pass. If any CRITICAL case still fails, include it as evidence for the Reality Checker.
 
-### Step 5.3 — Reality Check
+### Step 6.2c — E2E Testing (3 mandatory iterations)
+
+<HARD-GATE>
+ALL 3 ITERATIONS ARE MANDATORY. Do NOT stop after iteration 1 even if all tests pass. The purpose of 3 runs is to catch flaky tests, timing-dependent failures, and race conditions that only surface on repeated execution. Skip this step ONLY if the project has no user-facing frontend.
+</HARD-GATE>
+
+Generate and execute end-to-end tests using Playwright against the running application. Tests cover critical user journeys derived from the design doc and architecture.
+
+**Iteration 1 — Generate & Run:**
+
+Call the Agent tool — description: "E2E test generation" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: L] Generate and run end-to-end Playwright tests for this application.
+
+INPUTS:
+- Architecture doc (user flows and API contracts): [paste relevant sections from docs/plans/architecture.md]
+- Design doc (core user journeys): [paste relevant sections]
+- Visual Design Spec (component selectors and page structure): [paste relevant sections from docs/plans/visual-design-spec.md]
+
+REQUIREMENTS:
+1. Identify 5-10 critical user journeys from the design doc (auth flows, core feature flows, data entry, navigation)
+2. Use Page Object Model pattern — one page object per major view
+3. Use data-testid selectors (add them to components if missing)
+4. Wait for API responses, NEVER use arbitrary timeouts (no waitForTimeout)
+5. Capture screenshots at critical verification points
+6. Configure multi-browser: Chromium + Firefox + WebKit
+7. Set up playwright.config.ts with: fullyParallel, retries: 0 (we handle retries ourselves), screenshot: 'only-on-failure', video: 'retain-on-failure', trace: 'on-first-retry'
+8. Run all tests. Report: total, passed, failed, with failure details and screenshot paths.
+9. Commit: 'test: e2e test suite for critical user journeys'
+
+Test priority:
+- CRITICAL: Auth, core feature happy path, data submission, payment/transaction flows
+- HIGH: Search, filtering, navigation, error states
+- MEDIUM: Responsive layout, animations, edge cases"
+
+Record results: total tests, pass count, fail count, failure details. Log to `docs/plans/.build-state.md` under `## E2E Testing`:
+
+```
+| Iter | Total | Passed | Failed | Flaky | Top Failure |
+|------|-------|--------|--------|-------|-------------|
+| 1    | ...   | ...    | ...    | ...   | ...         |
+```
+
+**Iteration 2 — Fix & Re-run:**
+
+Call the Agent tool — description: "E2E fix iteration 2" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: M] Fix E2E test failures and re-run the full suite.
+
+ITERATION 1 RESULTS: [paste failure details — test names, error messages, screenshot paths]
+
+For each failure:
+1. Diagnose: Is this a real bug, a flaky test, or a missing data-testid?
+2. Real bugs: Fix the application code
+3. Flaky tests: Add proper waits, fix race conditions, improve selectors
+4. Missing selectors: Add data-testid attributes to components
+5. Do NOT delete or skip failing tests — fix them
+
+Re-run ALL tests (not just previously failing ones). Report results.
+Commit fixes: 'fix: e2e test failures iteration 2'"
+
+Record results in the E2E table. Identify any tests that passed in iteration 1 but failed in iteration 2 — these are flaky candidates.
+
+**Iteration 3 — Final Stability Run:**
+
+Call the Agent tool — description: "E2E stability run" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: M] Final E2E stability run — iteration 3 of 3.
+
+PREVIOUS RESULTS:
+- Iteration 1: [pass/fail counts]
+- Iteration 2: [pass/fail counts]
+- Flaky candidates: [tests that had inconsistent results across iterations]
+
+REQUIREMENTS:
+1. Run ALL tests with --repeat-each=3 to detect flakiness (each test runs 3 times within this iteration)
+2. Any test failing inconsistently across the 3 sub-runs: quarantine with test.fixme() and file path + reason
+3. Fix any remaining consistent failures
+4. Generate final report with: total journeys, pass rate, flaky count, quarantined tests
+5. Commit: 'test: e2e stability fixes iteration 3'
+
+PASS CRITERIA: 95%+ pass rate across all tests. Quarantined flaky tests do not count against pass rate but must be logged."
+
+Record final results. Include in Reality Checker evidence.
+
+### Step 6.3 — Reality Check
 
-Call the Agent tool — description: "Final verdict" — prompt: "You are the Reality Checker. Default: NEEDS WORK. The hardening loop reached score [final_score] after [iterations] iterations. Score history: [paste table]. Review all evidence. Eval harness results: [baseline pass rate] → [final pass rate]. CRITICAL failures remaining: [list or none]. Verdict: PRODUCTION READY or NEEDS WORK with specifics."
+Call the Agent tool — description: "Final verdict" — prompt: "You are the Reality Checker. Default: NEEDS WORK. The hardening loop reached score [final_score] after [iterations] iterations. Score history: [paste table]. Review all evidence. Eval harness results: [baseline pass rate] → [final pass rate]. E2E test results: [paste E2E table — 3 iterations, final pass rate, quarantined count]. CRITICAL failures remaining: [list or none]. Verdict: PRODUCTION READY or NEEDS WORK with specifics."
 
 <HARD-GATE>Do NOT self-approve. Reality Checker must give the verdict.</HARD-GATE>
 
@@ -421,21 +564,21 @@ Call the Agent tool — description: "Final verdict" — prompt: "You are the Re
 
 ---
 
-## Phase 6: Ship
+## Phase 7: Ship
 
-### Step 6.0 — Pre-Ship Verification
+### Step 7.0 — Pre-Ship Verification
 
-Final verification gate. Run the Verification Protocol (`commands/protocols/verify.md`). ONE agent, 6 sequential checks (Build → Type → Lint → Test → Security → Diff), stop on first FAIL. Max 3 fix attempts. All checks must pass before documenting and shipping. If FAIL persists, return to Phase 5 for targeted fixes.
+Final verification gate. Run the Verification Protocol (`commands/protocols/verify.md`). ONE agent, 6 sequential checks (Build → Type → Lint → Test → Security → Diff), stop on first FAIL. Max 3 fix attempts. All checks must pass before documenting and shipping. If FAIL persists, return to Phase 6 for targeted fixes.
 
-### Step 6.1 — Documentation
+### Step 7.1 — Documentation
 
 Call the Agent tool — description: "Documentation" — mode: "bypassPermissions" — prompt: "Write project docs: README with setup/architecture/usage, API docs if applicable, deployment notes. Commit: 'docs: project documentation'."
 
-### Step 6.2 — Metric Loop: Documentation Quality
+### Step 7.2 — Metric Loop: Documentation Quality
 
 Run the Metric Loop Protocol on documentation. Define a metric based on completeness and whether a new developer could follow the README. Max 3 iterations.
 
-### Step 6.3 — Record Learnings
+### Step 7.3 — Record Learnings
 
 Append to `docs/plans/learnings.md` (create if it doesn't exist). Review the build and record 3-5 learnings:
 
@@ -457,4 +600,4 @@ Metric loops run: [count] | Avg iterations: [N]
 Remaining: [any NEEDS WORK items]
 ```
 
-Mark all TodoWrite items complete. Update `docs/plans/.build-state.md`: "Phase: 6 COMPLETE."
+Mark all TodoWrite items complete. Update `docs/plans/.build-state.md`: "Phase: 7 COMPLETE."

package/commands/protocols/build-fix.md

@@ -4,7 +4,7 @@ You are the orchestrator. A build, type-check, or lint check has failed. Do NOT
 
 ## 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.
+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
 

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

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -12,7 +12,7 @@ They are complementary: eval harness failures become specific issues for the met
 ## Step 0: Define Eval Cases
 
 YOU (the orchestrator) define eval cases based on:
-- Audit findings from Phase 5.1 (highest-severity items first)
+- 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)
 
@@ -46,11 +46,11 @@ Count PASS cases / total cases. This is the eval baseline. Record to `docs/plans
 
 ## 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.
+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 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.
+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.
 
 ---
 

package/commands/protocols/metric-loop.md

@@ -30,9 +30,9 @@ Then create a score log table:
 
 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):
+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: [4.1 Implement | 4.1b Cleanup | 4.2 Metric Loop | 4.3 Loop Exit | 4.4 Verify]
+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.
 

package/hooks/session-start

@@ -9,10 +9,21 @@ if [ -f "docs/plans/.build-state.md" ]; then
 fi
 
 # Skip if the build is already complete
-if echo "$BUILD_STATE" | grep -q "Phase: 6 COMPLETE"; then
+if echo "$BUILD_STATE" | grep -q "Phase: 7 COMPLETE"; then
   BUILD_STATE=""
 fi
 
+# Check if we're past Phase 3 but missing design artifacts
+if [ -n "$BUILD_STATE" ]; then
+  CURRENT_PHASE=$(echo "$BUILD_STATE" | grep -oP 'Phase: \K[0-9]+' | head -1)
+  if [ "$CURRENT_PHASE" -ge 4 ] 2>/dev/null && [ ! -f "docs/plans/visual-design-spec.md" ]; then
+    DESIGN_WARNING="
+DESIGN GATE VIOLATION: Current phase is ${CURRENT_PHASE} but docs/plans/visual-design-spec.md does not exist.
+Phase 3 (Design & Visual Identity) may have been skipped. DO NOT proceed with Foundation or Build.
+Return to Phase 3 and produce visual-design-spec.md before continuing."
+  fi
+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."
@@ -69,17 +80,19 @@ ORCHESTRATOR
 ${BUILD_STATE}
 ${METRIC_LOOP}
 ${RESUME_POINT}
+${DESIGN_WARNING}
 
 NEXT ACTIONS:
 1. Re-read commands/build.md to reload the full orchestrator process
 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"
+3. Re-read commands/protocols/design.md if you are in Phase 3 (Design & Visual Identity)
+4. Re-read docs/plans/sprint-tasks.md for task list and acceptance criteria
+5. Re-read docs/plans/architecture.md for architecture context
+6. Re-read CLAUDE.md for build decisions
+7. Re-read docs/plans/learnings.md if it exists (patterns and pitfalls from previous builds)
+8. Rebuild TodoWrite from docs/plans/.build-state.md (TodoWrite does NOT survive compaction)
+9. Resume from the phase and step indicated in your state above
+10. 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.5.0",
+  "version": "1.6.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"