buildwright 0.0.11 → 0.0.13

package/README.md

@@ -1,439 +1,140 @@
 # Buildwright
 
-**Ship code you don't read. Let automated systems be your reviewer.**
-
-An agent-first autonomous development workflow where humans approve specifications and agents handle everything else — implementation, testing, security review, code review, and shipping.
-
----
-
-## The Flow
-
-```mermaid
-flowchart TD
-      A["/bw-new-feature"] --> B{Greenfield?}
-      B -- Yes --> C[Ask product vision<br>Derive tech stack from vision]
-      C --> D
-      B -- No --> D["1. RESEARCH<br>Deep-read codebase"]
-      D --> E["1.5. RESOLVE AMBIGUITIES<br>Auto-decide or ask user<br>(BUILDWRIGHT_AUTO_APPROVE)"]
-      E --> F["2. PLAN<br>Generate spec"]
-      F --> G["3. VALIDATE<br>Staff Engineer review (auto)"]
-      G --> H["4. APPROVE<br>Human or auto<br>(BUILDWRIGHT_AUTO_APPROVE)"]
-      H --> I["5. BUILD<br>TDD per milestone<br>→ verify after each"]
-      I --> J["6.5 UPDATE DOCS<br>README · CHANGELOG · docs/"]
-      J --> K["7. SHIP"]
-      K --> L[Verify]
-      L --> M[Security]
-      M --> N[Review]
-      N --> O["PR Ready ✓"]
-
-      P["/bw-quick"] --> Q[Quick research]
-      Q --> R[Implement TDD]
-      R --> S[Verify]
-      S --> U[Security]
-      U --> V[Code Review]
-      V --> W[Update Docs]
-      W --> T["Commit Ready ✓"]
-```
-
-> If anything fails → commit completed work, push, PR with failure report, exit(1). No orphaned branches.
-
----
-
-## Greenfield Projects
+Buildwright is a lightweight engineering discipline layer for agent-led
+software work: understand, test, implement, document, verify, review, ship.
 
-Starting a new project? Buildwright handles it:
+It is not a multi-agent framework. It keeps a small command surface and stores
+only useful project context.
 
-```
-/bw-new-feature "Add product catalog with search"
+## Commands
 
-> "This looks like a new project. What is the product vision, and do you have
-> any tech constraints (team expertise, deployment environment, integrations,
-> compliance)?"
-E-commerce platform for handmade crafts. Team knows Python. Deploying to AWS Lambda.
+| Command | Purpose |
+|---------|---------|
+| `/bw-plan` | Think/research only; no code changes |
+| `/bw-work` | Implement bug fixes, refactors, and features |
+| `/bw-verify` | Run typecheck, lint, test, and build gates |
+| `/bw-ship` | Security review, code review, push, and PR |
+| `/bw-analyse` | Analyse a brownfield codebase and write context docs |
 
-> [AI generates steering docs + spec]
-> [Derives and presents tech stack for approval]
+## Workflow
 
-PROPOSED TECH STACK
-───────────────────
-[Stack derived from your product vision and constraints]
-Chosen because: [2-3 sentences linking requirements to stack]
-Alternatives considered: [brief list]
+Use `/bw-work` for implementation:
 
-Reply "approved" to proceed with this stack.
-Or adjust: "approved, but use PostgreSQL instead of DynamoDB"
+```text
+Understand -> Research -> Plan if needed -> Red -> Green -> Refactor -> Docs -> Verify -> Security -> Review -> Commit/Ship
 ```
 
-One question. One approval. Tech stack + spec reviewed together.
-
----
+Small tasks use lightweight research. Larger features produce
+`docs/specs/[feature]/research.md` and `docs/specs/[feature]/spec.md`.
+Cross-domain work uses a normal implementation plan; there is no separate
+multi-agent architecture.
 
-## Autonomous Mode
+TDD is explicit:
 
-Want fully autonomous operation? Skip human approval entirely:
+- Red: write a failing test for the bug or expected behavior.
+- Green: make the smallest passing implementation.
+- Refactor: improve structure while tests stay green.
 
-```bash
-# Set environment variable
-export BUILDWRIGHT_AUTO_APPROVE=true
+Documentation is part of done. Every user-facing change must update affected
+README, docs, command text, API docs, examples, or changelog. If no docs apply,
+the agent must say why.
 
