buildwright 0.0.3

package/README.md

@@ -0,0 +1,82 @@
+# buildwright
+
+Agent-first autonomous development workflow. Ship code you don't read.
+
+## Install
+
+```bash
+npm install -g buildwright
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# Navigate to your project
+cd my-project
+git init  # if not already a git repo
+
+# Set up Buildwright
+buildwright init
+
+# Customize for your project
+nano .buildwright/steering/product.md   # add product context
+nano .buildwright/steering/tech.md      # add tech stack + commands
+
+# Start building
+claude
+> /bw-new-feature "Add user authentication"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `buildwright init` | Set up Buildwright in the current project |
+| `buildwright update` | Update commands/agents/claws from GitHub (preserves your steering docs) |
+| `buildwright sync` | Re-sync `.buildwright/` to `.claude/`, `.opencode/`, `.cursor/rules/` |
+
+## What `init` Does
+
+1. Copies all Buildwright templates to your project:
+   - `.buildwright/` — canonical config (agents, claws, commands, steering)
+   - `scripts/` — sync and hook scripts
+   - `Makefile`, `CLAUDE.md`, `BUILDWRIGHT.md`
+2. Makes scripts executable
+3. Runs `make sync` to generate `.claude/`, `.opencode/`, `.cursor/rules/`
+4. Installs git hooks for auto-sync on `.buildwright/` changes
+
+## What `update` Does
+
+Downloads the latest release from GitHub and updates:
+- `.buildwright/commands/` — slash command definitions
+- `.buildwright/agents/` — agent personas
+- `.buildwright/claws/` — domain specialist prompts
+- `CLAUDE.md` — agent instructions
+
+**Preserves** your customizations in `.buildwright/steering/` (product.md, tech.md, etc.).
+
+## Slash Commands (inside AI editors)
+
+| 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 (DB + API + UI) |
+| `/bw-ship` | Quality gates + push + PR |
+| `/bw-verify` | Quick typecheck/lint/test/build |
+| `/bw-analyse` | Analyse brownfield codebase |
+| `/bw-help` | Show all commands |
+
+## Offline Support
+
+All templates are bundled in the npm package — `buildwright init` works without internet access after installation. Use `buildwright update` to pull the latest templates from GitHub.
+
+## More Information
+
+See the [full documentation](https://github.com/raunakkathuria/buildwright) on GitHub.
+
+## License
+
+MIT

package/bin/buildwright.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const { init } = require('../src/commands/init');
+const { update } = require('../src/commands/update');
+const { sync } = require('../src/commands/sync');
+
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('buildwright')
+  .description('Agent-first autonomous development workflow')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Set up Buildwright in the current project')
+  .action(() => {
+    init();
+  });
+
+program
+  .command('update')
+  .description('Update commands, agents, and claws from GitHub (preserves steering docs)')
+  .action(async () => {
+    await update();
+  });
+
+program
+  .command('sync')
+  .description('Re-sync .buildwright/ to .claude/, .opencode/, and .cursor/rules/')
+  .action(() => {
+    sync();
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "buildwright",
+  "version": "0.0.3",
+  "description": "Agent-first autonomous development workflow. Ship code you don't read.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "buildwright": "./bin/buildwright.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack.js",
+    "postpack": "node scripts/postpack.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isGitRepo, isBuildwrightInstalled } = require('../utils/detect');
+const { copyDir, chmodScripts } = require('../utils/copy-files');
+const { runSync, runInstallHooks } = require('../utils/run-script');
+
+// ANSI colours
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+function init() {
+  const cwd = process.cwd();
+
+  // 1. Check git repo
+  const hasGit = isGitRepo(cwd);
+  if (!hasGit) {
+    console.log(`${YELLOW}Note: No git repository detected. Git hooks will be skipped.${RESET}`);
+    console.log(`Run ${BOLD}git init && make install-hooks${RESET} later to enable auto-sync hooks.\n`);
+  }
+
+  // 2. Check for existing installation
+  if (isBuildwrightInstalled(cwd)) {
+    console.log(`${YELLOW}Buildwright is already installed in this directory.${RESET}`);
+    console.log(`To update commands/agents/claws to the latest version, run: ${BOLD}buildwright update${RESET}`);
+    process.exit(1);
+  }
+
+  console.log(`${BOLD}Setting up Buildwright in ${cwd}...${RESET}\n`);
+
+  // 3. Copy templates → cwd
+  const templatesDir = path.join(__dirname, '..', '..', 'templates');
+  if (!fs.existsSync(templatesDir)) {
+    console.error('Error: templates directory not found in npm package. Reinstall buildwright.');
+    process.exit(1);
+  }
+
+  const templateEntries = fs.readdirSync(templatesDir);
+  for (const entry of templateEntries) {
+    const src = path.join(templatesDir, entry);
+    const dest = path.join(cwd, entry);
+    const stat = fs.statSync(fs.realpathSync(src));
+
+    if (stat.isDirectory()) {
+      console.log(`  Copying ${entry}/`);
+      copyDir(src, dest);
+    } else {
+      console.log(`  Copying ${entry}`);
+      fs.copyFileSync(fs.realpathSync(src), dest);
+    }
+  }
+
+  // 4. chmod +x scripts
+  chmodScripts(path.join(cwd, 'scripts'));
+  console.log('');
+
+  // 5. Run make sync
+  console.log(`${CYAN}Running make sync...${RESET}`);
+  const syncOk = runSync(cwd);
+  if (!syncOk) {
+    console.log(`${YELLOW}Warning: make sync failed. Run ${BOLD}make sync${RESET}${YELLOW} manually after setup.${RESET}`);
+  }
+  console.log('');
+
+  // 6. Run make install-hooks (only if inside a git repo)
+  if (hasGit) {
+    console.log(`${CYAN}Installing git hooks...${RESET}`);
+    const hooksOk = runInstallHooks(cwd);
+    if (!hooksOk) {
+      console.log(`${YELLOW}Warning: hook installation failed. Run ${BOLD}make install-hooks${RESET}${YELLOW} manually.${RESET}`);
+    }
+    console.log('');
+  }
+
+  // 7. Success message
+  console.log(`${GREEN}${BOLD}Buildwright is ready!${RESET}\n`);
+  console.log('Next steps:');
+  console.log(`  1. Edit ${BOLD}.buildwright/steering/product.md${RESET} — add your product context`);
+  console.log(`  2. Edit ${BOLD}.buildwright/steering/tech.md${RESET}  — add your tech stack`);
+  console.log(`  3. Open your AI editor and run ${BOLD}/bw-new-feature "your feature"${RESET}\n`);
+  console.log(`For help: ${BOLD}buildwright --help${RESET}`);
+}
+
+module.exports = { init };

package/src/commands/sync.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const { isBuildwrightInstalled } = require('../utils/detect');
+const { runSync } = require('../utils/run-script');
+
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+function sync() {
+  const cwd = process.cwd();
+
+  if (!isBuildwrightInstalled(cwd)) {
+    console.log(`${YELLOW}Buildwright is not installed in this directory.${RESET}`);
+    console.log(`Run ${BOLD}buildwright init${RESET} first.`);
+    process.exit(1);
+  }
+
+  console.log(`${CYAN}Syncing .buildwright/ to tool configs...${RESET}`);
+  const ok = runSync(cwd);
+
+  if (ok) {
+    console.log(`${GREEN}${BOLD}Sync complete!${RESET}`);
+    console.log('.claude/, .opencode/, .cursor/rules/, and AGENTS.md are up to date.');
+  } else {
+    console.log(`${YELLOW}Sync failed. Make sure make is installed or run scripts/sync-agents.sh directly.${RESET}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { sync };

