buildwright 0.0.12 → 0.0.13

package/templates/.buildwright/commands/bw-new-feature.md

@@ -1,539 +0,0 @@
----
-name: bw-new-feature
-description: Research codebase, generate spec, validate, get approval, implement with TDD, and ship
-arguments:
-  - name: requirements
-    description: Path to requirements file OR inline description of what to build
-    required: true
-  - name: skip-research
-    description: Skip research phase (not recommended)
-    required: false
-  - name: parallel
-    description: Enable parallel multi-agent implementation
-    required: false
----
-
-## Feature Development Pipeline
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   NEW FEATURE PIPELINE                      │
-├─────────────────────────────────────────────────────────────┤
-│  0.   DETECT             → Greenfield or existing project?         │
-│  1.   RESEARCH           → Deep-read codebase, understand context  │
-│  1.5. RESOLVE AMBIGUITIES → Auto-decide or ask user               │
-│  2.   PLAN               → Generate spec informed by research      │
-│  3. VALIDATE  → Staff Engineer reviews spec (auto)          │
-│  4. APPROVE   → Human reviews and says "approved"           │
-│  5. BUILD     → TDD: test → implement → verify              │
-│  6. SHIP      → verify → security → review → release        │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Phase 0: Detect (Greenfield or Existing?)
-
-**Check for existing tech indicators:**
-- Language manifests: `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `setup.py`
-- Dependency files: `requirements.txt`, lock files
-- Build files: `Makefile`, `build.gradle`, `CMakeLists.txt`
-- Source directories: `src/`, `lib/`, `app/`, `cmd/`
-- Git history: `git log --oneline -5` (any commits = existing project)
-
-**Decision:**
-- **Any found** → **Existing Project Path**: Run Tech Discovery Protocol (Command Discovery in CLAUDE.md), read steering docs, proceed to Phase 1.
-- **None found** → **Greenfield Path** (below).
-
-### Greenfield Path
-
-1. Ask ONE question:
-   ```
-   This looks like a new project. What is the product vision, and do you have any
-   tech constraints (team expertise, deployment environment, integrations, compliance)?
-   ```
-2. **STOP and wait for the answer.** Do NOT proceed until answered.
-3. Derive the stack from the answer — reason from: product type, team knowledge, deployment constraints, scale, compliance. **No hardcoded default stack.**
-4. Generate `.buildwright/steering/product.md` and `.buildwright/steering/tech.md` from the answer.
-5. At Phase 4 (Human Approval), present the proposed tech stack alongside the spec:
-   ```
-   PROPOSED TECH STACK
-   ───────────────────
-   [Stack derived from your requirements]
-
-   Chosen because: [2-3 sentences linking requirements to stack choice]
-   Alternatives considered: [brief list]
-
-   Reply "approved" or adjust: "approved, but use X instead of Y"
-   ```
-6. After approval, finalize `tech.md` with actual commands so future runs use Step 1 of the discovery protocol.
-
-**Existing Project Priority Rule (always apply):**
-1. Team's filled-in `tech.md` > auto-detection
-2. Existing code patterns > Buildwright conventions
-3. Existing deployment config (`Dockerfile`, `k8s/`, `compose.yml`) > DevOps claw defaults
-4. Existing test patterns > TDD suggestions in claws
-5. Never modify working infrastructure to match Buildwright defaults
-
----
-
-## Phase 1: Understand Requirements
-
-If $ARGUMENTS.requirements is a file path, read it.
-Otherwise, treat it as an inline description.
-
-**Gather:**
-- What is being requested
-- User personas and goals
-- Constraints mentioned
-- Success criteria
-
----
-
-## Phase 2: Research (CRITICAL)
-
-**Skip only if $ARGUMENTS.skip-research is set. Not recommended.**
-
-This phase prevents the #1 failure mode: code that works in isolation but breaks the surrounding system.
-
-### 2.1 Read Steering Documents
-
-```bash
-# Always read these first
-cat .buildwright/steering/product.md   # Product context
-cat .buildwright/steering/tech.md      # Tech stack, commands, patterns
-```
-
-Extract:
-- Product vision and current focus
-- Tech stack and conventions
-- Existing patterns to follow
-- Commands to use
-
-### 2.1b Read Codebase Analysis Docs (if present)
-
-If `.buildwright/codebase/` exists (generated by `/bw-analyse`), read all docs there:
-
-```bash
-ls .buildwright/codebase/ 2>/dev/null && cat .buildwright/codebase/*.md
-```
-
-These docs contain pre-mapped context:
-- `STACK.md` — confirmed tech stack and dependencies
-- `ARCHITECTURE.md` — layer structure, entry points, data flow
-- `CONVENTIONS.md` — naming patterns, import style, test framework
-- `CONCERNS.md` — known issues and gaps to avoid repeating
-
-**If codebase docs exist:** they replace most of the general scanning in 2.2. Focus your
-deep-read (2.2) on the specific files relevant to this feature only. Follow the
-conventions and architecture exactly — do not invent new patterns.
-
-**If not present:** proceed with 2.2 as written. Consider running `/bw-analyse` first on
-brownfield projects for faster, more accurate results.
-
----
-
-### 2.2 Deep-Read Relevant Codebase
-
-Based on the requirements, identify and deeply read relevant areas:
-
-```bash
-# Find related files
-find . -type f -name "*.ts" | xargs grep -l "[relevant terms]"
-
-# Read each file thoroughly - understand, don't skim
-```
-
-**Read with these questions:**
-- How does similar functionality work today?
-- What patterns are used for this type of feature?
-- What services/utilities already exist that I should use?
-- What types/structs already exist that I can reuse instead of creating new ones?
-- What would break if I change this?
-
-### 2.3 Read Existing Tests
-
-```bash
-# Find related tests
-find . -type f -name "*.test.*" -o -name "*.spec.*" | xargs grep -l "[relevant terms]"
-```
-
-Understand:
-- How similar features are tested
-- Expected behaviors
-- Edge cases already handled
-
-### 2.4 Write Research Document
-
-Create `docs/specs/[feature-name]/research.md`:
-
-```markdown
-# Research: [Feature Name]
-
-## Date
-[Current date]
-
-## Requirements Summary
-[Brief summary of what's being built]
-
----
-
-## Product Context
-[Relevant info from product.md]
-- Product vision alignment
-- Related features
-- User personas affected
-
----
-
-## Technical Context
-[Relevant info from tech.md]
-- Stack components involved
-- Conventions to follow
-- Commands to use
-
----
-
-## Codebase Analysis
-
-### Relevant Files
-| File | Purpose | Key Functions |
-|------|---------|---------------|
-| [path] | [what it does] | [functions to use/extend] |
-
-### Existing Patterns
-- [Pattern 1]: Used in [file], should follow for [reason]
-- [Pattern 2]: [description]
-
-### Services/Utilities to Reuse
-- [Service]: [what it does, how to use]
-- [Utility]: [what it does, how to use]
-
-### Reusable Types & Functions
-- [Function/Type]: [location] — [what it does, how to reuse]
-- [Function/Type]: [location] — [what it does, how to reuse]
-
-Flag any near-duplicates found during research. If two utilities do similar things,
-recommend which one to use and whether to consolidate.
-
-### Integration Points
-- [System A]: Will need to integrate via [method]
-- [System B]: [description]
-
----
-
-## Test Patterns
-- Similar features tested with: [approach]
-- Test utilities available: [list]
-- Coverage expectations: [from quality-gates.md]
-
----
-
-## Risks & Considerations
-- [Risk 1]: [description and mitigation]
-- [Risk 2]: [description and mitigation]
-
----
-
-## Recommendations for Implementation
-- Use [existing utility] for [purpose]
-- Follow [pattern] from [file]
-- Avoid [anti-pattern] because [reason]
-```
-
-**This document becomes input for the planning phase.**
-
----
-
-## Phase 1.5: Resolve Ambiguities (CRITICAL — DO NOT SKIP)
-
-Based on research findings, identify ALL underspecified aspects before designing:
-
-1. Review the research document and original requirements
-2. Identify gaps: edge cases, error handling, integration points, scope boundaries, backward compatibility, performance needs
-
-**If BUILDWRIGHT_AUTO_APPROVE is not set to `false` (default — autonomous mode):**
-- Make your best judgment for each ambiguity based on research findings
-- Document each decision and rationale in the research document under "Assumptions Made"
-- Prefer the simpler, safer, more conventional choice
-- Proceed directly to specification
-
-**If BUILDWRIGHT_AUTO_APPROVE=false (interactive mode):**
-- Present all questions to the user in a clear, organized list
-- Wait for answers before proceeding to specification
-
-This phase prevents the #2 failure mode: building the wrong thing because requirements were ambiguous.
-
----
-
-## Phase 3: Generate Technical Specification
-
-Create `docs/specs/[feature-name]/spec.md`
-
-**The spec must reference and build upon research.md findings.**
-
-### Section 1: Overview
-- Problem Statement
-- Success Metrics (measurable)
-- Scope (in/out)
-
-### Section 2: Design Principles Applied
-- How KISS, YAGNI, no premature optimization are applied
-- **Reference existing patterns from research**
-
-### Section 3: Approaches Considered (CRITICAL)
-- Design at least 2 approaches with different trade-off focuses:
-  - **Minimal changes**: Smallest change, maximum reuse of existing code
-  - **Clean architecture**: Best maintainability and elegant abstractions
-  - **Pragmatic balance** (optional): Speed + quality middle ground
-- For each: pros/cons/complexity/estimate
-- **Autonomous mode**: Pick the best approach, document rationale
-- **Interactive mode**: Present recommendation and let user choose
-- **Reference existing patterns and code from research**
-
-### Section 4: User Journeys
-- Primary flows with diagrams
-- Edge cases and handling
-
-### Section 5: Technical Design
-- Architecture diagram
-- Data model (if applicable)
-- API design (if applicable)
-- **Reference existing services/utilities from research**
-
-### Section 6: What We're NOT Doing
-- Explicit list of excluded features
-- Why each is excluded
-
-### Section 7: Security Considerations
-- Input validation, auth, data protection
-
-### Section 8: Testing Strategy
-- **Follow test patterns identified in research**
-- What to test, what NOT to test
-
-### Section 9: Implementation Milestones
-- Each: independently deployable, 2-4 hours, clear done criteria
-- **Reference specific files/functions from research**
-
-### Section 10: Open Questions & Assumptions
-
----
-
-## Phase 4: Validate Specification (AUTO)
-
-Adopt Staff Engineer persona from `.buildwright/agents/staff-engineer.md`.
-
-Review the spec for:
-- Does it leverage existing patterns from research?
-- Problem clearly understood?
-- Approaches genuinely evaluated?
-- Design principles applied?
-- Risks identified?
-- Milestones realistic?
-
-Act on findings by severity:
-- **Critical Issues**: Fix in spec and re-validate. These block approval.
-- **Recommendations**: Fix if straightforward (< 5 min). Otherwise note as TODO in spec — address during implementation.
-- **Observations**: Acknowledge and move on. Do not modify spec.
-
-If zero critical issues remain → proceed to approval.
-
----
-
-## Phase 5: Request Human Approval
-
-Present summary:
-
-```
-═══════════════════════════════════════════════════════════════
-SPECIFICATION COMPLETE
-═══════════════════════════════════════════════════════════════
-
-Feature: [name]
-Research: docs/specs/[feature-name]/research.md
-Spec: docs/specs/[feature-name]/spec.md
-
-RESEARCH FINDINGS
-─────────────────
-• Existing patterns to follow: [list]
-• Services to reuse: [list]
-• Key risks identified: [list]
-
-APPROACH CHOSEN
-───────────────
-[Brief description]
-
-Considered [N] alternatives. Chose this because:
-• [Reason 1]
-• [Reason 2]
-
-MILESTONES
-──────────
-1. [Milestone 1] (~X hrs)
-2. [Milestone 2] (~X hrs)
-3. [Milestone 3] (~X hrs)
-
-Total: ~[X] hours
-
-STAFF ENGINEER REVIEW: ✅ Passed
-
-═══════════════════════════════════════════════════════════════
-
-Please review:
-• docs/specs/[feature-name]/research.md (codebase analysis)
-• docs/specs/[feature-name]/spec.md (implementation plan)
-
-Reply "approved" to proceed with implementation.
-Reply with feedback to revise.
-═══════════════════════════════════════════════════════════════
-```
-
-**If BUILDWRIGHT_AUTO_APPROVE is not set to `false` (default — autonomous mode):**
-- Commit spec to git (audit trail): `docs: add spec for [feature-name]`
-- Proceed directly to Phase 6: Implement
-
-**If BUILDWRIGHT_AUTO_APPROVE=false (interactive mode):**
-- STOP and wait for human to say "approved".
-
----
-
-## Phase 6: Implement (After Approval)
-
-### Detect Implementation Mode
-
-**Single-domain or small scope** → Sequential implementation (below)
-
-**Multi-domain (3+ independent components, 8+ hours, crosses layer boundaries)** → Recommend Claw Architecture:
-
-```
-╔═══════════════════════════════════════════════════════════════╗
-║  MULTI-DOMAIN FEATURE DETECTED                                ║
-╠═══════════════════════════════════════════════════════════════╣
-║                                                               ║
-║  This feature touches [N] domains: [list]                     ║
-║                                                               ║
-║  Recommendation: Use /bw-claw for multi-agent execution       ║
-║                                                               ║
-║  Benefits:                                                    ║
-║  • Each domain gets a specialist agent (claw)                 ║
-║  • Interface contracts prevent integration failures           ║
-║  • Parallel execution where possible                          ║
-║                                                               ║
-║  /bw-claw "[feature description]"                             ║
-║                                                               ║
-║  Or say "continue" to proceed with single-agent mode.         ║
-╚═══════════════════════════════════════════════════════════════╝
-```
-
-If parallel selected, $ARGUMENTS.parallel set, or user says "claw":
-- Switch to `/bw-claw` pipeline
-- STOP this command
-
-### Sequential Implementation (Default)
-
-For each milestone:
-
-1. **Write tests first (TDD)**
-   - Follow test patterns from research.md
-   - Create failing tests
-   - Commit: `test: add tests for [milestone]`
-
-2. **Implement**
-   - Follow patterns identified in research.md
-   - Use existing services/utilities discovered — do NOT reimplement
-   - Reuse existing types and structures — create new ones only when no existing type fits
-   - If you find yourself writing logic that resembles something in the codebase, stop and reuse or extract
-   - Write minimal code to pass tests
-   - Remember: KISS, YAGNI, DRY
-
-3. **Verify (with retry)**
-   ```bash
-   [typecheck] [lint] [test] [build]
-   ```
-   - If fails → Fix and retry (up to BUILDWRIGHT_AGENT_RETRIES attempts, default 2)
-   - If same error repeats → Not making progress — handle failure (see below)
-   - If still failing after retries → Handle failure:
-     - **Autonomous** (`BUILDWRIGHT_AUTO_APPROVE=true`, default): Commit completed milestones, push branch, create PR with failure summary (see BUILDWRIGHT.md template), exit(1).
-     - **Interactive** (`BUILDWRIGHT_AUTO_APPROVE=false`): STOP and report blocker.
-
-4. **If ALL pass:** Run milestone quality check, then commit.
-
-### Milestone Quality Check
-
-After each milestone passes verification, briefly self-review for:
-- **Simplicity**: Is this the simplest solution? Any unnecessary complexity?
-- **Duplication**: Does this duplicate existing functions, types, or logic? Can anything be reused or extracted?
-- **Necessity**: Is every new type, abstraction, and code path required by the current requirements? Remove anything speculative.
-- **Correctness**: Any logic errors or missed edge cases in the new code?
-- **Conventions**: Does the new code follow established project patterns?
-
-Only flag HIGH SIGNAL issues (confidence ≥ 80). Fix issues autonomously — don't gold-plate, ship what works.
-
-5. **Commit:** `feat([scope]): [description]`
-
----
-
-## Phase 6.5: Update Project Documentation
-
-Based on what you just implemented, identify which documentation files are affected
-and update them. Common candidates:
-
-- **README.md** — new commands, env vars, setup steps, or usage changed
-- **docs/** — any guides or API reference covering the changed functionality
-- **CHANGELOG.md** — add an entry for any user-facing change
-
-State up front which files you will update (e.g. "Updating README.md: adding env var X").
-Skip entirely if nothing user-facing changed (internal refactor, test-only changes).
-
-If docs were updated, commit them before calling `/bw-ship`:
-```bash
-git add [doc files]
-git commit -m "docs: update documentation for [feature-name]"
-```
-
----
-
-## Phase 7: Ship
-
-Run `/bw-ship` which chains:
-1. verify → typecheck, lint, test, build
-2. security → OWASP, SAST, secrets, deps
-3. review → Staff Engineer code review
-4. release → commit, push, PR
-
-`/bw-ship` handles autonomous failure internally — if any step fails in autonomous mode, it commits completed work, pushes, creates a failed PR, and exits(1). See ship.md for details.
-
----
-
-## Final Report
-
-```
-═══════════════════════════════════════════════════════════════
-FEATURE COMPLETE
-═══════════════════════════════════════════════════════════════
-
-Feature: [name]
-Branch: feature/[feature-name]
-PR: [URL]
-
-ARTIFACTS
-─────────
-• Research: docs/specs/[feature-name]/research.md
-• Spec: docs/specs/[feature-name]/spec.md
-
-PIPELINE STATUS
-───────────────
-✅ Research Complete
-✅ Spec Generated
-✅ Spec Reviewed (Staff Engineer)
-✅ Human Approved
-✅ Implemented (TDD)
-✅ Verified
-✅ Security Reviewed
-✅ Code Reviewed (Staff Engineer)
-✅ Shipped
-
-Quality gates running in CI. PR ready for team review.
-═══════════════════════════════════════════════════════════════
-```