buildanything 1.7.0 → 1.8.0

package/agents/ios-swift-ui-design.md

@@ -0,0 +1,104 @@
+---
+name: ios-swift-ui-design
+description: READS `docs/plans/ios-design-board.md` + user-provided mockups/screenshots and produces a SwiftUI implementation plan for impl agents. Does NOT generate the design board itself (that's `/buildanything:build` Phase 3 Step 3.1). Use when starting from a visual design or UI description before feature planning.
+tools: Read, Glob, Grep, Skill
+model: opus
+color: cyan
+---
+
+# iOS UI Design Analysis
+
+## Identity
+
+You are an expert UI/UX analyst for iOS applications.
+
+**Mission:** READ `docs/plans/ios-design-board.md` + user-provided UI requirements (mockups, screenshots, OR text descriptions) and produce SwiftUI implementation specifications.
+**Goal:** Produce detailed UI analysis that informs architecture and view implementation.
+
+**Boundary:** This agent does NOT generate the design board. Design board generation is owned by `/buildanything:build` Phase 3 Step 3.1. If `docs/plans/ios-design-board.md` does not exist, HALT and instruct the user to run Phase 3 first.
+
+## CRITICAL: READ-ONLY MODE
+
+**You MUST NOT create, edit, or delete any implementation files.**
+Your role is UI analysis ONLY. Focus on understanding and specifying the UI requirements.
+
+## Context
+
+**Platform:** iOS 26.0+, Swift 6.2+, Xcode 26.3
+**Context Budget:** Target <100K tokens; prioritize critical UI design decisions.
+
+## Skill Usage
+
+Invoke these skills when relevant:
+- `swiftui-design-principles` — 10-rule polish checklist
+- `swiftui-ui-patterns` — common SwiftUI patterns
+- `swiftui-liquid-glass` — Liquid Glass material + iOS 26 aesthetics
+- `ios-hig` — Human Interface Guidelines
+- `ios-26-platform` — platform-level API changes
+
+## Input Types
+
+This agent accepts ANY of the following:
+
+### Text Description
+- Parse into concrete UI requirements
+- Ask clarifying questions if ambiguous
+- Suggest appropriate iOS patterns based on HIG
+- **Most common input type** — no mockup required
+
+### Screenshot / Image / Mockup
+- Analyze visual hierarchy
+- Identify standard iOS components
+- Note custom elements that need implementation
+- Evaluate spacing, typography, color usage
+
+### Figma / Design Reference
+- If URL provided, ask user to paste screenshots or describe key screens
+- Work from the description/images provided
+
+## Analysis Checklist
+
+For each screen or component, evaluate:
+
+### Component Identification
+- [ ] Navigation pattern (NavigationStack, TabView, sheet, fullScreenCover)
+- [ ] List/scroll patterns (List, ScrollView, LazyVStack)
+- [ ] Input elements (TextField, Picker, Toggle, Slider)
+- [ ] Media elements (Image, AsyncImage, video)
+- [ ] Custom components needed
+
+### Layout Structure
+- [ ] Container hierarchy (VStack, HStack, ZStack, Grid)
+- [ ] Spacing and padding patterns
+- [ ] Safe area handling
+- [ ] Keyboard avoidance needs
+
+### HIG Compliance
+- [ ] Standard iOS patterns used appropriately
+- [ ] System colors and materials (including Liquid Glass where appropriate)
+- [ ] Typography (system fonts, Dynamic Type support)
+- [ ] Touch target sizes (minimum 44pt)
+- [ ] Platform conventions (navigation, gestures)
+
+### Interaction Patterns
+- [ ] Tap actions, swipe gestures, long-press menus
+- [ ] Pull-to-refresh, drag and drop
+- [ ] Haptic feedback points
+
+### State Requirements
+- [ ] Data driving each view
+- [ ] Loading, empty, error, and input states
+
+### Accessibility
+- [ ] VoiceOver labels and actions
+- [ ] Reduce Motion alternatives
+- [ ] Color contrast
+- [ ] Dynamic Type scaling
+
+## Output
+
+Produce a structured UI plan: per-screen component tree, state requirements, HIG/accessibility notes, and SwiftUI implementation hints. Do not write view code — that's the implementer's job.
+
+---
+
+Vendored from: https://github.com/johnrogers/claude-swift-engineering/blob/main/plugins/swift-engineering/agents/swift-ui-design.md

package/commands/build.md

@@ -99,6 +99,12 @@ For implementation agents (Phase 5+): Do NOT paste the entire Design Document or
 
 Tag agent prompts with `[COMPLEXITY: S/M/L]` based on task size from `docs/plans/sprint-tasks.md`. This is advisory — the tag documents intent for future model routing support.
 
+### Mode-Specific Tool Stacks
+
+Mode-specific tool stacks, per-phase branches, and persona rules are in separate files — the orchestrator loads only ONE based on `project_type` (see Phase 0 Step 0.1b below):
+- iOS: `protocols/ios-phase-branches.md` (includes iOS Mode Tool Stack)
+- Web: `protocols/web-phase-branches.md` (web defaults)
+
 ---
 
 ## Phase 0: Context & Pre-Flight
@@ -131,6 +137,30 @@ Before doing anything, scan for existing context:
 | **Partial context** | Some notes, conversation, rough sketch | Phase 1 runs fully. Feed context into brainstorming + research. |
 | **Raw idea** | One-line build request, no prior work | Phase 1 runs fully from scratch. |
 
+### Step 0.1b — Project Type Classification (iOS vs Web)
+
+Scan the build request AND any context from Step 0.1 for iOS signals. Keywords: **iOS, iPhone, iPad, SwiftUI, Swift, App Store, TestFlight, Xcode, Apple, Liquid Glass, watchOS, visionOS, SwiftData, HIG**.
+
+**Classification logic:**
+
+| Signal | Action |
+|---|---|
+| iOS keywords present in prompt | Confirm with user: "This looks like an iOS app — confirm? [y/n]" |
+| User confirms OR says iOS during brainstorming | Set `project_type: ios` in `docs/plans/.build-state.md` |
+| `.xcodeproj` / `Package.swift` / `*.swift` files in existing codebase | Set `project_type: ios` automatically |
+| No iOS signals, no Swift files | Default `project_type: web` (existing behavior) |
+
+**Autonomous mode:** skip the confirmation prompt. If iOS keywords are present, set `project_type: ios` and log the inference to `docs/plans/build-log.md`.
+
+**Conditional branch-file load:**
+- If `project_type=ios`: load `protocols/ios-phase-branches.md` AND `protocols/ios-context.md` into session context. Reference `protocols/ios-frameworks-map.md` by path only (do NOT load — agents Read it on-demand).
+- If `project_type=web`: load `protocols/web-phase-branches.md` into session context.
+- Load only ONE branch file. The other mode's content is irrelevant to this build.
+
+Record the classification in `docs/plans/.build-state.md` as a top-level field: `project_type: ios` or `project_type: web`. This field survives compaction and gates every branching block below.
+
+**Mode-specific additions to Phase 0:** See `protocols/ios-phase-branches.md` §Phase 0 additions (iOS only). No web-specific Phase 0 additions.
+
 ### Step 0.2 — Human Prerequisites Checklist
 
 Identify everything that requires HUMAN action before going heads-down:
@@ -169,12 +199,24 @@ Autonomous mode: Log checklist to `docs/plans/build-log.md`. Create `.env.exampl
 
 ---
 
+## Phase -1: iOS Bootstrap (iOS-only, greenfield only)
+
+**If `project_type=ios` AND no `.xcodeproj` exists:** follow `protocols/ios-phase-branches.md` §Phase -1 — iOS Bootstrap. Otherwise skip entirely (including all of web mode).
+
+**Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
+
+---
+
 ## Phase 1: Brainstorm & Research
 
 **Goal**: Turn the raw idea into a validated Design Document grounded in research. This ensures Phase 2 architects receive a design, not a guess.
 
 **Skip if** Step 0.1 classified context as "Full design" — go straight to Phase 2.
 
+**Mode-specific branch:**
+- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 1 (iOS skill bundle, ios-swift-architect, App Store/TestFlight/iOS 26 research angles)
+- If `project_type=web`: no additional branch instructions — proceed with the steps below.
+
 ### Step 1.1 — Brainstorming
 
 Follow the Brainstorm Protocol (`protocols/brainstorm.md`).
@@ -264,6 +306,10 @@ Update TodoWrite and `docs/plans/.build-state.md`.
 
 **Goal**: Convert the validated Design Document into a concrete architecture and ordered task list. Every agent receives the Design Document — not just the build request.
 
+**Mode-specific branch:**
+- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 2 (replaces Backend/Frontend architecture dispatch with SwiftUI/SwiftData/Concurrency/iOS security; adds Feature Flag Resolution at end of phase)
+- If `project_type=web`: no additional branch instructions — proceed with the steps below.
+
 ### Step 2.1 — Explore (existing codebase only)
 
 If existing code, call the Agent tool — description: "Explore codebase" — prompt: "Explore this codebase. Map architecture layers, file conventions, testing patterns, existing features. Report findings."
@@ -308,59 +354,27 @@ Save to `docs/plans/sprint-tasks.md`.
 
 Update TodoWrite and `docs/plans/.build-state.md`.
 
+**iOS feature flag resolution:** if `project_type=ios`, resolve `ios_features` before leaving Phase 2 per `protocols/ios-phase-branches.md` §Phase 2 → Feature Flag Resolution.
+
 **Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
 
 ---
 
 ## Phase 3: Design & Visual Identity
 
-**Goal**: Transform architecture into a research-backed visual design system, proven with Playwright screenshots. Fully autonomous — agents research, decide, and iterate without user input.
+**Goal**: Transform architecture into a research-backed visual design system grounded in real references (competitor sites for web, HIG + App Store for iOS).
 
 **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 a living style guide with every component rendered and interactive, and iterate with Playwright-verified visual QA before a single line of product code is written.
+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. Agents must research real references, make deliberate visual choices backed by that research, and iterate with 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.
+Phase 4 (Foundation) WILL NOT START without the design artifact for this mode (`docs/plans/visual-design-spec.md` for web, `docs/plans/ios-design-board.md` for iOS). If it does not exist, return here.
 </HARD-GATE>
 
-### Step 3.1 — Design Research (2 agents, parallel, both use Playwright)
-
-Follow the Design Protocol (`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 (`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 — Living Style Guide (1 implementation agent)
-
-Follow the Design Protocol (`protocols/design.md`), Step 3.3.
-
-Call the Agent tool — description: "Build living style guide" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: L] Build a living style guide page (/design-system route or standalone HTML). INPUTS: Visual Design Spec [paste], UX foundation [paste relevant sections], reference screenshots [list paths — these are your quality targets]. Must include rendered, interactive examples of: color swatches, typography scale, spacing scale, buttons (all states), form elements (all states), cards, navigation, feedback components (alerts, toasts, spinners, empty states), modals/overlays, and layout grid examples. Every component interactive (hover, focus, transitions work). Mobile-responsive. This ships with the product. Commit: 'feat: living style guide'."
-
-### Step 3.4 — Visual QA Loop (Playwright + Metric Loop)
-
-Run the Metric Loop Protocol (`protocols/metric-loop.md`) using the measurement criteria from the Design Protocol (`protocols/design.md`, Step 3.4).
-
-Measurement: Playwright screenshots of the living style guide sections (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.
+**Mode-specific branch:**
+- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 3 (HIG + App Store + screenlane harvest → iOS Design Board, SwiftUI Preview QA loop, max 3 iterations)
+- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 3 (competitor/Awwwards research → Visual Design Spec → living style guide at `/design-system` → Playwright visual QA, max 5 iterations)
 
 **Compaction checkpoint.** Update `docs/plans/.build-state.md` per the format above.
 
@@ -369,22 +383,16 @@ Log to `docs/plans/build-log.md`: final screenshot paths, score history table, d
 ## 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.
+Before starting Phase 4: Phase 2 must be approved AND Phase 3 must have produced the design artifact for this mode.
+- Web: `docs/plans/visual-design-spec.md` must exist.
+- iOS: `docs/plans/ios-design-board.md` must exist.
+If the artifact does not exist, DO NOT PROCEED. Return to Phase 3.
+Step 4.2 (Design System) MUST implement from the design artifact — 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 4.2 — Design System (frontend only)
-
-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. The living style guide from Phase 3 is the reference implementation — components must match. Commit: 'feat: design system'."
-
-### Step 4.2b — Acceptance Test Scaffolding
-
-Call the Agent tool — description: "Scaffold acceptance tests" — mode: "bypassPermissions" — prompt: "Read docs/plans/sprint-tasks.md. For every task with a Behavioral Test field, create a Playwright test stub in tests/e2e/acceptance/. Use Page Object Model. Each test should: navigate to the page, perform the interaction, assert the expected outcome. Tests should FAIL right now (features aren't built yet) — that's correct. Also ensure agent-browser is available (run `which agent-browser`). Commit: 'test: scaffold acceptance tests from sprint tasks'."
+**Mode-specific branch (Steps 4.1, 4.2, 4.2b):**
+- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 4 (entitlements generator + Info.plist hardening, XcodeBuildMCP folder structure, SwiftUI design tokens, Maestro flow stubs)
+- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 4 (web project scaffolding, CSS design system tokens, Playwright acceptance test stubs)
 
 ### Step 4.3 — Metric Loop: Scaffold Health
 
@@ -411,18 +419,20 @@ Update TodoWrite and state.
 ## Phase 5: Build — Metric-Driven Dev Loops
 
 <HARD-GATE>
-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.
+Before starting: Phase 2 must be approved, Phase 3 must produce `docs/plans/visual-design-spec.md` (web) or `docs/plans/ios-design-board.md` (iOS), Phase 4 must pass. You MUST call the Agent tool for EVERY task. No exceptions.
 </HARD-GATE>
 
+**Mode-specific branch (Step 5.1 implement, Step 5.2 metric loop, Step 5.3b smoke test):**
+- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 5 (iOS skill bundle, feature-flag-gated skill loading, iOS implement prompt, SwiftUI Preview metric loop, Maestro smoke tests)
+- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 5 (web implement prompt, agent-browser metric loop, localhost smoke tests)
+
 Expand TodoWrite with each sprint task.
 
-**For EACH task:**
+**For EACH task, run Steps 5.1 → 5.1b → 5.2 → 5.3 → 5.3b → 5.4 below.** Step 5.1 implementation prompt and Step 5.3b smoke test technology are defined in the mode-specific branch file. The remaining steps (cleanup, loop exit, verification) are mode-agnostic and live here.
 
 ### 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]. For UI tasks: the living style guide at /design-system shows every component's exact styling and states — match it. 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.
+Per the mode-specific branch file referenced above. 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 5.1b — Cleanup (De-Sloppify)
 
@@ -438,7 +448,7 @@ Call the Agent tool — description: "Cleanup [task name]" — mode: "bypassPerm
 
 ### 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. For UI-facing tasks, include behavioral verification: the measurement agent should use agent-browser to verify the feature renders and responds to interaction, not just read the code. Max 5 iterations.
+Run the Metric Loop Protocol on the task implementation. Define a metric based on the task's acceptance criteria. For UI-facing tasks, include behavioral verification per the mode-specific branch file (web: agent-browser; iOS: SwiftUI Preview captures). Max 5 iterations.
 
 ### Step 5.3 — Loop Exit
 
@@ -454,11 +464,9 @@ After each task: update TodoWrite and `docs/plans/.build-state.md`.
 
 Skip if this task has no Behavioral Test criteria (API-only, config, infrastructure tasks).
 
-Run the Smoke Test Protocol (`protocols/smoke-test.md`). This uses agent-browser to open the app, execute the task's behavioral acceptance criteria, and verify the feature actually works.
+Run the Smoke Test Protocol (`protocols/smoke-test.md`). Technology is mode-specific — follow the branch file (web: agent-browser + localhost; iOS: Maestro flow against simulator via XcodeBuildMCP). Evidence saved to `docs/plans/evidence/[task-name]/`.
 
-Evidence saved to `docs/plans/evidence/[task-name]/`: annotated screenshot, snapshot diff, error log, network log, HAR file.
-
-On FAIL: spawn fix agent with the evidence. The fix agent receives: what was expected (from acceptance criteria), what actually happened (snapshot diff + errors + screenshot), and the relevant source files. Max 2 fix-and-retest cycles.
+On FAIL: spawn fix agent with the evidence (expected vs actual, errors, screenshots, relevant source files). Max 2 fix-and-retest cycles.
 
 On PASS: proceed to Step 5.4.
 
@@ -476,117 +484,9 @@ Run the Verification Protocol (`protocols/verify.md`). If FAIL, fix before start
 
 Run the Verification Protocol (`protocols/verify.md`). All checks must pass before starting expensive audit agents.
 
-### Step 6.1 — Initial Audit (5 agents in parallel, ONE message)
-
-Read the NFRs from `docs/plans/sprint-tasks.md`. Pass the relevant NFR thresholds to each audit agent so they have concrete targets, not generic checks.
-
-Call the Agent tool 5 times in one message:
-
-1. Description: "API testing" — Prompt: "Comprehensive API validation: all endpoints, edge cases, error responses, auth flows. NFR targets: [paste performance and reliability NFRs]. Report findings with counts."
-
-2. Description: "Performance audit" — Prompt: "Measure response times, identify bottlenecks, flag performance issues. NFR targets: [paste performance NFRs — e.g., API < 200ms, page load < 3s]. Report benchmarks AGAINST these targets."
-
-3. Description: "Accessibility audit" — Prompt: "WCAG compliance audit on all interfaces. NFR target: [paste accessibility NFR — e.g., WCAG AA]. Check screen reader, keyboard nav, contrast. Report issues with counts."
-
-4. Description: "Security audit" — Prompt: "Security review: auth, input validation, data exposure, dependency vulnerabilities. NFR targets: [paste security NFRs]. Report findings with severity."
-
-5. Description: "UX quality audit" — Prompt: "UX quality review of every user-facing page. NFR targets: [paste accessibility NFRs]. First, screenshot the living style guide at /design-system as your reference for how components should look. Then review every product page and check: loading states (every async action must show a loading indicator), error states (every form and API call must show user-friendly error feedback), empty states (every list/table must handle zero items gracefully), mobile responsiveness (test at 375px viewport — touch targets >= 44px, no horizontal scroll, readable text), form validation (inline feedback, not just alert()), transition smoothness (no layout shifts, no janky animations), visual consistency (compare each page's components against the style guide — buttons, inputs, cards, colors, spacing should match). Report issues with page, severity, and screenshot."
-
-### Step 6.1b — Eval Harness
-
-Run the Eval Harness Protocol (`protocols/eval-harness.md`). Define 8-15 concrete, executable eval cases from the audit findings and architecture doc. For UI flows, eval cases should use agent-browser: "agent-browser open /dashboard -> agent-browser click @submit -> agent-browser wait --text Success -> expect text contains confirmation ID". 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 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 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 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 the **User Journeys** defined in `docs/plans/sprint-tasks.md` (Step 0 of the Planning Protocol). Each journey = one E2E test file.
-
-**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:
-- User Journeys from docs/plans/sprint-tasks.md: [paste the User Journeys section — each journey becomes one E2E test]
-- Architecture doc (API contracts): [paste relevant sections from docs/plans/architecture.md]
-- NFRs from docs/plans/sprint-tasks.md: [paste — use performance thresholds as test assertions]
-- Visual Design Spec (component selectors): [paste relevant sections from docs/plans/visual-design-spec.md]
-
-REQUIREMENTS:
-1. One E2E test per User Journey from sprint-tasks.md (each journey = one test file covering the full flow)
-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 from iteration 1: [paste failure details — test names, error messages, screenshot paths]. Diagnose each as real bug, flaky test, or missing selector. Fix accordingly — do NOT delete or skip tests. Re-run ALL tests. Commit: 'fix: e2e test failures iteration 2'."
-
-Record results in the E2E table. Identify flaky candidates (passed iter 1, failed iter 2 or vice versa).
-
-**Iteration 3 — Final Stability Run:**
-
-Call the Agent tool — description: "E2E stability run" — mode: "bypassPermissions" — prompt: "[COMPLEXITY: M] Final E2E stability run (3 of 3). Previous results — Iter 1: [pass/fail counts], Iter 2: [pass/fail counts], Flaky candidates: [list]. Run ALL tests with --repeat-each=3. Quarantine inconsistent tests with test.fixme(). Fix remaining consistent failures. PASS CRITERIA: 95%+ pass rate (quarantined flaky tests excluded but logged). Commit: 'test: e2e stability fixes iteration 3'."
-
-Record final results. Include in Reality Checker evidence.
-
-### Step 6.2d — Autonomous Dogfooding
-
-Run the agent-browser dogfood skill against the running app. Unlike the per-task smoke tests (which verify specific acceptance criteria), dogfooding is **exploratory** — it autonomously navigates every reachable page, clicks buttons, fills forms, checks console errors, and finds issues we didn't think to test.
-
-Start the dev server if not running. Then invoke the dogfood skill:
-
-Call the Agent tool — description: "Dogfood the app" — mode: "bypassPermissions" — prompt: "Run the agent-browser dogfood skill against the running app at http://localhost:[port]. Explore every reachable page. Click every button. Fill every form. Check console for errors. Report a structured list of issues with severity ratings (critical/high/medium/low), screenshots, and repro steps. If dogfood skill is not available, use agent-browser manually: snapshot each page, click all interactive elements, check errors and network requests. Also evaluate UX quality: missing loading states, poor error messages, broken mobile layouts (resize to 375px), visual inconsistencies, missing empty states, form validation gaps. Report UX issues separately from functional issues."
-
-**Fix loop:** For each CRITICAL or HIGH issue found:
-1. Classify: is this a code bug (fix in Phase 5 style — spawn implementation fix agent) or a structural problem (needs architecture change — spawn architect agent to propose a fix plan, then implementation agent to execute)?
-2. Spawn the appropriate fix agent with: the issue description, repro steps, screenshot, affected page/component.
-3. After fixes, re-run dogfood on the affected pages only (not the full app). If new CRITICAL/HIGH issues appear, repeat. Max 3 fix cycles.
-
-MEDIUM/LOW issues: log to `docs/plans/build-log.md` for the Reality Checker.
-
-### Step 6.2e — Fake Data Detector
-
-Call the Agent tool — description: "Fake data audit" — mode: "bypassPermissions" — prompt: "Run the Fake Data Detector Protocol (protocols/fake-data-detector.md). Check for mock/hardcoded data in production paths. Static analysis: grep for Math.random() business data, hardcoded API responses, setTimeout faking async, placeholder text. Dynamic analysis: inspect HAR files from docs/plans/evidence/ for missing real API calls, static responses, absent WebSocket traffic. Report findings with file:line references and severity."
-
-**Fix loop:** For each CRITICAL finding:
-1. Spawn a fix agent with: the finding (file:line, what's fake, what it should be), and the relevant source files.
-2. The fix agent replaces fake data with real API calls, real WebSocket connections, real data sources. If real data sources aren't available (missing API keys, no backend), the fix agent must flag this as a blocker — not paper over it with better-looking fake data.
-3. After fixes, re-run the fake data detector (static checks only — fast). Max 2 fix cycles.
-
-Remaining findings feed into the Reality Checker in Step 6.4.
+**Mode-specific branch (Steps 6.1 → 6.2e):**
+- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 6 — dispatch iOS twin commands (`/buildanything:verify` → `/buildanything:ux-review` → `/buildanything:fix`) in sequence. Skip Steps 6.1, 6.1b, 6.2, 6.2b, 6.2c, 6.2d, 6.2e. Then run Step 6.4 Reality Check below with iOS evidence.
+- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 6 — run Steps 6.1 (5-agent audit), 6.1b (eval harness), 6.2 (metric loop), 6.2b (eval re-run), 6.2c (Playwright E2E, 3 mandatory iterations), 6.2d (agent-browser dogfood), 6.2e (fake data detector). Then run Step 6.4 Reality Check below.
 
 ### Step 6.4 — Reality Check
 
@@ -618,6 +518,10 @@ Do not loop forever.
 
 ## Phase 7: Ship
 
+**Mode-specific branch (Step 7.1 documentation + deploy):**
+- If `project_type=ios`: follow `protocols/ios-phase-branches.md` §Phase 7 — ship pipeline is optional (simulator-only is a valid end-state). If shipping, run asc-* agents + fastlane. Skip web Step 7.1 below.
+- If `project_type=web`: follow `protocols/web-phase-branches.md` §Phase 7 (Step 7.1 documentation + deploy notes).
+
 ### Step 7.0 — Pre-Ship Verification
 
 Run the Verification Protocol (`protocols/verify.md`). All checks must pass before documenting and shipping. If FAIL persists after 3 fix attempts, return to Phase 6.
@@ -635,7 +539,7 @@ If any features are MISSING: spawn implementation agents to build them, then re-
 
 ### 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'."
+Per the mode-specific branch file referenced at the top of Phase 7.
 
 ### Step 7.2 — Metric Loop: Documentation Quality
 

package/commands/fix.md

@@ -9,6 +9,15 @@ Input: $ARGUMENTS
 
 ---
 
+## Project-type branching
+
+Read `docs/plans/.build-state.md` → `project_type`.
+
+- **If `project_type=web`** (or unset): continue with the web flow below (Steps 1-5, unchanged).
+- **If `project_type=ios`**: jump to **§ iOS Fix (project_type=ios)** at the bottom of this file and run that twin instead. Do not run the web steps.
+
+---
+
 ## Step 1: Scope the Bug
 
 Parse the user's description. Identify:
@@ -87,3 +96,59 @@ State concisely:
 - **Cause**: why it was broken (one sentence)
 - **Fix**: what was changed and in which files
 - **Evidence**: before and after screenshots taken in Steps 2 and 4
+
+---
+
+## iOS Fix (project_type=ios)
+
+Load `protocols/ios-context.md` as your persona. Same verb (fix one bug), different stack: XcodeBuildMCP + Maestro instead of agent-browser + localhost.
+
+### i1. Preflight
+**Run iOS preflight:** see `protocols/ios-preflight.md`. If any check fails, stop and report — do not try to scaffold.
+
+### i2. Reproduce
+- Boot the target simulator via XcodeBuildMCP.
+- Install + launch the app (`BuildProject` if needed, then install the `.app`).
+- Trigger the bug via ONE of:
+  1. **Existing Maestro flow** — replay the failing flow in `maestro/` if one exists.
+  2. **Ad-hoc sim navigation** — drive the sim via XcodeBuildMCP UI tools to reach the bug.
+  3. **User demo** — if interaction is complex, ask user to reproduce once while you observe.
+- Capture evidence: sim screenshot (`before-fix.png`) + crash log / console output (if any) via XcodeBuildMCP.
+- If the bug cannot be reproduced: save screenshot, report observed state, stop.
+
+### i3. Classify
+Match the symptom to exactly one row. Dispatch the skill in the rightmost column.
+
+| Symptom | Classification | Fix skill / agent |
+|---|---|---|
+| View renders wrong, modifier order, missing `@State`/`@Binding`, layout broken | SwiftUI bug | `skills/ios/swiftui-pro` |
+| Data race, actor isolation warning, `Sendable` violation, hang on main | Concurrency | `skills/ios/swift-concurrency` |
+| `@Query` not updating, predicate wrong, migration failure, CloudKit sync | SwiftData | `skills/ios/swiftdata-pro` |
+| VoiceOver silent/wrong, Dynamic Type clipping, contrast fail, Reduce Motion ignored | Accessibility | `skills/ios/swift-accessibility` |
+| Touch target <44pt, no dark mode, hard-coded padding, HIG violation | HIG | `skills/ios/ios-hig` |
+| Build fails, signing error, entitlement / Info.plist / provisioning | Build/infra | dispatch `build-error-resolver` agent |
+| Keychain/Crypto misuse, ATS exception, insecure storage, secret leak | Security | `skills/ios/swift-security-expert` |
+
+If symptom doesn't match any row, pick the closest and note the gap in the fix report.
+
+### i4. Fix
+Dispatch the classified skill with mode "bypassPermissions". Pass as input:
+- Bug description (from `$ARGUMENTS`)
+- Reproduction evidence (screenshot path, crash log excerpt)
+- Affected file(s) — scope tightly, do not dump the whole project
+- Expected behavior (one sentence)
+
+### i5. Verify loop
+1. `BuildProject` via XcodeBuildMCP — must succeed with zero warnings/errors.
+2. Re-install on sim, re-run the Maestro flow OR re-trigger via sim nav.
+3. Capture `after-fix.png` sim screenshot.
+4. Visual diff: compare before/after against expected.
+5. Spot-check one adjacent screen/flow for regression.
+6. If still failing → return to **i3. Classify** (bug may be mis-classified). **Max 3 fix-verify iterations** per locked plan; after that, report what's fixed, what remains, stop.
+
+### i6. Output
+Append to `docs/plans/.build-state.md`:
+- **Bug**: what was broken
+- **Classification**: which row from i3
+- **Fix**: files changed + skill used
+- **Evidence**: `before-fix.png`, `after-fix.png`, build status

package/commands/setup.md

@@ -0,0 +1,73 @@
+---
+description: "Install buildanything's external dependencies — companion plugins, agent-browser CLI, Chrome for Testing, and skills"
+---
+
+# Setup
+
+You are installing buildanything's external dependencies. The plugin itself is already installed (that's how this command is running), but the companion plugins, CLI tools, and skills it depends on are not — they need to be installed separately. This command does that in one shot.
+
+Run every step below. Each step is idempotent: check first, install only if missing, continue on failure. Collect results as you go and report them all at the end.
+
+## Step 1: Install companion plugins from `claude-plugins-official`
+
+For each plugin below, run `claude plugin install <name>@claude-plugins-official`. If the command fails, record the failure and continue — do NOT abort.
+
+| Plugin | Purpose |
+|--------|---------|
+| `feature-dev` | code-architect, code-explorer, code-reviewer |
+| `pr-review-toolkit` | silent-failure-hunter, code-simplifier, type-design-analyzer |
+| `code-review` | final code review passes |
+| `commit-commands` | clean git commits |
+| `playwright` | browser automation for design research and visual QA |
+
+For each one, treat a non-zero exit as "already installed or failed" — record it as `skipped` and keep going. Treat a success as `installed`.
+
+## Step 2: Install the `agent-browser` CLI globally
+
+1. Run `which agent-browser`. If it returns a path, record as `already present` and skip to Step 3.
+2. Otherwise run `npm install -g agent-browser`. Record `installed` or `failed` based on exit status.
+
+## Step 3: Download Chrome for Testing
+
+Run `agent-browser install`. This downloads a pinned Chrome build. If `agent-browser` isn't on PATH (Step 2 failed), record `skipped (agent-browser CLI missing)` and continue. Otherwise record `ready` or `failed`.
+
+Note: this is safe to re-run — `agent-browser install` no-ops if Chrome is already downloaded.
+
+## Step 4: Install the `agent-browser` skill
+
+Run `npx skills add vercel-labs/agent-browser`. Record `installed` or `failed`.
+
+## Step 5: Install the `dogfood` skill
+
+Run `npx skills add vercel-labs/agent-browser --skill dogfood`. Record `installed` or `failed`.
+
+## Report
+
+Print a single summary block with three sections:
+
+```
+buildanything setup complete.
+
+Already present:
+  - <item>
+  - <item>
+
+Installed:
+  - <item>
+  - <item>
+
+Failed:
+  - <item> — retry with: <exact command>
+  - <item> — retry with: <exact command>
+```
+
+Omit any section that has no entries. For every item in the `Failed` section, include the exact manual-install command the user can run themselves. If everything succeeded or was already present, print only a one-line success message instead of the full block.
+
+After the summary, print this reminder:
+
+```
+Next: restart Claude Code so newly installed plugins/skills are loaded.
+Then try:
+  /buildanything:build <your idea>
+  /buildanything:idea-sweep <your idea>
+```