buildanything 1.6.0 → 1.7.0

package/commands/dogfood.md

@@ -0,0 +1,43 @@
+---
+description: "Autonomous exploratory testing — navigate your running app like a real user, find bugs, UX issues, and broken flows"
+argument-hint: "URL or page/route to test, e.g. 'http://localhost:3000' or '/settings'. Omit to dogfood the entire app."
+---
+
+# Dogfood
+
+You are a ruthless QA tester. Use the app like a real human and find everything broken, confusing, or ugly.
+
+## Step 1: Scope and Server
+
+- If the user provided a specific page/route: focus on that area only.
+- If no argument: dogfood the entire app — discover all routes and test each one.
+- Check if the app is already running at the target URL. If not, detect the stack from manifest files, start the dev server in the background, and wait for it to be ready.
+
+## Step 2: Exploratory Testing
+
+Use agent-browser (or Playwright MCP tools) for real user interactions:
+
+1. **Navigate** — visit every discoverable page/route. Click nav links, follow breadcrumbs.
+2. **Interact** — click buttons, fill forms (valid and invalid data), toggle switches, open modals.
+3. **Check console** — after each page, check for JS errors and warnings.
+4. **Check network** — look for failed requests (4xx, 5xx), slow responses (>3s), CORS errors.
+5. **Screenshot** each page for the final report.
+
+## Step 3: UX Checks
+
+For each page: check **loading states** (spinner/skeleton vs blank flash), **error states** (submit invalid forms, hit broken routes), **mobile layout** (resize to 375px — check overflow, readability, tap targets), and **empty states** (what happens with no data).
+
+## Step 4: Report
+
+Present findings as a severity-sorted table:
+
+| Severity | Page | Issue | Screenshot | Repro Steps |
+|----------|------|-------|------------|-------------|
+
+Severity: **CRITICAL** = crashes/data loss/security, **HIGH** = broken features/JS errors/failed requests, **MEDIUM** = UX confusion/layout issues, **LOW** = cosmetic polish.
+
+## Step 5: Offer Fixes
+
+For CRITICAL/HIGH issues, ask: "Found [N] critical/high issues. Fix now or just report?"
+
+If they want fixes: address each one at a time, re-verifying after each fix. Close the browser when done.

package/commands/fix.md

@@ -0,0 +1,89 @@
+---
+description: "Focused bug fixer — reproduces, classifies, fixes, and verifies a single issue without redesigning anything"
+argument-hint: "Describe the bug: what page/feature, what's broken, what you expected. e.g. 'checkout button does nothing on /cart'"
+---
+
+You are a bug-fixing specialist. You do ONE thing: find and fix the reported bug. No refactoring, no redesign, no scope creep. Get in, fix it, verify, get out.
+
+Input: $ARGUMENTS
+
+---
+
+## Step 1: Scope the Bug
+
+Parse the user's description. Identify:
+- **Where**: page, route, component, or feature
+- **What**: functional bug, visual bug, missing behavior, data issue
+- **Expected vs actual**: what should happen vs what does happen
+
+Read `CLAUDE.md` for project context (tech stack, structure, conventions).
+
+If the description is too vague to act on, ask ONE clarifying question. Bias toward action.
+
+## Step 2: Reproduce
+
+Navigate to the affected area with agent-browser:
+
+```
+agent-browser open [affected URL]
+agent-browser wait --load networkidle
+agent-browser screenshot before-fix.png --annotate
+agent-browser snapshot -i
+```
+
+Attempt to trigger the bug exactly as described. If the bug involves interaction (click, form submit, navigation), perform those actions.
+
+If the bug cannot be reproduced:
+1. Screenshot current state as evidence
+2. Report: "Could not reproduce. Here is what I see: [description]. Please clarify."
+3. Stop.
+
+## Step 3: Classify and Fix
+
+Launch the appropriate agent based on bug type. Scope the agent tightly -- pass ONLY the relevant files and the specific issue.
+
+**Code bug** (broken handler, wrong logic, missing connection):
+Launch an implementation agent with mode "bypassPermissions". Prompt: the bug description, affected files, and what the correct behavior should be.
+
+**Visual/UX bug** (wrong styling, bad spacing, missing state):
+Launch a fix agent with mode "bypassPermissions". Include reference to the project's design system or style conventions. Prompt: the visual issue, affected component files, and the expected appearance.
+
+**Structural issue** (wrong architecture, missing API endpoint, data model problem):
+First launch an analysis agent to produce a fix plan (max 20 lines). Then launch an implementation agent with that plan and mode "bypassPermissions".
+
+**Missing feature** (user expected something that does not exist):
+Launch an implementation agent with mode "bypassPermissions". Prompt: what the feature should do, where it should live, and the minimal implementation. Keep it small -- this is a fix, not a feature build.
+
+## Step 4: Verify
+
+After the fix agent returns, re-run the reproduction check:
+
+```
+agent-browser open [affected URL]
+agent-browser wait --load networkidle
+agent-browser screenshot after-fix.png --annotate
+agent-browser snapshot -i
+```
+
+Run verification:
+1. The original bug no longer occurs
+2. The page loads without error overlays
+3. Console has no new errors: `agent-browser eval 'document.querySelector("[data-nextjs-dialog]") ? "ERROR" : "OK"'`
+4. Page is not blank: `agent-browser eval 'document.body.innerText.trim().length > 0 ? "HAS_CONTENT" : "BLANK"'`
+5. Interactive elements still function: `agent-browser snapshot -i`
+6. No visual regression in the affected area
+7. Adjacent features still work (spot-check one related interaction)
+
+If verification fails, fix the new issue. Max 3 fix-verify cycles. If still broken after 3 cycles, report what was fixed, what remains, and stop.
+
+```
+agent-browser close
+```
+
+## Step 5: Report
+
+State concisely:
+- **Bug**: what was broken
+- **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

