buildanything 1.8.0 → 2.1.1

package/agents/visual-research.md

@@ -0,0 +1,118 @@
+---
+name: visual-research
+description: Playwright-driven visual sweep of rival UIs or awards sites. Runs in two input modes — Competitive Audit or Inspiration Mining — and returns design-references.md grouped by DNA axis.
+color: blue
+model: sonnet
+effort: medium
+---
+
+# Visual Research
+
+## Skill Access
+
+This agent does not consult vendored skills. It operates from its system prompt alone. Visual sweep via Playwright is evidence collection against the locked DNA axes; it does not need framework implementation guidance. Library catalog decisions happen in the downstream design agents.
+
+You run the Phase 3.1 visual sweep. The 6-axis Visual DNA has already been locked by Brand Guardian at Step 3.0 — your job is to validate and enrich that choice with concrete reference material, not to decide the direction. You are goal-directed, not exploratory. Every screenshot you return must be tagged with the DNA axis it exemplifies; anything else is catalogue noise.
+
+You run in one of two input modes, chosen by the caller:
+
+- **`competitive-audit`** — find 5-8 rival products that exemplify the locked DNA (not all competitors, just the ones that nail the axes we chose)
+- **`inspiration-mining`** — find 5-8 Awwwards / Godly / SiteInspire sites that match the DNA
+
+Both modes run the same Playwright capture loop with different URL seeds.
+
+## Inputs
+
+- Path to `DESIGN.md` — the locked 7-axis DNA lives in `## Overview > ### Brand DNA`
+- Mode flag: `competitive-audit` or `inspiration-mining`
+- Optional list of specific site URLs from the user or earlier research
+- Optional path to `docs/plans/phase1-scratch/findings-digest.md` (for competitor hints from Phase 1)
+
+## Core Responsibilities
+
+- Walk 5-8 candidate sites per run using Playwright MCP at desktop 1920x1080 and mobile 375x812
+- Analyze which DNA axes each site nails and which it fails on
+- Discard candidates that score below target on 3+ axes — they are not references for this DNA
+- Group surviving references by DNA axis in `design-references.md` (motion refs, material refs, typography refs, density refs, character refs)
+- Record the file:line or section locator where the reference element lives on each captured site
+
+## Hard Rules
+
+- Goal-directed, not exploratory. You are validating and enriching the locked DNA — you are not cataloguing the landscape. A reference that doesn't exemplify at least one locked DNA axis does not go in the file.
+- Every screenshot is tagged with the DNA axis or axes it exemplifies. Untagged captures are rejected.
+- Desktop 1920x1080 AND mobile 375x812 for every site. Breakpoint parity matters for the downstream Design Critic.
+- No self-authored commentary on rival products. Describe the visual treatment, cite the axis, move on.
+- If fewer than 4 candidates survive the filter, widen the URL seed list and re-run rather than padding with weak matches.
+
+## Workflow
+
+### Shared setup
+1. Read `DESIGN.md` `## Overview > ### Brand DNA`. Write the 7 axis values (Scope, Density, Character, Material, Motion, Type, Copy) to a local scratchpad so every capture can be scored against them.
+2. Pick the mode branch below based on the input flag.
+
+### Competitive Audit mode
+3a. Build the candidate URL list:
+   - Start with user-provided URLs if any
+   - Read `docs/plans/phase1-scratch/findings-digest.md` if present and pull named rivals
+   - Otherwise, use WebFetch / WebSearch to find 10-15 products in the same category as the design-doc
+4a. For each candidate, visit the landing page, pricing page, and one core product screen. Score each against the 6 DNA axes on a 0-3 scale. Keep candidates with total ≥ 12.
+5a. For each survivor, capture desktop + mobile screenshots of the DNA-exemplifying sections (hero, key interactive, motion moments). Tag each capture with the DNA axis it exemplifies.
+
+### Inspiration Mining mode
+3b. Build the candidate URL list:
+   - Query Awwwards, Godly.website, and SiteInspire via WebFetch for recent entries matching the DNA Character and Material values
+   - Supplement with user-provided URLs if any
+4b. For each candidate, visit the main page and any case-study detail pages that match the DNA. Apply the same 0-3 × 6-axis score. Keep candidates with total ≥ 12.
+5b. Capture desktop + mobile screenshots of the DNA-exemplifying sections. Tag each capture.
+
+### Shared finalize
+6. Group captured references by DNA axis in `design-references.md`:
+   - `## Motion references` — 2-5 entries, each with URL, file path to screenshot, and one-line description of why it exemplifies the Motion axis
+   - `## Material references` — same format
+   - `## Typography references` — same format
+   - `## Density references` — same format
+   - `## Character references` — same format
+7. For any axis with fewer than 2 references, note it as a gap in the file footer. The Design Critic will work with what exists; the gap is an honest signal, not a failure.
+8. Write `design-references.md` to the plan directory using the Write tool. Return the file path plus a short summary (count per axis, mode used, survivor ratio).
+
+## Output Format
+
+`design-references.md` shape:
+
+```markdown
+---
+mode: competitive-audit
+dna_source: visual-dna.md
+captured_at: 2026-04-14
+candidate_count: 12
+survivor_count: 6
+---
+
+# Design References
+
+## Motion references
+- [Linear](https://linear.app) — `screens/linear-home-desktop.png` — scroll-bound section reveals exemplify Cinematic motion with long cubic-bezier curves
+- [Raycast](https://raycast.com) — `screens/raycast-hero-mobile.png` — micro-interactions on the hero CTA show Expressive motion without overshooting Cinematic
+
+## Material references
+- ...
+
+## Typography references
+- ...
+
+## Density references
+- ...
+
+## Character references
+- ...
+
+## Gaps
+- Motion references for "Cinematic + Dashboard" combination underpopulated — only 1 survivor. Design Critic should treat as weak evidence.
+```
+
+## Tools
+
+- Playwright MCP (primary) — `browser_navigate`, `browser_take_screenshot`, `browser_resize` for breakpoint parity
+- WebFetch / WebSearch for URL discovery
+- Write for the final `design-references.md`
+- Read for `DESIGN.md` and `docs/plans/phase1-scratch/findings-digest.md`

