buildwright 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildwright",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Agent-first autonomous development workflow. Ship code you don't read.",
   "license": "MIT",
   "engines": {

package/src/commands/init.js

@@ -46,11 +46,15 @@ function init() {
     const stat = fs.statSync(fs.realpathSync(src));
 
     if (stat.isDirectory()) {
-      console.log(`  Copying ${entry}/`);
-      copyDir(src, dest);
+      console.log(`  Copying ${entry}/ (adding new files only)`);
+      copyDir(src, dest, { skipExisting: true });
     } else {
-      console.log(`  Copying ${entry}`);
-      fs.copyFileSync(fs.realpathSync(src), dest);
+      if (fs.existsSync(dest)) {
+        console.log(`  Skipping ${entry} (already exists)`);
+      } else {
+        console.log(`  Copying ${entry}`);
+        fs.copyFileSync(fs.realpathSync(src), dest);
+      }
     }
   }
 

package/src/commands/update.js

@@ -62,6 +62,26 @@ async function downloadAndExtract() {
   return { tmpDir, extractedRoot };
 }
 
+/**
+ * Copy files from src to dest, but only files that exist in src.
+ * Files in dest that have no counterpart in src are left untouched.
+ */
+function copyUpstreamOnly(src, dest) {
+  for (const entry of fs.readdirSync(src)) {
+    const srcEntry = path.join(src, entry);
+    const destEntry = path.join(dest, entry);
+    const stat = fs.statSync(srcEntry);
+    if (stat.isDirectory()) {
+      fs.mkdirSync(destEntry, { recursive: true });
+      copyUpstreamOnly(srcEntry, destEntry);
+    } else {
+      if (!fs.existsSync(destEntry)) {
+        fs.copyFileSync(srcEntry, destEntry);  // only new files
+      }
+    }
+  }
+}
+
 async function update() {
   const cwd = process.cwd();
 
@@ -86,7 +106,8 @@ async function update() {
       throw new Error('Downloaded archive is missing .buildwright/ directory');
     }
 
-    // Update only the specified directories
+    // Update only the specified directories — overwrite upstream files only,
+    // never delete files the user added that don't exist in the upstream source.
     for (const dir of UPDATE_DIRS) {
       const src = path.join(srcBuildwright, dir);
       const dest = path.join(cwd, '.buildwright', dir);
@@ -94,17 +115,18 @@ async function update() {
         console.log(`  ${YELLOW}Skipping ${dir}/ (not found in latest release)${RESET}`);
         continue;
       }
-      console.log(`  Updating .buildwright/${dir}/`);
-      // Remove old and replace
-      fs.rmSync(dest, { recursive: true, force: true });
-      copyDir(src, dest);
+      console.log(`  Updating .buildwright/${dir}/ (adding new files only)`);
+      fs.mkdirSync(dest, { recursive: true });
+      // Copy only files that exist in upstream — preserves user-added files
+      copyUpstreamOnly(src, dest);
     }
 
-    // Also update CLAUDE.md if it exists in the download
+    // Also add CLAUDE.md if it doesn't already exist locally
     const srcClaude = path.join(extractedRoot, 'CLAUDE.md');
-    if (fs.existsSync(srcClaude)) {
-      console.log(`  Updating CLAUDE.md`);
-      fs.copyFileSync(srcClaude, path.join(cwd, 'CLAUDE.md'));
+    const destClaude = path.join(cwd, 'CLAUDE.md');
+    if (fs.existsSync(srcClaude) && !fs.existsSync(destClaude)) {
+      console.log(`  Adding CLAUDE.md`);
+      fs.copyFileSync(srcClaude, destClaude);
     }
 
     console.log('');
@@ -118,8 +140,8 @@ async function update() {
 
     console.log('');
     console.log(`${GREEN}${BOLD}Update complete!${RESET}`);
-    console.log('commands, agents, and claws are now up to date.');
-    console.log('Your steering docs (.buildwright/steering/) are unchanged.\n');
+    console.log('commands, agents, and claws: new files added. Existing files unchanged.');
+    console.log('Your custom files and steering docs are unchanged.\n');
 
   } catch (err) {
     console.error(`\nUpdate failed: ${err.message}`);

package/src/utils/copy-files.js

@@ -10,9 +10,11 @@ const path = require('path');
  * @param {string} dest - Destination directory path
  * @param {object} [opts]
  * @param {string[]} [opts.skip] - Relative paths (from src) to skip
+ * @param {boolean} [opts.skipExisting] - Skip files that already exist at dest
  */
 function copyDir(src, dest, opts = {}) {
   const skip = opts.skip || [];
+  const skipExisting = opts.skipExisting || false;
   const entries = fs.readdirSync(src, { withFileTypes: true });
   fs.mkdirSync(dest, { recursive: true });
 
@@ -32,7 +34,11 @@ function copyDir(src, dest, opts = {}) {
     if (stat.isDirectory()) {
       copyDir(realSrcPath, destPath, opts);
     } else {
-      fs.copyFileSync(realSrcPath, destPath);
+      if (skipExisting && fs.existsSync(destPath)) {
+        // leave existing file untouched
+      } else {
+        fs.copyFileSync(realSrcPath, destPath);
+      }
     }
   }
 }

package/templates/.buildwright

@@ -0,0 +1 @@
+../../.buildwright

package/templates/.env.example

@@ -0,0 +1 @@
+../../.env.example

package/templates/.github

@@ -0,0 +1 @@
+../../.github

package/templates/BUILDWRIGHT.md

@@ -1,99 +1 @@
-# Buildwright Development Workflow
-
-This project uses agent-first autonomous development. See [README.md](README.md) for full setup, concepts, and workflow details.
-
-## Quick Start
-
-```bash
-# After cloning, generate tool-specific configs from .buildwright/
-make sync
-
-# Install git hooks to auto-sync on .buildwright/ changes
-make install-hooks
-
-# Start your agent tool
-claude
-```
-
-## Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/bw-new-feature` | Full pipeline: research → spec → approve → build → ship |
-| `/bw-quick` | Fast path for bug fixes, small tasks |
-| `/bw-claw` | Cross-domain features: Architect decomposes → claws execute per domain → integrate → ship |
-| `/bw-ship` | Quality gates + release: verify → security → review → push → PR |
-| `/bw-verify` | Quick checks: typecheck, lint, test, build |
-| `/bw-analyse` | Analyse existing codebase → write structured docs to `.buildwright/codebase/` → update tech.md |
-| `/bw-help` | Show available commands |
-
-## Environment Variables
-
-| Variable | Default | Required | Purpose |
-|----------|---------|----------|---------|
-| `GITHUB_TOKEN` | — | Yes | Push branches and open PRs via `gh`. Needs `repo` scope. |
-| `BUILDWRIGHT_AUTO_APPROVE` | `true` | No | Autonomous mode — skip human approval, fail gracefully on errors |
-| `BUILDWRIGHT_AGENT_RETRIES` | `2` | No | Number of verify retries before giving up |
-
-## Failure Behavior
-
-| Mode | Any Failure | Behavior |
-|------|-------------|----------|
-| Autonomous (`BUILDWRIGHT_AUTO_APPROVE=true`, default) | Commit + push + failed PR + exit(1) | CI/CD fails, PR shows failure details |
-| Interactive (`BUILDWRIGHT_AUTO_APPROVE=false`) | STOP, show error | Human fixes in-session |
-
-**Autonomous failure path** (verify retries exhausted / critical security / review blocked):
-1. Commit all completed work to feature branch
-2. Push branch
-3. Create PR with failure summary (see template below)
-4. Exit with error code (pipeline fails in CI/CD)
-
-**Interactive failure path**: STOP and report blocker.
-
-### PR Failure Summary Template
-
-```markdown
-## BUILDWRIGHT: Pipeline Failed
-
-**Feature:** [name]
-**Mode:** Autonomous
-**Failed at:** [Verify / Security / Review]
-**Reason:** [Retries exhausted / Critical vulnerability / Changes requested]
-
-### Pipeline Status
-| Step | Status | Details |
-|------|--------|---------|
-| Verify | [pass/fail] | [details] |
-| Security | [pass/fail/skipped] | [details] |
-| Review | [pass/fail/skipped] | [details] |
-
-### Completed Work
-- [list of completed milestones/steps]
-
-### Failure Details
-- [error summary, specific findings, or review feedback]
-
-### Skipped
-- [steps that were blocked by the failure]
-
-### To Resume
-Fix the issue on this branch, then re-run the relevant command.
-```
-
-## Severity Triage
-
-| Severity | Action | Example |
-|----------|--------|---------|
-| **Critical / High** | Block — must fix before merge | SQL injection, exposed secrets, auth bypass |
-| **Medium** | Fix in this PR if feasible, otherwise track | Missing rate limiting, verbose error messages |
-| **Low / Info** | Advisory — log and move on | Minor header hardening, informational findings |
-
-Only Critical/High findings block the pipeline. Medium and Low findings are reported but don't prevent shipping.
-
-## Agent Personas
-
-| Agent | File | Purpose |
-|-------|------|---------|
-| Staff Engineer | `.buildwright/agents/staff-engineer.md` | Spec & code review, confidence scoring (≥80) |
-| Security Engineer | `.buildwright/agents/security-engineer.md` | Security review, exploit scenarios, hard exclusions |
-| Architect | `.buildwright/agents/architect.md` | Claw Architecture — decomposes cross-domain features |
+../../BUILDWRIGHT.md

package/templates/CLAUDE.md

@@ -1,150 +1 @@
-# Buildwright Development
-
-## Mission
-Agent-first autonomous development. Humans approve specs; agents implement, test, and ship.
-
-## Steering Documents
-
-At the start of every session, read **all** `.md` files in `.buildwright/steering/`.
-Also read all `.md` files in `.buildwright/codebase/` if that directory exists — these
-are codebase analysis docs (stack, architecture, conventions, concerns) generated by
-/bw-analyse. Do not assume a fixed set of files; discover what is there.
-
-## Agents & Claws
-- Agent personas in `.buildwright/agents/` — Architect, Staff Engineer, Security Engineer
-- Domain-specialist claws in `.buildwright/claws/` — Frontend, Backend, Database (+ TEMPLATE for custom)
-- Use `/bw-claw` for cross-domain features that need the Claw Architecture
-- For multi-claw work: use the best available model for Architect and Security review; lighter models suffice for Database and API claws.
-
-## Project Structure
-
-`.buildwright/` is the canonical configuration directory (committed to git). Tool-specific directories are generated from it and gitignored:
-
-```
-.buildwright/           ← Canonical source (committed)
-  agents/               ← Architect, Staff Engineer, Security Engineer
-  claws/                ← Frontend, Backend, Database, TEMPLATE
-  codebase/             ← Generated by /bw-analyse (stack, architecture, conventions, concerns)
-  commands/             ← bw-new-feature, bw-claw, bw-quick, bw-ship, bw-verify, bw-help
-  steering/             ← product.md, tech.md, quality-gates.md, naming-conventions.md
-  tasks/
-
-.claude/                ← Generated by `make sync` (gitignored, except settings.json)
-.opencode/              ← Generated by `make sync` (gitignored)
-.cursor/rules/          ← Generated by `make sync` (gitignored)
-AGENTS.md               ← Generated by `make sync` (gitignored)
-```
-
-After cloning or editing `.buildwright/`, run `make sync` to regenerate tool-specific configs.
-
-## Operating Mode
-
-### Default Behavior
-- AUTONOMOUS mode: Execute fully without asking for confirmation
-- Verify your own work through tests and checks
-- Commit when verification passes
-- Only stop if genuinely blocked (missing info, failing tests after retries)
-- **Autonomous failure handling**: When `BUILDWRIGHT_AUTO_APPROVE=true` (default) and any step fails after retries, commit completed work, push, create PR with failure details, and exit(1). In interactive mode (`BUILDWRIGHT_AUTO_APPROVE=false`), STOP and report blocker as before.
-
-### Workflow Priority
-1. **New features (single domain)**: /bw-new-feature → Research → Spec → Approval → Implement → Ship
-2. **Cross-domain features**: /bw-claw → Architect decomposes → Claws execute per domain → Integrate → Ship
-3. **Small tasks/bugs**: /bw-quick → Quick research → Implement → Verify → Commit
-4. **Refactors**: /bw-new-feature (if scope unclear) or /bw-quick (if scope clear)
-5. **Ship existing work**: /bw-ship → Verify → Security → Review → Push → PR
-6. **Quick quality check**: /bw-verify → typecheck, lint, test, build
-7. **Show commands**: /bw-help
-8. **Analyse existing codebase**: /bw-analyse → reads codebase → writes structured docs to .buildwright/codebase/ → updates tech.md. Run first on any brownfield project.
-
-## Command Discovery
-
-Run once per session. Cache the result — do not re-detect on every step.
-
-1. Read `.buildwright/steering/tech.md`. If "Project Commands" has real commands (not template placeholders) → use them. STOP.
-2. Auto-detect from project files in priority order: `package.json` → Node.js (check lock files: `pnpm-lock.yaml`→pnpm, `yarn.lock`→yarn, `bun.lockb`→bun, else→npm) | `Cargo.toml` → cargo | `go.mod` → go | `pyproject.toml` → check `poetry.lock`→poetry, `uv.lock`→uv, else→pip/hatch | `setup.py` → pip | `requirements.txt` → pip | `Makefile` → read targets.
-3. Derive four commands — typecheck, lint, test, build. If a stack has no equivalent for an operation, mark it SKIP (not a failure). Python has no build step; that's fine.
-4. Write discovered commands to tech.md so future runs use step 1.
-5. If still ambiguous: in a greenfield context go to the Greenfield Path (see bw-new-feature). Otherwise ask: "What commands run your tests, linter, and build?"
-
-## Credentials & Environment Variables
-
-| Variable | Default | Required | Purpose |
-|----------|---------|----------|---------|
-| `GITHUB_TOKEN` | — | Yes | Push branches and open PRs via `gh`. Needs `repo` scope. |
-| `BUILDWRIGHT_AUTO_APPROVE` | `true` | No | Autonomous mode — skip human approval, fail gracefully on errors |
-| `BUILDWRIGHT_AGENT_RETRIES` | `2` | No | Number of verify retries before giving up |
-
-`GITHUB_TOKEN` is the only credential. Use a fine-grained personal access token scoped to a single repository with "Contents: Read and write" and "Pull requests: Read and write" permissions. `BUILDWRIGHT_AUTO_APPROVE` is a configuration flag, not a secret.
-
-## Verification Loop (CRITICAL)
-
-Before EVERY commit, discover commands first (see Command Discovery above), then run:
-
-1. **Type check** — run DISCOVERED_TYPECHECK (SKIP gracefully if this stack has none)
-2. **Lint** — run DISCOVERED_LINT (SKIP gracefully if this stack has none)
-3. **Test** — run DISCOVERED_TEST
-4. **Build** — run DISCOVERED_BUILD (SKIP gracefully if this stack has no build step, e.g. Python)
-
-If ANY required step fails: fix and retry (max 2 attempts). If same error repeats or still failing: STOP and report blocker.
-
-## Git Rules
-- Atomic commits: only commit files you changed
-- Conventional commits: feat:, fix:, refactor:, test:, docs:, chore:
-- List each file explicitly in commit message
-- Never edit .env files
-- Never run destructive git operations without explicit instruction
-- Multi-agent safety: NEVER use git stash (other agents may be working)
-- Only `.buildwright/` is committed — never commit `.claude/` or `.opencode/` content files
-- After editing any file in `.buildwright/`, run `make sync` before committing
-- Before committing, update README.md, docs/, or CHANGELOG.md if the change affects user-facing behavior
-
-## Cross-Domain Features (Claw Architecture)
-When a feature touches multiple domains (e.g., DB + API + UI):
-1. `/bw-claw` triggers the Architect persona (`.buildwright/agents/architect.md`)
-2. Architect registers new fields in `.buildwright/steering/naming-conventions.md` BEFORE spawning claws
-3. Each claw (`.buildwright/claws/*.md`) executes its domain task using TDD
-4. Claws derive naming from the conventions registry — they never invent their own
-5. Architect integrates and runs quality gates
-
-## Design Principles (ALWAYS APPLY)
-
-1. **KISS (Keep It Simple, Stupid)**
-   - Prefer simple solutions over clever ones
-   - If it feels complex, step back and simplify
-   - Code should be readable by a junior developer
-
-2. **YAGNI (You Aren't Gonna Need It)**
-   - Build only what's required NOW
-   - No speculative features "for later"
-   - Avoid abstractions until they're proven needed
-
-3. **No Premature Optimization**
-   - Make it work first, then make it fast (if needed)
-   - Optimize only with profiling data
-   - Readability > micro-optimizations
-
-4. **Boring Technology**
-   - Prefer proven, well-documented solutions
-   - New tech only when it solves a real problem
-   - Consider maintenance burden
-
-5. **Fail Fast, Fail Loud**
-   - Validate inputs at boundaries
-   - Throw errors early with clear messages
-   - No silent failures
-
-## Code Standards
-- Follow existing patterns in the codebase exactly
-- Keep files under 500 lines; split proactively
-- Write tests for all new functionality (TDD preferred)
-- Avoid type system escape hatches (`any` in TypeScript, untyped `interface{}` in Go, `Any` in Python) — use proper types
-- Use Decimal/BigDecimal for financial calculations, NEVER floating point
-- All user inputs must be validated
-
-## Self-Improvement
-When you discover a pattern, gotcha, or better approach:
-- Add it below under "Learned Patterns"
-- Keep entries concise (one line each)
-
-## Learned Patterns
-<!-- Agent adds entries here as it learns -->
+../../CLAUDE.md

package/templates/Makefile

@@ -1,82 +1 @@
-.PHONY: dist clean sync sync-check cursor opencode openclaw validate install-hooks uninstall-hooks bump test-cli
-
-# ============================================================================
-# Sync — Generate .claude/, .opencode/, .cursor/rules/ from .buildwright/ (canonical)
-# Source of truth: .buildwright/ → .claude/ + .opencode/ + .cursor/rules/ + AGENTS.md + dist/
-# ============================================================================
-
-sync:
-	@chmod +x scripts/sync-agents.sh
-	@scripts/sync-agents.sh
-
-sync-check:
-	@chmod +x scripts/sync-agents.sh
-	@scripts/sync-agents.sh --check
-
-# ============================================================================
-# Package for distribution
-# ============================================================================
-
-# ClawHub — upload dist/buildwright/ folder to https://clawhub.ai/upload
-dist: sync
-	@echo "dist/buildwright/ ready — upload this folder to ClawHub"
-
-# Cursor — print setup instructions (rules generated by make sync)
-cursor: sync
-	@echo "Cursor rules generated at .cursor/rules/"
-	@echo "Open this project in Cursor — rules are applied automatically."
-	@echo "Settings > Rules shows steering rules as 'Always' and commands/agents/claws as 'Intelligent'."
-
-# OpenCode — install skill to user global config
-opencode: sync
-	@mkdir -p ~/.config/opencode/skills/buildwright
-	@cp SKILL.md ~/.config/opencode/skills/buildwright/SKILL.md
-	@echo "Installed to ~/.config/opencode/skills/buildwright/"
-
-# OpenClaw — install skill to user skills directory
-openclaw: sync
-	@mkdir -p ~/.openclaw/skills/buildwright
-	@cp SKILL.md ~/.openclaw/skills/buildwright/SKILL.md
-	@echo "Installed to ~/.openclaw/skills/buildwright/"
-
-# ============================================================================
-# Validate SKILL.md against Agent Skills spec (agentskills.io)
-# ============================================================================
-
-validate:
-	@chmod +x scripts/validate-skill.sh
-	@scripts/validate-skill.sh SKILL.md
-
-# ============================================================================
-# Git Hooks — keep .buildwright/ ↔ generated files in sync automatically
-# ============================================================================
-
-install-hooks:
-	@chmod +x scripts/install-hooks.sh
-	@scripts/install-hooks.sh
-
-uninstall-hooks:
-	@rm -f .git/hooks/pre-commit .git/hooks/post-merge .git/hooks/post-checkout
-	@echo "Buildwright hooks removed."
-
-# ============================================================================
-# Clean
-# ============================================================================
-
-bump: ## Bump version: make bump [BUMP=patch|minor|major]
-	@chmod +x scripts/bump-version.sh
-	@scripts/bump-version.sh $(or $(BUMP),patch)
-
-test-cli: ## Pack and install CLI globally for local testing
-	@echo "Packing cli/..."
-	@cd cli && npm pack
-	@TARBALL=$$(ls cli/buildwright-*.tgz | tail -1) && \
-	  npm install -g "./$$TARBALL" && \
-	  rm -f "$$TARBALL"
-	@echo ""
-	@echo "✓ buildwright installed globally from local pack"
-	@echo "  Test it: cd /tmp && mkdir test-bw && cd test-bw && buildwright init"
-	@echo "  Uninstall: npm uninstall -g buildwright"
-
-clean:
-	rm -rf dist/
+../../Makefile

package/templates/docs

@@ -0,0 +1 @@
+../../docs

package/templates/scripts

@@ -0,0 +1 @@
+../../scripts

package/templates/.buildwright/agents/README.md

@@ -1,53 +0,0 @@
-# Agent Personas
-
-This directory contains reusable agent personas that commands can reference.
-
-## Available Agents
-
-| Agent | File | Used By | Key Capabilities |
-|-------|------|---------|-------------------|
-| Architect | `architect.md` | `/bw-claw` | Decomposes cross-domain work, defines interfaces, coordinates claws |
-| Staff Engineer | `staff-engineer.md` | `/bw-new-feature`, `/bw-ship` | Confidence scoring (>=80), HIGH SIGNAL criteria, false-positive exclusions |
-| Security Engineer | `security-engineer.md` | `/bw-ship` | Confidence scoring (>=0.8), exploit scenarios, hard exclusions |
-
-## Claw Architecture
-
-For domain-specialist agents (claws), see `.buildwright/claws/`.
-
-The Architect agent coordinates claws:
-```
-        Architect (Brain)
-             |
-   +---------+---------+
-   |         |         |
- UI Claw  API Claw  DB Claw
-```
-
-## Adding New Agents
-
-1. Create a new file: `[role-name].md`
-2. Define:
-   - Mindset and expertise
-   - What they look for
-   - Output format
-   - Rules/guidelines
-3. Reference in commands via: `Read and adopt persona from .buildwright/agents/[role-name].md`
-
-## Planned Agents (Future)
-
-| Agent | Purpose |
-|-------|---------|
-| QA Engineer | Test coverage review, edge case identification |
-| Performance Engineer | Performance review, bottleneck identification |
-| DevOps Engineer | Infrastructure review, deployment concerns |
-| Database Engineer | Schema review, query optimization |
-| UX Engineer | API design review, developer experience |
-| Technical Writer | Documentation quality |
-
-## Agent Design Principles
-
-1. **Specific expertise** — Each agent has a focused domain
-2. **Consistent output** — Predictable format for parsing/automation
-3. **Actionable feedback** — Problems come with solutions
-4. **Severity levels** — Distinguish blocking from advisory
-5. **Context-aware** — Adapt to project type and risk level

package/templates/.buildwright/agents/architect.md

@@ -1,143 +0,0 @@
-# Architect Agent (Brain)
-
-You are a **System Architect** — the brain of the Claw Architecture. You analyze requirements, decompose work across domains, spawn specialized claws, and combine their results into a cohesive whole.
-
-You have 20+ years building complex distributed systems. You think in layers, interfaces, and contracts.
-
-## Your Role
-
-1. **Analyze** — Understand the feature request across all system layers
-2. **Decompose** — Break work into domain-specific tasks for claws
-3. **Coordinate** — Define interfaces and shared naming conventions
-4. **Integrate** — Combine claw outputs, run integration checks
-5. **Ship** — Run Buildwright quality gates on the combined result
-
-## How You Think
-
-```
-"What domains does this feature touch?"
-"What's the contract between each domain?"
-"Can these claws work in parallel or do they have dependencies?"
-"What shared vocabulary do the claws need?"
-```
-
-## Decomposition Process
-
-### Step 1: Identify Domains
-
-Read the project structure and determine which layers exist:
-
-| Domain | Typical Directories | Claw |
-|--------|-------------------|------|
-| Frontend/UI | `ui/`, `frontend/`, `src/components/`, `app/` | UI Claw |
-| Backend/API | `api/`, `backend/`, `server/`, `src/routes/` | API Claw |
-| Database | `database/`, `db/`, `migrations/`, `prisma/` | DB Claw |
-| Infrastructure | `infra/`, `terraform/`, `k8s/`, `helm/`, `Dockerfile` | DevOps Claw (`devops.md`) |
-
-### Step 2: Define Interfaces
-
-Before spawning claws, define the contracts between them:
-
-```markdown
-## Interface Contract: [Feature Name]
-
-### New Fields
-| Concept | Database | API (JSON) | UI (JS) |
-|---------|----------|------------|---------|
-| [field] | snake_case | camelCase | camelCase |
-
-### New Endpoints
-| Method | Path | Request | Response |
-|--------|------|---------|----------|
-| [verb] | [path] | [schema] | [schema] |
-
-### Dependencies Between Claws
-[claw A] must complete before [claw B] because [reason]
-```
-
-### Step 3: Create Claw Tasks
-
-For each domain that needs changes, create a clear task:
-
-```markdown
-## Claw Task: [Domain] — [Feature]
-
-### Context
-[What this claw needs to know about the overall feature]
-
-### Interface Contract
-[Relevant subset of the interface contract]
-
-### Specific Work
-1. [Concrete step 1]
-2. [Concrete step 2]
-
-### Verification
-- [How to verify this claw's work in isolation]
-- [Integration points to test]
-```
-
-### Step 4: Execution Strategy
-
-Determine the execution order:
-
-```
-PARALLEL (no dependencies):
-  UI Claw ─────┐
-  API Claw ────├─► Brain combines
-  DB Claw ─────┘
-
-SEQUENTIAL (has dependencies):
-  DB Claw → API Claw → UI Claw
-  (schema first, then endpoints, then UI)
-
-MIXED (partial dependencies):
-  DB Claw ──► API Claw ──┐
-  UI Claw ────────────────├─► Brain combines
-  (UI can work on component while DB+API are sequential)
-```
-
-## Integration Phase
-
-After all claws complete:
-
-1. **Verify interfaces** — Do the pieces actually fit together?
-2. **Run integration tests** — End-to-end flows work?
-3. **Check naming consistency** — Shared vocabulary respected?
-4. **Run /bw-verify** — Full quality gates pass?
-
-## Output Format
-
-```
-## ARCHITECTURE PLAN
-═══════════════════
-
-### Feature: [name]
-### Domains Affected: [list]
-
-### Interface Contract
-[table of shared fields, endpoints, events]
-
-### Claw Tasks
-1. [Domain] Claw: [summary] — [parallel/sequential]
-2. [Domain] Claw: [summary] — [parallel/sequential]
-3. [Domain] Claw: [summary] — [parallel/sequential]
-
-### Execution Order
-[diagram showing parallel vs sequential]
-
-### Integration Checklist
-- [ ] [check 1]
-- [ ] [check 2]
-```
-
-## When NOT to Decompose
-
-Use single-agent mode (standard /bw-new-feature or /bw-quick) when:
-- Feature touches only one domain
-- Changes are small/bounded (< 2 hours)
-- No cross-layer interfaces needed
-- Project is a monolith with no clear domain separation
-
-The overhead of multi-agent coordination isn't worth it for simple tasks.
-