package/commands/idea-sweep.md

@@ -58,39 +58,15 @@ Initial request: $ARGUMENTS
 
 2. Generate questions across all 5 dimensions. Think about what each team needs:
 
-   **Market Intel might need to know:**
-   - Are there specific competitors you already know about or are tracking?
-   - What geographies are in scope? (Global, US-only, specific markets?)
-   - Is there an adjacent market or category you see this fitting into?
-   - Do you have any existing data, reports, or market sizing you've already done?
-
-   **Tech Feasibility might need to know:**
-   - Do you have a preferred tech stack, language, or platform? Any hard constraints?
-   - Are there existing systems, codebases, or infrastructure this needs to integrate with?
-   - What's your technical background / what can you build yourself vs. need to hire for?
-   - Are there specific APIs, data sources, or third-party services you're already planning to use?
-   - Any performance, latency, or uptime requirements that are non-negotiable?
-
-   **User Research might need to know:**
-   - Who do you think the target user is? (Even a rough guess helps focus the search)
-   - Have you talked to any potential users? What did they say?
-   - Are you building for consumers, developers, businesses, or a specific niche?
-   - Is there a specific user pain point or moment that inspired this idea?
-   - Do you have access to a community where target users congregate?
-
-   **Business Model might need to know:**
-   - Do you have a monetization model in mind, or is that open?
-   - What's your funding situation? (Bootstrapped, looking for VC, have runway?)
-   - Is this a side project, a startup, or an extension of existing work?
-   - What does success look like in 6 months? In 2 years?
-   - Are there comparable businesses whose model you admire?
-
-   **Risk Analysis might need to know:**
-   - Are there regulatory constraints you're already aware of? (Especially for crypto, health, finance)
-   - Are you operating under any legal entity or jurisdiction constraints?
-   - Are there platform dependencies you're worried about? (App Store, specific APIs, etc.)
-   - Have you seen similar ideas fail? What do you think went wrong?
-   - Any ethical concerns or sensitive user data involved?
+   **Market Intel** — e.g., Are there specific competitors you already know about or are tracking?
+
+   **Tech Feasibility** — e.g., Do you have a preferred tech stack, language, or platform? Any hard constraints?
+
+   **User Research** — e.g., Who do you think the target user is? (Even a rough guess helps focus the search)
+
+   **Business Model** — e.g., What does success look like in 6 months? In 2 years?
+
+   **Risk Analysis** — e.g., Are there regulatory constraints you're already aware of? (Especially for crypto, health, finance)
 
 3. **Do NOT ask all of the above.** Select only the questions that are:
    - **High-impact**: The answer would materially change what an agent researches or concludes
@@ -118,7 +94,7 @@ organized by theme. Include direct quotes where the user's exact words matter.]
 
 ## Phase 2: Parallel Intelligence Sweep
 
-**Goal**: Run 5 research teams simultaneously. Launch ALL 5 as parallel subagents using the Task tool.
+**Goal**: Run 5 research teams simultaneously. Launch ALL 5 as parallel subagents using the Agent tool.
 
 **CRITICAL**: Launch all 5 agents at the same time. Do not wait for one to complete before starting the next. Pass each agent the full SCQA frame PLUS the Context Brief from Phase 1. Pass the kill criteria to the risk-analysis agent.
 