-# Then run as usual
-/bw-new-feature "Add user authentication"
-```
+## Steering
 
-**What happens:**
-- Research, plan, validate still run (quality preserved)
-- Spec documents committed to git BEFORE implementation
-- No approval wait — proceeds directly to build
-- Full audit trail in version control
+Buildwright installs one default steering file:
 
+```text
+.buildwright/steering/philosophy.md
 ```
-docs(spec): add specification for user-auth
-
-- research.md: codebase analysis
-- spec.md: implementation plan
-- Validated by Staff Engineer agent
 
-Auto-approved: BUILDWRIGHT_AUTO_APPROVE=true
-```
+That file contains KISS, YAGNI, DRY, boring technology, fail-fast, TDD,
+documentation discipline, and financial-code rules.
 
-**Use autonomous mode when:**
-- You trust the workflow for routine features
-- Running in CI/CD pipelines
-- Batch processing multiple features
-- You want to review specs via git history instead of real-time
+Project-specific steering is created only when there is real content:
 
----
-
-## Quick Start
-
-### npm (Recommended)
-
-```bash
-npm install -g buildwright
-cd my-project && buildwright init
+```text
+.buildwright/steering/tech.md       # created after stack/command discovery
+.buildwright/steering/product.md    # created for greenfield or explicit product context
 ```
 
-Requires Node.js 18+. All templates are bundled — works offline after install. Run `buildwright update` to pull the latest commands/agents/claws from GitHub.
-
-### For Claude Code
+`/bw-analyse` writes deeper brownfield context to:
 
-```bash
-# Add to any project
-curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
-
-# Customize steering docs
-nano .buildwright/steering/product.md   # Your product context
-nano .buildwright/steering/tech.md      # Your tech stack
-
-# Start building
-claude
-> /bw-new-feature "Add user authentication with OAuth2"
+```text
+.buildwright/codebase/STACK.md
+.buildwright/codebase/ARCHITECTURE.md
+.buildwright/codebase/CONVENTIONS.md
+.buildwright/codebase/CONCERNS.md
 ```
 
-### For an existing clone
-
-```bash
-# After cloning the repo, generate tool-specific configs
-make sync
+## Install
 
-# This creates:
-#   .claude/        (commands, agents, claws, steering — from .buildwright/)
-#   .opencode/      (commands, agents, claws, steering — from .buildwright/)
-#   .cursor/rules/  (commands, agents, claws, steering — from .buildwright/)
-#   AGENTS.md       (from CLAUDE.md — for OpenCode compatibility)
-
-# Install git hooks to auto-sync on .buildwright/ changes
-make install-hooks
-```
-
-### For OpenClaw
-
-The recommended approach is to run the setup script, which installs the full workflow (commands, agents, claws, steering docs) into your project:
+### CLI
 
 ```bash
-curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
-make sync
+npm install -g buildwright
+cd your-project
+buildwright init
 ```
 
-Alternatively, install just the skill globally for reference across all projects:
+Then open your AI editor and run:
 
-```bash
-mkdir -p ~/.openclaw/skills/buildwright
-curl -s https://raw.githubusercontent.com/raunakkathuria/buildwright/main/SKILL.md > ~/.openclaw/skills/buildwright/SKILL.md
+```text
+/bw-work "your task"
 ```
 
-> **Note:** The global skill install provides buildwright's workflow guidance via SKILL.md. The slash commands (`/bw-new-feature`, `/bw-claw`, etc.) require the full project setup above.
-
-### For OpenCode
-
-Same as above — run the setup script for the full workflow:
+### From Source
 
 ```bash
-curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
+git clone https://github.com/raunakkathuria/buildwright.git
+cd buildwright
 make sync
 ```
 
-Or install the skill globally:
-
-```bash
-mkdir -p ~/.config/opencode/skills/buildwright
-curl -s https://raw.githubusercontent.com/raunakkathuria/buildwright/main/SKILL.md > ~/.config/opencode/skills/buildwright/SKILL.md
-```
-
-> **Note:** The global skill install provides buildwright's workflow guidance via SKILL.md. The slash commands require the full project setup.
-
-### For Cursor
-
-Same setup — run the setup script for the full workflow:
-
-```bash
-curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
-```
-
-Cursor rules are generated automatically in `.cursor/rules/` by the sync step. Open the project in Cursor — steering rules apply always, commands/agents/claws apply intelligently.
-
-### For Codex CLI
+## Project Layout
 
-Buildwright skills are discovered by Codex via `~/.agents/skills/`. After cloning:
+```text
+.buildwright/
+  agents/
+    staff-engineer.md
+    security-engineer.md
+  commands/
+    bw-analyse.md
+    bw-plan.md
+    bw-ship.md
+    bw-verify.md
+    bw-work.md
+  steering/
+    philosophy.md
 
