buildanything 1.7.0 → 1.8.0

package/protocols/planning.md

@@ -0,0 +1,87 @@
+# Planning Protocol
+
+You are the orchestrator converting a validated Design Document and Architecture Document into an ordered, developer-ready task list.
+
+## Input
+
+You need two documents before running this protocol:
+- **Design Document** (`docs/plans/YYYY-MM-DD-[topic]-design.md`) — scope, user flows, data model, tech stack
+- **Architecture Document** (`docs/plans/architecture.md`) — services, API contracts, database schema, component tree
+
+## Step 0: User Journeys & NFRs (orchestrator-authored)
+
+Before breaking into tasks, YOU (the orchestrator) define two things from documents you already have:
+
+**User Journeys (3-7):** End-to-end flows derived from the Design Document's user flows and Architecture's page routes. Each journey is a numbered sequence of user actions covering one core workflow.
+
+```
+### Journey 1: [name]
+1. User [action] on [page]
+2. User [action] → sees [result]
+3. User [action] → system [response]
+...
+```
+
+Every journey step must map to at least one sprint task. If a step has no task, you have a planning gap — add the task. These journeys become the spec for Phase 6 E2E tests.
+
+**Non-Functional Requirements (NFRs):** Extract from the architecture and research docs. Keep to what's measurable:
+
+```
+## NFRs
+- **Performance:** [e.g., API response < 200ms, page load < 3s, streaming data latency < 1s]
+- **Accessibility:** [e.g., WCAG AA, keyboard navigable, screen reader compatible]
+- **Security:** [e.g., auth required for all /api routes, data encrypted at rest, no secrets in client bundle]
+- **Reliability:** [e.g., graceful degradation on API failure, retry logic for network errors]
+```
+
+Only include NFRs the project actually needs — don't add generic ones. These feed into Phase 6 hardening audit thresholds.
+
+Save both to the top of `docs/plans/sprint-tasks.md`, before the task list.
+
+## Step 1: Break Down
+
+Decompose the architecture into ordered, atomic tasks. Each task must be:
+
+- **Implementable independently** — a developer agent can build it without needing unfinished work from other tasks
+- **Testable** — there are concrete acceptance criteria that can be verified
+- **Scoped to MVP** — if the design doc says a feature is deferred, do not create tasks for it
+
+For each task:
+
+```
+### Task [N]: [name]
+**Type:** frontend / backend / integration / infrastructure
+**Description:** [what to build, 2-3 sentences]
+**Acceptance Criteria:**
+- [ ] [specific, verifiable criterion]
+- [ ] [specific, verifiable criterion]
+**Dependencies:** [task numbers that must complete first, or "none"]
+**Size:** S (< 1 hour) / M (1-3 hours) / L (3+ hours)
+**Behavioral Test:** [For UI tasks: "Navigate to [page], [action], verify [expected outcome]". For API tasks: "curl -X POST /api/[endpoint] with [payload] → expect [response]". For non-interactive tasks: "N/A"]
+```
+
+## Step 2: Order
+
+Order tasks by dependency chain, then by priority within each dependency level:
+
+1. Infrastructure/scaffolding first (project setup, database schema, base config)
+2. Core data model and API endpoints
+3. Primary user flow (the main thing the user does)
+4. Supporting features
+5. Polish, error handling, edge cases
+
+Flag any circular dependencies — these indicate an architecture problem that needs resolution before building.
+
+## Step 3: Validate
+
+Check the task list against the design doc:
+
+- Every feature in MVP scope has at least one task
+- No task exceeds the MVP boundary
+- No task is too large (L tasks should be split if possible)
+- Dependency chains are no deeper than 3 levels
+- Acceptance criteria are specific enough that a developer agent can verify them without ambiguity
+
+## Step 4: Save
+
+Save to `docs/plans/sprint-tasks.md`.

package/protocols/smoke-test.md

