buildwright 0.0.14 → 0.0.16

package/README.md

@@ -95,6 +95,12 @@ and Buildwright-owned support scripts. It also removes paths from the old
 pre-`/bw-work` model so generated tool configs do not contain both old and new
 workflows.
 
+Steering is only touched if Buildwright ships the file. The default
+`philosophy.md` is refreshed in place only when it is unmodified (a known shipped
+version); a customized `philosophy.md` is preserved. Any steering file Buildwright
+does not ship — your `tech.md`, `product.md`, or org-injected docs such as
+`quality-gates.md` — is never deleted or overwritten.
+
 ### From Source
 
 ```bash
@@ -103,6 +109,49 @@ cd buildwright
 make sync
 ```
 
+### Global install
+
+Per-project `buildwright init` is the recommended setup — it commits the
+workflow config to your repo so it is versioned and shared with your team. If
+you would rather have the workflow available in **every** project without
+running `init` each time, install it globally from a Buildwright checkout.
+
+```bash
+make global      # install for all supported tools at once
+```
+
+Or install for a single tool:
+
+| Command | Tool | Installs to |
+|---------|------|-------------|
+| `make claude` | Claude Code | `~/.claude/commands/`, `~/.claude/agents/` |
+| `make codex` | Codex CLI | `~/.agents/skills/buildwright/` (symlink) |
+| `make opencode` | OpenCode | `~/.config/opencode/skills/buildwright/` |
+| `make openclaw` | OpenClaw | `~/.openclaw/skills/buildwright/` |
+
+Global install makes the **workflow** (the `/bw-*` commands and agents)
+discoverable everywhere. Project-specific context — steering docs, tech/product
+details, and `/bw-analyse` codebase docs — still comes from each project's
+`.buildwright/` directory. In a project without `.buildwright/`, commands fall
+back to stack auto-detection, and the `/bw-work` and `/bw-ship` review steps read
+the engineer personas from `~/.claude/agents/` (installed by `make claude`). Run
+`buildwright init` there when you want full project context (custom steering,
+codebase docs).
+
+Note: `make claude` is what installs the `security-engineer` / `staff-engineer`
+persona files into `~/.claude/agents/`, so Claude Code's review steps find them
+everywhere. The other tools install commands/skills only — under
+Codex/OpenCode/OpenClaw the review personas come from a project's
+`.buildwright/agents/`, so run `buildwright init` for full reviews there.
+
+Re-run the same command after `git pull` to update. To uninstall:
+
+```bash
+rm ~/.claude/commands/bw-*.md ~/.claude/agents/{staff,security}-engineer.md
+rm ~/.agents/skills/buildwright                     # codex symlink
+rm -rf ~/.config/opencode/skills/buildwright ~/.openclaw/skills/buildwright
+```
+
 ## Project Layout
 
 ```text
@@ -119,14 +168,16 @@ make sync
   steering/
     philosophy.md
 
+AGENTS.md               # canonical agent instructions (committed)
+CLAUDE.md               # pointer stub → AGENTS.md (committed)
 .claude/                # generated by make sync
 .opencode/              # generated by make sync
 .cursor/rules/          # generated by make sync
-AGENTS.md               # generated by make sync
 skills/                 # generated by make sync for Codex CLI
 ```
 
-`.buildwright/` is canonical. Generated tool directories are gitignored.
+`.buildwright/` and `AGENTS.md` are canonical and committed. `CLAUDE.md` is a
+pointer stub to `AGENTS.md`. Generated tool directories are gitignored.
 
 ## Development
 