-```bash
-cd ~/.codex/buildwright && make codex
-# Creates: ~/.agents/skills/buildwright → skills/
+.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
 ```
 
-Or follow the detailed guide in [`.codex/INSTALL.md`](.codex/INSTALL.md).
-
-Each `bw-*` command is available as a Codex skill. `AGENTS.md` (generated by `make sync`) is also read automatically by Codex at the project level.
-
----
-
-## When to Use What
+`.buildwright/` is canonical. Generated tool directories are gitignored.
 
-| Scenario | Approach | Why |
-|----------|----------|-----|
-| New feature, unclear scope | `/bw-new-feature` | Research prevents building the wrong thing |
-| New feature, clear scope | `/bw-new-feature` | Spec creates audit trail + validation |
-| Bug fix | `/bw-quick` | Fast path with full quality gates |
-| Small task (< 2 hrs) | `/bw-quick` | Lightweight planning, full quality gates |
-| Config change | `/bw-quick` | Quick path with security scan + code review |
-| Refactor, clear scope | `/bw-quick` | You already know what to change |
-| Refactor, unclear scope | `/bw-new-feature` | Research phase prevents breaking things |
-| Unfamiliar / brownfield codebase | `/bw-analyse` | Generates stack, architecture, conventions, and concerns docs so every session starts with real context |
-| Greenfield project | `/bw-new-feature` | Auto-generates steering docs + tech stack |
-| Prototype / spike | Just code it | Ceremony kills exploration speed |
-| One-off script | Just code it | No need for spec, review, or CI |
-| Learning / experimenting | Just code it | Pipeline adds friction to discovery |
+## Development
 
----
-
-## Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/bw-analyse` | Analyse codebase: writes stack, architecture, conventions, concerns to `.buildwright/codebase/`, updates `tech.md` |
-| `/bw-new-feature` | Full pipeline: research → spec → approve → build → ship |
-| `/bw-claw` | Multi-agent: architect decomposes → claws execute per domain |
-| `/bw-quick` | Fast path for bug fixes, small tasks |
-| `/bw-plan` | Research a question, produce a written deliverable — no implementation, no commits |
-| `/bw-ship` | Quality gates + release: verify → security → review → push → PR |
-| `/bw-verify` | Quick checks: typecheck, lint, test, build |
-| `/bw-help` | Show available commands |
-
----
-
-## Agent Personas
-
-Modular, extensible agent personas in `.buildwright/agents/`:
-
-| Agent | File | Used By | Purpose |
-|-------|------|---------|---------|
-| Staff Engineer | `staff-engineer.md` | `/bw-new-feature`, `/bw-ship` | Spec & code review |
-| Security Engineer | `bw-security-engineer.md` | `/bw-ship` | OWASP, SAST, security review |
-
-### Adding New Agents
+After editing `.buildwright/`, run:
 
 ```bash
-# Create new agent persona
-cat > .buildwright/agents/qa-engineer.md << 'EOF'
-# QA Engineer Agent
-
-You are a QA Engineer specialized in test coverage...
-
-## What You Look For
-...
-
-## Output Format
-...
-EOF
-```
-
-Then reference in commands:
-```markdown
-## Adopt Persona
-Read and adopt persona from `.buildwright/agents/qa-engineer.md`
-```
-
----
-
-## Security Review
-
-The security phase in `/bw-ship` covers:
-
-| Category | Checks |
-|----------|--------|
-| **OWASP Top 10** | All 10 categories (A01-A10:2021) |
-| **SAST** | Static analysis via Semgrep |
-| **Secrets** | API keys, passwords, tokens, private keys |
-| **Dependencies** | npm audit, cargo audit, pip-audit |
-| **Financial** | No float for currency, transaction integrity, audit logging |
-
-### Severity Triage
-
-Findings are classified by severity to avoid blocking on low-risk items:
-
-| 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 |
-
----
-
-## Project Structure
-
-```
-your-project/
-├── CLAUDE.md                      # Agent instructions (committed)
-├── BUILDWRIGHT.md                 # Human documentation (committed)
-├── SKILL.md                       # Agent Skills standard (committed)
-├── .buildwright/                  # Canonical config (committed)
-│   ├── agents/                    # Reusable personas
-│   │   ├── architect.md
-│   │   ├── staff-engineer.md
-│   │   └── security-engineer.md
-│   ├── claws/                     # Domain specialists
-│   │   ├── frontend.md
-│   │   ├── backend.md
-│   │   ├── database.md
-│   │   └── TEMPLATE.md
-│   ├── codebase/                  # Analysis docs (generated by /bw-analyse)
-│   │   ├── STACK.md
-│   │   ├── ARCHITECTURE.md
-│   │   ├── CONVENTIONS.md
-│   │   └── CONCERNS.md
-│   ├── commands/                  # Slash commands
-│   │   ├── bw-analyse.md
-│   │   ├── bw-claw.md
-│   │   ├── bw-new-feature.md
-│   │   ├── bw-plan.md
-│   │   ├── bw-quick.md
-│   │   ├── bw-ship.md
-│   │   ├── bw-verify.md
-│   │   └── bw-help.md
-│   ├── steering/                  # Project context
-│   │   ├── product.md
-│   │   ├── tech.md
-│   │   ├── quality-gates.md
-│   │   └── naming-conventions.md
-│   └── tasks/
-├── .claude/                       # Generated by `make sync` (gitignored)
-│   ├── settings.json              # Claude Code permissions (committed)
-│   └── agents/, claws/, commands/, steering/  (generated)
-├── .opencode/                     # Generated by `make sync` (gitignored)
-├── .cursor/rules/                 # Generated by `make sync` (gitignored)
-├── AGENTS.md                      # Generated by `make sync` (gitignored)
-├── scripts/
-│   ├── sync-agents.sh             # Sync .buildwright/ → .claude/ + .opencode/ + .cursor/rules/
-│   ├── install-hooks.sh           # Install git hooks (run via: make install-hooks)
-│   ├── validate-skill.sh          # Validate SKILL.md against agentskills.io
-│   └── hooks/                     # Git hooks source (committed, installed to .git/hooks/)
-│       ├── pre-commit             # Auto-sync when .buildwright/ files are staged
-│       ├── post-merge             # Auto-sync after git pull/merge
-│       └── post-checkout          # Auto-sync on branch switches
-├── docs/
-│   ├── requirements/
-│   └── specs/
-└── .github/
-    └── workflows/
-        └── quality-gates.yml
+make sync
+make sync-check
+make validate
 ```
 
