buildwright

Lightweight engineering workflow for agent-led development. Provides plan, work, verify, ship, and analyse commands with TDD, documentation discipline, security review, code review, and quality gates.

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/framework/ and .buildwright/steering/ at session start.

Framework behavior (.buildwright/framework/) is Buildwright-owned and fixed — identical in every install, refreshed on update, not customized:

• .buildwright/framework/autonomy.md — the single autonomy behaviour (no mode flag), auto-continue through ready work, and context-inferred failure handling.
• .buildwright/framework/capability.md — prefer each host tool's native capabilities (plan/file-write/task-tracking/sub-agents/parallelism/worktrees/ hooks) with documented fallbacks, for execution mechanics only — they never replace Buildwright's steering or process.
• .buildwright/framework/findings.md — convention for recording report-upstream and before-production deferrals.

Steering (.buildwright/steering/) is project-owned and customizable, preserved across updates. The shipped default:

• .buildwright/steering/philosophy.md — KISS, YAGNI, DRY, boring technology, fail fast, Red -> Green -> Refactor, documentation discipline, and financial code rules.

Further 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.