buildwright 0.0.11 → 0.0.13

package/templates/CLAUDE.md

@@ -1,160 +1,123 @@
 # Buildwright Development
 
 ## Mission
-Agent-first autonomous development. Humans approve specs; agents implement, test, and ship.
+
+Agent-first disciplined development. Humans approve intent when needed; agents
+understand, test, implement, document, verify, review, 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.
+At the start of every session, recursively discover and read all `.md` files
+under `.buildwright/steering/`. Use:
+
+```bash
+find .buildwright/steering -type f -name "*.md" | sort
+```
+
+The default steering file is `philosophy.md`.
 
-## 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.
+Also recursively read all `.md` files under `.buildwright/codebase/` if that
+directory exists. These are codebase analysis docs generated by `/bw-analyse`.
+
+Do not assume a fixed set of project steering files. `tech.md` and `product.md`
+are created only when Buildwright has real project-specific content.
 
 ## Project Structure
 
-`.buildwright/` is the canonical configuration directory (committed to git). Tool-specific directories are generated from it and gitignored:
+`.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-plan, 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)
+.buildwright/
+  agents/               # Staff Engineer, Security Engineer
+  codebase/             # Generated by /bw-analyse
+  commands/             # bw-work, bw-plan, bw-verify, bw-ship, bw-analyse
+  steering/             # philosophy.md plus lazy-created tech.md/product.md
+
+.claude/                # Generated by make sync
+.opencode/              # Generated by make sync
+.cursor/rules/          # Generated by make sync
+AGENTS.md               # Generated by make sync
 ```
 
-After cloning or editing `.buildwright/`, run `make sync` to regenerate tool-specific configs.
+After cloning or editing `.buildwright/`, run `make sync`.
 
-## Operating Mode
+## Commands
 
-### 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.
-9. **Research/planning without implementation**: /bw-plan → Understand question → Research (read-only) → Synthesize → Write deliverable. No code changes, no commits.
+Use the smallest command that matches the intent:
+
+1. `/bw-plan` — think/research only; no code changes, commits, or PRs.
+2. `/bw-work` — implement bug fixes, refactors, and features.
+3. `/bw-verify` — run typecheck, lint, test, and build gates.
+4. `/bw-ship` — verify, security review, code review, push, and PR.
+5. `/bw-analyse` — analyse brownfield codebases and write `.buildwright/codebase/` docs.
 
 ## Command Discovery
 
-Run once per session. Cache the result — do not re-detect on every step.
+Run once per session and cache the result.
+
+1. Read `.buildwright/steering/tech.md` if it exists. If it has real commands,
+   use them.
+2. Otherwise auto-detect from project files in priority order:
+   `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `setup.py`,
+   `requirements.txt`, `Makefile`.
+3. Derive typecheck, lint, test, build, and dev commands. Mark unavailable
+   gates as `SKIP`.
+4. Write discovered commands to `.buildwright/steering/tech.md`.
+5. If still ambiguous, ask for the missing commands.
 
-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?"
+## Operating Mode
+
+- Execute autonomously unless information is genuinely missing.
+- Verify your own work through tests and checks.
+- Commit only after verification passes.
+- Stop only when genuinely blocked.
 
-## Credentials & Environment Variables
+`BUILDWRIGHT_AUTO_APPROVE=true` means autonomous mode. If a step fails after
+retries, commit completed work, push, create a PR with failure details, and
+exit non-zero. In interactive mode (`BUILDWRIGHT_AUTO_APPROVE=false`), stop and
+report the blocker.
 
-| 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 |
+## Verification Loop
 
-`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.
+Before every commit, run discovered gates:
 
-## Verification Loop (CRITICAL)
+1. Typecheck
+2. Lint
+3. Test
+4. Build
 
-Before EVERY commit, discover commands first (see Command Discovery above), then run:
+Skip only gates that are unavailable for the stack. If a required step fails,
+fix and retry up to `BUILDWRIGHT_AGENT_RETRIES` times, default 2.
 
-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)
+## Documentation Discipline
 
-If ANY required step fails: fix and retry (max 2 attempts). If same error repeats or still failing: STOP and report blocker.
+Documentation is part of done.
+
+Before every commit, update affected README, docs, command text, API docs,
+examples, changelog, or generated user-facing docs. If no docs need updating,
+say why in the final report.
 
 ## 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, SKILL.md, docs/, or CHANGELOG.md if the change affects user-facing behavior