package/bin/adapters/cycle-counter-tool.ts

@@ -0,0 +1,155 @@
+/**
+ * Adapter: wraps Kiro's cycle-counter handlers in the SdkMcpToolDefinition
+ * shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/cycle-counter.ts) is owned by Kiro and
+ * must not be edited; this adapter lives here to preserve that boundary and
+ * to keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Kiro's handlers mutate the CounterState object in place. The adapter echoes
+ * the updated state back to the caller so the orchestrator can pipe it into
+ * a single atomic state_save (A3 crash-seam protocol).
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §4 Stage 4
+ * Task: 4.2.4
+ */
+
+import { z } from "zod";
+import {
+  cycleCounterCheck,
+  clearInFlightEdge,
+  handleStaleEdge,
+  type CounterState,
+} from "../../src/orchestrator/mcp/cycle-counter.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const inFlightEdgeSchema = z.object({
+  decision_id: z.string().min(1),
+  target_phase: z.string().min(1),
+  counter_value: z.number().int().nonnegative(),
+  started_at: z.string().min(1),
+});
+
+const counterStateSchema = z.object({
+  backward_routing_count: z.record(z.string(), z.number().int().nonnegative()),
+  backward_routing_count_by_target_phase: z.record(z.string(), z.number().int().nonnegative()),
+  in_flight_backward_edge: inFlightEdgeSchema.optional(),
+});
+
+const checkInputShape = {
+  state: counterStateSchema,
+  input: z.object({
+    decision_id: z.string().min(1),
+    target_phase: z.string().min(1),
+  }),
+  max_cycles: z.number().int().positive().optional(),
+};
+
+const clearInputShape = {
+  state: counterStateSchema,
+};
+
+const staleInputShape = {
+  state: counterStateSchema,
+  threshold_ms: z.number().int().positive().optional(),
+};
+
+export function buildCycleCounterCheckTool(tool: ToolConstructor) {
+  return tool(
+    "cycle_counter_check",
+    "Check and increment backward-routing counters (per-decision + per-target-phase). Returns {action: allow|escalate_to_user, decision_count, phase_count, state} where state is the mutated CounterState to persist via state_save.",
+    checkInputShape,
+    async (args) => {
+      try {
+        const state = args.state as CounterState;
+        const result = cycleCounterCheck(state, args.input, args.max_cycles);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ ...result, state }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `cycle_counter_check error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildClearInFlightEdgeTool(tool: ToolConstructor) {
+  return tool(
+    "clear_in_flight_edge",
+    "Clear the in_flight_backward_edge field (called by target phase on re-entry). Returns {state} for the caller to persist via state_save.",
+    clearInputShape,
+    async (args) => {
+      try {
+        const state = args.state as CounterState;
+        clearInFlightEdge(state);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ state }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `clear_in_flight_edge error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildHandleStaleEdgeTool(tool: ToolConstructor) {
+  return tool(
+    "handle_stale_edge",
+    "On --resume, if in_flight_backward_edge is older than threshold_ms (default 60000), decrement both counters and clear the edge. Returns {cleaned:boolean, state}.",
+    staleInputShape,
+    async (args) => {
+      try {
+        const state = args.state as CounterState;
+        const cleaned = handleStaleEdge(state, args.threshold_ms);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ cleaned, state }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `handle_stale_edge error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/adapters/scribe-tool.ts

@@ -0,0 +1,73 @@
+/**
+ * Adapter: wraps Kiro's scribeDecision(input, filePath) handler in the
+ * SdkMcpToolDefinition shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/scribe.ts) is owned by Kiro and must
+ * not be edited; this adapter lives here to preserve that boundary and to
+ * keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §4 Stage 1
+ * Task: 1.2.4
+ */
+
+import { resolve } from "node:path";
+import { z } from "zod";
+import { scribeDecision, loadCounters } from "../../src/orchestrator/mcp/scribe.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const DEFAULT_DECISIONS_PATH = "docs/plans/decisions.jsonl";
+
+const rejectedAlternativeSchema = z.object({
+  approach: z.string().min(1),
+  reason: z.string().min(1),
+  revisit_criterion: z.string().min(1),
+});
+
+const scribeInputShape = {
+  phase: z.string().min(1),
+  summary: z.string().min(1),
+  decided_by: z.string().min(1),
+  impact_level: z.enum(["low", "medium", "high", "critical"]),
+  chosen_approach: z.string().min(1),
+  rejected_alternatives: z.array(rejectedAlternativeSchema).max(3).optional(),
+  ref: z
+    .string()
+    .min(1)
+    .regex(/^[a-zA-Z0-9_\-./]+\.(md|json|jsonl|yaml|yml)(#[a-zA-Z0-9_\-/.]+)?$/),
+};
+
+export function buildScribeTool(tool: ToolConstructor, cwd: string) {
+  const decisionsPath = resolve(cwd, DEFAULT_DECISIONS_PATH);
+  loadCounters(decisionsPath);
+
+  return tool(
+    "scribe_decision",
+    "Append a decision row to docs/plans/decisions.jsonl. Single-writer per migration plan; validates against decisions.schema.json.",
+    scribeInputShape,
+    async (args) => {
+      try {
+        const row = scribeDecision(args, decisionsPath);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(row),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `scribe_decision error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/adapters/state-save-tool.ts

@@ -0,0 +1,130 @@
+/**
+ * Adapter: wraps Kiro's state-save handler (stateSave/stateRead/verifyIntegrity)
+ * in the SdkMcpToolDefinition shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/state-save.ts) is owned by Kiro and must
+ * not be edited; this adapter lives here to preserve that boundary and to
+ * keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §4 Stage 3
+ * Task: 3.2.4
+ */
+
+import { z } from "zod";
+import {
+  stateSave,
+  stateRead,
+  verifyIntegrity,
+} from "../../src/orchestrator/mcp/state-save.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const saveInputShape = {
+  path: z.string().min(1),
+  state: z.record(z.string(), z.unknown()),
+};
+
+const readInputShape = {
+  path: z.string().min(1),
+};
+
+const verifyInputShape = {
+  path: z.string().min(1),
+  expected_sha256: z.string().min(1),
+};
+
+export function buildStateSaveTool(tool: ToolConstructor) {
+  return tool(
+    "state_save",
+    "Atomically persist state to a JSON file via write-to-.tmp + fsync + rename. Returns {success, path, sha256, bytesWritten}. Single writer for .build-state.json.",
+    saveInputShape,
+    async (args) => {
+      try {
+        const result = stateSave(args.path, args.state as Record<string, unknown>);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `state_save error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildStateReadTool(tool: ToolConstructor) {
+  return tool(
+    "state_read",
+    "Read state from a JSON file and compute its SHA-256 checksum. Returns {state, sha256}.",
+    readInputShape,
+    async (args) => {
+      try {
+        const result = stateRead(args.path);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `state_read error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildVerifyIntegrityTool(tool: ToolConstructor) {
+  return tool(
+    "verify_integrity",
+    "Verify a state file's SHA-256 matches the expected checksum. Returns {matches:boolean}.",
+    verifyInputShape,
+    async (args) => {
+      try {
+        const matches = verifyIntegrity(args.path, args.expected_sha256);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ matches }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `verify_integrity error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/adapters/write-lease-tool.ts

@@ -0,0 +1,127 @@
+/**
+ * Adapter: wraps Kiro's write-lease handler (acquire/release/list) in the
+ * SdkMcpToolDefinition shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/write-lease.ts) is owned by Kiro and must
+ * not be edited; this adapter lives here to preserve that boundary and to
+ * keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §A5
+ * Task: 2.3.4
+ */
+
+import { z } from "zod";
+import {
+  acquireWriteLease,
+  releaseLease,
+  getActiveLeases,
+} from "../../src/orchestrator/mcp/write-lease.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const acquireInputShape = {
+  task_id: z.string().min(1),
+  file_paths: z.array(z.string().min(1)).min(1),
+};
+
+const releaseInputShape = {
+  task_id: z.string().min(1),
+};
+
+const listInputShape = {} as const;
+
+export function buildAcquireWriteLeaseTool(tool: ToolConstructor) {
+  return tool(
+    "acquire_write_lease",
+    "Acquire an exclusive write lease on one or more file paths for a task. Returns granted:true with the lease, or granted:false with conflict details when another task holds an overlapping lease.",
+    acquireInputShape,
+    async (args) => {
+      try {
+        const result = await acquireWriteLease(args.task_id, args.file_paths);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `acquire_write_lease error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildReleaseWriteLeaseTool(tool: ToolConstructor) {
+  return tool(
+    "release_write_lease",
+    "Release all write leases held by a task. Called by SubagentStop hook on dispatch return. Returns released:true if a lease existed, false otherwise.",
+    releaseInputShape,
+    async (args) => {
+      try {
+        const released = releaseLease(args.task_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ released }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `release_write_lease error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildListWriteLeasesTool(tool: ToolConstructor) {
+  return tool(
+    "list_write_leases",
+    "List all active write leases (holder, paths, acquired_at). Read-only; intended for orchestrator diagnostics and .build-state.json persistence snapshots.",
+    listInputShape,
+    async () => {
+      try {
+        const leases = getActiveLeases();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ leases }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `list_write_leases error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/buildanything-runtime.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin shim: delegates to the TypeScript entry via tsx.
+// Mirrors the hook pattern (npx --no-install tsx) used by subagent-start,
+// pre-tool-use, and compile-writer-owner-cache — consistent behavior across
+// the whole plugin when tsx is not globally installed.
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const tsEntry = path.join(__dirname, 'buildanything-runtime.ts');
+const result = spawnSync('npx', ['--no-install', 'tsx', tsEntry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+process.exit(result.status ?? (result.error ? 1 : 0));