buildanything 1.2.1 → 1.6.0

package/commands/protocols/planning.md

@@ -0,0 +1,56 @@
+# 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 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)
+```
+
+## 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/commands/protocols/verify.md

@@ -0,0 +1,63 @@
+# 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` |
+
+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 6 checks sequentially, stop on first failure. Report: VERIFY: PASS (6/6) 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 |
+
+<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 (6/6)` 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 (`commands/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]." |
+
+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/hooks/hooks.json

@@ -14,11 +14,11 @@
     ],
     "PreCompact": [
       {
-        "matcher": "",
+        "matcher": ".*",
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "ORCHESTRATOR STATE SAVE — Context is about to be compacted. If you are running the /buildanything:build pipeline, you MUST do these things NOW before your context is lost:\n\n1. Use TodoWrite to update all task statuses (complete, in-progress, pending)\n2. Write `docs/plans/.build-state.md` with: current phase, step, task progress, retry counter, agents used, pending quality gate results\n3. The next thing that will happen after compaction is the SessionStart hook will fire and re-inject your orchestrator identity. But you MUST save state NOW or your progress tracking is lost."
+            "prompt": "ORCHESTRATOR STATE SAVE — Context is about to be compacted. If you are running the /buildanything:build pipeline, you MUST do these things NOW before your context is lost:\n\n1. Save all task statuses to docs/plans/.build-state.md (TodoWrite does NOT survive compaction — .build-state.md is your only persistent store)\n2. Write `docs/plans/.build-state.md` with ALL of the following:\n   - Current phase and step\n   - Task progress (which tasks done, which in progress)\n   - If you are in a metric loop: the Active Metric Loop section with metric definition, current iteration, full score history table, and what action to take next\n   - Agents used so far\n   - Whether running in autonomous mode\n   - dispatches_since_save and last_save values\n3. The next thing after compaction is the SessionStart hook re-injecting your state. Save EVERYTHING or you lose your metric loop progress."
           }
         ]
       }

package/hooks/session-start

@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
 # buildanything: SessionStart hook
 # Re-injects orchestrator identity after context compaction, resume, or clear.
-# Modeled after superpowers' session-start pattern.
 
 # Check if a build pipeline is active by looking for .build-state.md
 BUILD_STATE=""
@@ -9,20 +8,69 @@ if [ -f "docs/plans/.build-state.md" ]; then
   BUILD_STATE=$(cat "docs/plans/.build-state.md")
 fi
 
+# Skip if the build is already complete
+if echo "$BUILD_STATE" | grep -q "Phase: 7 COMPLETE"; then
+  BUILD_STATE=""
+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)
+  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.
+Phase 3 (Design & Visual Identity) may have been skipped. DO NOT proceed with Foundation or Build.
+Return to Phase 3 and produce visual-design-spec.md before continuing."
+  fi
+fi
+
 # If no active build, just provide a minimal reminder
 if [ -z "$BUILD_STATE" ]; then
   CONTEXT="buildanything plugin is installed. Use /buildanything:build to start a full product pipeline, or /buildanything:idea-sweep for parallel research."
 else
-  # Active build detected — re-inject full orchestrator context
+  # Check if there's an active metric loop
+  METRIC_LOOP=""
+  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
+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"
+  fi
+
+  # Check for resume point
+  RESUME_POINT=""
+  if echo "$BUILD_STATE" | grep -q "Resume Point"; then
+    RESUME_POINT="
+RESUME POINT DETECTED — This build can be continued with /buildanything:build --resume.
+The state file contains a structured Resume Point with phase, step, and task progress.
+Reset dispatches_since_save to 0 (fresh context window)."
+  fi
+
+  # Active build detected — inject orchestrator identity and rules directly
+  # These are inlined so they survive context compaction (no file re-read required)
   read -r -d '' CONTEXT << 'ORCHESTRATOR'
 BUILDANYTHING ORCHESTRATOR — ACTIVE BUILD DETECTED
 
-You are the Agents Orchestrator running the buildanything pipeline. You are NOT a solo developer. You coordinate specialist agents.
+<HARD-GATE>
+YOU ARE AN ORCHESTRATOR. YOU COORDINATE AGENTS. YOU DO NOT WRITE CODE.
+Every step below tells you to call the Agent tool. DO IT. Do not role-play as the agent. Do not write implementation code yourself. Do not skip the Agent tool call "because it's faster."
+"Launch an agent" = call the Agent tool (the actual tool in your toolbar, the one that spawns a subprocess).
+For implementation agents, set mode: "bypassPermissions".
+For parallel work, put multiple Agent tool calls in ONE message.
+</HARD-GATE>
+
+ORCHESTRATOR DISCIPLINE:
+YOU ARE A DISPATCHER, NOT A DOER. Your context is precious — protect it.
+- TWO agent types: Research/analysis agents (keep full output — it's your decision-making input). Implementation agents (keep summary only — the code is in the repo).
+- NEVER read source code, write code, or debug yourself — spawn agents for all implementation work.
+- 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 dispatch to specialist agents
+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 task goes through Dev→Test→Review loops
+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
 
 YOUR CURRENT STATE (from docs/plans/.build-state.md):
@@ -30,12 +78,21 @@ ORCHESTRATOR
 
   CONTEXT="${CONTEXT}
 ${BUILD_STATE}
+${METRIC_LOOP}
+${RESUME_POINT}
+${DESIGN_WARNING}
 
 NEXT ACTIONS:
 1. Re-read commands/build.md to reload the full orchestrator process
-2. Resume from the phase and step indicated in your state above
-3. Use TodoWrite to track task progress
-4. Dispatch work to specialist agents — do not implement directly"
+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)
+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"
 fi
 
 # Output as additional_context for Claude Code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildanything",
-  "version": "1.2.1",
+  "version": "1.6.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"