modbender Buildwright
Spec-driven autonomous development. Humans approve intent; agents handle everything else.
What this skill does
When activated, Buildwright directs the agent to:
- Read your codebase and steering documents
- Write a one-page spec (
docs/specs/[feature]/spec.md) - Stop for human approval — unless
BUILDWRIGHT_AUTO_APPROVE=true - Implement the feature with TDD
- Run quality gates: typecheck, lint, test, build
- Run optional security scans (if semgrep / gitleaks / trufflehog are installed)
- Run a Staff Engineer prompt-based code review
- Commit, push, and open a PR via
gh
Requirements
| Requirement | Purpose | Required |
|---|---|---|
git |
Commits and pushes | Yes |
gh (GitHub CLI) |
Opens PRs | Yes |
| Git credentials (SSH key or token) | Push access to repo | Yes |
semgrep |
SAST security scan | Optional |
gitleaks / trufflehog |
Secrets detection | Optional |
Agent Personas (prompt-based, no binaries)
Staff Engineer and Security Engineer are prompt-engineering personas — instructions loaded from .claude/agents/ files. They are not external tools or binaries. The agent adopts these personas to review specs and code using defined criteria and confidence thresholds.
Autonomous Mode
BUILDWRIGHT_AUTO_APPROVE controls whether the agent waits for human approval at the spec stage.
| Value | Behavior |
|---|---|
| Not set | Interactive — stops and waits for "approved" before building |
false |
Interactive — same as default |
true |
Autonomous — commits spec to git (audit trail) and proceeds without waiting |
Recommendation for first use: Leave BUILDWRIGHT_AUTO_APPROVE unset until you have reviewed a few specs and are comfortable with the workflow.
Commands
/bw-new-feature <description>
Full pipeline for new features. Auto-detects greenfield vs existing projects.
/bw-new-feature "Add OAuth2 login"
Flow: Research → Spec → Staff Engineer validates → Human approves → TDD build → Verify → Security scan → Code review → PR
Artifacts produced:
docs/specs/[feature]/research.md— what the agent found in your codebasedocs/specs/[feature]/spec.md— implementation plan with approaches considered
/bw-quick <task>
Fast path for bug fixes and small tasks (<2 hrs). No spec, no approval step.
/bw-quick "Fix the login timeout bug"
/bw-ship [message]
Quality pipeline for existing work: verify → security → review → PR.
/bw-ship "feat(auth): add OAuth2 support"
/bw-verify
Quick checks only: typecheck → lint → test → build.
/bw-help
Show all available commands.
Failure Behavior
If any gate fails after retries, the agent commits completed work, pushes, and opens a PR with a structured failure report. It does not leave orphaned branches or silent failures.
Retry Policy
| Gate | Retries | Rationale |
|---|---|---|
| Verify (typecheck, lint, test, build) | 2x | Fixable by the agent |
| Security scan | None | Requires human judgment |
| Code review | None | Architectural decisions need humans |
More Information
Full documentation, source code, and setup instructions: https://github.com/raunakkathuria/buildwright