@@ -138,8 +189,8 @@ make sync-check
 make validate
 ```
 
-`make sync` regenerates tool-specific config, Codex skills, `AGENTS.md`, and the
-CLI README.
+`make sync` regenerates tool-specific config, Codex skills, and the CLI README.
+`AGENTS.md` and `CLAUDE.md` are hand-maintained root files, not generated.
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildwright",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Lightweight engineering workflow for agent-led development.",
   "license": "MIT",
   "engines": {
@@ -15,6 +15,7 @@
     "templates/"
   ],
   "scripts": {
+    "test": "node --test",
     "prepack": "node scripts/prepack.js",
     "postpack": "node scripts/postpack.js"
   },

package/src/commands/update.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const https = require('https');
 const { execSync } = require('child_process');
 const { isBuildwrightInstalled } = require('../utils/detect');
@@ -35,9 +36,6 @@ const REMOVED_PATHS = [
   '.buildwright/claws',
   '.buildwright/skills',
   '.buildwright/tasks/TEMPLATE.md',
-  '.buildwright/steering/quality-gates.md',
-  '.buildwright/steering/naming-conventions.md',
-  '.buildwright/steering/engineering-philosophy.md',
   'docs/requirements/TEMPLATE.md',
   '.claude/commands/bw-new-feature.md',
   '.claude/commands/bw-quick.md',
@@ -65,6 +63,60 @@ const REMOVED_PATHS = [
   'skills/bw-help',
 ];
 
+// Steering files Buildwright ships and may update in place. Keyed by filename,
+// each value is the set of SHA-256 hashes of every version Buildwright has ever
+// shipped for that file. An existing steering file is overwritten on update ONLY
+// when its hash is in this set (i.e. it is an unmodified, previously-shipped
+// copy); a customized file (hash absent) is preserved. Files Buildwright does not
+// ship at all are never touched.
+//
+// RELEASE STEP: whenever a managed steering file changes, append the superseded
+// version's SHA-256 here so unmodified installs keep auto-updating.
+const MANAGED_STEERING_HASHES = {
+  'philosophy.md': new Set([
+    '476fe491e139a211d9483942bd60435513813227c589ae0c29ba1e082672757a',
+  ]),
+};
+
+function sha256(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+/**
+ * Copy shipped steering files into dest. New shipped files are added. An existing
+ * file is overwritten only when its content matches a known shipped hash (i.e. the
+ * user has not customized it); customized or unmanaged files are preserved. Files
+ * not shipped by Buildwright are never touched. Steering is a flat dir of .md files.
+ * @param {object} [managedHashes] - filename -> Set of known shipped hashes
+ * @returns {{updated: string[], preserved: string[]}}
+ */
+function updateSteering(src, dest, managedHashes = MANAGED_STEERING_HASHES) {
+  fs.mkdirSync(dest, { recursive: true });
+  const updated = [];
+  const preserved = [];
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const realSrc = fs.realpathSync(path.join(src, entry.name));
+    const destPath = path.join(dest, entry.name);
+    if (!fs.existsSync(destPath)) {
+      fs.copyFileSync(realSrc, destPath);
+      updated.push(entry.name);
+      continue;
+    }
+    const known = managedHashes[entry.name];
+    const localHash = sha256(destPath);
+    if (known && known.has(localHash)) {
+      if (sha256(realSrc) !== localHash) {
+        fs.copyFileSync(realSrc, destPath);
+        updated.push(entry.name);
+      }
+    } else {
+      preserved.push(entry.name);
+    }
+  }
+  return { updated, preserved };
+}
+
 /**
  * Download a URL following redirects. Returns a Buffer.
  */
@@ -120,7 +172,7 @@ async function update() {
 
   console.log(`${BOLD}Updating Buildwright in ${cwd}...${RESET}\n`);
   console.log(`Updating: ${UPDATE_DIRS.map(d => `.buildwright/${d}/`).join(', ')}`);
-  console.log(`Preserving: project-created steering files such as tech.md and product.md\n`);
+  console.log(`Preserving: customized and org-injected steering files (only an unmodified philosophy.md is refreshed)\n`);
 
   let tmpDir;
   try {
@@ -163,7 +215,14 @@ async function update() {
       }
       console.log(`  Updating .buildwright/${dir}/`);
       fs.mkdirSync(dest, { recursive: true });
-      copyDir(src, dest, { skipExisting: dir === 'steering' });
+      if (dir === 'steering') {
+        const { preserved } = updateSteering(src, dest);
+        if (preserved.length > 0) {
+          console.log(`    Preserved customized steering files: ${preserved.join(', ')}`);
+        }
+      } else {
+        copyDir(src, dest);
+      }
     }
 
     for (const file of SUPPORT_FILES) {
@@ -175,12 +234,15 @@ async function update() {
     }
     console.log(`  Updated Buildwright support scripts`);
 
-    // Also add CLAUDE.md if it doesn't already exist locally
-    const srcClaude = path.join(extractedRoot, 'CLAUDE.md');
-    const destClaude = path.join(cwd, 'CLAUDE.md');
-    if (fs.existsSync(srcClaude) && !fs.existsSync(destClaude)) {
-      console.log(`  Adding CLAUDE.md`);
-      fs.copyFileSync(srcClaude, destClaude);
+    // Add the canonical AGENTS.md and the CLAUDE.md pointer stub if absent
+    // locally. Existing files are left untouched (treated as user-owned).
+    for (const file of ['AGENTS.md', 'CLAUDE.md']) {
+      const src = path.join(extractedRoot, file);
+      const dest = path.join(cwd, file);
+      if (fs.existsSync(src) && !fs.existsSync(dest)) {
+        console.log(`  Adding ${file}`);
+        fs.copyFileSync(src, dest);
+      }
     }
 
     console.log('');
@@ -208,4 +270,4 @@ async function update() {
   }
 }
 
-module.exports = { update };
+module.exports = { update, updateSteering, REMOVED_PATHS, MANAGED_STEERING_HASHES };

package/src/commands/update.test.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const { updateSteering, REMOVED_PATHS, MANAGED_STEERING_HASHES } = require('./update');
+
+const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+function tmpProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bw-update-test-'));
+  const src = path.join(root, 'src');
+  const dest = path.join(root, 'dest');
+  fs.mkdirSync(src, { recursive: true });
+  fs.mkdirSync(dest, { recursive: true });
+  return { root, src, dest };
+}
+
+test('copies a shipped steering file that is absent locally', () => {
+  const { src, dest } = tmpProject();
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+
+  const { updated, preserved } = updateSteering(src, dest, {});
+
+  assert.deepStrictEqual(updated, ['philosophy.md']);
+  assert.deepStrictEqual(preserved, []);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'philosophy.md'), 'utf8'), 'NEW philosophy');
+});
+
+test('overwrites an unmodified shipped file (hash match) with the latest', () => {
+  const { src, dest } = tmpProject();
+  const oldContent = 'OLD philosophy';
+  fs.writeFileSync(path.join(dest, 'philosophy.md'), oldContent);
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+
+  const managed = { 'philosophy.md': new Set([sha256(oldContent)]) };
+  const { updated, preserved } = updateSteering(src, dest, managed);
+
+  assert.deepStrictEqual(updated, ['philosophy.md']);
+  assert.deepStrictEqual(preserved, []);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'philosophy.md'), 'utf8'), 'NEW philosophy');
+});
+
+test('preserves a customized steering file (hash not in the managed set)', () => {
+  const { src, dest } = tmpProject();
+  const customContent = 'CUSTOM org philosophy';
+  fs.writeFileSync(path.join(dest, 'philosophy.md'), customContent);
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+
+  // managed set only knows some other (shipped) hash, not the custom content
+  const managed = { 'philosophy.md': new Set([sha256('some shipped version')]) };
+  const { updated, preserved } = updateSteering(src, dest, managed);
+
+  assert.deepStrictEqual(updated, []);
+  assert.deepStrictEqual(preserved, ['philosophy.md']);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'philosophy.md'), 'utf8'), customContent);
+});
+
+test('never touches an org steering file that Buildwright does not ship', () => {
+  const { src, dest } = tmpProject();
+  // Buildwright ships only philosophy.md
+  fs.writeFileSync(path.join(src, 'philosophy.md'), 'NEW philosophy');
+  // org injected its own doc at a colliding-style path
+  const orgDoc = 'org quality gates';
+  fs.writeFileSync(path.join(dest, 'quality-gates.md'), orgDoc);
+
+  updateSteering(src, dest, MANAGED_STEERING_HASHES);
+
+  assert.strictEqual(fs.existsSync(path.join(dest, 'quality-gates.md')), true);
+  assert.strictEqual(fs.readFileSync(path.join(dest, 'quality-gates.md'), 'utf8'), orgDoc);
+});
+
+test('REMOVED_PATHS no longer deletes org-injected steering docs', () => {
+  assert.ok(!REMOVED_PATHS.includes('.buildwright/steering/quality-gates.md'));
+  assert.ok(!REMOVED_PATHS.includes('.buildwright/steering/naming-conventions.md'));
+  assert.ok(!REMOVED_PATHS.includes('.buildwright/steering/engineering-philosophy.md'));
+});
+
+test('REMOVED_PATHS still cleans up non-steering legacy paths', () => {
+  assert.ok(REMOVED_PATHS.includes('.buildwright/commands/bw-quick.md'));
+  assert.ok(REMOVED_PATHS.includes('.buildwright/agents/architect.md'));
+});

package/templates/.buildwright/agents/README.md

@@ -1,9 +1,27 @@
 # Agent Personas
 
-This directory contains reusable review personas. They are prompt instructions,
-not separate runtimes.
+This directory contains reusable review personas. Each file is a valid agent
+definition (with `name`/`description` frontmatter) so the tools that expect a
+subagent registry — Claude Code (`.claude/agents/`, `~/.claude/agents/`),
+OpenCode (`.opencode/agents/`) — load them cleanly. They are still adopted
+**inline** by the commands below, not spawned as separate orchestration runtimes;
+Buildwright is not a multi-agent framework.
 
 | Agent | File | Used By | Purpose |
 |-------|------|---------|---------|
 | Staff Engineer | `staff-engineer.md` | `/bw-work`, `/bw-ship` | Spec and code review with confidence scoring and high-signal findings |
 | Security Engineer | `security-engineer.md` | `/bw-work`, `/bw-ship` | OWASP Top 10, secrets, auth, injection, dependency review |
+
+## How they are triggered
+
+The reviews run automatically inside the command flows — there is no separate
+step to invoke:
+
+- `/bw-work` — Phase 7 (Security Review) and Phase 8 (Code Review) run after the
+  implementation passes its verification gates, before commit.
+- `/bw-ship` — Step 2 (Security Review) and Step 3 (Code Review) run as part of
+  the ship pipeline, before push/PR.
+
+At each of those phases the command adopts the matching persona — reading it from
+the project's `.buildwright/agents/<name>.md`, or from `~/.claude/agents/<name>.md`
+for a global install without a project `.buildwright/`.

package/templates/.buildwright/agents/security-engineer.md

@@ -1,3 +1,8 @@
+---
+name: security-engineer
+description: Security review persona — OWASP Top 10, secrets, authentication/authorization, injection, and dependency risks. Used by /bw-work and /bw-ship.
+---
+
 # Security Engineer Agent
 
 You are a **Security Engineer** specialized in application security with expertise in OWASP, secure coding, and vulnerability assessment.

package/templates/.buildwright/agents/staff-engineer.md

@@ -1,3 +1,8 @@
+---
+name: staff-engineer
+description: Code and spec review persona — logic errors, edge cases, error handling, pattern fit, complexity, and missing tests/docs, with confidence scoring and high-signal findings. Used by /bw-work and /bw-ship.
+---
+
 # Staff Engineer Agent
 
 You are a **Staff Engineer** with 15+ years of experience building production systems at scale.

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

@@ -85,7 +85,9 @@ If FAIL after retries:
 
 ## Step 2: Security Review — No retry (needs human judgment)
 
-Adopt Security Engineer persona from `.buildwright/agents/security-engineer.md`.
+Adopt the Security Engineer persona from `.buildwright/agents/security-engineer.md`.
+For a global install in a project without `.buildwright/`, read it from
+`~/.claude/agents/security-engineer.md` instead.
 
 ### 2.1 Determine Scope
 ```bash
