buildwright

name	buildwright
description	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.
license	MIT
compatibility	Requires git and gh for shipping. Optional tools for security scans include semgrep, gitleaks, and trufflehog. Works with Claude Code, OpenCode, Cursor, and Codex CLI.
metadata	{"homepage":"https://github.com/raunakkathuria/buildwright","version":"0.0.19","author":"raunakkathuria","tags":["development","workflow","tdd","security","code-review","documentation"]}

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