buildwright 0.0.5 → 0.0.6

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

@@ -0,0 +1,245 @@
+---
+name: bw-quick
+description: Fast path for ad-hoc tasks (bug fixes, small features, config changes) without full planning
+arguments:
+  - name: task
+    description: What to do (inline description)
+    required: true
+---
+
+## Quick Mode
+
+Fast path for ad-hoc tasks that don't need full planning.
+
+**Use for:**
+- Bug fixes
+- Small features (< 2 hours)
+- Config changes
+- One-off tasks
+- Refactors with clear scope
+
+**Don't use for:**
+- New features with unclear scope
+- Changes touching multiple systems
+- Anything needing architectural decisions
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      QUICK MODE                             │
+├─────────────────────────────────────────────────────────────┤
+│  1. Understand task                                         │
+│  2. Quick research (relevant files only)                    │
+│  3. Implement with TDD                                      │
+│  4. Verify (typecheck, lint, test, build)                   │
+│  5. Commit                                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Step 1: Understand Task
+
+**First, run Tech Discovery Protocol** (Command Discovery in CLAUDE.md) to determine the project's
+test, lint, typecheck, and build commands. Cache the result for subsequent steps.
+
+If no project files are found (greenfield — no `package.json`, `Cargo.toml`, `go.mod`, etc.),
+ask for the product vision before proceeding. Quick tasks on a blank project need context.
+
+Parse: $ARGUMENTS.task
+
+Identify:
+- What needs to change
+- Why (bug, feature, refactor)
+- Expected outcome
+- Scope boundaries
+
+If scope is unclear or large, recommend:
+```
+This task seems complex. Consider using /bw-new-feature instead for:
+• Proper research phase
+• Technical specification
+• Staff Engineer review
+
+Continue with /bw-quick anyway? (say "continue" or use /bw-new-feature)
+```
+
+---
+
+## Step 2: Quick Research
+
+**Lightweight research - only what's needed for this task.**
+
+```bash
+# Find directly relevant files
+grep -r "[relevant terms]" --include="*.ts" --include="*.tsx" -l .
+
+# Read the specific files that will change
+cat [files to modify]
+
+# Check for existing tests
+find . -name "*.test.*" -o -name "*.spec.*" | xargs grep -l "[relevant terms]"
+```
+
+Understand:
+- Current implementation
+- Patterns used in these files
+- Related tests
+
+**Do NOT write a research document. Keep it in context.**
+
+---
+
+## Step 3: Implement with TDD
+
+### 3.1 Write/Update Tests First
+
+If bug fix:
+```bash
+# Write a failing test that reproduces the bug
+```
+
+If feature:
+```bash
+# Write tests for the expected behavior
+```
+
+Commit: `test: add test for [task]`
+
+### 3.2 Implement
+
+- Fix the bug / add the feature
+- Follow existing patterns in the file
+- Minimal changes only
+- KISS, YAGNI
+
+### 3.3 Update Docs (if applicable)
+
+If this task changed anything user-facing, state which doc files need updating
+then update them (README.md, docs/, CHANGELOG.md). Skip for internal-only changes.
+
+### 3.4 Verify (with retry)
+
+```bash
+# Run project's verification commands
+[typecheck]
+[lint]
+[test]
+[build]
+```
+
+- If fails → Fix and retry (up to BUILDWRIGHT_AGENT_RETRIES attempts, default 2)
+- If same error repeats → Not making progress — handle failure (see below)
+- If still failing after retries → Handle failure:
+  - **Autonomous** (`BUILDWRIGHT_AUTO_APPROVE=true`, default): Commit completed work, push branch, exit(1). No PR for quick tasks.
+  - **Interactive** (`BUILDWRIGHT_AUTO_APPROVE=false`): STOP and report blocker.
+
+### 3.5 Commit
+
+```bash
+git add [changed files]
+git commit -m "[type]([scope]): [description]"
+```
+
+Commit types:
+- `fix:` for bug fixes
+- `feat:` for small features
+- `refactor:` for refactors
+- `chore:` for config/maintenance
+
+---
+
+## Step 4: Report
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                      QUICK TASK COMPLETE                      ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  Task: [description]                                          ║
+║  Type: [bug fix / feature / refactor / chore]                 ║
+║                                                               ║
+║  Changes:                                                     ║
+║  • [file1]: [what changed]                                    ║
+║  • [file2]: [what changed]                                    ║
+║                                                               ║
+║  Verification:                                                ║
+║  ✅ Type Check                                                ║
+║  ✅ Lint                                                      ║
+║  ✅ Tests                                                     ║
+║  ✅ Build                                                     ║
+║                                                               ║
+║  Commit: [hash] [message]                                     ║
+║                                                               ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  Ready to push? Run: git push                                 ║
+║  Or run /bw-ship for full security + code review                 ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## When to Escalate
+
+If during implementation you discover:
+- Task is larger than expected
+- Changes needed in multiple systems
+- Architectural decisions required
+- Unclear requirements
+
+**STOP and recommend:**
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                    SCOPE ESCALATION                           ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  This task is more complex than expected:                     ║
+║  • [Reason 1]                                                 ║
+║  • [Reason 2]                                                 ║
+║                                                               ║
+║  Recommendation: Use /bw-new-feature for proper planning         ║
+║                                                               ║
+║  /bw-new-feature "[task description with discovered context]"    ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Examples
+
+### Bug Fix
+```
+/bw-quick "Fix login timeout - session expires after 5 minutes instead of 30"
+```
+
+### Small Feature
+```
+/bw-quick "Add loading spinner to the submit button"
+```
+
+### Config Change
+```
+/bw-quick "Increase rate limit from 100 to 500 requests per minute"
+```
+
+### Refactor
+```
+/bw-quick "Extract the validation logic from UserForm into a separate hook"
+```
+
+---
+
+## Difference from /bw-new-feature
+
+| Aspect | /bw-quick | /bw-new-feature |
+|--------|--------|--------------|
+| Research | Quick (in-context) | Full (research.md) |
+| Spec | None | Full spec.md |
+| Staff Engineer Review | None | Spec + Code |
+| Security Review | Optional (via /bw-ship) | Required |
+| Estimated Time | < 2 hours | Any |
+| Scope | Clear, bounded | Any |
+| Commits | 1-2 | Per milestone |

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