@@ -0,0 +1,110 @@
+# Smoke Test Protocol (Behavioral Verification via agent-browser)
+
+You are the orchestrator. You are about to verify that a completed task actually works in a browser by interacting with it and collecting machine-readable evidence.
+
+## When to Run
+
+After a UI-affecting task passes the Verification Protocol. Skip for non-UI tasks (API-only, config, infrastructure, CLI tools). If the task has no behavioral acceptance criteria or no affected page/route, skip.
+
+## Inputs
+
+- **Acceptance criteria**: the task's behavioral acceptance criteria (e.g., "clicking Submit saves the form and shows a success toast").
+- **Affected route**: the page or route to test (e.g., `/settings`).
+
+## Step 0: Preflight
+
+Check that `agent-browser` is available:
+
+```
+which agent-browser
+```
+
+If not installed, log "SMOKE: SKIPPED -- agent-browser not available" to `docs/plans/.build-state.md` and return. Do not block the build.
+
+## Step 1: Start Dev Server
+
+Detect the dev script from `package.json` (`dev`, `start`, or `serve`). If the server is already running on the expected port, skip. Otherwise start it in the background and wait for the port to be listening.
+
+## Step 2: Capture Baseline
+
+```
+agent-browser open http://localhost:[port]/[affected-route]
+agent-browser wait --load networkidle
+agent-browser snapshot -i
+```
+
+Save the snapshot output as the "before" state. This is your baseline for diffing.
+
+## Step 3: Execute Acceptance Criteria
+
+For EACH behavioral acceptance criterion, sequentially:
+
+1. **Interact** -- execute the required action (`agent-browser click`, `fill`, `select`, `press`, etc.).
+2. **Diff** -- `agent-browser diff snapshot`. If the diff is empty after an interaction that should change the DOM, the feature is broken. Mark criterion FAIL.
+3. **Wait for outcome** -- `agent-browser wait --text "expected outcome"` with a 10s timeout. Timeout means FAIL.
+4. **Check network** -- `agent-browser network requests --status 4xx,5xx`. Any failed API call related to this criterion means FAIL.
+
+After each page navigation, re-snapshot. Element refs (`@e1`, `@e2`, etc.) invalidate on navigation.
+
+## Step 4: Collect Evidence
+
+After all criteria are tested:
+
+```
+agent-browser errors
+agent-browser screenshot --annotate
+agent-browser network har stop
+```
+
+For UI tasks, also capture a mobile viewport screenshot:
+
+```
+agent-browser resize 375 812
+agent-browser screenshot --annotate
+```
+
+Save the mobile screenshot to the evidence directory as `[task-name]-mobile.png`.
+
+```
+agent-browser resize 1920 1080
+```
+
+If the mobile screenshot shows horizontal scrolling, overlapping elements, or text smaller than 14px, flag as a UX issue in the smoke test results.
+
+Save all evidence to `docs/plans/evidence/[task-name]/`:
+
+| File | Content | Format |
+|------|---------|--------|
+| `before.snapshot.txt` | Baseline DOM snapshot | text |
+| `after.snapshot.txt` | Final DOM snapshot | text |
+| `screenshot.png` | Annotated screenshot of final state | image |
+| `errors.txt` | Uncaught JS exceptions | text |
+| `session.har` | Full network trace | HAR |
+
+Start HAR capture (`agent-browser network har start`) at Step 2 and stop at Step 4. The HAR file is saved for Phase 6.2d fake data analysis -- do not parse it here.
+
+## Step 5: Verdict
+
+**PASS**: all criteria verified, zero uncaught exceptions, zero failed API calls. Log "SMOKE: PASS" to `docs/plans/.build-state.md`. Close the browser.
+
+**FAIL**: spawn a fix agent with this prompt:
+
+"Fix smoke test failure for [task-name]. EXPECTED: [criterion text]. ACTUAL: [what happened -- empty diff / timeout / network error]. Evidence: [annotated screenshot path], [snapshot diff], [error log], [failed network requests]. Fix the implementation to match the expected behavior."
+
+After the fix agent completes, re-run from Step 2.
+
+<HARD-GATE>
+MAX 2 RETRY CYCLES: smoke -> fix -> re-smoke -> fix -> re-smoke. If still failing after 2 fix attempts:
+- **Interactive mode:** present evidence to the user. Include the annotated screenshot, snapshot diff, and error log.
+- **Autonomous mode:** log "SMOKE: FAILED after 2 retries" to `docs/plans/build-log.md` and proceed with a warning.
+Do not loop further.
+</HARD-GATE>
+
+## Rules
+
+- Use `agent-browser` CLI commands only. Not Playwright MCP, not Playwright directly.
+- Evidence is for the agent, not humans. No video recording, no dashboards.
+- Element refs (`@e1`, `@e2`) invalidate on every page change. Re-snapshot after any navigation.
+- One criterion at a time. Measure each interaction's impact before moving to the next.
+- HAR file is for downstream analysis (Phase 6.2d). This protocol does not parse it.
+- `agent-browser close` before returning, regardless of pass/fail.

