buildanything 1.7.0 → 1.8.0

package/commands/ux-review.md

@@ -11,6 +11,15 @@ You are a UX engineer. Your job: find visual and interaction problems in the liv
 
 ---
 
+## Project-type branching
+
+Read `docs/plans/.build-state.md` → `project_type`.
+
+- **If `project_type=web`** (or unset): follow Steps 1-5 below (existing web flow, unchanged).
+- **If `project_type=ios`**: skip Steps 1-5. Run the iOS UX Review twin (§ iOS UX Review at the bottom of this file). iOS has no `/design-system` route — HIG + a synthesized design board are the reference.
+
+---
+
 ## Step 1: Determine Scope
 
 Parse `$ARGUMENTS`:
@@ -79,3 +88,57 @@ Present a summary:
 For deferred issues, explain why (e.g., requires design decision, backend change needed).
 
 Close the browser. Done.
+
+---
+
+## iOS UX Review (project_type=ios)
+
+iOS has no `/design-system` component gallery. The reference surface is **Apple HIG + a synthesized design board** (competitor screenshots + app vibe). Inherit the Senior iOS Engineer persona from `protocols/ios-context.md` for every dispatched agent.
+
+### Step 1: Preflight
+
+**Run iOS preflight:** see `protocols/ios-preflight.md`. Then read app vibe words + category from `docs/plans/.build-state.md` (captured in Phase 3).
+
+### Step 2: Design Board (read-only)
+
+The design board is GENERATED by `/buildanything:build` Phase 3 Step 3.1 — this command only READS it.
+
+- If `docs/plans/ios-design-board.md` does NOT exist: **HALT** and instruct the user to run `/buildanything:build` Phase 3 first. Do not regenerate here.
+- If it exists: use it as-is. Do NOT re-scrape references. **Cache rule:** to refresh the board, the user must delete `docs/plans/ios-design-board.md` and re-run Phase 3.
+
+### Step 3: Capture Current State
+
+Via XcodeBuildMCP:
+1. Boot simulator (default: iPhone 17 Pro, iOS 26.x)
+2. Build + launch app
+3. Walk the primary user flow; capture simulator screenshots for each screen in scope
+4. Save to `docs/plans/ios-ux-review/screens/` with timestamped filenames
+
+For scoped reviews (single screen/issue from `$ARGUMENTS`), capture only that screen.
+
+### Step 4: Dispatch Review Skills (parallel-safe)
+
+Run all four in parallel, each inheriting `protocols/ios-context.md`:
+
+a. **`skills/ios/ios-debugger-agent`** — simulator screenshot sweep + UI state capture + console/log scrape for runtime UI warnings.
+b. **`skills/ios/ios-hig`** (audit mode) — HIG severity audit. Return findings framed as **P0** (blocker / ships broken), **P1** (fix-before-ship), **P2** (polish).
+c. **`skills/ios/swift-accessibility`** (Mode 3: audit pass) — VoiceOver labels, Dynamic Type scaling, contrast ratios, hit-target sizes across all SwiftUI screens in scope.
+d. **`skills/ios/swiftui-design-principles`** — 10-rule visual polish checklist (spacing, hierarchy, alignment, color, type, motion, consistency, affordance, feedback, restraint).
+e. **`writing-for-interfaces`** — microcopy + tone review. If `skills/ios/writing-for-interfaces/` does not exist, skip microcopy review and log a NOTE in the UX report: "Microcopy review skipped — writing-for-interfaces not yet ported."
+
+### Step 5: Compare Against Design Board
+
+Diff live simulator screenshots against `docs/plans/ios-design-board.md`:
+- Where does the live app match the board's vibe / patterns?
+- Where does it drift (color, spacing, hierarchy, type, navigation model)?
+- Which board patterns are NOT yet implemented but should be?
+
+### Step 6: Output Report
+
+Write `docs/plans/ios-ux-review-report.md`:
+
+| Finding | Severity | Screen | Source | Recommended Fix |
+|---------|----------|--------|--------|-----------------|
+| ... | P0/P1/P2 | ContentView | hig / a11y / principles / board-diff | one-line fix |
+
+Include: summary counts per severity, top 3 fixes to do next, list of screens reviewed, path to design board. Do NOT auto-fix — `/fix` (iOS branch) consumes this report.

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.0",
+  "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.