@@ -0,0 +1,288 @@
+---
+name: bw-ship
+description: Run full quality pipeline (verify → security → review) then commit, push, and create PR. Fails fast if any step fails.
+arguments:
+  - name: message
+    description: Commit message (conventional format). Required if there are uncommitted changes.
+    required: false
+---
+
+## Ship Pipeline
+
+This command runs the full quality pipeline before shipping.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      SHIP PIPELINE                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. VERIFY (quick checks) ← Retry up to 2x                  │
+│     └─ typecheck → lint → test → build                     │
+│              │                                              │
+│              ▼ PASS? Continue : Retry/STOP                  │
+│                                                             │
+│  2. SECURITY (OWASP + SAST) ← No retry                      │
+│     └─ dependencies → secrets → OWASP scan                 │
+│              │                                              │
+│              ▼ PASS? Continue : STOP                        │
+│                                                             │
+│  3. REVIEW (Staff Engineer) ← No retry                      │
+│     └─ logic → errors → patterns → quality                 │
+│              │                                              │
+│              ▼ PASS? Continue : STOP                        │
+│                                                             │
+│  4. RELEASE                                                 │
+│     └─ commit → push → create PR                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 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.
+
+Run quick verification checks:
+
+```bash
+# Discover and run project commands
+# Type check
+# Lint
+# Test
+# Build
+```
+
+**If fails → Fix and retry (up to BUILDWRIGHT_AGENT_RETRIES attempts, default 2).**
+**If same error repeats → Not making progress — handle failure (see below).**
+**If still failing after retries → Handle failure:**
+
+- **Autonomous** (`BUILDWRIGHT_AUTO_APPROVE=true`, default): Commit completed work, push branch, create PR with failure summary (see BUILDWRIGHT.md template), exit(1).
+- **Interactive** (`BUILDWRIGHT_AUTO_APPROVE=false`): STOP and report blocker to human.
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  STEP 1: VERIFY                                               ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Type Check:  ✅/❌                                            ║
+║  Lint:        ✅/❌                                            ║
+║  Tests:       ✅/❌                                            ║
+║  Build:       ✅/❌                                            ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Attempt: [1/2/3]                                             ║
+║  Status: PASS / RETRY / FAIL                                  ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+If FAIL after retries:
+- **Autonomous**: Commit + push + create failed PR (using BUILDWRIGHT.md template) + exit(1).
+- **Interactive**: Report specific errors and STOP.
+
+---
+
+## Step 2: Security Review — No retry (needs human judgment)
+
+Adopt Security Engineer persona from `.buildwright/agents/security-engineer.md`.
+
+### 2.1 Determine Scope
+```bash
+git diff --name-only main...HEAD
+# Or if no main branch:
+git diff --name-only HEAD
+```
+
+### 2.2 Automated Scans
+Run tools from the Security Engineer persona's "Tools to Use" section:
+- Dependency vulnerabilities (`npm audit` / `cargo audit` / etc.) — skip gracefully if unavailable
+- Secrets detection (pattern scan for API keys, passwords, tokens, private keys)
+- SAST (`semgrep --config p/owasp-top-ten .` if available)
+
+```bash
+# Skip gracefully if tools are unavailable
+[DISCOVERED_AUDIT_COMMAND] 2>/dev/null || echo "Dependency audit not available for this stack"
+semgrep --config p/owasp-top-ten . 2>/dev/null || echo "semgrep not available"
+```
+
+Where DISCOVERED_AUDIT_COMMAND is the stack-appropriate audit tool, e.g.:
+`npm audit` | `cargo audit` | `pip-audit` | `bundle audit` | `go list -m -json all | nancy sleuth`
+
+### 2.3 Manual Review (Phased)
+
+**Phase A — Repository Context:** Understand existing security posture — frameworks, middleware, auth patterns, trust boundaries.
+
+**Phase B — Comparative Analysis:** Does new code follow established security patterns? Does it bypass or weaken existing controls?
+
+**Phase C — Vulnerability Assessment:** Check changed code against OWASP Top 10 (A01-A10) using the full checklist from the Security Engineer persona.
+
+**If CRITICAL vulnerabilities found → No retry. Handle failure:**
+
+- **Autonomous** (`BUILDWRIGHT_AUTO_APPROVE=true`, default): Commit completed work, push branch, create PR with failure summary (see BUILDWRIGHT.md template), exit(1).
+- **Interactive** (`BUILDWRIGHT_AUTO_APPROVE=false`): STOP immediately. Security issues require human judgment.
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  STEP 2: SECURITY                                             ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Dependencies:  ✅/❌  ([N] vulnerabilities)                   ║
+║  Secrets:       ✅/❌  ([N] found)                             ║
+║  OWASP Scan:    ✅/❌  ([N] issues)                            ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Status: SECURE / CRITICAL VULNERABILITIES                    ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+If CRITICAL VULNERABILITIES:
+- **Autonomous**: Commit + push + create failed PR (using BUILDWRIGHT.md template) + exit(1).
+- **Interactive**: Report specific issues and STOP.
+
+---
+
+## Step 3: Code Review — No retry (architectural decisions)
+
+Adopt Staff Engineer persona from `.buildwright/agents/staff-engineer.md`.
+
+### 3.1 Determine Scope
+```bash
+git diff main...HEAD
+# Or if no main branch:
+git diff HEAD
+```
+
+### 3.2 Phased Review
+
+**Phase A — Repository Context:** Understand existing patterns, conventions, error handling, and testing approaches.
+
+**Phase B — Comparative Analysis:** Does new code follow established patterns? Does it bypass or weaken existing controls?
+
+**Phase C — Issue Assessment:** Review changes for real issues. For each: verify it's real, confirm it was INTRODUCED by these changes, assign confidence (only report ≥ 80).
+
+Assess against categories from the Staff Engineer persona's "In Code" checklist.
+
+**⚠️ APPROVED WITH COMMENTS** → Proceed to release. Fix recommendations if straightforward, otherwise note for follow-up.
+**❌ CHANGES REQUESTED** → No retry. Handle failure:
+
+- **Autonomous** (`BUILDWRIGHT_AUTO_APPROVE=true`, default): Commit completed work, push branch, create PR with failure summary (see BUILDWRIGHT.md template), exit(1).
+- **Interactive** (`BUILDWRIGHT_AUTO_APPROVE=false`): STOP immediately. Code review issues often involve architectural decisions that need human input.
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  STEP 3: CODE REVIEW                                          ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Logic:         ✅/❌                                          ║
+║  Error Handling:✅/❌                                          ║
+║  Performance:   ✅/❌                                          ║
+║  Maintainability:✅/❌                                         ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Status: APPROVED / CHANGES REQUESTED                         ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+If CHANGES REQUESTED:
+- **Autonomous**: Commit + push + create failed PR (using BUILDWRIGHT.md template) + exit(1).
+- **Interactive**: Report specific issues and STOP.
+
+---
+
+## Step 4: Release
+
+All checks passed. Now ship:
+
+### 4.1 Stage Changes
+```bash
+git add [specific files you changed]  # NEVER git add -A
+```
+
+### 4.2 Commit
+```bash
+# Use provided message or generate from changes
+git commit -m "$ARGUMENTS.message"
+```
+
+If no message provided and there are changes, generate a conventional commit message based on the changes.
+
+### 4.3 Push
+```bash
+# Push to remote
+git push origin HEAD
+```
+
+### 4.4 Create PR
+```bash
+# Create pull request
+gh pr create --fill
+```
+
+If `gh` is not available, provide the PR creation URL.
+
+---
+
+## Final Report
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                        SHIP COMPLETE                          ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  ✅ Verify:    PASSED                                         ║
+║  ✅ Security:  PASSED                                         ║
+║  ✅ Review:    APPROVED                                       ║
+║  ✅ Release:   SHIPPED                                        ║
+║                                                               ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Commit:  [commit hash]                                       ║
+║  Branch:  [branch name]                                       ║
+║  PR:      [PR URL]                                            ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  Quality gates will run in CI.                                ║
+║  PR will auto-merge when all gates pass.                      ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Failure Handling
+
+### Interactive Mode (`BUILDWRIGHT_AUTO_APPROVE=false`)
+
+STOP and show the blocker:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                      SHIP BLOCKED                             ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  ❌ Failed at: [STEP NAME]                                    ║
+║                                                               ║
+║  Reason:                                                      ║
+║  [Specific failure details]                                   ║
+║                                                               ║
+║  To fix:                                                      ║
+║  [Actionable remediation steps]                               ║
+║                                                               ║
+║  After fixing, run /bw-ship again.                               ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### Autonomous Mode (`BUILDWRIGHT_AUTO_APPROVE=true`, default)
+
+Commit completed work, push, create PR with failure details, and exit(1):
+
+1. Stage and commit all completed work to the feature branch
+2. Push branch to remote
+3. Create PR using the failure summary template from BUILDWRIGHT.md
+4. Exit with non-zero code so CI/CD registers the failure
+
+The PR title should be prefixed with `[FAILED]` and the body should follow the PR Failure Summary Template documented in BUILDWRIGHT.md.
+
+---
+
+## Multi-Agent Safety
+
+- Only commit files you modified
+- Never use `git stash`
+- Pull before push if needed
+- Use atomic commits

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