package/src/commands/update.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { execSync } = require('child_process');
+const { isBuildwrightInstalled } = require('../utils/detect');
+const { copyDir } = require('../utils/copy-files');
+const { runSync } = require('../utils/run-script');
+
+// ANSI colours
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+const GITHUB_REPO = 'raunakkathuria/buildwright';
+const UPDATE_DIRS = ['commands', 'agents', 'claws'];
+
+/**
+ * Download a URL following redirects. Returns a Buffer.
+ */
+function download(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'buildwright-cli' } }, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        return download(res.headers.location).then(resolve).catch(reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      const chunks = [];
+      res.on('data', chunk => chunks.push(chunk));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Download and extract the GitHub tarball to a temp directory.
+ * Returns the path to the extracted root.
+ */
+async function downloadAndExtract() {
+  const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'buildwright-update-'));
+  const tarPath = path.join(tmpDir, 'buildwright.tar.gz');
+
+  console.log(`${CYAN}Downloading latest Buildwright from GitHub...${RESET}`);
+  const url = `https://api.github.com/repos/${GITHUB_REPO}/tarball/main`;
+  const data = await download(url);
+  fs.writeFileSync(tarPath, data);
+
+  console.log(`${CYAN}Extracting...${RESET}`);
+  execSync(`tar xzf "${tarPath}" -C "${tmpDir}"`, { stdio: 'pipe' });
+
+  // The tarball extracts to a directory like raunakkathuria-buildwright-<sha>/
+  const entries = fs.readdirSync(tmpDir).filter(e => e !== 'buildwright.tar.gz');
+  if (entries.length === 0) throw new Error('Tarball extraction produced no files');
+
+  const extractedRoot = path.join(tmpDir, entries[0]);
+  return { tmpDir, extractedRoot };
+}
+
+async function update() {
+  const cwd = process.cwd();
+
+  if (!isBuildwrightInstalled(cwd)) {
+    console.log(`${YELLOW}Buildwright is not installed in this directory.${RESET}`);
+    console.log(`Run ${BOLD}buildwright init${RESET} first.`);
+    process.exit(1);
+  }
+
+  console.log(`${BOLD}Updating Buildwright in ${cwd}...${RESET}\n`);
+  console.log(`Updating: ${UPDATE_DIRS.map(d => `.buildwright/${d}/`).join(', ')}`);
+  console.log(`Preserving: .buildwright/steering/ (your customizations)\n`);
+
+  let tmpDir;
+  try {
+    const result = await downloadAndExtract();
+    tmpDir = result.tmpDir;
+    const extractedRoot = result.extractedRoot;
+
+    const srcBuildwright = path.join(extractedRoot, '.buildwright');
+    if (!fs.existsSync(srcBuildwright)) {
+      throw new Error('Downloaded archive is missing .buildwright/ directory');
+    }
+
+    // Update only the specified directories
+    for (const dir of UPDATE_DIRS) {
+      const src = path.join(srcBuildwright, dir);
+      const dest = path.join(cwd, '.buildwright', dir);
+      if (!fs.existsSync(src)) {
+        console.log(`  ${YELLOW}Skipping ${dir}/ (not found in latest release)${RESET}`);
+        continue;
+      }
+      console.log(`  Updating .buildwright/${dir}/`);
+      // Remove old and replace
+      fs.rmSync(dest, { recursive: true, force: true });
+      copyDir(src, dest);
+    }
+
+    // Also update CLAUDE.md if it exists in the download
+    const srcClaude = path.join(extractedRoot, 'CLAUDE.md');
+    if (fs.existsSync(srcClaude)) {
+      console.log(`  Updating CLAUDE.md`);
+      fs.copyFileSync(srcClaude, path.join(cwd, 'CLAUDE.md'));
+    }
+
+    console.log('');
+
+    // Re-run sync
+    console.log(`${CYAN}Running make sync...${RESET}`);
+    const syncOk = runSync(cwd);
+    if (!syncOk) {
+      console.log(`${YELLOW}Warning: make sync failed. Run ${BOLD}make sync${RESET}${YELLOW} manually.${RESET}`);
+    }
+
+    console.log('');
+    console.log(`${GREEN}${BOLD}Update complete!${RESET}`);
+    console.log('commands, agents, and claws are now up to date.');
+    console.log('Your steering docs (.buildwright/steering/) are unchanged.\n');
+
+  } catch (err) {
+    console.error(`\nUpdate failed: ${err.message}`);
+    console.error(`You can update manually by downloading from: https://github.com/${GITHUB_REPO}`);
+    process.exit(1);
+  } finally {
+    if (tmpDir) {
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  }
+}
+
+module.exports = { update };

package/src/utils/copy-files.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Recursively copy src directory to dest directory.
+ * Resolves symlinks before copying so npm pack works correctly.
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @param {object} [opts]
+ * @param {string[]} [opts.skip] - Relative paths (from src) to skip
+ */
+function copyDir(src, dest, opts = {}) {
+  const skip = opts.skip || [];
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    const relativePath = path.relative(src, srcPath);
+
+    if (skip.some(s => relativePath === s || relativePath.startsWith(s + path.sep))) {
+      continue;
+    }
+
+    // Resolve symlinks
+    const realSrcPath = fs.realpathSync(srcPath);
+    const stat = fs.statSync(realSrcPath);
+
+    if (stat.isDirectory()) {
+      copyDir(realSrcPath, destPath, opts);
+    } else {
+      fs.copyFileSync(realSrcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Make all .sh files and hook scripts executable under a directory.
+ */
+function chmodScripts(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      chmodScripts(fullPath);
+    } else if (entry.name.endsWith('.sh') || !entry.name.includes('.')) {
+      // executable if .sh or no extension (hook scripts)
+      try {
+        fs.chmodSync(fullPath, 0o755);
+      } catch {
+        // ignore on platforms that don't support chmod
+      }
+    }
+  }
+}
+
+module.exports = { copyDir, chmodScripts };

package/src/utils/detect.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Check if current directory is a git repository.
+ * Walks up the directory tree looking for a .git directory.
+ */
+function isGitRepo(cwd) {
+  let dir = cwd;
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+
+/**
+ * Check if Buildwright is already installed in the given directory.
+ */
+function isBuildwrightInstalled(cwd) {
+  return fs.existsSync(path.join(cwd, '.buildwright'));
+}
+
+module.exports = { isGitRepo, isBuildwrightInstalled };

package/src/utils/run-script.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run a shell command synchronously in the given directory.
+ * Prints output as it runs. Returns true on success.
+ */
+function run(command, cwd) {
+  try {
+    execSync(command, { cwd, stdio: 'inherit' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run make sync or fall back to running sync-agents.sh directly.
+ * Returns true on success.
+ */
+function runSync(cwd) {
+  const makefile = path.join(cwd, 'Makefile');
+  if (fs.existsSync(makefile)) {
+    if (run('make sync', cwd)) return true;
+  }
+  const syncScript = path.join(cwd, 'scripts', 'sync-agents.sh');
+  if (fs.existsSync(syncScript)) {
+    chmodX(syncScript);
+    return run(`bash "${syncScript}"`, cwd);
+  }
+  return false;
+}
+
+/**
+ * Run make install-hooks or fall back to install-hooks.sh directly.
+ * Returns true on success.
+ */
+function runInstallHooks(cwd) {
+  const makefile = path.join(cwd, 'Makefile');
+  if (fs.existsSync(makefile)) {
+    if (run('make install-hooks', cwd)) return true;
+  }
+  const hooksScript = path.join(cwd, 'scripts', 'install-hooks.sh');
+  if (fs.existsSync(hooksScript)) {
+    chmodX(hooksScript);
+    return run(`bash "${hooksScript}"`, cwd);
+  }
+  return false;
+}
+
+/**
+ * Make a file executable.
+ */
+function chmodX(filePath) {
+  try {
+    fs.chmodSync(filePath, 0o755);
+  } catch {
+    // ignore
+  }
+}
+
+module.exports = { run, runSync, runInstallHooks, chmodX };

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

@@ -0,0 +1,53 @@
+# Agent Personas
+
+This directory contains reusable agent personas that commands can reference.
+
+## Available Agents
+
+| Agent | File | Used By | Key Capabilities |
+|-------|------|---------|-------------------|
+| Architect | `architect.md` | `/bw-claw` | Decomposes cross-domain work, defines interfaces, coordinates claws |
+| Staff Engineer | `staff-engineer.md` | `/bw-new-feature`, `/bw-ship` | Confidence scoring (>=80), HIGH SIGNAL criteria, false-positive exclusions |
+| Security Engineer | `security-engineer.md` | `/bw-ship` | Confidence scoring (>=0.8), exploit scenarios, hard exclusions |
+
+## Claw Architecture
+
+For domain-specialist agents (claws), see `.buildwright/claws/`.
+
+The Architect agent coordinates claws:
+```
+        Architect (Brain)
+             |
+   +---------+---------+
+   |         |         |
+ UI Claw  API Claw  DB Claw
+```
+
+## Adding New Agents
+
+1. Create a new file: `[role-name].md`
+2. Define:
+   - Mindset and expertise
+   - What they look for
+   - Output format
+   - Rules/guidelines
+3. Reference in commands via: `Read and adopt persona from .buildwright/agents/[role-name].md`
+
+## Planned Agents (Future)
+
+| Agent | Purpose |
+|-------|---------|
+| QA Engineer | Test coverage review, edge case identification |
+| Performance Engineer | Performance review, bottleneck identification |
+| DevOps Engineer | Infrastructure review, deployment concerns |
+| Database Engineer | Schema review, query optimization |
+| UX Engineer | API design review, developer experience |
+| Technical Writer | Documentation quality |
+
+## Agent Design Principles
+
+1. **Specific expertise** — Each agent has a focused domain
+2. **Consistent output** — Predictable format for parsing/automation
+3. **Actionable feedback** — Problems come with solutions
+4. **Severity levels** — Distinguish blocking from advisory
+5. **Context-aware** — Adapt to project type and risk level