Buildwright

Buildwright is a lightweight engineering discipline layer: understand, test,

implement, document, verify, review, ship.

Commands

/bw-work

Implement bug fixes, refactors, and features.

Flow: understand -> research -> plan if needed -> Red -> Green -> Refactor ->

docs -> verify -> security review -> code review -> commit/ship.

For larger features, /bw-work writes docs/specs/[feature]/research.md and

docs/specs/[feature]/spec.md. For small tasks, it keeps research lightweight.

Every user-facing change must update affected docs or state why no docs apply.

/bw-plan

Research a question or topic and produce a written deliverable. No source

changes, commits, pushes, or PRs.

/bw-verify

Run project quality gates: typecheck, lint, test, and build. Commands come from

.buildwright/steering/tech.md when present; otherwise Buildwright detects and

writes them.

/bw-ship

Run verify, security review, Staff Engineer review, then commit, push, and open

a PR. Shipping confirms documentation was updated or explicitly not applicable.

/bw-analyse

Analyse a brownfield codebase and write .buildwright/codebase/STACK.md,

ARCHITECTURE.md, CONVENTIONS.md, and CONCERNS.md. Also creates or updates

.buildwright/steering/tech.md with discovered stack and commands.

Steering

Buildwright recursively reads every .md file under .buildwright/steering/.

It installs one default steering file:

• .buildwright/steering/philosophy.md — KISS, YAGNI, DRY, boring technology,

fail fast, Red -> Green -> Refactor, documentation discipline, and financial

code rules.

Project-specific steering is lazy-created:

• tech.md after command and stack discovery.
• product.md only for greenfield work or explicit product context.

Personas

Buildwright uses prompt-based review personas:

• Staff Engineer for spec/code review.
• Security Engineer for security review.

Safety

Buildwright does not edit .env files, run destructive git operations, force

push, or merge PRs. It stages only files changed for the current work.