@@ -0,0 +1,108 @@
+---
+name: bw-verify
+description: Run quick quality checks (typecheck, lint, test, build). For full checks including security and AI review, use /bw-ship.
+---
+
+Running quick verification...
+
+## 1. Discover Project Commands
+
+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.
+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.
+
+---
+
+## 2. Type Check
+
+Run DISCOVERED_TYPECHECK.
+
+Examples by runtime (use only what was discovered — do not hardcode):
+- Node/TypeScript: `npx tsc --noEmit` or the project's typecheck script
+- Rust: `cargo check`
+- Go: `go build ./...`
+- Python: `mypy .` or `pyright`
+- Other: SKIP if no type checker exists for this stack
+
+**Result:** PASS / FAIL / SKIP
+**Details:** [error count and locations if failed]
+
+---
+
+## 3. Lint
+
+Run DISCOVERED_LINT.
+
+Examples by runtime (use only what was discovered):
+- Node/TypeScript: project lint script or `npx eslint .`
+- Rust: `cargo clippy -- -D warnings`
+- Go: `golangci-lint run`
+- Python: `ruff check .` or `flake8`
+- Other: SKIP if no linter configured
+
+**Result:** PASS / FAIL / SKIP
+**Details:** [warning/error count]
+
+---
+
+## 4. Tests
+
+Run DISCOVERED_TEST.
+
+Examples by runtime (use only what was discovered):
+- Node/TypeScript: project test script or `npx jest`
+- Rust: `cargo test`
+- Go: `go test ./...`
+- Python: `pytest`
+- Other: consult Makefile or CI workflow
+
+**Result:** PASS / FAIL
+**Details:** [test count, coverage % if available]
+
+---
+
+## 5. Build
+
+Run DISCOVERED_BUILD.
+
+Examples by runtime (use only what was discovered):
+- Node/TypeScript: project build script
+- Rust: `cargo build --release`
+- Go: `go build ./...`
+- Python: SKIP — no build step for interpreted scripts
+- Other: SKIP if this stack has no build step
+
+**Result:** PASS / FAIL / SKIP
+**Details:** [any warnings]
+
+---
+
+## Summary
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                    QUICK VERIFICATION                         ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Stack detected:  [runtime]                                   ║
+║  Commands used:   [list of commands actually run]             ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Type Check:  ✅ PASS / ❌ FAIL / ⏭ SKIP                     ║
+║  Lint:        ✅ PASS / ❌ FAIL / ⏭ SKIP  ([N] warnings)     ║
+║  Tests:       ✅ PASS / ❌ FAIL  ([N] tests, [X]% coverage)   ║
+║  Build:       ✅ PASS / ❌ FAIL / ⏭ SKIP                     ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Status: PASS / BLOCKED                                       ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+If BLOCKED: List specific failures with file:line references.
+
+---
+
+## Next Steps
+
+- If PASS: Run `/bw-ship` for full quality pipeline (security + review + release)
+- If BLOCKED: Fix issues and re-run `/bw-verify`

