buildwright 0.0.9 → 0.0.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +401 -45
- package/package.json +1 -1
- package/templates/scripts/sync-agents.sh +10 -0
package/README.md
CHANGED
|
@@ -1,81 +1,437 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Buildwright
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Ship code you don't read. Let automated systems be your reviewer.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
An agent-first autonomous development workflow where humans approve specifications and agents handle everything else — implementation, testing, security review, code review, and shipping.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## The Flow
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
flowchart TD
|
|
13
|
+
A["/bw-new-feature"] --> B{Greenfield?}
|
|
14
|
+
B -- Yes --> C[Ask product vision<br>Derive tech stack from vision]
|
|
15
|
+
C --> D
|
|
16
|
+
B -- No --> D["1. RESEARCH<br>Deep-read codebase"]
|
|
17
|
+
D --> E["1.5. RESOLVE AMBIGUITIES<br>Auto-decide or ask user<br>(BUILDWRIGHT_AUTO_APPROVE)"]
|
|
18
|
+
E --> F["2. PLAN<br>Generate spec"]
|
|
19
|
+
F --> G["3. VALIDATE<br>Staff Engineer review (auto)"]
|
|
20
|
+
G --> H["4. APPROVE<br>Human or auto<br>(BUILDWRIGHT_AUTO_APPROVE)"]
|
|
21
|
+
H --> I["5. BUILD<br>TDD per milestone<br>→ verify after each"]
|
|
22
|
+
I --> J["6.5 UPDATE DOCS<br>README · CHANGELOG · docs/"]
|
|
23
|
+
J --> K["7. SHIP"]
|
|
24
|
+
K --> L[Verify]
|
|
25
|
+
L --> M[Security]
|
|
26
|
+
M --> N[Review]
|
|
27
|
+
N --> O["PR Ready ✓"]
|
|
28
|
+
|
|
29
|
+
P["/bw-quick"] --> Q[Quick research]
|
|
30
|
+
Q --> R[Implement TDD]
|
|
31
|
+
R --> S[Verify]
|
|
32
|
+
S --> U[Security]
|
|
33
|
+
U --> V[Code Review]
|
|
34
|
+
V --> W[Update Docs]
|
|
35
|
+
W --> T["Commit Ready ✓"]
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
> If anything fails → commit completed work, push, PR with failure report, exit(1). No orphaned branches.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Greenfield Projects
|
|
43
|
+
|
|
44
|
+
Starting a new project? Buildwright handles it:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
/bw-new-feature "Add product catalog with search"
|
|
48
|
+
|
|
49
|
+
> "This looks like a new project. What is the product vision, and do you have
|
|
50
|
+
> any tech constraints (team expertise, deployment environment, integrations,
|
|
51
|
+
> compliance)?"
|
|
52
|
+
E-commerce platform for handmade crafts. Team knows Python. Deploying to AWS Lambda.
|
|
53
|
+
|
|
54
|
+
> [AI generates steering docs + spec]
|
|
55
|
+
> [Derives and presents tech stack for approval]
|
|
56
|
+
|
|
57
|
+
PROPOSED TECH STACK
|
|
58
|
+
───────────────────
|
|
59
|
+
[Stack derived from your product vision and constraints]
|
|
60
|
+
Chosen because: [2-3 sentences linking requirements to stack]
|
|
61
|
+
Alternatives considered: [brief list]
|
|
62
|
+
|
|
63
|
+
Reply "approved" to proceed with this stack.
|
|
64
|
+
Or adjust: "approved, but use PostgreSQL instead of DynamoDB"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
One question. One approval. Tech stack + spec reviewed together.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Autonomous Mode
|
|
72
|
+
|
|
73
|
+
Want fully autonomous operation? Skip human approval entirely:
|
|
6
74
|
|
|
7
75
|
```bash
|
|
8
|
-
|
|
76
|
+
# Set environment variable
|
|
77
|
+
export BUILDWRIGHT_AUTO_APPROVE=true
|
|
78
|
+
|
|
79
|
+
# Then run as usual
|
|
80
|
+
/bw-new-feature "Add user authentication"
|
|
9
81
|
```
|
|
10
82
|
|
|
11
|
-
|
|
83
|
+
**What happens:**
|
|
84
|
+
- Research, plan, validate still run (quality preserved)
|
|
85
|
+
- Spec documents committed to git BEFORE implementation
|
|
86
|
+
- No approval wait — proceeds directly to build
|
|
87
|
+
- Full audit trail in version control
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
docs(spec): add specification for user-auth
|
|
91
|
+
|
|
92
|
+
- research.md: codebase analysis
|
|
93
|
+
- spec.md: implementation plan
|
|
94
|
+
- Validated by Staff Engineer agent
|
|
95
|
+
|
|
96
|
+
Auto-approved: BUILDWRIGHT_AUTO_APPROVE=true
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Use autonomous mode when:**
|
|
100
|
+
- You trust the workflow for routine features
|
|
101
|
+
- Running in CI/CD pipelines
|
|
102
|
+
- Batch processing multiple features
|
|
103
|
+
- You want to review specs via git history instead of real-time
|
|
104
|
+
|
|
105
|
+
---
|
|
12
106
|
|
|
13
107
|
## Quick Start
|
|
14
108
|
|
|
109
|
+
### npm (Recommended)
|
|
110
|
+
|
|
15
111
|
```bash
|
|
16
|
-
|
|
17
|
-
cd my-project
|
|
18
|
-
|
|
112
|
+
npm install -g buildwright
|
|
113
|
+
cd my-project && buildwright init
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Requires Node.js 18+. All templates are bundled — works offline after install. Run `buildwright update` to pull the latest commands/agents/claws from GitHub.
|
|
117
|
+
|
|
118
|
+
### For Claude Code
|
|
19
119
|
|
|
20
|
-
|
|
21
|
-
|
|
120
|
+
```bash
|
|
121
|
+
# Add to any project
|
|
122
|
+
curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
|
|
22
123
|
|
|
23
|
-
# Customize
|
|
24
|
-
nano .buildwright/steering/product.md #
|
|
25
|
-
nano .buildwright/steering/tech.md #
|
|
124
|
+
# Customize steering docs
|
|
125
|
+
nano .buildwright/steering/product.md # Your product context
|
|
126
|
+
nano .buildwright/steering/tech.md # Your tech stack
|
|
26
127
|
|
|
27
128
|
# Start building
|
|
28
129
|
claude
|
|
29
|
-
> /bw-new-feature "Add user authentication"
|
|
130
|
+
> /bw-new-feature "Add user authentication with OAuth2"
|
|
30
131
|
```
|
|
31
132
|
|
|
32
|
-
|
|
133
|
+
### For an existing clone
|
|
33
134
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
| `buildwright update` | Update commands/agents/claws from GitHub (preserves your steering docs) |
|
|
38
|
-
| `buildwright sync` | Re-sync `.buildwright/` to `.claude/`, `.opencode/`, `.cursor/rules/` |
|
|
135
|
+
```bash
|
|
136
|
+
# After cloning the repo, generate tool-specific configs
|
|
137
|
+
make sync
|
|
39
138
|
|
|
40
|
-
|
|
139
|
+
# This creates:
|
|
140
|
+
# .claude/ (commands, agents, claws, steering — from .buildwright/)
|
|
141
|
+
# .opencode/ (commands, agents, claws, steering — from .buildwright/)
|
|
142
|
+
# .cursor/rules/ (commands, agents, claws, steering — from .buildwright/)
|
|
143
|
+
# AGENTS.md (from CLAUDE.md — for OpenCode compatibility)
|
|
41
144
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
- `Makefile`, `CLAUDE.md`, `BUILDWRIGHT.md`
|
|
46
|
-
2. Makes scripts executable
|
|
47
|
-
3. Runs `make sync` to generate `.claude/`, `.opencode/`, `.cursor/rules/`
|
|
48
|
-
4. Installs git hooks for auto-sync on `.buildwright/` changes
|
|
145
|
+
# Install git hooks to auto-sync on .buildwright/ changes
|
|
146
|
+
make install-hooks
|
|
147
|
+
```
|
|
49
148
|
|
|
50
|
-
|
|
149
|
+
### For OpenClaw
|
|
51
150
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
-
|
|
56
|
-
|
|
151
|
+
The recommended approach is to run the setup script, which installs the full workflow (commands, agents, claws, steering docs) into your project:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
|
|
155
|
+
make sync
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Alternatively, install just the skill globally for reference across all projects:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
mkdir -p ~/.openclaw/skills/buildwright
|
|
162
|
+
curl -s https://raw.githubusercontent.com/raunakkathuria/buildwright/main/SKILL.md > ~/.openclaw/skills/buildwright/SKILL.md
|
|
163
|
+
```
|
|
57
164
|
|
|
58
|
-
**
|
|
165
|
+
> **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.
|
|
59
166
|
|
|
60
|
-
|
|
167
|
+
### For OpenCode
|
|
168
|
+
|
|
169
|
+
Same as above — run the setup script for the full workflow:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
|
|
173
|
+
make sync
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Or install the skill globally:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
mkdir -p ~/.config/opencode/skills/buildwright
|
|
180
|
+
curl -s https://raw.githubusercontent.com/raunakkathuria/buildwright/main/SKILL.md > ~/.config/opencode/skills/buildwright/SKILL.md
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
> **Note:** The global skill install provides buildwright's workflow guidance via SKILL.md. The slash commands require the full project setup.
|
|
184
|
+
|
|
185
|
+
### For Cursor
|
|
186
|
+
|
|
187
|
+
Same setup — run the setup script for the full workflow:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
curl -sL https://raw.githubusercontent.com/raunakkathuria/buildwright/main/setup.sh | bash
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
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.
|
|
194
|
+
|
|
195
|
+
### For Codex CLI
|
|
196
|
+
|
|
197
|
+
Buildwright skills are discovered by Codex via `~/.agents/skills/`. After cloning:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
cd ~/.codex/buildwright && make codex
|
|
201
|
+
# Creates: ~/.agents/skills/buildwright → skills/
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Or follow the detailed guide in [`.codex/INSTALL.md`](.codex/INSTALL.md).
|
|
205
|
+
|
|
206
|
+
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.
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## When to Use What
|
|
211
|
+
|
|
212
|
+
| Scenario | Approach | Why |
|
|
213
|
+
|----------|----------|-----|
|
|
214
|
+
| New feature, unclear scope | `/bw-new-feature` | Research prevents building the wrong thing |
|
|
215
|
+
| New feature, clear scope | `/bw-new-feature` | Spec creates audit trail + validation |
|
|
216
|
+
| Bug fix | `/bw-quick` | Fast path with full quality gates |
|
|
217
|
+
| Small task (< 2 hrs) | `/bw-quick` | Lightweight planning, full quality gates |
|
|
218
|
+
| Config change | `/bw-quick` | Quick path with security scan + code review |
|
|
219
|
+
| Refactor, clear scope | `/bw-quick` | You already know what to change |
|
|
220
|
+
| Refactor, unclear scope | `/bw-new-feature` | Research phase prevents breaking things |
|
|
221
|
+
| Unfamiliar / brownfield codebase | `/bw-analyse` | Generates stack, architecture, conventions, and concerns docs so every session starts with real context |
|
|
222
|
+
| Greenfield project | `/bw-new-feature` | Auto-generates steering docs + tech stack |
|
|
223
|
+
| Prototype / spike | Just code it | Ceremony kills exploration speed |
|
|
224
|
+
| One-off script | Just code it | No need for spec, review, or CI |
|
|
225
|
+
| Learning / experimenting | Just code it | Pipeline adds friction to discovery |
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## Commands
|
|
61
230
|
|
|
62
231
|
| Command | Purpose |
|
|
63
232
|
|---------|---------|
|
|
233
|
+
| `/bw-analyse` | Analyse codebase: writes stack, architecture, conventions, concerns to `.buildwright/codebase/`, updates `tech.md` |
|
|
64
234
|
| `/bw-new-feature` | Full pipeline: research → spec → approve → build → ship |
|
|
235
|
+
| `/bw-claw` | Multi-agent: architect decomposes → claws execute per domain |
|
|
65
236
|
| `/bw-quick` | Fast path for bug fixes, small tasks |
|
|
66
|
-
| `/bw-
|
|
67
|
-
| `/bw-ship` | Quality gates + push
|
|
68
|
-
| `/bw-verify` | Quick typecheck
|
|
69
|
-
| `/bw-
|
|
70
|
-
|
|
237
|
+
| `/bw-plan` | Research a question, produce a written deliverable — no implementation, no commits |
|
|
238
|
+
| `/bw-ship` | Quality gates + release: verify → security → review → push → PR |
|
|
239
|
+
| `/bw-verify` | Quick checks: typecheck, lint, test, build |
|
|
240
|
+
| `/bw-help` | Show available commands |
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## Agent Personas
|
|
245
|
+
|
|
246
|
+
Modular, extensible agent personas in `.buildwright/agents/`:
|
|
247
|
+
|
|
248
|
+
| Agent | File | Used By | Purpose |
|
|
249
|
+
|-------|------|---------|---------|
|
|
250
|
+
| Staff Engineer | `staff-engineer.md` | `/bw-new-feature`, `/bw-ship` | Spec & code review |
|
|
251
|
+
| Security Engineer | `bw-security-engineer.md` | `/bw-ship` | OWASP, SAST, security review |
|
|
252
|
+
|
|
253
|
+
### Adding New Agents
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
# Create new agent persona
|
|
257
|
+
cat > .buildwright/agents/qa-engineer.md << 'EOF'
|
|
258
|
+
# QA Engineer Agent
|
|
259
|
+
|
|
260
|
+
You are a QA Engineer specialized in test coverage...
|
|
261
|
+
|
|
262
|
+
## What You Look For
|
|
263
|
+
...
|
|
264
|
+
|
|
265
|
+
## Output Format
|
|
266
|
+
...
|
|
267
|
+
EOF
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Then reference in commands:
|
|
271
|
+
```markdown
|
|
272
|
+
## Adopt Persona
|
|
273
|
+
Read and adopt persona from `.buildwright/agents/qa-engineer.md`
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Security Review
|
|
279
|
+
|
|
280
|
+
The security phase in `/bw-ship` covers:
|
|
281
|
+
|
|
282
|
+
| Category | Checks |
|
|
283
|
+
|----------|--------|
|
|
284
|
+
| **OWASP Top 10** | All 10 categories (A01-A10:2021) |
|
|
285
|
+
| **SAST** | Static analysis via Semgrep |
|
|
286
|
+
| **Secrets** | API keys, passwords, tokens, private keys |
|
|
287
|
+
| **Dependencies** | npm audit, cargo audit, pip-audit |
|
|
288
|
+
| **Financial** | No float for currency, transaction integrity, audit logging |
|
|
289
|
+
|
|
290
|
+
### Severity Triage
|
|
291
|
+
|
|
292
|
+
Findings are classified by severity to avoid blocking on low-risk items:
|
|
293
|
+
|
|
294
|
+
| Severity | Action | Example |
|
|
295
|
+
|----------|--------|---------|
|
|
296
|
+
| **Critical / High** | Block — must fix before merge | SQL injection, exposed secrets, auth bypass |
|
|
297
|
+
| **Medium** | Fix in this PR if feasible, otherwise track | Missing rate limiting, verbose error messages |
|
|
298
|
+
| **Low / Info** | Advisory — log and move on | Minor header hardening, informational findings |
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Project Structure
|
|
303
|
+
|
|
304
|
+
```
|
|
305
|
+
your-project/
|
|
306
|
+
├── CLAUDE.md # Agent instructions (committed)
|
|
307
|
+
├── BUILDWRIGHT.md # Human documentation (committed)
|
|
308
|
+
├── SKILL.md # Agent Skills standard (committed)
|
|
309
|
+
├── .buildwright/ # Canonical config (committed)
|
|
310
|
+
│ ├── agents/ # Reusable personas
|
|
311
|
+
│ │ ├── architect.md
|
|
312
|
+
│ │ ├── staff-engineer.md
|
|
313
|
+
│ │ └── security-engineer.md
|
|
314
|
+
│ ├── claws/ # Domain specialists
|
|
315
|
+
│ │ ├── frontend.md
|
|
316
|
+
│ │ ├── backend.md
|
|
317
|
+
│ │ ├── database.md
|
|
318
|
+
│ │ └── TEMPLATE.md
|
|
319
|
+
│ ├── codebase/ # Analysis docs (generated by /bw-analyse)
|
|
320
|
+
│ │ ├── STACK.md
|
|
321
|
+
│ │ ├── ARCHITECTURE.md
|
|
322
|
+
│ │ ├── CONVENTIONS.md
|
|
323
|
+
│ │ └── CONCERNS.md
|
|
324
|
+
│ ├── commands/ # Slash commands
|
|
325
|
+
│ │ ├── bw-analyse.md
|
|
326
|
+
│ │ ├── bw-claw.md
|
|
327
|
+
│ │ ├── bw-new-feature.md
|
|
328
|
+
│ │ ├── bw-plan.md
|
|
329
|
+
│ │ ├── bw-quick.md
|
|
330
|
+
│ │ ├── bw-ship.md
|
|
331
|
+
│ │ ├── bw-verify.md
|
|
332
|
+
│ │ └── bw-help.md
|
|
333
|
+
│ ├── steering/ # Project context
|
|
334
|
+
│ │ ├── product.md
|
|
335
|
+
│ │ ├── tech.md
|
|
336
|
+
│ │ ├── quality-gates.md
|
|
337
|
+
│ │ └── naming-conventions.md
|
|
338
|
+
│ └── tasks/
|
|
339
|
+
├── .claude/ # Generated by `make sync` (gitignored)
|
|
340
|
+
│ ├── settings.json # Claude Code permissions (committed)
|
|
341
|
+
│ └── agents/, claws/, commands/, steering/ (generated)
|
|
342
|
+
├── .opencode/ # Generated by `make sync` (gitignored)
|
|
343
|
+
├── .cursor/rules/ # Generated by `make sync` (gitignored)
|
|
344
|
+
├── AGENTS.md # Generated by `make sync` (gitignored)
|
|
345
|
+
├── scripts/
|
|
346
|
+
│ ├── sync-agents.sh # Sync .buildwright/ → .claude/ + .opencode/ + .cursor/rules/
|
|
347
|
+
│ ├── install-hooks.sh # Install git hooks (run via: make install-hooks)
|
|
348
|
+
│ ├── validate-skill.sh # Validate SKILL.md against agentskills.io
|
|
349
|
+
│ └── hooks/ # Git hooks source (committed, installed to .git/hooks/)
|
|
350
|
+
│ ├── pre-commit # Auto-sync when .buildwright/ files are staged
|
|
351
|
+
│ ├── post-merge # Auto-sync after git pull/merge
|
|
352
|
+
│ └── post-checkout # Auto-sync on branch switches
|
|
353
|
+
├── docs/
|
|
354
|
+
│ ├── requirements/
|
|
355
|
+
│ └── specs/
|
|
356
|
+
└── .github/
|
|
357
|
+
└── workflows/
|
|
358
|
+
└── quality-gates.yml
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
> **Note:** After cloning, run `make sync && make install-hooks` to generate tool-specific configs and install git hooks that auto-sync on `.buildwright/` changes.
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## Design Principles (Built-In)
|
|
366
|
+
|
|
367
|
+
Every spec and implementation follows:
|
|
368
|
+
|
|
369
|
+
| Principle | Meaning |
|
|
370
|
+
|-----------|---------|
|
|
371
|
+
| **KISS** | Keep It Simple — prefer simple over clever |
|
|
372
|
+
| **YAGNI** | You Aren't Gonna Need It — build only what's needed now |
|
|
373
|
+
| **No Premature Optimization** | Make it work first, optimize with data |
|
|
374
|
+
| **Boring Technology** | Proven tools over shiny new ones |
|
|
375
|
+
| **Fail Fast** | Validate early, error loudly |
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## Extending the Workflow
|
|
380
|
+
|
|
381
|
+
### Add New Agent
|
|
382
|
+
|
|
383
|
+
1. Create `.buildwright/agents/[role].md`
|
|
384
|
+
2. Define mindset, checklist, output format
|
|
385
|
+
3. Reference in commands with `Adopt persona from...`
|
|
386
|
+
|
|
387
|
+
### Add New Command
|
|
388
|
+
|
|
389
|
+
1. Create `.buildwright/commands/[name].md`
|
|
390
|
+
2. Define arguments, phases, output format
|
|
391
|
+
3. Reference agents as needed
|
|
392
|
+
|
|
393
|
+
### Planned Agents (Future)
|
|
394
|
+
|
|
395
|
+
| Agent | Purpose |
|
|
396
|
+
|-------|---------|
|
|
397
|
+
| QA Engineer | Test coverage, edge cases |
|
|
398
|
+
| Performance Engineer | Bottleneck identification |
|
|
399
|
+
| DevOps Engineer | Infrastructure review |
|
|
400
|
+
| Database Engineer | Schema review, query optimization |
|
|
401
|
+
| UX Engineer | API design review |
|
|
402
|
+
|
|
403
|
+
---
|
|
404
|
+
|
|
405
|
+
## Customization
|
|
406
|
+
|
|
407
|
+
| File | Purpose | Edit Frequency |
|
|
408
|
+
|------|---------|----------------|
|
|
409
|
+
| `.buildwright/steering/product.md` | Product context | Per project |
|
|
410
|
+
| `.buildwright/steering/tech.md` | Tech stack & commands | Per project |
|
|
411
|
+
| `.buildwright/agents/*.md` | Agent personas | Rarely |
|
|
412
|
+
| `.buildwright/commands/*.md` | Slash commands | Rarely |
|
|
413
|
+
| `CLAUDE.md` | Learned patterns | As discovered |
|
|
414
|
+
|
|
415
|
+
---
|
|
416
|
+
|
|
417
|
+
## FAQ
|
|
418
|
+
|
|
419
|
+
### Do I need to review code?
|
|
420
|
+
No. `/bw-ship` handles security review and code review automatically using Staff Engineer and Security Engineer personas.
|
|
71
421
|
|
|
72
|
-
|
|
422
|
+
### What if a step fails?
|
|
423
|
+
- **Verify fails**: Retries up to 2x automatically.
|
|
424
|
+
- **Security/Review fails**: No retry — requires judgment.
|
|
425
|
+
- **Autonomous mode** (`BUILDWRIGHT_AUTO_APPROVE=true`): Commits completed work, pushes, creates PR with failure details, exits with error code.
|
|
426
|
+
- **Interactive mode** (`BUILDWRIGHT_AUTO_APPROVE=false`): STOP immediately — human fixes in-session.
|
|
73
427
|
|
|
74
|
-
|
|
428
|
+
### Can I skip security review?
|
|
429
|
+
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.
|
|
75
430
|
|
|
76
|
-
|
|
431
|
+
### How do I add project-specific rules?
|
|
432
|
+
Add to `CLAUDE.md` under "Learned Patterns" or create a new agent.
|
|
77
433
|
|
|
78
|
-
|
|
434
|
+
---
|
|
79
435
|
|
|
80
436
|
## License
|
|
81
437
|
|
package/package.json
CHANGED
|
@@ -284,6 +284,15 @@ if [ "$CHECK_ONLY" = false ] && [ -f "SKILL.md" ]; then
|
|
|
284
284
|
echo " packaged dist/buildwright/SKILL.md for ClawHub"
|
|
285
285
|
fi
|
|
286
286
|
|
|
287
|
+
# ============================================================================
|
|
288
|
+
# 7. README.md → cli/README.md (single source of truth for npm package page)
|
|
289
|
+
# ============================================================================
|
|
290
|
+
|
|
291
|
+
if [ "$CHECK_ONLY" = false ] && [ -f "README.md" ]; then
|
|
292
|
+
cp README.md cli/README.md
|
|
293
|
+
echo " README.md → cli/README.md"
|
|
294
|
+
fi
|
|
295
|
+
|
|
287
296
|
# ============================================================================
|
|
288
297
|
# Result
|
|
289
298
|
# ============================================================================
|
|
@@ -306,6 +315,7 @@ else
|
|
|
306
315
|
echo " CLAUDE.md → AGENTS.md"
|
|
307
316
|
echo " SKILL.md → dist/buildwright/SKILL.md"
|
|
308
317
|
echo " .buildwright/commands/ → skills/ (Codex CLI skill discovery)"
|
|
318
|
+
echo " README.md → cli/README.md (npm package page)"
|
|
309
319
|
|
|
310
320
|
# Validate all commands are documented in SKILL.md and README.md
|
|
311
321
|
if [ -f "scripts/validate-docs.sh" ]; then
|