buildwright 0.0.5 → 0.0.7

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,86 @@
-../../Makefile
+.PHONY: dist clean sync sync-check cursor opencode openclaw validate install-hooks uninstall-hooks bump release 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 files only (no git ops): make bump [BUMP=patch|minor|major]
+	@chmod +x scripts/bump-version.sh
+	@scripts/bump-version.sh $(or $(BUMP),patch)
+
+release: ## Full release: bump, commit, tag, push, GitHub release, npm publish: make release [BUMP=patch|minor|major]
+	@chmod +x scripts/release.sh
+	@scripts/release.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]

package/templates/scripts/bump-version.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# npm versions that are reserved/broken and must never be published
+BLOCKED_VERSIONS=("1.0.0" "1.0.1" "1.0.2")
+
+BUMP="${1:-patch}"   # patch | minor | major
+
+# 1. Bump cli/package.json (no git tag yet)
+cd cli
+npm version "$BUMP" --no-git-tag-version
+NEW_VERSION=$(node -p "require('./package.json').version")
+
+# 2. Check if new version is blocked — if so, keep patching until clear
+while printf '%s\n' "${BLOCKED_VERSIONS[@]}" | grep -qx "$NEW_VERSION"; do
+  echo "⚠️  Version $NEW_VERSION is reserved on npm — skipping to next patch..."
+  npm version patch --no-git-tag-version
+  NEW_VERSION=$(node -p "require('./package.json').version")
+done
+cd ..
+
+# 3. Update SKILL.md frontmatter
+sed -i.bak "s/^  version: \".*\"/  version: \"$NEW_VERSION\"/" SKILL.md
+rm -f SKILL.md.bak
+
+# 4. Sync dist/
+make sync
+
+echo ""
+echo "✓ Bumped to v$NEW_VERSION"
+echo ""
+echo "Files updated: cli/package.json  SKILL.md"
+echo "Run 'make release' to commit, tag, push, create GitHub release, and npm publish."

package/templates/scripts/hooks/post-checkout

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Buildwright post-checkout hook
+# Runs after git checkout.
+# $1 = previous HEAD, $2 = new HEAD, $3 = 1 (branch switch) or 0 (file checkout)
+# Only acts on branch switches ($3 == 1) where .buildwright/ content differs.
+
+set -e
+
+PREV_HEAD="$1"
+NEW_HEAD="$2"
+BRANCH_SWITCH="$3"
+
+# Skip file-level checkouts
+if [ "$BRANCH_SWITCH" != "1" ]; then
+  exit 0
+fi
+
+if git diff --name-only "$PREV_HEAD" "$NEW_HEAD" 2>/dev/null | grep -q '^\.buildwright/'; then
+  echo "Buildwright: .buildwright/ differs between branches — running make sync..."
+  make sync
+  echo "Buildwright: sync complete."
+fi
+
+exit 0

package/templates/scripts/hooks/post-merge

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Buildwright post-merge hook
+# Runs after git pull / git merge.
+# If any file under .buildwright/ changed in the merge, run make sync automatically.
+
+set -e
+
+if git diff --name-only ORIG_HEAD HEAD 2>/dev/null | grep -q '^\.buildwright/'; then
+  echo "Buildwright: .buildwright/ changed in merge — running make sync..."
+  make sync
+  echo "Buildwright: sync complete."
+fi
+
+exit 0

package/templates/scripts/hooks/pre-commit

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Buildwright pre-commit hook
+# If any staged file is under .buildwright/, run make sync before committing.
+# Never blocks the commit — sync is a convenience to keep generated files current.
+
+set -e
+
+if git diff --cached --name-only | grep -q '^\.buildwright/'; then
+  echo "Buildwright: .buildwright/ changes detected — running make sync..."
+  make sync
+  echo "Buildwright: sync complete."
+fi
+
+exit 0

package/templates/scripts/install-hooks.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Buildwright hook installer
+# Copies scripts/hooks/* to .git/hooks/ and makes them executable.
+# Idempotent — safe to run multiple times.
+
+set -e
+
+if ! git rev-parse --show-toplevel >/dev/null 2>&1; then
+  echo "Not inside a git repository — skipping hook installation."
+  echo "Run 'git init && make install-hooks' to enable auto-sync hooks."
+  exit 0
+fi
+
+HOOKS_SRC="$(cd "$(dirname "$0")/hooks" && pwd)"
+HOOKS_DEST="$(git rev-parse --show-toplevel)/.git/hooks"
+
+if [ ! -d "$HOOKS_SRC" ]; then
+  echo "Error: hooks source directory not found at $HOOKS_SRC" >&2
+  exit 1
+fi
+
+if [ ! -d "$HOOKS_DEST" ]; then
+  echo "Error: .git/hooks directory not found. Are you inside a git repo?" >&2
+  exit 1
+fi
+
+for hook in "$HOOKS_SRC"/*; do
+  name="$(basename "$hook")"
+  dest="$HOOKS_DEST/$name"
+  cp "$hook" "$dest"
+  chmod +x "$dest"
+  echo "  Installed: .git/hooks/$name"
+done
+
+echo "Buildwright hooks installed successfully."

package/templates/scripts/release.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BUMP="${1:-patch}"
+
+# Guard: working tree must be clean before we start
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  echo "Error: working tree has uncommitted changes. Commit or stash before releasing."
+  exit 1
+fi
+
+# Step 1: bump version files (cli/package.json + SKILL.md + make sync)
+make bump BUMP="$BUMP"
+
+# Read new version from the bumped package.json
+NEW_VERSION=$(node -p "require('./cli/package.json').version")
+
+# Step 2: commit version files
+git add cli/package.json cli/package-lock.json SKILL.md
+git commit -m "chore: bump version to v$NEW_VERSION"
+
+# Step 3: annotated tag
+git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
+
+# Step 4: push commit + tag
+git push
+git push origin "v$NEW_VERSION"
+
+# Step 5: GitHub release with auto-generated notes
+gh release create "v$NEW_VERSION" --title "v$NEW_VERSION" --generate-notes
+
+# Step 6: publish to npm
+cd cli && npm publish
+
+echo ""
+echo "✓ Released v$NEW_VERSION"
+echo "  GitHub: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/releases/tag/v$NEW_VERSION"
+echo "  npm:    https://www.npmjs.com/package/buildwright/v/$NEW_VERSION"