buildwright 0.0.5 → 0.0.7

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`)

package/templates/.buildwright/steering/product.md

@@ -0,0 +1,16 @@
+# Product Context
+
+## What We're Building
+[Describe your product/project here]
+
+## Key Features
+[List main features]
+
+## User Personas
+[Describe target users]
+
+## Business Constraints
+[Timeline, compliance, integrations]
+
+## Current Focus
+[What's being worked on now]

package/templates/.buildwright/steering/quality-gates.md

@@ -0,0 +1,35 @@
+# Quality Gates
+
+These automated gates replace human code review. ALL must pass for merge.
+
+## Gate 1: Static Analysis
+- [ ] Type check passes (zero errors)
+- [ ] Lint passes (zero errors, warnings acceptable)
+- [ ] No new lint warnings introduced
+
+## Gate 2: Tests
+- [ ] All existing tests pass
+- [ ] New code has tests
+- [ ] Coverage does not decrease
+- [ ] Critical paths have >80% coverage
+
+## Gate 3: Security
+- [ ] No high/critical vulnerabilities in dependencies
+- [ ] No secrets in code
+- [ ] SAST scan passes (if configured)
+
+## Gate 4: Build
+- [ ] Production build succeeds
+- [ ] No build warnings
+
+## Gate 5: AI Review (Optional)
+- [ ] No blocking issues from AI reviewer
+
+## Financial/Trading Code (Additional)
+- [ ] No floating-point for currency
+- [ ] All inputs validated
+- [ ] Rate limiting on sensitive endpoints
+- [ ] Audit logging for transactions
+
+## Auto-Merge Criteria
+When ALL gates pass → PR auto-merges → Deploy triggers

package/templates/.buildwright/steering/tech.md

@@ -0,0 +1,27 @@
+# Technical Context
+
+## Stack
+[List your tech stack]
+
+## Project Commands
+
+Fill in these slots with your project's actual commands. If left empty, Buildwright
+auto-detects from project files (package.json, Cargo.toml, go.mod, pyproject.toml,
+Makefile) and populates this section on the first run.
+
+```
+typecheck: [command]  # Examples: npx tsc --noEmit | cargo check | go build ./... | mypy .
+lint:      [command]  # Examples: npx eslint . | cargo clippy | golangci-lint run | ruff check .
+test:      [command]  # Examples: npm test | cargo test | go test ./... | pytest
+build:     [command]  # Examples: npm run build | cargo build --release | go build ./...
+dev:       [command]  # Examples: npm run dev | cargo run | go run ./... | uvicorn app:main
+```
+
+## Architecture
+[High-level architecture notes]
+
+## Code Patterns
+[Patterns used in this codebase]
+
+## Dependencies
+[Key dependencies and why]

package/templates/.buildwright/tasks/TEMPLATE.md

@@ -0,0 +1,79 @@
+# Task: [Feature Name]
+
+## Quick Reference
+- **Status**: DRAFTING | SPEC_REVIEW | IMPLEMENTING | CODE_REVIEW | COMPLETE | BLOCKED
+- **Branch**: feature/[name]
+- **Spec**: docs/specs/[name]/spec.md
+- **Current Owner**: [agent-role or "unassigned"]
+
+---
+
+## Status: DRAFTING
+
+## Branch: feature/[name]
+
+## Current Owner: unassigned
+
+---
+
+## Phases
+
+### Phase 1: Specification
+| Field | Value |
+|-------|-------|
+| Owner | architect-agent |
+| Status | ⏳ PENDING |
+| Output | docs/specs/[name]/spec.md |
+| Started | - |
+| Completed | - |
+
+### Phase 2: Implementation
+| Field | Value |
+|-------|-------|
+| Owner | implementer-agent |
+| Status | ⏳ WAITING |
+| Branch | feature/[name] |
+| Started | - |
+| Completed | - |
+
+**Milestones**:
+- [ ] Milestone 1: [description]
+- [ ] Milestone 2: [description]
+- [ ] Milestone 3: [description]
+
+### Phase 3: Review & Ship
+| Field | Value |
+|-------|-------|
+| Owner | reviewer-agent |
+| Status | ⏳ WAITING |
+| PR | - |
+| Started | - |
+| Completed | - |
+
+---
+
+## Context for Next Agent
+
+### Decisions Made
+- 
+
+### Key Files Modified
+- 
+
+### Known Issues / TODOs
+- 
+
+### Test Commands
+```bash
+npm run test
+```
+
+---
+
+## Blockers
+None currently.
+
+---
+
+## Communication Log
+- [timestamp] [agent]: Starting work

package/templates/.env.example

@@ -1 +1,11 @@
-../../.env.example
+# Buildwright Environment Variables
+# Copy to .env or export in your shell: source .env.example
+
+# Autonomous mode — skip human approval, fail gracefully on errors
+# true (default): Pipeline runs fully autonomous. Failures commit + push + create failed PR + exit(1).
+# false: Pipeline stops on failure and waits for human input.
+BUILDWRIGHT_AUTO_APPROVE=true
+
+# Number of verify retries (typecheck, lint, test, build) before giving up
+# Default: 2
+BUILDWRIGHT_AGENT_RETRIES=2

package/templates/.github/workflows/quality-gates.yml

@@ -0,0 +1,150 @@
+name: Quality Gates
+
+on:
+  pull_request:
+    branches: [main, master]
+  push:
+    branches: [main, master]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Verify sync script runs without errors (catches broken scripts or missing deps)
+      - name: Verify sync script
+        run: make sync
+
+      # Detect package manager and project type
+      - name: Detect project type
+        id: detect
+        run: |
+          if [ -f "package.json" ]; then
+            echo "type=node" >> $GITHUB_OUTPUT
+            if [ -f "pnpm-lock.yaml" ]; then
+              echo "pm=pnpm" >> $GITHUB_OUTPUT
+            elif [ -f "yarn.lock" ]; then
+              echo "pm=yarn" >> $GITHUB_OUTPUT
+            elif [ -f "bun.lockb" ]; then
+              echo "pm=bun" >> $GITHUB_OUTPUT
+            else
+              echo "pm=npm" >> $GITHUB_OUTPUT
+            fi
+          elif [ -f "Cargo.toml" ]; then
+            echo "type=rust" >> $GITHUB_OUTPUT
+          elif [ -f "go.mod" ]; then
+            echo "type=go" >> $GITHUB_OUTPUT
+          elif [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+            echo "type=python" >> $GITHUB_OUTPUT
+          fi
+
+      # Node.js setup
+      - name: Setup Node.js
+        if: steps.detect.outputs.type == 'node'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup pnpm
+        if: steps.detect.outputs.pm == 'pnpm'
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - name: Install dependencies (Node)
+        if: steps.detect.outputs.type == 'node'
+        run: |
+          case "${{ steps.detect.outputs.pm }}" in
+            pnpm) pnpm install --frozen-lockfile ;;
+            yarn) yarn install --frozen-lockfile ;;
+            bun) bun install ;;
+            *) npm ci ;;
+          esac
+
+      # Rust setup
+      - name: Setup Rust
+        if: steps.detect.outputs.type == 'rust'
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+
+      # Go setup
+      - name: Setup Go
+        if: steps.detect.outputs.type == 'go'
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      # Python setup
+      - name: Setup Python
+        if: steps.detect.outputs.type == 'python'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies (Python)
+        if: steps.detect.outputs.type == 'python'
+        run: |
+          pip install -e ".[dev]" || pip install -r requirements.txt
+
+      # Quality checks
+      - name: Type Check
+        run: |
+          case "${{ steps.detect.outputs.type }}" in
+            node) ${{ steps.detect.outputs.pm }} run typecheck || npx tsc --noEmit ;;
+            rust) cargo check ;;
+            go) go build ./... ;;
+            python) mypy . || pyright || echo "No type checker configured" ;;
+          esac
+
+      - name: Lint
+        run: |
+          case "${{ steps.detect.outputs.type }}" in
+            node) ${{ steps.detect.outputs.pm }} run lint || npx eslint . ;;
+            rust) cargo clippy -- -D warnings ;;
+            go) golangci-lint run || echo "golangci-lint not installed" ;;
+            python) ruff check . || flake8 ;;
+          esac
+
+      - name: Test
+        run: |
+          case "${{ steps.detect.outputs.type }}" in
+            node) ${{ steps.detect.outputs.pm }} test ;;
+            rust) cargo test ;;
+            go) go test ./... ;;
+            python) pytest ;;
+          esac
+
+      - name: Build
+        run: |
+          case "${{ steps.detect.outputs.type }}" in
+            node) ${{ steps.detect.outputs.pm }} run build ;;
+            rust) cargo build --release ;;
+            go) go build ./... ;;
+            python) echo "No build step" ;;
+          esac
+
+      - name: Security Audit
+        run: |
+          case "${{ steps.detect.outputs.type }}" in
+            node) ${{ steps.detect.outputs.pm }} audit --audit-level=high || true ;;
+            rust) cargo audit || echo "cargo-audit not installed" ;;
+            go) govulncheck ./... || echo "govulncheck not installed" ;;
+            python) pip-audit || safety check || echo "No Python audit tool" ;;
+          esac
+
+  auto-merge:
+    needs: quality
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Auto-merge on quality pass
+        uses: pascalgn/automerge-action@v0.15.6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MERGE_METHOD: squash
+          MERGE_LABELS: ""

package/templates/BUILDWRIGHT.md

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