package/templates/.buildwright/steering/naming-conventions.md

@@ -0,0 +1,40 @@
+# Naming Conventions
+
+Shared vocabulary across all agents and claws. When any agent adds a new field, endpoint, or concept, it MUST be registered here so all other agents derive their naming from this registry.
+
+## Layer-Specific Naming Rules
+
+| Layer | Convention | Example |
+|-------|-----------|---------|
+| Database columns | `snake_case` | `photo_url`, `created_at` |
+| API (JSON keys) | `camelCase` | `photoUrl`, `createdAt` |
+| UI (JavaScript) | `camelCase` | `photoUrl`, `createdAt` |
+| CSS classes | `kebab-case` | `photo-upload`, `member-card` |
+| URL paths | `kebab-case` | `/api/team-members/:id/photo` |
+| Environment vars | `SCREAMING_SNAKE` | `BUILDWRIGHT_AUTO_APPROVE` |
+| File names | `kebab-case` | `photo-upload.tsx`, `team-members.ts` |
+
+## Canonical Field Registry
+
+Register new fields here when they cross domain boundaries.
+
+| Concept | Database | API (JSON) | UI (JS) | Notes |
+|---------|----------|------------|---------|-------|
+| — | `snake_case` | `camelCase` | `camelCase` | Convention |
+<!-- Add new fields below this line -->
+
+## Canonical Endpoint Registry
+
+Register new endpoints here when they're defined by the Architect.
+
+| Purpose | Method | Path | Request Body | Response Body |
+|---------|--------|------|-------------|--------------|
+<!-- Add new endpoints below this line -->
+
+## Rules
+
+1. **Architect registers first** — Before spawning claws, the Architect adds new fields/endpoints to this file
+2. **Claws derive, never invent** — Each claw looks up naming from this registry, never creates its own
+3. **One source of truth** — If a name isn't here, ask the Architect before proceeding
+4. **No abbreviations** — Use `photo_url` not `pic_url`, `description` not `desc`
+5. **Consistent pluralization** — Collections are plural (`members`), single items are singular (`member`)