buildwright 0.0.9 → 0.0.11

package/README.md

@@ -1,81 +1,438 @@
-# buildwright
+# Buildwright
 
-Agent-first autonomous development workflow. Ship code you don't read.
+**Ship code you don't read. Let automated systems be your reviewer.**
 
-## Install
+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
+
+Starting a new project? Buildwright handles it:
+
+```
+/bw-new-feature "Add product catalog with search"
+
+> "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.
+
+> [AI generates steering docs + spec]
+> [Derives and presents tech stack for approval]
+
+PROPOSED TECH STACK
+───────────────────
+[Stack derived from your product vision and constraints]
+Chosen because: [2-3 sentences linking requirements to stack]
+Alternatives considered: [brief list]
+
+Reply "approved" to proceed with this stack.
+Or adjust: "approved, but use PostgreSQL instead of DynamoDB"
+```
+
+One question. One approval. Tech stack + spec reviewed together.
+
+---
+
+## Autonomous Mode
+
+Want fully autonomous operation? Skip human approval entirely:
 
 ```bash
-npm install -g buildwright
+# Set environment variable
+export BUILDWRIGHT_AUTO_APPROVE=true
+
+# Then run as usual
+/bw-new-feature "Add user authentication"
 ```
 
-Requires Node.js 18+.
+**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
+
+```
+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
+```
+
+**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
+
+---
 
 ## Quick Start
 
+### npm (Recommended)
+
 ```bash
-# Navigate to your project
-cd my-project
-git init  # if not already a git repo
+npm install -g buildwright
+cd my-project && buildwright init
+```
+
+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
 
-# Set up Buildwright
-buildwright init
+```bash
+# Add to any project
+curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
 
-# Customize for your project
-nano .buildwright/steering/product.md   # add product context
-nano .buildwright/steering/tech.md      # add tech stack + commands
+# 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"
+> /bw-new-feature "Add user authentication with OAuth2"
 ```
 
-## Commands
+### For an existing clone
 
-| 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/` |
+```bash
+# After cloning the repo, generate tool-specific configs
+make sync
 
-## What `init` Does
+# 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)
 
-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
+# Install git hooks to auto-sync on .buildwright/ changes
+make install-hooks
+```
 
-## What `update` Does
+### For OpenClaw
 
-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
+The recommended approach is to run the setup script, which installs the full workflow (commands, agents, claws, steering docs) into your project:
+
+```bash
+curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
+make sync
+```
+
+Alternatively, install just the skill globally for reference across all projects:
+
+```bash
+mkdir -p ~/.openclaw/skills/buildwright
+curl -s https://raw.githubusercontent.com/raunakkathuria/buildwright/main/SKILL.md > ~/.openclaw/skills/buildwright/SKILL.md
+```
 
-**Preserves** your customizations in `.buildwright/steering/` (product.md, tech.md, etc.).
+> **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.
 
-## Slash Commands (inside AI editors)
+### For OpenCode
+
+Same as above — run the setup script for the full workflow:
+
+```bash
+curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
+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
+
+Buildwright skills are discovered by Codex via `~/.agents/skills/`. After cloning:
+
+```bash
+cd ~/.codex/buildwright && make codex
+# Creates: ~/.agents/skills/buildwright → skills/
+```
+
+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
+
+| 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 |
+
+---
+
+## 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-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 |
+| `/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
+
+```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
+```
+
+> **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.
 
-## Offline Support
+### 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.
 
-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.
+### 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.
 
-## More Information
+### How do I add project-specific rules?
+Add to `CLAUDE.md` under "Learned Patterns" or create a new agent.
 
-See the [full documentation](https://github.com/raunakkathuria/buildwright) on GitHub.
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildwright",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Agent-first autonomous development workflow. Ship code you don't read.",
   "license": "MIT",
   "engines": {

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

@@ -35,6 +35,8 @@ You are a **Staff Engineer** with 15+ years of experience building production sy
 - Security vulnerabilities
 - Performance foot-guns
 - Unnecessary complexity
+- Duplicated logic that should reuse existing functions or be extracted into shared utilities
+- Unnecessary new types or abstractions when existing ones suffice
 - Missing validation
 - Poor abstractions
 - Technical debt being introduced
@@ -107,6 +109,8 @@ Only flag issues where:
 - Security vulnerabilities with a concrete exploit path (defer to security phase in /bw-ship)
 - Data loss or corruption risk with a traceable scenario
 - Missing validation at system boundaries where untrusted input enters
+- Reimplemented logic that already exists elsewhere in the codebase (DRY violation with concrete duplicate identified)
+- New types, wrappers, or abstractions not required by current requirements (YAGNI violation)
 
 Do NOT flag:
 - Potential issues that depend on specific inputs or runtime state

package/templates/.buildwright/commands/bw-new-feature.md

@@ -148,6 +148,7 @@ find . -type f -name "*.ts" | xargs grep -l "[relevant terms]"
 - How does similar functionality work today?
 - What patterns are used for this type of feature?
 - What services/utilities already exist that I should use?
+- What types/structs already exist that I can reuse instead of creating new ones?
 - What would break if I change this?
 
 ### 2.3 Read Existing Tests
@@ -208,6 +209,13 @@ Create `docs/specs/[feature-name]/research.md`:
 - [Service]: [what it does, how to use]
 - [Utility]: [what it does, how to use]
 
+### Reusable Types & Functions
+- [Function/Type]: [location] — [what it does, how to reuse]
+- [Function/Type]: [location] — [what it does, how to reuse]
+
+Flag any near-duplicates found during research. If two utilities do similar things,
+recommend which one to use and whether to consolidate.
+
 ### Integration Points
 - [System A]: Will need to integrate via [method]
 - [System B]: [description]
@@ -433,9 +441,11 @@ For each milestone:
 
 2. **Implement**
    - Follow patterns identified in research.md
-   - Use existing services/utilities discovered
+   - Use existing services/utilities discovered — do NOT reimplement
+   - Reuse existing types and structures — create new ones only when no existing type fits
+   - If you find yourself writing logic that resembles something in the codebase, stop and reuse or extract
    - Write minimal code to pass tests
-   - Remember: KISS, YAGNI
+   - Remember: KISS, YAGNI, DRY
 
 3. **Verify (with retry)**
    ```bash