-> **Note:** After cloning, run `make sync && make install-hooks` to generate tool-specific configs and install git hooks that auto-sync on `.buildwright/` changes.
-
----
-
-## Design Principles (Built-In)
-
-Every spec and implementation follows:
-
-| Principle | Meaning |
-|-----------|---------|
-| **KISS** | Keep It Simple — prefer simple over clever |
-| **YAGNI** | You Aren't Gonna Need It — build only what's needed now, no speculative abstractions |
-| **DRY** | Don't Repeat Yourself — reuse existing code, extract common logic |
-| **No Premature Optimization** | Make it work first, optimize with data |
-| **Boring Technology** | Proven tools over shiny new ones |
-| **Fail Fast** | Validate early, error loudly |
-
----
-
-## Extending the Workflow
-
-### Add New Agent
-
-1. Create `.buildwright/agents/[role].md`
-2. Define mindset, checklist, output format
-3. Reference in commands with `Adopt persona from...`
-
-### Add New Command
-
-1. Create `.buildwright/commands/[name].md`
-2. Define arguments, phases, output format
-3. Reference agents as needed
-
-### Planned Agents (Future)
-
-| Agent | Purpose |
-|-------|---------|
-| QA Engineer | Test coverage, edge cases |
-| Performance Engineer | Bottleneck identification |
-| DevOps Engineer | Infrastructure review |
-| Database Engineer | Schema review, query optimization |
-| UX Engineer | API design review |
-
----
-
-## Customization
-
-| File | Purpose | Edit Frequency |
-|------|---------|----------------|
-| `.buildwright/steering/product.md` | Product context | Per project |
-| `.buildwright/steering/tech.md` | Tech stack & commands | Per project |
-| `.buildwright/agents/*.md` | Agent personas | Rarely |
-| `.buildwright/commands/*.md` | Slash commands | Rarely |
-| `CLAUDE.md` | Learned patterns | As discovered |
-
----
-
-## FAQ
-
-### Do I need to review code?
-No. `/bw-ship` handles security review and code review automatically using Staff Engineer and Security Engineer personas.
-
-### What if a step fails?
-- **Verify fails**: Retries up to 2x automatically.
-- **Security/Review fails**: No retry — requires judgment.
-- **Autonomous mode** (`BUILDWRIGHT_AUTO_APPROVE=true`): Commits completed work, pushes, creates PR with failure details, exits with error code.
-- **Interactive mode** (`BUILDWRIGHT_AUTO_APPROVE=false`): STOP immediately — human fixes in-session.
-
-### Can I skip security review?
-No. Both `/bw-ship` and `/bw-quick` include mandatory security and code review steps. Use `/bw-verify` for quick checks during active development, before committing.
-
-### How do I add project-specific rules?
-Add to `CLAUDE.md` under "Learned Patterns" or create a new agent.
+`make sync` regenerates tool-specific config, Codex skills, `AGENTS.md`, and the
+CLI README.
 