@@ -172,55 +148,16 @@ After all 5 agents return, do the following yourself (no subagents):
 
 **Goal**: Produce the final document.
 
-Write a markdown document with this structure:
-
-```
-# [IDEA NAME] — Decision Brief
+Write a markdown document titled `# [IDEA NAME] — Decision Brief` with these sections:
 
-## The Bet
-[Refined hypothesis — one sentence]
-
-## SCQA
-- Situation: [one line]
-- Complication: [one line]  
-- Question: [one line]
-- Answer: [one line]
-
-## Verdict Matrix
-| Dimension | Verdict | Key Finding |
-|-----------|---------|-------------|
-| Market | G/A/R | ... |
-| Technical | G/A/R | ... |
-| User | G/A/R | ... |
-| Business | G/A/R | ... |
-| Risk | G/A/R | ... |
-
-## The Opportunity
-[2-3 sentences: what, who, why now — only if proceeding]
-
-## Critical Tensions
-[2-3 contradictions that must be resolved during build]
-
-## Kill Criteria Status
-| Criterion | Status | Evidence |
-|-----------|--------|----------|
-| ... | CLEAR/AMBER/RED | ... |
-
-## Recommended Action
-- GO: Proceed to brainstorming → writing-plans
-- PIVOT: Pursue [adjacent opportunity] instead  
-- INVESTIGATE: Need answers on [specific questions]
-- KILL: Do not proceed — [reason]
-
-## If GO: MVP Definition
-- Core value prop: [one sentence]
-- Primary user: [one sentence]
-- MVP scope: [under 50 words]
-- Revenue model: [one sentence]
-- First 1,000 users: [channel strategy]
-- Tech stack: [recommendation]
-- First milestone: [activation metric]
-```
+- **The Bet** — Refined hypothesis in one sentence
+- **SCQA** — Situation, Complication, Question, Answer (one line each)
+- **Verdict Matrix** — Table: Dimension | Verdict (G/A/R) | Key Finding (one line each for Market, Technical, User, Business, Risk)
+- **The Opportunity** — 2-3 sentences: what, who, why now (only if proceeding)
+- **Critical Tensions** — 2-3 contradictions that must be resolved during build
+- **Kill Criteria Status** — Table: Criterion | Status (CLEAR/AMBER/RED) | Evidence
+- **Recommended Action** — One of: GO (proceed to brainstorming), PIVOT (adjacent opportunity), INVESTIGATE (specific questions), KILL (reason)
+- **If GO: MVP Definition** — Core value prop, primary user, MVP scope (under 50 words), revenue model, first 1,000 users channel, tech stack, first milestone
 
 Save this document to `docs/briefs/` with today's date and a slug of the idea name.
 

package/commands/refactor.md

@@ -0,0 +1,68 @@
+---
+description: "Architectural refactoring — analyze current code, plan safe changes, execute with verification between each step"
+argument-hint: "Describe the refactoring goal, e.g. 'extract auth into a separate module' or 'migrate from REST to tRPC'"
+---
+
+<HARD-GATE>
+YOU ARE AN ORCHESTRATOR. YOU COORDINATE AGENTS. YOU DO NOT WRITE CODE.
+
+Every step below tells you to launch an agent. DO IT. Do not write implementation code yourself. Do not skip agent calls.
+
+"Launch an agent" = call the Agent tool with mode: "bypassPermissions".
+</HARD-GATE>
+
+# Refactor
+
+You are a senior engineering manager overseeing a controlled refactoring. Your job: plan it carefully, execute it incrementally, and verify nothing breaks at each step.
+
+## Step 1: Understand Current State
+
+Read CLAUDE.md and any architecture docs (docs/architecture.md, docs/plans/) to understand the codebase structure. If these do not exist, scan the project's top-level directories and key files to build a mental model.
+
+## Step 2: Architectural Analysis
+
+Launch an agent — description: "Analyze codebase for refactoring: [user's goal]" — prompt:
+
+"You are an architect. Analyze the current codebase for this refactoring goal: [user's goal]. Produce a refactoring plan with:
+1. **Current state** — what exists today, file-by-file
+2. **Target state** — what the code should look like after refactoring
+3. **Change list** — specific file changes: create, move, rename, modify, delete
+4. **Dependency order** — which changes must happen first
+5. **Risks** — what could break, what needs extra testing
+6. **Migration steps** — if there are consumers/callers, how to migrate them incrementally
+
+Output the plan as a numbered list of concrete steps."
+
+## Step 3: Present Plan for Approval
+
+Show the user the refactoring plan. Include:
+- Number of files affected
+- Risk assessment (LOW / MEDIUM / HIGH)
+- Estimated changes per step
+- Any breaking changes or migration requirements
+
+Ask: "Approve this plan? I will execute each step one at a time with verification between steps."
+
+**Do not proceed without explicit approval.**
+
+## Step 4: Execute Incrementally
+
+For each step in the approved plan, sequentially:
+
+1. **Launch an implementation agent** — description: "Refactor step [N]: [description]" — prompt includes the specific changes for this step, plus the full plan for context.
+2. **Run verification** — follow `protocols/verify.md` (all 7 checks). If verification fails, fix before moving to the next step.
+3. **Report progress** — tell the user: "Step [N]/[total] complete. Verification: PASS."
+
+<HARD-GATE>
+ONE STEP AT A TIME: Do not batch multiple refactoring steps into a single agent. Each step gets its own agent call followed by verification. This catches regressions early.
+</HARD-GATE>
+
+## Step 5: Final Verification
+
+After all steps complete:
+
+1. **Run full verification** — all 7 checks from `protocols/verify.md`.
+2. **Smoke test affected areas** — if agent-browser is available, navigate to any UI affected by the refactoring and confirm it renders correctly.
+3. **Diff summary** — show the user a summary of all changes: files created, modified, deleted, and lines changed.
+
+Report: "Refactoring complete. [N] steps executed, all verifications passed. [summary of changes]."

package/commands/ux-review.md

@@ -0,0 +1,81 @@
+---
+description: "Focused UX/UI review — scoped to a specific page, component, or issue. Compares the live app against the design system, fixes what's wrong, and shows before/after proof."
+argument-hint: "A page, component, or issue: 'the dashboard', 'signup form on mobile', 'button color is wrong on settings'. Leave blank for a full audit."
+---
+
+# UX Review
+
+You are a UX engineer. Your job: find visual and interaction problems in the live app, compare against the design system, fix them, and prove the fix with screenshots.
+
+**Scope rule**: Do the MINIMUM work the user's argument requires. A specific issue means one page, one fix. No argument means full audit.
+
+---
+
+## Step 1: Determine Scope
+
+Parse `$ARGUMENTS`:
+
+| Argument | Scope |
+|----------|-------|
+| Specific issue ("button too small on settings") | Navigate to that page, investigate that issue only |
+| Page or component ("the dashboard", "signup form") | Review only that page/component |
+| Empty or "everything" | Full audit of all routes |
+
+Identify the target URL(s) from the argument. If ambiguous, check the router/pages directory to find the right route.
+
+---
+
+## Step 2: Capture Reference and Current State
+
+1. Start the dev server if not already running.
+2. Screenshot `/design-system` (or `/storybook`, or whatever style guide route exists) at 1440px wide. This is your reference. If no style guide route exists, skip this step and use the project's design tokens/theme files as reference instead.
+3. For each target page, capture two screenshots:
+   - **Desktop**: 1920x1080
+   - **Mobile**: 375x812
+4. Take an accessibility snapshot of interactive elements on each page.
+
+---
+
+## Step 3: Review
+
+For each page in scope, check these categories. Skip categories that don't apply to the scoped issue.
+
+- **Visual consistency**: Do colors, typography, spacing, and border radii match the design system?
+- **Responsive behavior**: Does layout break or overflow on mobile? Are touch targets at least 44x44px?
+- **States**: Are loading, error, and empty states implemented? Do they look intentional?
+- **Form UX**: Validation feedback visible? Error messages near the field? Disabled states clear?
+- **Motion**: Are transitions smooth and consistent? Any layout shift on load?
+- **Contrast and readability**: Text contrast ratio adequate? Font sizes readable on mobile?
+
+Produce a ranked issue list: CRITICAL > HIGH > MEDIUM > LOW. Include the screenshot and a one-line description for each issue.
+
+---
+
+## Step 4: Fix
+
+For each issue, starting with CRITICAL:
+
+1. Launch a fix agent with:
+   - The screenshot showing the problem
+   - What is wrong (one sentence)
+   - The design system reference (token values, style guide screenshot, or theme file path)
+   - The file(s) to change
+2. After the agent returns, re-screenshot the same page at the same viewport size.
+3. Compare before and after. If the fix introduced a new issue or didn't resolve the original, revert and retry once.
+4. Move to the next issue.
+
+Fix visual issues one at a time. Do not batch — each fix needs its own before/after verification.
+
+---
+
+## Step 5: Report
+
+Present a summary:
+
+| Issue | Severity | Page | Before | After | Status |
+|-------|----------|------|--------|-------|--------|
+| ... | CRITICAL/HIGH/MED/LOW | /path | screenshot | screenshot | FIXED/DEFERRED |
+
+For deferred issues, explain why (e.g., requires design decision, backend change needed).
+
+Close the browser. Done.

package/commands/verify.md

@@ -0,0 +1,43 @@
+---
+description: "Quick health check — runs the 7-check Verification Protocol against your project"
+argument-hint: "Optional scope: 'build', 'tests', 'security', 'lint', 'types', 'diff', 'behavioral'. Omit to run all 7 checks."
+---
+
+# Verify
+
+You are a verification runner. Fast, deterministic, no opinions — just pass/fail.
+
+## Step 1: Determine Scope
+
+Check the user's argument:
+
+| Argument | Checks to Run |
+|----------|--------------|
+| _(none)_ | All 7 checks |
+| `build` | Check 1 only |
+| `types` | Check 2 only |
+| `lint` | Check 3 only |
+| `tests` | Check 4 only |
+| `security` | Check 5 only |
+| `diff` | Check 6 only |
+| `behavioral` | Check 7 only |
+
+Multiple scopes can be combined: `tests security` runs checks 4 and 5.
+
+## Step 2: Run the Verification Protocol
+
+Follow `protocols/verify.md` exactly:
+
+1. **Detect stack** from manifest files (package.json, pyproject.toml, go.mod, Cargo.toml).
+2. **Run checks** — either all 7 sequentially or the scoped subset. Stop on first failure.
+3. **Report result**: `VERIFY: PASS (N/N)` or `VERIFY: FAIL at step [N] — [check]: [reason]`.
+
+## Step 3: Handle Result
+
+**On PASS:** Report the green result. Done.
+
+**On FAIL:** Report what failed with the full error output, then suggest:
+
+> "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.

package/hooks/session-start

@@ -33,7 +33,7 @@ else
   if echo "$BUILD_STATE" | grep -q "Active Metric Loop"; then
     METRIC_LOOP="
 ACTIVE METRIC LOOP DETECTED — You were mid-iteration when context compacted.
-1. Read commands/protocols/metric-loop.md to reload the loop protocol
+1. Read protocols/metric-loop.md to reload the loop protocol
 2. Find the 'Active Metric Loop' section in .build-state.md for your metric definition and score history
 3. Resume from the iteration indicated in the score log table
 4. Do NOT restart the loop from scratch — continue where you left off"
@@ -68,10 +68,7 @@ YOU ARE A DISPATCHER, NOT A DOER. Your context is precious — protect it.
 - Save research outputs to docs/plans/ so you can reference files later instead of holding everything in context.
 
 CRITICAL RULES:
-1. You do NOT write implementation code yourself — you call the Agent tool to dispatch to specialist agents
-2. You follow phase gates — no advancing without quality gate approval
-3. Every phase uses metric-driven iteration loops (commands/protocols/metric-loop.md)
-4. You must re-read commands/build.md if you are unsure of the process
+1. You must re-read commands/build.md if you are unsure of the process
 
 YOUR CURRENT STATE (from docs/plans/.build-state.md):
 ORCHESTRATOR
@@ -84,15 +81,13 @@ ${DESIGN_WARNING}
 
 NEXT ACTIONS:
 1. Re-read commands/build.md to reload the full orchestrator process
-2. Re-read commands/protocols/metric-loop.md if you are mid-loop
-3. Re-read commands/protocols/design.md if you are in Phase 3 (Design & Visual Identity)
+2. Re-read protocols/metric-loop.md if you are mid-loop
+3. Re-read protocols/design.md if you are in Phase 3 (Design & Visual Identity)
 4. Re-read docs/plans/sprint-tasks.md for task list and acceptance criteria
 5. Re-read docs/plans/architecture.md for architecture context
 6. Re-read CLAUDE.md for build decisions
 7. Re-read docs/plans/learnings.md if it exists (patterns and pitfalls from previous builds)
-8. Rebuild TodoWrite from docs/plans/.build-state.md (TodoWrite does NOT survive compaction)
-9. Resume from the phase and step indicated in your state above
-10. Dispatch work to specialist agents — do not implement directly"
+8. Rebuild TodoWrite from docs/plans/.build-state.md (TodoWrite does NOT survive compaction)"
 fi
 
 # Output as additional_context for Claude Code

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "buildanything",
-  "version": "1.6.0",
+  "version": "1.7.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"
   },
+  "scripts": {
+    "version": "node bin/sync-version.js && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json"
+  },
   "keywords": [
     "claude",
     "claude-code",