package/protocols/verify.md

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

package/protocols/web-phase-branches.md

@@ -0,0 +1,201 @@
+# Web Phase Branches
+
+_Loaded into orchestrator session context when `project_type=web` (the default). Contains per-phase web-specific instructions. Mode-agnostic phase scaffolding lives in `commands/build.md`._
+
+## Phase 3 — Design (web branch)
+
+**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 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. Phase 4 (Foundation) WILL NOT START without `docs/plans/visual-design-spec.md`. If it does not exist, return here.
+
+### 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.
+
+Phase 4 HARD-GATE: web mode requires `docs/plans/visual-design-spec.md` to exist before Phase 4 starts. If missing, return to Phase 3.
+
+## Phase 4 — Foundation (web branch)
+
+### Step 4.1 — Scaffolding (web)
+
+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 (web, 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 (web)
+
+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'."
+
+## Phase 5 — Build (web branch)
+
+### Step 5.1 — Implement (web)
+
+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.
+
+### Step 5.2 — Metric Loop (web)
+
+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.
+
+### Step 5.3b — Behavioral Smoke Test (web)
+
+Uses agent-browser against localhost to open the app, execute the task's behavioral acceptance criteria, and verify the feature actually works. Evidence saved to `docs/plans/evidence/[task-name]/`: annotated screenshot, snapshot diff, error log, network log, HAR file.
+
+## Phase 6 — Harden (web branch)
+
+### 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.
+
+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.4 in `commands/build.md`).
+
+### 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 (in `commands/build.md`).
+
+## Phase 7 — Ship (web branch)
+
+### Step 7.1 — Documentation (web)
+
+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'."
+
+Deployment target per the design doc (Vercel/Netlify/Railway/Fly.io/etc.) — include the deploy flow specific to that target in the README.

package/skills/ios/_VENDORED.md

