buildanything 1.7.1 → 1.8.0

package/commands/verify.md

@@ -7,6 +7,13 @@ argument-hint: "Optional scope: 'build', 'tests', 'security', 'lint', 'types', '
 
 You are a verification runner. Fast, deterministic, no opinions — just pass/fail.
 
+## Project-type branching
+
+Read `docs/plans/.build-state.md` → `project_type`.
+
+- **If `project_type=web`** (or unset): run the existing web flow below (Steps 1–3).
+- **If `project_type=ios`**: skip Steps 1–3 and jump to the **iOS Verify** section at the bottom of this file.
+
 ## Step 1: Determine Scope
 
 Check the user's argument:
@@ -41,3 +48,68 @@ Follow `protocols/verify.md` exactly:
 > "Verification failed at [check]. Run `/buildanything:build` with a fix prompt, or I can attempt a targeted fix now."
 
 Do not auto-fix unless the user asks. This command is for reporting, not repairing.
+
+---
+
+## iOS Verify (project_type=ios)
+
+iOS functional-correctness twin. Runs a sequential skill bundle (not parallel — each pass feeds the next) over the Xcode project. No 0-100 scoring — pass/fail gates only.
+
+### Preflight
+
+**Run iOS preflight:** see `protocols/ios-preflight.md`. If any preflight check fails, emit `VERIFY: FAIL at preflight — [reason]` and stop.
+
+### Load context
+
+Every dispatched agent below inherits `protocols/ios-context.md` (Senior iOS Engineer sidecar). Inject it as the first block of each agent prompt.
+
+### Dispatch sequence (sequential)
+
+Run in order. Stop on first hard blocker; soft findings accumulate into the report.
+
+**a. Test triage — `skills/ios/swift-testing-expert`**
+> Load `protocols/ios-context.md`. Triage existing `@Test` / XCTest suites: parallel-safety, isolation correctness, missing coverage on critical paths, test-plan wiring. Output: list of test issues with severity.
+
+**b. Snapshot / doubles review — `skills/ios/swift-testing` _(TBD — bocato cherry-pick not yet ported; skip with a note if absent)_**
+> If skill exists: review snapshot tests and Fowler-style test doubles. If absent: log `swift-testing (bocato) — PENDING PORT` in the report and continue.
+
+**c. Security audit — `skills/ios/swift-security-expert` (audit mode)**
+> Load `protocols/ios-context.md`. Audit Keychain usage, CryptoKit calls, ATS exceptions in Info.plist, biometric gating. Report any hardcoded secrets or weak primitives. Severity: P0 / P1 / P2.
+
+**d. App Review compliance — `agents/ios-app-review-guardian`**
+> Load `protocols/ios-context.md`. Check App Review guidelines, privacy manifest (`PrivacyInfo.xcprivacy`), IAP/StoreKit rules, required usage-description strings, tracking/ATT compliance. Report blockers vs. warnings.
+
+**e. Maestro flow authoring — `skills/ios/ios-maestro-flow-author`** _(conditional)_
+> If a critical user journey lacks E2E coverage, author a `.yaml` Maestro flow for it. Skip if coverage is adequate.
+
+**f. Build + test run — XcodeBuildMCP**
+> `BuildProject` all targets → run the active test plan via XcodeBuildMCP → capture failures, warnings, and test output. This is the hard gate.
+
+### Pass/fail gates
+
+All must pass for `VERIFY: PASS`:
+
+| Gate | Pass condition |
+|------|----------------|
+| Build | XcodeBuildMCP `BuildProject` succeeds, zero errors |
+| Tests | All tests in active test plan pass |
+| Security audit | No P0 findings from `swift-security-expert` |
+| App Review | No blockers from `ios-app-review-guardian` (warnings OK) |
+| A11y warnings | No new a11y warnings introduced since last verify |
+
+Any gate failing → `VERIFY: FAIL at [gate] — [reason]`.
+
+### Output
+
+Write `docs/plans/ios-verify-report.md` with:
+
+- One-line pass/fail summary
+- Per-agent section (testing, security, app-review, maestro, build)
+- Findings list grouped by severity (P0/P1/P2)
+- Diff vs. previous report if one exists
+
+Log the final line to `docs/plans/.build-state.md` the same way web mode does.
+
+### Note on Step 6.0 (Pre-Hardening Verification)
+
+Step 6.0 references `protocols/verify.md` which auto-branches on `project_type`. iOS builds flow through the iOS twin section of this file. No separate Step 6.0 action needed for iOS.

package/hooks/session-start

@@ -2,6 +2,17 @@
 # buildanything: SessionStart hook
 # Re-injects orchestrator identity after context compaction, resume, or clear.
 