@@ -142,7 +144,9 @@ If CRITICAL VULNERABILITIES:
 
 ## Step 3: Code Review — No retry (architectural decisions)
 
-Adopt Staff Engineer persona from `.buildwright/agents/staff-engineer.md`.
+Adopt the Staff Engineer persona from `.buildwright/agents/staff-engineer.md`.
+For a global install in a project without `.buildwright/`, read it from
+`~/.claude/agents/staff-engineer.md` instead.
 
 ### 3.1 Determine Scope
 ```bash

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

@@ -112,7 +112,9 @@ gate fails, fix and retry up to `BUILDWRIGHT_AGENT_RETRIES` times, default 2.
 
 ## Phase 7: Security Review
 
-Adopt `.buildwright/agents/security-engineer.md`. Review the changed diff for:
+Adopt the Security Engineer persona from `.buildwright/agents/security-engineer.md`
+(or `~/.claude/agents/security-engineer.md` for a global install without a project
+`.buildwright/`). Review the changed diff for:
 - Secrets
 - Dependency vulnerabilities, if tooling exists
 - Input validation and authorization
@@ -123,7 +125,9 @@ Stop on critical vulnerabilities.
 
 ## Phase 8: Code Review
 
-Adopt `.buildwright/agents/staff-engineer.md`. Review the changed diff for:
+Adopt the Staff Engineer persona from `.buildwright/agents/staff-engineer.md`
+(or `~/.claude/agents/staff-engineer.md` for a global install without a project
+`.buildwright/`). Review the changed diff for:
 - Logic errors and missed edge cases
 - Error handling
 - Pattern fit and unnecessary complexity

package/templates/AGENTS.md

@@ -0,0 +1,126 @@
+# Buildwright Development
+
+## Mission
+
+Agent-first disciplined development. Humans approve intent when needed; agents
+understand, test, implement, document, verify, review, and ship.
+
+## Steering Documents
+
+At the start of every session, recursively discover and read all `.md` files
+under `.buildwright/steering/`. Use:
+
+```bash
+find .buildwright/steering -type f -name "*.md" | sort
+```
+
+The default steering file is `philosophy.md`.
+
+Also recursively read all `.md` files under `.buildwright/codebase/` if that
+directory exists. These are codebase analysis docs generated by `/bw-analyse`.
+
+Do not assume a fixed set of project steering files. `tech.md` and `product.md`
+are created only when Buildwright has real project-specific content.
+
+## Project Structure
+
+`.buildwright/` and this `AGENTS.md` are the canonical, committed configuration.
+Tool-specific directories are generated from `.buildwright/` by `make sync` and
+gitignored:
+
+```
+.buildwright/
+  agents/               # Staff Engineer, Security Engineer
+  codebase/             # Generated by /bw-analyse
+  commands/             # bw-work, bw-plan, bw-verify, bw-ship, bw-analyse
+  steering/             # philosophy.md plus lazy-created tech.md/product.md
+
+AGENTS.md               # Canonical agent instructions (this file)
+CLAUDE.md               # Pointer stub → AGENTS.md
+.claude/                # Generated by make sync
+.opencode/              # Generated by make sync
+.cursor/rules/          # Generated by make sync
+```
+
+After cloning or editing `.buildwright/`, run `make sync`.
+
+## Commands
+
+Use the smallest command that matches the intent:
+
+1. `/bw-plan` — think/research only; no code changes, commits, or PRs.
+2. `/bw-work` — implement bug fixes, refactors, and features.
+3. `/bw-verify` — run typecheck, lint, test, and build gates.
+4. `/bw-ship` — verify, security review, code review, push, and PR.
+5. `/bw-analyse` — analyse brownfield codebases and write `.buildwright/codebase/` docs.
+
+## Command Discovery
+
+Run once per session and cache the result.
+
+1. Read `.buildwright/steering/tech.md` if it exists. If it has real commands,
+   use them.
+2. Otherwise auto-detect from project files in priority order:
+   `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `setup.py`,
+   `requirements.txt`, `Makefile`.
+3. Derive typecheck, lint, test, build, and dev commands. Mark unavailable
+   gates as `SKIP`.
+4. Write discovered commands to `.buildwright/steering/tech.md`.
+5. If still ambiguous, ask for the missing commands.
+
+## Operating Mode
+
+- Execute autonomously unless information is genuinely missing.
+- Verify your own work through tests and checks.
+- Commit only after verification passes.
+- Stop only when genuinely blocked.
+
+`BUILDWRIGHT_AUTO_APPROVE=true` means autonomous mode. If a step fails after
+retries, commit completed work, push, create a PR with failure details, and
+exit non-zero. In interactive mode (`BUILDWRIGHT_AUTO_APPROVE=false`), stop and
+report the blocker.
+
+## Verification Loop
+
+Before every commit, run discovered gates:
+
+1. Typecheck
+2. Lint
+3. Test
+4. Build
+
+Skip only gates that are unavailable for the stack. If a required step fails,
+fix and retry up to `BUILDWRIGHT_AGENT_RETRIES` times, default 2.
+
+## Documentation Discipline
+
+Documentation is part of done.
+
+Before every commit, update affected README, docs, command text, API docs,
+examples, changelog, or generated user-facing docs. If no docs need updating,
+say why in the final report.
+
+## Git Rules
+
+- Atomic commits: only commit files you changed.
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`.
+- Never edit `.env` files.
+- Never run destructive git operations without explicit instruction.
+- Never use `git stash`.
+- `.buildwright/` and the root `AGENTS.md` are canonical and committed.
+  `CLAUDE.md` is a committed pointer stub. Do not commit generated `.claude/`,
+  `.opencode/`, `.cursor/rules/`, or `skills/`.
+- After editing `.buildwright/`, run `make sync`.
+
+## Philosophy
+
+Always apply `.buildwright/steering/philosophy.md`: KISS, YAGNI, DRY, boring
+technology, fail fast, Red -> Green -> Refactor, and documentation discipline.
+
+## Self-Improvement
+
+When you discover a reusable pattern or gotcha, add it below.
+
+## Learned Patterns
+
+<!-- Agent adds entries here as it learns -->

package/templates/CLAUDE.md

@@ -1,123 +1,7 @@
-# Buildwright Development
+# Buildwright
 
-## Mission
+Project instructions for all AI assistants live in **AGENTS.md** at the repo
+root. Read that file.
 
-Agent-first disciplined development. Humans approve intent when needed; agents
-understand, test, implement, document, verify, review, and ship.
-
-## Steering Documents
-
-At the start of every session, recursively discover and read all `.md` files
-under `.buildwright/steering/`. Use:
-
-```bash
-find .buildwright/steering -type f -name "*.md" | sort
-```
-
-The default steering file is `philosophy.md`.
-
-Also recursively read all `.md` files under `.buildwright/codebase/` if that
-directory exists. These are codebase analysis docs generated by `/bw-analyse`.
-
-Do not assume a fixed set of project steering files. `tech.md` and `product.md`
-are created only when Buildwright has real project-specific content.
-
-## Project Structure
-
-`.buildwright/` is the canonical configuration directory committed to git.
-Tool-specific directories are generated from it and gitignored:
-
-```
-.buildwright/
-  agents/               # Staff Engineer, Security Engineer
-  codebase/             # Generated by /bw-analyse
-  commands/             # bw-work, bw-plan, bw-verify, bw-ship, bw-analyse
-  steering/             # philosophy.md plus lazy-created tech.md/product.md
-
-.claude/                # Generated by make sync
-.opencode/              # Generated by make sync
-.cursor/rules/          # Generated by make sync
-AGENTS.md               # Generated by make sync
-```
-
-After cloning or editing `.buildwright/`, run `make sync`.
-
-## Commands
-
-Use the smallest command that matches the intent:
-
-1. `/bw-plan` — think/research only; no code changes, commits, or PRs.
-2. `/bw-work` — implement bug fixes, refactors, and features.
-3. `/bw-verify` — run typecheck, lint, test, and build gates.
-4. `/bw-ship` — verify, security review, code review, push, and PR.
-5. `/bw-analyse` — analyse brownfield codebases and write `.buildwright/codebase/` docs.
-
-## Command Discovery
-
-Run once per session and cache the result.
-
-1. Read `.buildwright/steering/tech.md` if it exists. If it has real commands,
-   use them.
-2. Otherwise auto-detect from project files in priority order:
-   `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `setup.py`,
-   `requirements.txt`, `Makefile`.
-3. Derive typecheck, lint, test, build, and dev commands. Mark unavailable
-   gates as `SKIP`.
-4. Write discovered commands to `.buildwright/steering/tech.md`.
-5. If still ambiguous, ask for the missing commands.
-
-## Operating Mode
-
-- Execute autonomously unless information is genuinely missing.
-- Verify your own work through tests and checks.
-- Commit only after verification passes.
-- Stop only when genuinely blocked.
-
-`BUILDWRIGHT_AUTO_APPROVE=true` means autonomous mode. If a step fails after
-retries, commit completed work, push, create a PR with failure details, and
-exit non-zero. In interactive mode (`BUILDWRIGHT_AUTO_APPROVE=false`), stop and
-report the blocker.
-
-## Verification Loop
-
-Before every commit, run discovered gates:
-
-1. Typecheck
-2. Lint
-3. Test
-4. Build
-
-Skip only gates that are unavailable for the stack. If a required step fails,
-fix and retry up to `BUILDWRIGHT_AGENT_RETRIES` times, default 2.
-
-## Documentation Discipline
-
-Documentation is part of done.
-
-Before every commit, update affected README, docs, command text, API docs,
-examples, changelog, or generated user-facing docs. If no docs need updating,
-say why in the final report.
-
-## Git Rules
-
-- Atomic commits: only commit files you changed.
-- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`.
-- Never edit `.env` files.
-- Never run destructive git operations without explicit instruction.
-- Never use `git stash`.
-- Only `.buildwright/` is canonical. Do not commit generated `.claude/`,
-  `.opencode/`, `.cursor/rules/`, `skills/`, or `AGENTS.md`.
-- After editing `.buildwright/`, run `make sync`.
-
-## Philosophy
-
-Always apply `.buildwright/steering/philosophy.md`: KISS, YAGNI, DRY, boring
-technology, fail fast, Red -> Green -> Refactor, and documentation discipline.
-
-## Self-Improvement
-
-When you discover a reusable pattern or gotcha, add it below.
-
-## Learned Patterns
-
-<!-- Agent adds entries here as it learns -->
+`AGENTS.md` is the single source of truth — Claude Code, Codex, OpenCode, and
+Cursor all consume it.

package/templates/Makefile

@@ -1,4 +1,4 @@
-.PHONY: dist clean sync sync-check cursor opencode openclaw codex validate install-hooks uninstall-hooks bump release test-cli
+.PHONY: dist clean sync sync-check cursor claude opencode openclaw codex global validate install-hooks uninstall-hooks bump release test-cli
 
 # ============================================================================
 # Sync — Generate .claude/, .opencode/, .cursor/rules/ from .buildwright/ (canonical)
@@ -21,12 +21,27 @@ sync-check:
 dist: sync
 	@echo "dist/buildwright/ ready — upload this folder to ClawHub"
 
+# ============================================================================
+# Global install — make the workflow available in every project, per tool.
+# Each target installs into a user-level (~/...) location. `make global` runs
+# them all. Project-specific steering still comes from each project's
+# .buildwright/ (created by `buildwright init`).
+# ============================================================================
+
 # 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 as 'Intelligent'."
 
+# Claude Code — install commands + agents to user global config
+claude: sync
+	@mkdir -p ~/.claude/commands ~/.claude/agents
+	@cp .claude/commands/bw-*.md ~/.claude/commands/
+	@cp .claude/agents/staff-engineer.md .claude/agents/security-engineer.md ~/.claude/agents/
+	@echo "Installed Buildwright commands + agents to ~/.claude/"
+	@echo "Restart Claude Code to discover /bw-* commands globally."
+
 # OpenCode — install skill to user global config
 opencode: sync
 	@mkdir -p ~/.config/opencode/skills/buildwright
@@ -46,6 +61,10 @@ codex: sync
 	@echo "Installed to ~/.agents/skills/buildwright"
 	@echo "Restart Codex to discover Buildwright skills."
 
+# Global — install across all supported tools in one step
+global: claude codex opencode openclaw
+	@echo "Buildwright installed globally for Claude Code, Codex, OpenCode, and OpenClaw."
+
 # ============================================================================
 # Validate SKILL.md against Agent Skills spec (agentskills.io)
 # ============================================================================

package/templates/scripts/sync-agents.sh

@@ -12,9 +12,11 @@
 #   .cursor/rules/steering/  ← .mdc files with alwaysApply: true
 #   .cursor/rules/commands/  ← .mdc files with alwaysApply: false
 #   .cursor/rules/agents/    ← .mdc files with alwaysApply: false
-#   AGENTS.md                ← CLAUDE.md with OpenCode header prepended
 #   dist/buildwright/        ← SKILL.md packaged for ClawHub
 #
+# Note: AGENTS.md (canonical, committed) and CLAUDE.md (pointer stub) are NOT
+# generated — they are hand-maintained root files.
+#
 # Usage: scripts/sync-agents.sh [--check]
 #   --check: Verify sync without modifying files (exit 1 if out of sync)
 
@@ -129,9 +131,23 @@ set_cursor_frontmatter() {
   esac
 }
 
+# strip_frontmatter FILE
+# Emits FILE's body with a leading YAML frontmatter block (--- ... ---) removed.
+# Files without frontmatter are emitted unchanged. Cursor .mdc files carry their
+# own frontmatter, so the source's name/description block must not leak into the
+# rule body.
+strip_frontmatter() {
+  awk '
+    NR==1 && $0=="---" { in_fm=1; next }
+    in_fm && $0=="---" { in_fm=0; next }
+    !in_fm             { print }
+  ' "$1"
+}
+
 # sync_cursor_dir SRC DST_SUBDIR PRESET
 # Converts .md files in SRC to .mdc files in .cursor/rules/DST_SUBDIR,
 # prepending YAML frontmatter and rewriting @.buildwright/ → @.cursor/rules/.
+# The source's own frontmatter (if any) is stripped first.
 # Skips README and TEMPLATE files.
 sync_cursor_dir() {
   local src="$1"
@@ -178,7 +194,7 @@ sync_cursor_dir() {
           printf '%s\n' "globs: []"
           printf 'alwaysApply: %s\n' "$CURSOR_ALWAYS_APPLY"
           printf '%s\n' "---"
-          sed 's|@\.buildwright/|@.cursor/rules/|g' "$src_file"
+          strip_frontmatter "$src_file" | sed 's|@\.buildwright/|@.cursor/rules/|g'
         } > "$tmpfile"
         if ! diff -q "$dst_file" "$tmpfile" > /dev/null 2>&1; then
           echo "OUT OF SYNC: $dst_file"
@@ -194,7 +210,7 @@ sync_cursor_dir() {
         printf '%s\n' "globs: []"
         printf 'alwaysApply: %s\n' "$CURSOR_ALWAYS_APPLY"
         printf '%s\n' "---"
-        sed 's|@\.buildwright/|@.cursor/rules/|g' "$src_file"
+        strip_frontmatter "$src_file" | sed 's|@\.buildwright/|@.cursor/rules/|g'
       } > "$dst_file"
     fi
   done < <(find "$src" -type f -name "*.md" | sort)
@@ -230,40 +246,7 @@ sync_dir ".buildwright/steering"  ".opencode/steering"
 sync_dir ".buildwright/codebase"  ".opencode/codebase"
 
 # ============================================================================
-# 3. CLAUDE.md → AGENTS.md
-# ============================================================================
-
-generate_agents_md() {
-  local target="$1"
-  printf '%s\n' "---" \
-    "# OpenCode agent instructions" \
-    "# Auto-generated from CLAUDE.md — do not edit directly" \
-    "# Run: scripts/sync-agents.sh to regenerate" \
-    "---" \
-    "" > "$target"
-  cat CLAUDE.md >> "$target"
-}
-
-if [ "$CHECK_ONLY" = true ]; then
-  if [ ! -f "AGENTS.md" ]; then
-    echo "MISSING: AGENTS.md (should be generated from CLAUDE.md)"
-    SYNC_NEEDED=true
-  else
-    TMPFILE=$(mktemp)
-    generate_agents_md "$TMPFILE"
-    if ! diff -q "AGENTS.md" "$TMPFILE" > /dev/null 2>&1; then
-      echo "OUT OF SYNC: AGENTS.md differs from CLAUDE.md"
-      SYNC_NEEDED=true
-    fi
-    rm -f "$TMPFILE"
-  fi
-else
-  generate_agents_md "AGENTS.md"
-  echo "  generated AGENTS.md from CLAUDE.md"
-fi
-
-# ============================================================================
-# 4. .buildwright/ → .cursor/rules/ (convert to .mdc with frontmatter)
+# 3. .buildwright/ → .cursor/rules/ (convert to .mdc with frontmatter)
 # ============================================================================
 
 sync_cursor_dir ".buildwright/steering"  "steering"  "steering"
@@ -272,7 +255,7 @@ sync_cursor_dir ".buildwright/commands"  "commands"  "command"
 sync_cursor_dir ".buildwright/agents"    "agents"    "agent"
 
 # ============================================================================
-# 5. .buildwright/commands/ → skills/ (Codex CLI skill discovery)
+# 4. .buildwright/commands/ → skills/ (Codex CLI skill discovery)
 # ============================================================================
 
 if [ "$CHECK_ONLY" = false ]; then
@@ -287,7 +270,7 @@ if [ "$CHECK_ONLY" = false ]; then
 fi
 
 # ============================================================================
-# 6. Package for ClawHub (dist/)
+# 5. Package for ClawHub (dist/)
 # ============================================================================
 
 if [ "$CHECK_ONLY" = false ] && [ -f "SKILL.md" ]; then
@@ -297,7 +280,7 @@ if [ "$CHECK_ONLY" = false ] && [ -f "SKILL.md" ]; then
 fi
 
 # ============================================================================
-# 7. README.md → cli/README.md (single source of truth for npm package page)
+# 6. README.md → cli/README.md (single source of truth for npm package page)
 # Only runs in the buildwright repo itself, which has a cli/ directory.
 # Generated services do not have cli/ and must not fail here.
 # ============================================================================
@@ -326,7 +309,6 @@ else
   echo "  .buildwright/ → .claude/         (paths rewritten)"
   echo "  .buildwright/ → .opencode/       (paths rewritten)"
   echo "  .buildwright/ → .cursor/rules/   (.mdc with frontmatter)"
-  echo "  CLAUDE.md     → AGENTS.md"
   echo "  SKILL.md      → dist/buildwright/SKILL.md"
   echo "  .buildwright/commands/ → skills/          (Codex CLI skill discovery)"
   if [ -d "cli" ]; then