buildwright 0.0.3 → 0.0.5

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

@@ -1,245 +0,0 @@
----
-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

@@ -1,288 +0,0 @@
----
-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

@@ -1,108 +0,0 @@
----
-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

@@ -1,40 +0,0 @@
-# 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`)