@@ -453,6 +463,8 @@ For each milestone:
 
 After each milestone passes verification, briefly self-review for:
 - **Simplicity**: Is this the simplest solution? Any unnecessary complexity?
+- **Duplication**: Does this duplicate existing functions, types, or logic? Can anything be reused or extracted?
+- **Necessity**: Is every new type, abstraction, and code path required by the current requirements? Remove anything speculative.
 - **Correctness**: Any logic errors or missed edge cases in the new code?
 - **Conventions**: Does the new code follow established project patterns?
 
@@ -522,6 +534,6 @@ PIPELINE STATUS
 ✅ Code Reviewed (Staff Engineer)
 ✅ Shipped
 
-Quality gates running in CI. Will auto-merge on pass.
+Quality gates running in CI. PR ready for team review.
 ═══════════════════════════════════════════════════════════════
 ```

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

@@ -96,6 +96,7 @@ find . -name "*.test.*" -o -name "*.spec.*" | xargs grep -l "[relevant terms]"
 Understand:
 - Current implementation
 - Patterns used in these files
+- Existing functions, types, and utilities that can be reused instead of reimplemented
 - Related tests
 
 **Do NOT write a research document. Keep it in context.**
@@ -122,8 +123,9 @@ Commit: `test: add test for [task]`
 
 - Fix the bug / add the feature
 - Follow existing patterns in the file
+- Reuse existing functions and types — do NOT reimplement what already exists
 - Minimal changes only
-- KISS, YAGNI
+- KISS, YAGNI, DRY
 
 ### 3.3 Update Documentation
 

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

@@ -153,7 +153,7 @@ git diff HEAD
 
 **Phase A — Repository Context:** Understand existing patterns, conventions, error handling, and testing approaches.
 
-**Phase B — Comparative Analysis:** Does new code follow established patterns? Does it bypass or weaken existing controls?
+**Phase B — Comparative Analysis:** Does new code follow established patterns? Does it reuse existing utilities and types instead of reimplementing? Does it bypass or weaken existing controls?
 
 **Phase C — Issue Assessment:** Review changes for real issues. For each: verify it's real, confirm it was INTRODUCED by these changes, assign confidence (only report ≥ 80).
 
@@ -236,7 +236,7 @@ If `gh` is not available, provide the PR creation URL.
 ╠═══════════════════════════════════════════════════════════════╣
 ║                                                               ║
 ║  Quality gates will run in CI.                                ║
-║  PR will auto-merge when all gates pass.                      ║
+║  PR ready for team review when all gates pass.                ║
 ║                                                               ║
 ╚═══════════════════════════════════════════════════════════════╝
 ```

package/templates/.buildwright/steering/quality-gates.md

@@ -31,5 +31,5 @@ These automated gates replace human code review. ALL must pass for merge.
 - [ ] Rate limiting on sensitive endpoints
 - [ ] Audit logging for transactions
 
