buildwright 0.0.5 → 0.0.6

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 |

package/templates/CLAUDE.md

@@ -1 +1,150 @@
-../../CLAUDE.md
+# Buildwright Development
+
+## Mission
+Agent-first autonomous development. Humans approve specs; agents implement, test, 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.
+
+## 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.
+
+## Project Structure
+
+`.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-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)
+```
+
+After cloning or editing `.buildwright/`, run `make sync` to regenerate tool-specific configs.
+
+## Operating Mode
+
+### 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.
+
+## Command Discovery
+
+Run once per session. Cache the result — do not re-detect on every step.
+
+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?"
+
+## Credentials & 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 |
+
+`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.
+
+## Verification Loop (CRITICAL)
+
+Before EVERY commit, discover commands first (see Command Discovery above), then run:
+
+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)
+
+If ANY required step fails: fix and retry (max 2 attempts). If same error repeats or still failing: STOP and report blocker.
+
+## 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, docs/, or CHANGELOG.md if the change affects user-facing behavior
+
+## 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
+
+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
+
+## 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
+
+## Self-Improvement
+When you discover a pattern, gotcha, or better approach:
+- Add it below under "Learned Patterns"
+- Keep entries concise (one line each)
+
+## Learned Patterns
+<!-- Agent adds entries here as it learns -->

package/templates/Makefile

@@ -1 +1,82 @@
-../../Makefile
+.PHONY: dist clean sync sync-check cursor opencode openclaw validate install-hooks uninstall-hooks bump test-cli
+
+# ============================================================================
+# Sync — Generate .claude/, .opencode/, .cursor/rules/ from .buildwright/ (canonical)
+# Source of truth: .buildwright/ → .claude/ + .opencode/ + .cursor/rules/ + AGENTS.md + dist/
+# ============================================================================
+
+sync:
+	@chmod +x scripts/sync-agents.sh
+	@scripts/sync-agents.sh
+
+sync-check:
+	@chmod +x scripts/sync-agents.sh
+	@scripts/sync-agents.sh --check
+
+# ============================================================================
+# Package for distribution
+# ============================================================================
+
+# ClawHub — upload dist/buildwright/ folder to https://clawhub.ai/upload
+dist: sync
+	@echo "dist/buildwright/ ready — upload this folder to ClawHub"
+
+# Cursor — print setup instructions (rules generated by make 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'."
+
+# OpenCode — install skill to user global config
+opencode: sync
+	@mkdir -p ~/.config/opencode/skills/buildwright
+	@cp SKILL.md ~/.config/opencode/skills/buildwright/SKILL.md
+	@echo "Installed to ~/.config/opencode/skills/buildwright/"
+
+# OpenClaw — install skill to user skills directory
+openclaw: sync
+	@mkdir -p ~/.openclaw/skills/buildwright
+	@cp SKILL.md ~/.openclaw/skills/buildwright/SKILL.md
+	@echo "Installed to ~/.openclaw/skills/buildwright/"
+
+# ============================================================================
+# Validate SKILL.md against Agent Skills spec (agentskills.io)
+# ============================================================================
+
+validate:
+	@chmod +x scripts/validate-skill.sh
+	@scripts/validate-skill.sh SKILL.md
+
+# ============================================================================
+# Git Hooks — keep .buildwright/ ↔ generated files in sync automatically
+# ============================================================================
+
+install-hooks:
+	@chmod +x scripts/install-hooks.sh
+	@scripts/install-hooks.sh
+
+uninstall-hooks:
+	@rm -f .git/hooks/pre-commit .git/hooks/post-merge .git/hooks/post-checkout
+	@echo "Buildwright hooks removed."
+
+# ============================================================================
+# Clean
+# ============================================================================
+
+bump: ## Bump version: make bump [BUMP=patch|minor|major]
+	@chmod +x scripts/bump-version.sh
+	@scripts/bump-version.sh $(or $(BUMP),patch)
+
+test-cli: ## Pack and install CLI globally for local testing
+	@echo "Packing cli/..."
+	@cd cli && npm pack
+	@TARBALL=$$(ls cli/buildwright-*.tgz | tail -1) && \
+	  npm install -g "./$$TARBALL" && \
+	  rm -f "$$TARBALL"
+	@echo ""
+	@echo "✓ buildwright installed globally from local pack"
+	@echo "  Test it: cd /tmp && mkdir test-bw && cd test-bw && buildwright init"
+	@echo "  Uninstall: npm uninstall -g buildwright"
+
+clean:
+	rm -rf dist/

package/templates/docs/requirements/TEMPLATE.md

@@ -0,0 +1,33 @@
+# Feature: [Name]
+
+## Problem Statement
+[What problem are we solving? Who has this problem?]
+
+## Success Metrics
+- [Metric]: [Target]
+
+## User Stories
+As a [role], I want [capability] so that [benefit].
+
+## Functional Requirements
+
+### Must Have (MVP)
+1. [Requirement]
+   - Acceptance: [Criteria]
+
+### Should Have
+1. [Requirement]
+
+### Out of Scope
+- [What NOT to build]
+
+## Constraints
+- Timeline: [Deadline]
+- Technical: [Integrations, platforms]
+- Regulatory: [Compliance]
+
+## Examples / Edge Cases
+1. [Scenario]: [Expected behavior]
+
+## Open Questions
+[Questions needing answers]