+# Dep check: warn if plugin deps (installed via bin/setup.js) are missing.
+DEPS_WARNING=""
+MISSING=()
+command -v agent-browser >/dev/null 2>&1 || MISSING+=("agent-browser CLI")
+{ [ -e "$HOME/.claude/skills/agent-browser" ] || [ -e "$HOME/.claude/skills/agent-browser.md" ]; } || MISSING+=("agent-browser skill")
+{ [ -e "$HOME/.claude/skills/dogfood" ] || [ -e "$HOME/.claude/skills/dogfood.md" ]; } || MISSING+=("dogfood skill")
+if [ ${#MISSING[@]} -gt 0 ]; then
+  JOINED=$(IFS=,; echo "${MISSING[*]}"); JOINED=${JOINED//,/, }
+  DEPS_WARNING="buildanything: missing deps (${JOINED}). Run /buildanything:setup to complete install."
+fi
+
 # Check if a build pipeline is active by looking for .build-state.md
 BUILD_STATE=""
 if [ -f "docs/plans/.build-state.md" ]; then
@@ -15,7 +26,7 @@ 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)
+  CURRENT_PHASE=$(echo "$BUILD_STATE" | sed -n 's/.*Phase: *\([0-9][0-9]*\).*/\1/p' | 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.
@@ -90,6 +101,12 @@ NEXT ACTIONS:
 8. Rebuild TodoWrite from docs/plans/.build-state.md (TodoWrite does NOT survive compaction)"
 fi
 
+# Prepend deps warning (if any) to the context — applies to both branches.
+if [ -n "$DEPS_WARNING" ]; then
+  CONTEXT="${DEPS_WARNING}
+${CONTEXT}"
+fi
+
 # Output as additional_context for Claude Code
 # JSON-escape the context
 ESCAPED=$(printf '%s' "$CONTEXT" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildanything",
-  "version": "1.7.1",
+  "version": "1.8.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"
@@ -35,6 +35,9 @@
     "agents/",
     "commands/",
     "hooks/",
-    "README.md"
+    "protocols/",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md"
   ]
 }

package/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/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/protocols/cleanup.md

@@ -0,0 +1,54 @@
+# 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.
+
+## 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/protocols/design.md

@@ -0,0 +1,269 @@
+# 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.
+
+## Anti-AI-Template Checklist
+
+Penalize 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 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.
+
+---
+
+## 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."
+
+Apply the Anti-AI-Template Checklist above. 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 — Living Style Guide (1 implementation agent)
+
+Build a real, rendered style guide page that serves as the single source of truth for the entire product's visual language. This is what a design agency would deliver — not throwaway proof screens, but a reusable reference that every implementation agent can view and every QA check can compare against.
+
+```
+[COMPLEXITY: L] Build a living style guide at /design-system (or a standalone HTML file if no routing exists).
+
+INPUTS:
+- Visual Design Spec: [paste from docs/plans/visual-design-spec.md]
+- UX Foundation: [paste relevant component and interaction sections]
+- Reference screenshots: [list paths from docs/plans/design-references/ — these are your quality targets]
+
+The style guide MUST include rendered, interactive examples of:
+
+1. **Colors** — Every color from the palette rendered as swatches with hex/variable names. Light and dark mode side by side.
+2. **Typography** — Every heading level (h1-h6), body text, captions, labels, code text. Showing font family, size, weight, line height.
+3. **Spacing** — Visual scale showing 4px through 128px with labeled examples.
+4. **Buttons** — Primary, secondary, ghost, destructive. Every state: default, hover, active, focus-visible, disabled, loading. All rendered and interactive (hover them, click them).
+5. **Form Elements** — Text input, textarea, select, checkbox, radio, toggle, date picker. Every state: empty, filled, focused, error, disabled, loading.
+6. **Cards** — Content card, interactive card, stat card. With hover elevation, transitions.
+7. **Navigation** — Header, sidebar, breadcrumb, tabs, pagination. Active/inactive states.
+8. **Feedback** — Alerts (success, warning, error, info), toasts, loading spinners, skeleton screens, empty states, progress bars.
+9. **Modals & Overlays** — Modal, sheet, dropdown, tooltip, popover. Open/close transitions.
+10. **Layout Examples** — A sample section showing the grid system, responsive behavior at 375px/768px/1024px/1280px.
+
+REQUIREMENTS:
+- Use EXACT values from the Visual Design Spec. Do not deviate.
+- Every component must be interactive — hover states work, focus rings show, transitions animate.
+- Mobile-responsive — the style guide itself must be readable on mobile.
+- This page ships with the product as developer documentation.
+
+Commit: 'feat: living style guide'
+```
+
+---
+
+## Step 3.4 — Visual QA Loop (Playwright + Metric Loop)
+
+Run the Metric Loop Protocol (`protocols/metric-loop.md`).
+
+**Metric definition for `.build-state.md`:**
+
+```
+## Active Metric Loop
+Phase: 3
+Artifact: Living style guide (/design-system or standalone)
+Metric: Design system quality — component completeness, visual fidelity to spec, interactive states, competitive quality relative to research references
+How to measure: Playwright screenshots of style guide sections (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 design system / living style guide for quality.
+
+INPUTS:
+- Screenshots of the style guide page: [Playwright captures — desktop + mobile, each section]
+- 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)**
+   - 8px grid respected? Hero padding 120-200px, not 40px?
+   - Internal component padding < external margin (Gestalt proximity)?
+
+2. **Typography Hierarchy (0-100)**
+   - Line heights: body 1.5-1.6x, headings 1.1-1.3x?
+   - Consistent type scale from the spec applied?
+
+3. **Color Harmony (0-100)**
+   - 60-30-10 rule (60% neutral, 30% secondary, 10% accent)?
+   - WCAG AA contrast (4.5:1 body, 3:1 large text)? Shadows tinted not pure black?
+
+4. **Component Polish (0-100)**
+   - All states present (hover, focus-visible, disabled, loading)?
+   - Shadow/elevation and border radius per spec?
+
+5. **Responsive Quality (0-100)**
+   - Touch targets 44px+ on mobile? No horizontal scroll?
+   - Layout adapts per breakpoint (not just stacks)?
+
+6. **Originality (0-100)**
+   - Does this look DESIGNED or GENERATED?
+   - Apply the Anti-AI-Template Checklist above. Penalize heavily if 3+ items appear together.
+   - 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 style guide 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.
+- The living style guide is a REAL implementation with real CSS/components, not mockups or wireframes. Every component must be interactive and responsive. It ships with the product.
+- 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.