-## Auto-Merge Criteria
-When ALL gates pass → PR auto-merges → Deploy triggers
+## Merge Policy
+When ALL gates pass → PR is ready for merge (team follows their own merge process)

package/templates/.github/workflows/quality-gates.yml

@@ -133,18 +133,3 @@ jobs:
             go) govulncheck ./... || echo "govulncheck not installed" ;;
             python) pip-audit || safety check || echo "No Python audit tool" ;;
           esac
-
-  auto-merge:
-    needs: quality
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - name: Auto-merge on quality pass
-        uses: pascalgn/automerge-action@v0.15.6
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          MERGE_METHOD: squash
-          MERGE_LABELS: ""

package/templates/CLAUDE.md

@@ -119,6 +119,8 @@ When a feature touches multiple domains (e.g., DB + API + UI):
    - Build only what's required NOW
    - No speculative features "for later"
    - Avoid abstractions until they're proven needed
+   - No wrapper types, adapter layers, or extension points "just in case"
+   - If the requirements don't ask for it, don't build it
 
 3. **No Premature Optimization**
    - Make it work first, then make it fast (if needed)
@@ -135,6 +137,12 @@ When a feature touches multiple domains (e.g., DB + API + UI):
    - Throw errors early with clear messages
    - No silent failures
 
+6. **DRY (Don't Repeat Yourself)**
+   - Before writing new code, search for existing functions, types, and utilities that already do the job
+   - Reuse existing structures — if `User` exists, don't create `UserDTO` or `UserEntity` unless the codebase already separates those concerns
+   - If two pieces of code do similar things, extract the common part rather than duplicating
+   - Prefer importing over reimplementing
+
 ## Code Standards
 - Follow existing patterns in the codebase exactly
 - Keep files under 500 lines; split proactively

package/templates/scripts/sync-agents.sh

@@ -60,7 +60,11 @@ sync_dir() {
     tmpdir=$(mktemp -d)
     cp -R "$src/"* "$tmpdir/" 2>/dev/null || true
     if [ -n "$rewrite_from" ] && [ -n "$rewrite_to" ]; then
-      find "$tmpdir" -name "*.md" -exec sed -i "s|$rewrite_from|$rewrite_to|g" {} + 2>/dev/null || true
+      # Only rewrite @@.buildwright/ (read instructions) → tool-specific path
+      # Bare .buildwright/ (write/canonical instructions) stays untouched
+      find "$tmpdir" -name "*.md" -exec sed -i '' \
+        -e "s|@@${rewrite_from}|${rewrite_to}|g" \
+        {} + 2>/dev/null || true
     fi
     if ! diff -rq "$tmpdir" "$dst" > /dev/null 2>&1; then
       echo "OUT OF SYNC: $dst differs from $src"
@@ -71,8 +75,12 @@ sync_dir() {
     mkdir -p "$dst"
     rsync -a --delete "$src/" "$dst/" 2>/dev/null || (rm -rf "$dst"/* && cp -R "$src/"* "$dst/")
     # Rewrite path references for tool-specific copies
+    # @@.buildwright/ = "resolve to tool-specific dir" → gets rewritten
+    # Bare .buildwright/ = "canonical path" → stays untouched
     if [ -n "$rewrite_from" ] && [ -n "$rewrite_to" ]; then
-      find "$dst" -name "*.md" -exec sed -i "s|$rewrite_from|$rewrite_to|g" {} + 2>/dev/null || true
+      find "$dst" -name "*.md" -exec sed -i '' \
+        -e "s|@@${rewrite_from}|${rewrite_to}|g" \
+        {} + 2>/dev/null || true
     fi
     echo "  synced $src → $dst"
   fi
@@ -284,6 +292,15 @@ if [ "$CHECK_ONLY" = false ] && [ -f "SKILL.md" ]; then
   echo "  packaged dist/buildwright/SKILL.md for ClawHub"
 fi
 
+# ============================================================================
+# 7. README.md → cli/README.md (single source of truth for npm package page)
+# ============================================================================
+
+if [ "$CHECK_ONLY" = false ] && [ -f "README.md" ]; then
+  cp README.md cli/README.md
+  echo "  README.md → cli/README.md"
+fi
+
 # ============================================================================
 # Result
 # ============================================================================
@@ -306,6 +323,7 @@ else
   echo "  CLAUDE.md     → AGENTS.md"
   echo "  SKILL.md      → dist/buildwright/SKILL.md"
   echo "  .buildwright/commands/ → skills/          (Codex CLI skill discovery)"
+  echo "  README.md     → cli/README.md             (npm package page)"
 
   # Validate all commands are documented in SKILL.md and README.md
   if [ -f "scripts/validate-docs.sh" ]; then