@@ -0,0 +1,60 @@
+# Vendored iOS Skills (P0)
+
+_Wholesale copies from `research/swift-skills/` per `research/swift-skills/_docs/_COMPARISON.md` adoption plan. Source repos are the authoritative version — update from source, don't edit in place._
+
+| Skill | Source | License | Copyright | Captured |
+|---|---|---|---|---|
+| swiftui-pro | twostraws/SwiftUI-Agent-Skill | MIT | Paul Hudson | 2026-04-04 |
+| swift-concurrency | AvdLee/Swift-Concurrency-Agent-Skill | MIT | Antoine van der Lee | 2026-04-04 |
+| swift-security-expert | ivan-magda/swift-security-skill | MIT | Ivan Magda | 2026-04-04 |
+| swiftdata-pro | twostraws/SwiftData-Agent-Skill | MIT | Paul Hudson | 2026-04-04 |
+| swift-testing-expert | AvdLee/Swift-Testing-Agent-Skill | MIT | Antoine van der Lee | 2026-04-04 |
+| swift-accessibility | PasqualeVittoriosi/swift-accessibility-skill | MIT | Pasquale Vittoriosi | 2026-04-04 |
+| swiftui-ui-patterns | Dimillian/Skills | MIT | Dimillian | 2026-04-04 |
+| swiftui-view-refactor | Dimillian/Skills | MIT | Dimillian | 2026-04-04 |
+| swiftui-liquid-glass | Dimillian/Skills | MIT | Dimillian | 2026-04-04 |
+| swiftui-performance-audit | Dimillian/Skills | MIT | Dimillian | 2026-04-04 |
+| swiftui-design-principles | arjitj2 | license check pending | arjitj2 | 2026-04-04 |
+| ios-hig | johnrogers/claude-swift-engineering | MIT | John Rogers | 2026-04-04 |
+| ios-26-platform | johnrogers/claude-swift-engineering | MIT | John Rogers | 2026-04-04 |
+| widgetkit | dpearson2699/swift-ios-skills | PolyForm Perimeter 1.0 | dpearson2699 | 2026-04-04 |
+| activitykit | dpearson2699/swift-ios-skills | PolyForm Perimeter 1.0 | dpearson2699 | 2026-04-04 |
+| app-intents | dpearson2699/swift-ios-skills | PolyForm Perimeter 1.0 | dpearson2699 | 2026-04-04 |
+| apple-on-device-ai | dpearson2699/swift-ios-skills | PolyForm Perimeter 1.0 | dpearson2699 | 2026-04-04 |
+| ios-debugger-agent | Dimillian/Skills | MIT | Dimillian | 2026-04-04 |
+
+## Update procedure
+
+1. `cd research/swift-skills/<category>/<repo>/ && git pull`
+2. Copy the inner skill dir + root `LICENSE` into `skills/ios/<skill>/`
+3. Bump the Captured date in the table above
+4. Spot-check `SKILL.md` frontmatter `name:` still matches the target dir name
+
+## Excluded from vendoring
+
+- `.git/`, `node_modules/`, `.DS_Store`
+- Repo-root `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `package.json`
+- Repo-root `tests/` (swift-security-skill only)
+- `AGENTS.md`, `CLAUDE.md` at repo root (swift-security-skill)
+
+## Missing LICENSE files
+
+The following skill dirs currently lack a `LICENSE` file and need one copied in from upstream (or an in-house LICENSE added for stubs):
+
+- `ios-26-platform/` — vendored from johnrogers/claude-swift-engineering; upstream MIT LICENSE to be copied in.
+- `ios-hig/` — vendored from johnrogers/claude-swift-engineering; upstream MIT LICENSE to be copied in.
+- `ios-bootstrap/` — in-house stub; needs an in-house LICENSE.
+- `ios-entitlements-generator/` — in-house stub; needs an in-house LICENSE.
+- `ios-info-plist-hardening/` — in-house stub; needs an in-house LICENSE.
+- `ios-maestro-flow-author/` — in-house stub; needs an in-house LICENSE.
+
+## In-House Skills (buildanything iOS mode)
+
+Authored in-house for the buildanything plugin. Not vendored from upstream.
+
+| Skill | Status | Purpose | Fleshed-out? | Created |
+|---|---|---|---|---|
+| ios-bootstrap | expanding | Phase -1 scaffolding: create Xcode project, wire XcodeBuildMCP, verify toolchain | stub | 2026-04-04 |
+| ios-entitlements-generator | expanding | Derive `.entitlements` file from required iOS capabilities (Keychain, Push, HealthKit, etc.) | stub | 2026-04-04 |
+| ios-info-plist-hardening | expanding | Populate Info.plist usage-description strings, ATS settings, privacy manifest alignment | stub | 2026-04-04 |
+| ios-maestro-flow-author | expanding | Author Maestro `.yaml` E2E flows for critical user journeys | stub | 2026-04-04 |