----
+## Configuration
 
-## License
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `BUILDWRIGHT_AUTO_APPROVE` | `true` | Skip approval pauses and proceed autonomously |
+| `BUILDWRIGHT_AGENT_RETRIES` | `2` | Verification retry count |
+| `GITHUB_TOKEN` | unset | Used by `gh` when creating PRs |
 
-MIT
+Use a fine-grained GitHub token with contents and pull request permissions when
+you want `/bw-ship` to push branches and create PRs.

package/bin/buildwright.js

@@ -25,7 +25,7 @@ program
 
 program
   .command('update')
-  .description('Update commands, agents, and claws from GitHub (preserves steering docs)')
+  .description('Update commands, agents, and default steering from GitHub')
   .action(async () => {
     await update();
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "buildwright",
-  "version": "0.0.11",
-  "description": "Agent-first autonomous development workflow. Ship code you don't read.",
+  "version": "0.0.13",
+  "description": "Lightweight engineering workflow for agent-led development.",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/commands/commands.js

@@ -10,12 +10,10 @@ const DIM = '\x1b[2m';
 
 const HARDCODED = [
   { name: 'bw-analyse',     description: 'Analyse codebase: writes stack, architecture, conventions, concerns to .buildwright/codebase/' },
-  { name: 'bw-claw',        description: 'Multi-agent: architect decomposes → claws execute per domain' },
-  { name: 'bw-new-feature', description: 'Full pipeline: research → spec → approve → build → ship' },
   { name: 'bw-plan',        description: 'Research a question, produce a written deliverable — no implementation, no commits' },
-  { name: 'bw-quick',       description: 'Fast path for bug fixes, small tasks, config changes' },
   { name: 'bw-ship',        description: 'Quality gates + release: verify → security → review → push → PR' },
   { name: 'bw-verify',      description: 'Quick checks: typecheck, lint, test, build' },
+  { name: 'bw-work',        description: 'Implement bug fixes, refactors, and features' },
 ];
 
 function parseFrontmatter(content) {
@@ -28,7 +26,7 @@ function parseFrontmatter(content) {
 }
 
 function loadFromDir(dir) {
-  const files = fs.readdirSync(dir).filter(f => f.startsWith('bw-') && f.endsWith('.md') && f !== 'bw-help.md');
+  const files = fs.readdirSync(dir).filter(f => f.startsWith('bw-') && f.endsWith('.md'));
   const entries = [];
   for (const file of files) {
     const content = fs.readFileSync(path.join(dir, file), 'utf8');
@@ -74,7 +72,7 @@ function commands() {
     console.log(`${DIM}(Showing default commands. Run inside a Buildwright project to see project-specific commands.)${RESET}`);
     console.log('');
   }
-  console.log(`Run ${BOLD}buildwright help${RESET} for CLI setup commands.`);
+  console.log(`Run ${BOLD}buildwright --help${RESET} for CLI setup commands.`);
   console.log('');
 }
 

package/src/commands/init.js

@@ -26,7 +26,7 @@ function init() {
   // 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}`);
+    console.log(`To update commands and agents to the latest version, run: ${BOLD}buildwright update${RESET}`);
     process.exit(1);
   }
 
@@ -83,9 +83,9 @@ function init() {
   // 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(`  1. Run ${BOLD}/bw-analyse${RESET} first on unfamiliar brownfield projects`);
+  console.log(`  2. Open your AI editor and run ${BOLD}/bw-work "your task"${RESET}`);
+  console.log(`  3. Buildwright creates tech.md/product.md only when it has real project context\n`);
   console.log(`For help: ${BOLD}buildwright --help${RESET}`);
 }