buildwright 0.0.12 → 0.0.13

package/src/commands/update.js

@@ -16,7 +16,7 @@ const BOLD = '\x1b[1m';
 const RESET = '\x1b[0m';
 
 const GITHUB_REPO = 'raunakkathuria/buildwright';
-const UPDATE_DIRS = ['commands', 'agents', 'claws'];
+const UPDATE_DIRS = ['commands', 'agents', 'steering'];
 
 /**
  * Download a URL following redirects. Returns a Buffer.
@@ -62,26 +62,6 @@ 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();
 
@@ -93,7 +73,7 @@ async function update() {
 
   console.log(`${BOLD}Updating Buildwright in ${cwd}...${RESET}\n`);
   console.log(`Updating: ${UPDATE_DIRS.map(d => `.buildwright/${d}/`).join(', ')}`);
-  console.log(`Preserving: .buildwright/steering/ (your customizations)\n`);
+  console.log(`Preserving: project-created steering files such as tech.md and product.md\n`);
 
   let tmpDir;
   try {
@@ -106,8 +86,8 @@ async function update() {
       throw new Error('Downloaded archive is missing .buildwright/ directory');
     }
 
-    // Update only the specified directories — overwrite upstream files only,
-    // never delete files the user added that don't exist in the upstream source.
+    // This version is not backward compatible with the older command model.
+    // Update only adds current files; users should re-run init for a clean tree.
     for (const dir of UPDATE_DIRS) {
       const src = path.join(srcBuildwright, dir);
       const dest = path.join(cwd, '.buildwright', dir);
@@ -115,10 +95,9 @@ async function update() {
         console.log(`  ${YELLOW}Skipping ${dir}/ (not found in latest release)${RESET}`);
         continue;
       }
-      console.log(`  Updating .buildwright/${dir}/ (adding new files only)`);
+      console.log(`  Updating .buildwright/${dir}/`);
       fs.mkdirSync(dest, { recursive: true });
-      // Copy only files that exist in upstream — preserves user-added files
-      copyUpstreamOnly(src, dest);
+      copyDir(src, dest, { skipExisting: dir === 'steering' });
     }
 
     // Also add CLAUDE.md if it doesn't already exist locally
@@ -140,8 +119,8 @@ async function update() {
 
     console.log('');
     console.log(`${GREEN}${BOLD}Update complete!${RESET}`);
-    console.log('commands, agents, and claws: new files added. Existing files unchanged.');
-    console.log('Your custom files and steering docs are unchanged.\n');
+    console.log('commands, agents, and default steering: new files added. Existing files unchanged.');
+    console.log('Your custom files are unchanged.\n');
 
   } catch (err) {
     console.error(`\nUpdate failed: ${err.message}`);

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

@@ -1,53 +1,9 @@
 # Agent Personas
 
-This directory contains reusable agent personas that commands can reference.
+This directory contains reusable review personas. They are prompt instructions,
+not separate runtimes.
 
-## 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
+| Agent | File | Used By | Purpose |
+|-------|------|---------|---------|
+| Staff Engineer | `staff-engineer.md` | `/bw-work`, `/bw-ship` | Spec and code review with confidence scoring and high-signal findings |
+| Security Engineer | `security-engineer.md` | `/bw-work`, `/bw-ship` | OWASP Top 10, secrets, auth, injection, dependency review |

package/templates/.buildwright/commands/bw-analyse.md

@@ -1,6 +1,6 @@
 ---
 name: bw-analyse
-description: Analyse the codebase and write structured docs to .buildwright/codebase/. Updates tech.md with discovered stack and architecture.
+description: Analyse the codebase and write structured docs to .buildwright/codebase/. Creates or updates tech.md with discovered stack and commands.
 allowed-tools:
   - Read
   - Bash
@@ -12,16 +12,16 @@ allowed-tools:
 
 <objective>
 Analyse the existing codebase and produce structured reference documents in
-`.buildwright/codebase/`. Then update `.buildwright/steering/tech.md` with a summary
-so every session starts with real project context instead of template placeholders.
+`.buildwright/codebase/`. Then create or update `.buildwright/steering/tech.md`
+with real project context so future sessions do not rely on detection.
 </objective>
 
 <when_to_use>
 Run /bw-analyse when:
 - Starting on an unfamiliar or brownfield codebase
 - .buildwright/codebase/ is missing or stale
-- tech.md still contains template placeholders
-- Before /bw-new-feature or /bw-claw on an existing project
+- `.buildwright/steering/tech.md` is missing or stale
+- Before `/bw-work` on an unfamiliar existing project
 
 Skip when:
 - Greenfield project with no code yet
@@ -54,13 +54,12 @@ Skip when:
    - Find large files (potential complexity)
    - Note missing tests, security gaps, fragile areas
    - Write `.buildwright/codebase/CONCERNS.md`
-7. Update `.buildwright/steering/tech.md`:
-   - If the file does not exist, create it using the standard template (## Stack, ## Project Commands, ## Architecture, ## Code Patterns, ## Dependencies sections with placeholder values), then proceed.
-   - Replace placeholder in ## Stack with discovered languages, runtime, frameworks.
-   - Replace placeholder in ## Architecture with 3-5 line summary.
-   - Replace placeholder in ## Code Patterns with top 3 patterns from CONVENTIONS.md.
-   - Replace placeholder in ## Dependencies with key packages and their purpose.
-   - Leave ## Project Commands unchanged if already populated; populate if still a placeholder.
+7. Create or update `.buildwright/steering/tech.md` with real content:
+   - Stack: discovered languages, runtime, frameworks.
+   - Project Commands: typecheck, lint, test, build, and dev commands where available.
+   - System layout: 3-5 line summary.
+   - Code Patterns: top 3 patterns from CONVENTIONS.md.
+   - Dependencies: key packages and their purpose.
 8. Run `scripts/sync-agents.sh` to propagate codebase docs to all tool directories
 9. Commit: `chore: add codebase analysis to .buildwright/codebase/`
 10. Report: list 4 docs with line counts, summarise key findings, suggest next step
@@ -80,7 +79,7 @@ Note their existence only. Never quote their contents.
 
 <success_criteria>
 - [ ] .buildwright/codebase/ contains STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md
-- [ ] tech.md placeholder sections replaced with real content
+- [ ] tech.md exists with real stack and command content
 - [ ] No secrets or credentials in any written file
 - [ ] Changes committed
 </success_criteria>

package/templates/.buildwright/commands/bw-plan.md

@@ -22,8 +22,7 @@ Examples:
 - "Produce a static analysis report for this codebase"
 
 **Contrast with other commands:**
-- `/bw-new-feature` — research + spec + implement + ship
-- `/bw-quick` — implement immediately (no planning doc)
+- `/bw-work` — research + implement + verify + review
 - `/bw-analyse` — analyse this project's own codebase for Buildwright context
 - `/bw-plan` — research a question, write a deliverable, stop there
 
@@ -43,7 +42,7 @@ Examples:
 **Structured task file:**
 ```
 /bw-plan tasks/flutter-perf-review.md
-/bw-plan .buildwright/tasks/architecture-review.md
+/bw-plan docs/plans/architecture-review.md
 ```
 
 ---
@@ -79,7 +78,11 @@ sensible defaults and proceed. Note any assumptions in the deliverable.
 
 ## Phase 3 — Research
 
-**First, check for pre-analysed codebase docs:**
+Recursively discover and read all `.md` files under `.buildwright/steering/`.
+Read `philosophy.md` first when present because it defines the engineering
+principles that should shape recommendations.
+
+**Then, check for pre-analysed codebase docs:**
 
 If `.buildwright/codebase/` exists (generated by `/bw-analyse`), read it before scanning files:
 - `STACK.md` — confirmed tech stack for context

package/templates/.buildwright/commands/bw-ship.md

@@ -41,8 +41,10 @@ This command runs the full quality pipeline before shipping.
 
 ## Step 1: Verify (Quick Checks) — Retry up to 2x
 
-Before verifying, confirm that README.md, docs/, and CHANGELOG.md reflect the
-changes being shipped. Update any that are out of date.
+Before verifying, confirm documentation reflects the changes being shipped.
+Update affected README, docs, command text, API docs, examples, or CHANGELOG.
+If no docs need updating, record why in the final report. Documentation is part
+of done.
 
 Run quick verification checks:
 
@@ -227,6 +229,7 @@ If `gh` is not available, provide the PR creation URL.
 ║  ✅ Verify:    PASSED                                         ║
 ║  ✅ Security:  PASSED                                         ║
 ║  ✅ Review:    APPROVED                                       ║
+║  ✅ Docs:      UPDATED / NOT APPLICABLE                       ║
 ║  ✅ Release:   SHIPPED                                        ║
 ║                                                               ║
 ╠═══════════════════════════════════════════════════════════════╣

package/templates/.buildwright/commands/bw-verify.md

@@ -9,10 +9,10 @@ Running quick verification...
 
 Follow the Tech Discovery Protocol (see Command Discovery in CLAUDE.md):
 
-1. Read `.buildwright/steering/tech.md` — if "Project Commands" has real commands, use them.
+1. Read `.buildwright/steering/tech.md` if it exists — if "Project Commands" has real commands, use them.
 2. Otherwise auto-detect from project files: `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`, etc.
 3. Derive typecheck, lint, test, build commands. Mark as SKIP if a stack has no equivalent.
-4. Write discovered commands to `tech.md` for future runs.
+4. Write discovered commands to `.buildwright/steering/tech.md` for future runs.
 
 ---
 

package/templates/.buildwright/commands/bw-work.md

@@ -0,0 +1,149 @@
+---
+name: bw-work
+description: Implement bug fixes, refactors, and features with research, Red-Green-Refactor, docs, verification, security review, and code review
+arguments:
+  - name: task
+    description: What to build, fix, or refactor
+    required: true
+---
+
+# /bw-work
+
+Use this for implementation work: bug fixes, refactors, small changes, and new
+features. The command chooses the lightest workflow that still protects quality.
+
+## Core Loop
+
+```
+Understand -> Research -> Plan if needed -> Red -> Green -> Refactor -> Docs -> Verify -> Security -> Review -> Commit/Ship
+```
+
+Always recursively discover and read all `.md` files under
+`.buildwright/steering/`. Read `philosophy.md` first when present because it is
+the default baseline. Also recursively read `.buildwright/codebase/*.md` if
+that directory exists.
+
+## Phase 1: Understand
+
+Parse `$ARGUMENTS.task` and identify:
+- Work type: bug fix, feature, refactor, config/docs change
+- Project state: greenfield or brownfield
+- Scope: small/bounded or larger/unclear
+- User-facing impact and documentation likely affected
+
+If no project files exist, ask for product vision and constraints. Create
+`.buildwright/steering/product.md` from the answer and create `tech.md` after
+the stack and commands are chosen.
+
+## Phase 2: Command Discovery
+
+If `.buildwright/steering/tech.md` exists and has real commands, use them.
+Otherwise auto-detect from project files:
+
+- `package.json` -> npm/pnpm/yarn/bun scripts
+- `Cargo.toml` -> cargo
+- `go.mod` -> go
+- `pyproject.toml`, `setup.py`, `requirements.txt` -> Python tooling
+- `Makefile` -> make targets
+
+Derive typecheck, lint, test, build, and dev commands. Mark unavailable gates as
+`SKIP`. Write a real `.buildwright/steering/tech.md` so future runs reuse the
+discovery result. If detection is ambiguous, ask for the missing commands.
+
+## Phase 3: Research
+
+For small, clear tasks, do lightweight research in context:
+- Read only directly relevant source files and tests
+- Reuse existing functions, types, and patterns
+- Check `.buildwright/codebase/CONVENTIONS.md` if present
+
+For larger or unclear work, write:
+- `docs/specs/[feature]/research.md`
+- `docs/specs/[feature]/spec.md`
+
+The spec must include scope, approach, risks, test strategy, documentation
+impact, and implementation milestones. In interactive mode
+(`BUILDWRIGHT_AUTO_APPROVE=false`), stop for approval before implementation.
+
+Cross-domain work still uses a normal spec and implementation plan. Do not use
+legacy multi-agent terminology or domain-specialist personas.
+
+## Phase 4: Implement with TDD
+
+For every bug fix, behavior change, or feature milestone:
+
+### Red
+
+Write or update a failing test that describes the bug or expected behavior. Run
+the focused test and confirm it fails for the right reason.
+
+### Green
+
+Make the smallest implementation that passes the test. Follow existing
+patterns, reuse existing utilities, and avoid speculative abstractions.
+
+### Refactor
+
+Improve names, structure, duplication, and design while tests stay green. Keep
+the scope tied to the current requirement.
+
+## Phase 5: Documentation Check
+
+Documentation is part of done. Before verification, update every affected
+user-facing artifact:
+- README or setup docs
+- docs/ guides or API reference
+- command/help text
+- examples
+- CHANGELOG, if the project uses one
+
+If no documentation update is needed, record the reason in the final report.
+
+## Phase 6: Verify
+
+Run the discovered gates:
+1. Typecheck
+2. Lint
+3. Test
+4. Build
+
+Skip only gates that are genuinely unavailable for the stack. If a required
+gate fails, fix and retry up to `BUILDWRIGHT_AGENT_RETRIES` times, default 2.
+
+## Phase 7: Security Review
+
+Adopt `.buildwright/agents/security-engineer.md`. Review the changed diff for:
+- Secrets
+- Dependency vulnerabilities, if tooling exists
+- Input validation and authorization
+- OWASP Top 10 risks
+- Financial-code risks, especially floating point for currency
+
+Stop on critical vulnerabilities.
+
+## Phase 8: Code Review
+
+Adopt `.buildwright/agents/staff-engineer.md`. Review the changed diff for:
+- Logic errors and missed edge cases
+- Error handling
+- Pattern fit and unnecessary complexity
+- Missing tests
+- Missing documentation updates
+
+Fix blocking issues before committing.
+
+## Phase 9: Commit or Ship
+
+Use atomic conventional commits and stage only files changed for this work.
+
+For small local work, commit and report the result. For PR-ready work, run
+`/bw-ship` after verification, security, and review have passed.
+
+## Final Report
+
+Report:
+- Task and work type
+- Files changed
+- Tests and gates run
+- Documentation updated, or why not applicable
+- Commit hash or PR URL if created

package/templates/.buildwright/steering/philosophy.md

@@ -0,0 +1,45 @@
+# Philosophy
+
+Buildwright is a lightweight engineering discipline layer. It is not a
+multi-agent framework.
+
+## Principles
+
+- **KISS:** Prefer the simplest readable solution that solves the current need.
+- **YAGNI:** Do not add speculative features, extension points, or abstractions.
+- **DRY:** Search for existing functions, types, utilities, and docs before
+  creating new ones.
+- **Boring technology:** Prefer proven tools and project-local patterns.
+- **Fail fast:** Validate inputs at boundaries and surface clear errors.
+- **No premature optimization:** Make it correct first; optimize with evidence.
+
+## TDD
+
+Use Red -> Green -> Refactor for behavior changes.
+
+- **Red:** Write a failing test that reproduces the bug or describes expected
+  behavior.
+- **Green:** Write the smallest implementation that passes.
+- **Refactor:** Improve names, structure, duplication, and design while tests
+  stay green.
+
+## Documentation Is Part of Done
+
+Every feature, bug fix, behavior change, command change, config change, or
+public workflow change must check documentation before verification.
+
+Update affected docs in the same work item: README, docs, command text,
+examples, API docs, changelog, or generated user-facing docs. If no docs need
+updating, state why in the final report.
+
+## Financial Code
+
+Use Decimal, BigDecimal, integer minor units, or the project-approved money
+type for currency and trading calculations. Never use floating point for money.
+
+## Code Standards
+
+- Follow existing patterns exactly.
+- Keep files focused and readable.
+- Validate user input.
+- Avoid type-system escape hatches unless the project already requires them.

package/templates/BUILDWRIGHT.md

@@ -19,13 +19,11 @@ claude
 
 | 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-plan` | Think/research only; no code changes |
+| `/bw-work` | Implement bug fixes, refactors, and features |
 | `/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
 
@@ -96,4 +94,3 @@ Only Critical/High findings block the pipeline. Medium and Low findings are repo
 |-------|------|---------|
 | 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 |