-- After editing any `.buildwright/commands/` file, run `make sync` — it automatically checks that every command is documented in README.md and SKILL.md and warns about gaps
-
-## 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
-   - No wrapper types, adapter layers, or extension points "just in case"
-   - If the requirements don't ask for it, don't build it
-
-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
-
-6. **DRY (Don't Repeat Yourself)**
-   - Before writing new code, search for existing functions, types, and utilities that already do the job
-   - Reuse existing structures — if `User` exists, don't create `UserDTO` or `UserEntity` unless the codebase already separates those concerns
-   - If two pieces of code do similar things, extract the common part rather than duplicating
-   - Prefer importing over reimplementing
-
-## 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
+
+- Atomic commits: only commit files you changed.
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`.
+- Never edit `.env` files.
+- Never run destructive git operations without explicit instruction.
+- Never use `git stash`.
+- Only `.buildwright/` is canonical. Do not commit generated `.claude/`,
+  `.opencode/`, `.cursor/rules/`, `skills/`, or `AGENTS.md`.
+- After editing `.buildwright/`, run `make sync`.
+
+## Philosophy
+
+Always apply `.buildwright/steering/philosophy.md`: KISS, YAGNI, DRY, boring
+technology, fail fast, Red -> Green -> Refactor, and documentation discipline.
 
 ## Self-Improvement
-When you discover a pattern, gotcha, or better approach:
-- Add it below under "Learned Patterns"
-- Keep entries concise (one line each)
+
+When you discover a reusable pattern or gotcha, add it below.
 
 ## Learned Patterns
+
 <!-- Agent adds entries here as it learns -->

package/templates/Makefile

@@ -25,7 +25,7 @@ dist: 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'."
+	@echo "Settings > Rules shows steering rules as 'Always' and commands/agents as 'Intelligent'."
 
 # OpenCode — install skill to user global config
 opencode: sync

package/templates/scripts/release.sh

@@ -19,11 +19,11 @@ NEW_VERSION=$(node -p "require('./cli/package.json').version")
 git add cli/package.json cli/package-lock.json SKILL.md
 git commit -m "chore: bump version to v$NEW_VERSION"
 
-# Step 3: annotated tag
-git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
-
-# Step 4: push commit + tag
+# Step 3: push commit first
 git push
+
+# Step 4: annotated tag (after commit is on remote)
+git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
 git push origin "v$NEW_VERSION"
 
 # Step 5: GitHub release with auto-generated notes

package/templates/scripts/sync-agents.sh

@@ -5,17 +5,13 @@
 # Generates:
 #   .claude/commands/        ← from .buildwright/commands/ (paths rewritten to .claude/)
 #   .claude/agents/          ← from .buildwright/agents/
-#   .claude/claws/           ← from .buildwright/claws/
 #   .claude/steering/        ← from .buildwright/steering/
-#   .claude/tasks/           ← from .buildwright/tasks/
 #   .opencode/commands/      ← from .buildwright/commands/ (paths rewritten to .opencode/)
 #   .opencode/agents/        ← from .buildwright/agents/
-#   .opencode/claws/         ← from .buildwright/claws/
 #   .opencode/steering/      ← from .buildwright/steering/
 #   .cursor/rules/steering/  ← .mdc files with alwaysApply: true
 #   .cursor/rules/commands/  ← .mdc files with alwaysApply: false
 #   .cursor/rules/agents/    ← .mdc files with alwaysApply: false
-#   .cursor/rules/claws/     ← .mdc files with alwaysApply: false
 #   AGENTS.md                ← CLAUDE.md with OpenCode header prepended
 #   dist/buildwright/        ← SKILL.md packaged for ClawHub
 #
@@ -95,35 +91,29 @@ CURSOR_DESCRIPTION=""
 set_cursor_frontmatter() {
   local preset="$1"
   local filename="$2"
+  local base_filename
+  base_filename=$(basename "$filename")
 
   case "$preset" in
     steering|codebase) CURSOR_ALWAYS_APPLY="true" ;;
     *)                 CURSOR_ALWAYS_APPLY="false" ;;
   esac
 
-  case "${preset}:${filename}" in
+  case "${preset}:${base_filename}" in
     steering:product)            CURSOR_DESCRIPTION="Buildwright product context: goals, features, user personas, business constraints" ;;
     steering:tech)               CURSOR_DESCRIPTION="Buildwright technical context: stack, commands, architecture patterns" ;;
-    steering:quality-gates)      CURSOR_DESCRIPTION="Buildwright quality gates: automated checks that must pass before merge" ;;
-    steering:naming-conventions) CURSOR_DESCRIPTION="Buildwright naming conventions: canonical field and endpoint registry" ;;
+    steering:philosophy)         CURSOR_DESCRIPTION="Buildwright engineering philosophy: KISS, YAGNI, TDD, docs discipline" ;;
     codebase:STACK)              CURSOR_DESCRIPTION="Codebase tech stack: languages, runtime, frameworks, dependencies, integrations" ;;
     codebase:ARCHITECTURE)       CURSOR_DESCRIPTION="Codebase architecture: layers, data flow, entry points, directory structure" ;;
     codebase:CONVENTIONS)        CURSOR_DESCRIPTION="Codebase conventions: naming, code style, imports, error handling, testing patterns" ;;
     codebase:CONCERNS)           CURSOR_DESCRIPTION="Codebase concerns: tech debt, bugs, security risks, performance bottlenecks" ;;
-    command:bw-new-feature)      CURSOR_DESCRIPTION="Buildwright bw-new-feature: full pipeline for new features with spec and TDD" ;;
-    command:bw-claw)             CURSOR_DESCRIPTION="Buildwright bw-claw: multi-agent cross-domain feature development" ;;
-    command:bw-quick)            CURSOR_DESCRIPTION="Buildwright bw-quick: fast path for bug fixes and small tasks" ;;
+    command:bw-work)             CURSOR_DESCRIPTION="Buildwright bw-work: implement bug fixes, refactors, and features" ;;
     command:bw-ship)             CURSOR_DESCRIPTION="Buildwright bw-ship: quality pipeline then commit, push, and PR" ;;
     command:bw-verify)           CURSOR_DESCRIPTION="Buildwright bw-verify: quick quality checks (typecheck, lint, test, build)" ;;
-    command:bw-help)             CURSOR_DESCRIPTION="Buildwright bw-help: list all available Buildwright commands" ;;
     command:bw-analyse)          CURSOR_DESCRIPTION="Buildwright bw-analyse: analyse codebase, write structured docs to .buildwright/codebase/, update tech.md" ;;
-    agent:architect)             CURSOR_DESCRIPTION="Buildwright Architect agent persona" ;;
+    command:bw-plan)             CURSOR_DESCRIPTION="Buildwright bw-plan: research a question, produce a written deliverable — no implementation" ;;
     agent:staff-engineer)        CURSOR_DESCRIPTION="Buildwright Staff Engineer agent persona" ;;
     agent:security-engineer)     CURSOR_DESCRIPTION="Buildwright Security Engineer agent persona" ;;
-    claw:frontend)               CURSOR_DESCRIPTION="Buildwright Frontend domain specialist claw" ;;
-    claw:backend)                CURSOR_DESCRIPTION="Buildwright Backend domain specialist claw" ;;
-    claw:database)               CURSOR_DESCRIPTION="Buildwright Database domain specialist claw" ;;
-    claw:devops)                 CURSOR_DESCRIPTION="Buildwright DevOps domain specialist claw" ;;
     *)                           CURSOR_DESCRIPTION="Buildwright ${preset}: ${filename}" ;;
   esac
 }
@@ -143,20 +133,25 @@ sync_cursor_dir() {
   fi
 
   if [ "$CHECK_ONLY" = false ]; then
+    rm -rf "$dst"
     mkdir -p "$dst"
   fi
 
-  for src_file in "$src"/*.md; do
+  while IFS= read -r src_file; do
     [ -f "$src_file" ] || continue
-    local filename
-    filename=$(basename "$src_file" .md)
+    local rel_file filename base_filename
+    rel_file="${src_file#$src/}"
+    filename="${rel_file%.md}"
+    base_filename=$(basename "$filename")
 
     # Skip meta files — they're internal docs, not rules
-    case "$filename" in
+    case "$base_filename" in
       README|TEMPLATE) continue ;;
     esac
 
     local dst_file="$dst/$filename.mdc"
+    local dst_parent
+    dst_parent=$(dirname "$dst_file")
     set_cursor_frontmatter "$preset" "$filename"
 
     if [ "$CHECK_ONLY" = true ]; then
@@ -181,6 +176,7 @@ sync_cursor_dir() {
         rm -f "$tmpfile"
       fi
     else
+      mkdir -p "$dst_parent"
       {
         printf '%s\n' "---"
         printf 'description: "%s"\n' "$CURSOR_DESCRIPTION"
@@ -190,7 +186,7 @@ sync_cursor_dir() {
         sed 's|@\.buildwright/|@.cursor/rules/|g' "$src_file"
       } > "$dst_file"
     fi
-  done
+  done < <(find "$src" -type f -name "*.md" | sort)
 
   if [ "$CHECK_ONLY" = false ]; then
     echo "  synced $src → $dst (*.mdc)"
@@ -210,10 +206,8 @@ SYNC_NEEDED=false
 
 sync_dir ".buildwright/commands"  ".claude/commands"  ".buildwright/" ".claude/"
 sync_dir ".buildwright/agents"    ".claude/agents"    ".buildwright/" ".claude/"
-sync_dir ".buildwright/claws"     ".claude/claws"     ".buildwright/" ".claude/"
 sync_dir ".buildwright/steering"  ".claude/steering"
 sync_dir ".buildwright/codebase"  ".claude/codebase"
-sync_dir ".buildwright/tasks"     ".claude/tasks"
 
 # ============================================================================
 # 2. .buildwright/ → .opencode/ (rewrite .buildwright/ → .opencode/)
@@ -221,7 +215,6 @@ sync_dir ".buildwright/tasks"     ".claude/tasks"
 
 sync_dir ".buildwright/commands"  ".opencode/commands"  ".buildwright/" ".opencode/"
 sync_dir ".buildwright/agents"    ".opencode/agents"    ".buildwright/" ".opencode/"
-sync_dir ".buildwright/claws"     ".opencode/claws"     ".buildwright/" ".opencode/"
 sync_dir ".buildwright/steering"  ".opencode/steering"
 sync_dir ".buildwright/codebase"  ".opencode/codebase"
 
@@ -266,13 +259,13 @@ sync_cursor_dir ".buildwright/steering"  "steering"  "steering"
 sync_cursor_dir ".buildwright/codebase"  "codebase"  "codebase"
 sync_cursor_dir ".buildwright/commands"  "commands"  "command"
 sync_cursor_dir ".buildwright/agents"    "agents"    "agent"
-sync_cursor_dir ".buildwright/claws"     "claws"     "claw"
 
 # ============================================================================
 # 5. .buildwright/commands/ → skills/ (Codex CLI skill discovery)
 # ============================================================================
 
 if [ "$CHECK_ONLY" = false ]; then
+  rm -rf skills
   for file in .buildwright/commands/bw-*.md; do
     [ -f "$file" ] || continue
     name=$(basename "$file" .md)
@@ -294,9 +287,11 @@ fi
 
 # ============================================================================
 # 7. README.md → cli/README.md (single source of truth for npm package page)
+# Only runs in the buildwright repo itself, which has a cli/ directory.
+# Generated services do not have cli/ and must not fail here.
 # ============================================================================
 
-if [ "$CHECK_ONLY" = false ] && [ -f "README.md" ]; then
+if [ "$CHECK_ONLY" = false ] && [ -f "README.md" ] && [ -d "cli" ]; then
   cp README.md cli/README.md
   echo "  README.md → cli/README.md"
 fi
@@ -323,7 +318,9 @@ else
   echo "  CLAUDE.md     → AGENTS.md"
   echo "  SKILL.md      → dist/buildwright/SKILL.md"
   echo "  .buildwright/commands/ → skills/          (Codex CLI skill discovery)"
-  echo "  README.md     → cli/README.md             (npm package page)"
+  if [ -d "cli" ]; then
+    echo "  README.md     → cli/README.md             (npm package page)"
+  fi
 
   # Validate all commands are documented in SKILL.md and README.md
   if [ -f "scripts/validate-docs.sh" ]; then

package/templates/scripts/validate-docs.sh

@@ -25,11 +25,8 @@ missing=0
 for file in "$COMMANDS_DIR"/bw-*.md; do
   [ -f "$file" ] || continue
 
-  # Skip bw-help.md — it IS the help output, doesn't need its own docs section
-  basename=$(basename "$file")
-  [ "$basename" = "bw-help.md" ] && continue
-
   # Extract name from YAML frontmatter
+  basename=$(basename "$file")
   name=$(awk '/^---/{f=!f;next} f && /^name:/{print $2;exit}' "$file" 2>/dev/null | tr -d '\r')
 
   if [ -z "$name" ]; then

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.
-