bmad-autopilot-addon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Kunin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# BMAD Autopilot Add-On v1.0.0
+
+Autonomous end-to-end software delivery powered by the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD). One command takes your project from sprint plan to reviewed, tested, PR-ready code — with full git workflow and multi-agent intelligence.
+
+## The Problem
+
+BMAD provides a structured development workflow with 50+ skills and agent personas. But using it manually means invoking each skill one at a time, navigating menus, making routine decisions, and handling git operations yourself. For a sprint with 10 stories across 3 epics, that's dozens of manual steps, context switches, and session restarts.
+
+## The Solution: BMAD Autopilot
+
+```
+/bmad-autopilot-on
+```
+
+That's it. The autopilot takes over and drives your entire sprint to completion:
+
+### What it does, story by story
+
+1. **Reads your sprint plan** — picks the next story from `sprint-status.yaml`
+2. **Creates an isolated worktree** — each story gets its own branch via `git worktree add`, keeping `main` clean
+3. **Implements the story** — invokes `bmad-dev-story` which writes code and tests following TDD (RED then GREEN)
+4. **Lints the code** — auto-detects your language (Python, JS/TS, Rust, Go, Ruby) and runs the appropriate linter on changed files only
+5. **Stages explicitly** — never runs `git add -A`. Stages only changed files with pre-commit checks: secrets scanning, file size limits, binary detection
+6. **Commits with conventional messages** — `feat(epic): story title (story-key)` with all placeholders resolved from your sprint artifacts
+7. **Runs code review** — invokes `bmad-code-review` on the worktree diff
+8. **Applies every patch** — auto-accepts all review findings, commits each fix separately for clean git history
+9. **Pushes and creates a PR** (configurable) — auto-detects your platform (GitHub/GitLab) and creates a PR/MR with a detailed body. With `create_pr: false`, merges directly to main instead.
+10. **Moves to the next story** — syncs status, exits the worktree, commits artifacts to main, picks up the next story
+11. **Runs retrospective** — when all stories in an epic are done, runs `bmad-retrospective` and lists all PR URLs for merge
+
+### What makes it autonomous
+
+The autopilot handles everything that normally requires you to be present:
+
+- **Menu navigation** — BMAD skills present menus, confirmations, and choices. The autopilot auto-selects "Continue", "Create Mode", and makes context-appropriate decisions from your PRD and architecture docs.
+- **Decision making** — when a skill asks a design question, the autopilot derives the answer from existing project artifacts (PRD, architecture, story specs). Only truly unanswerable questions pause execution.
+- **Session management** — after 3 stories, the autopilot checkpoints state to disk and tells you to start a fresh session. `/bmad-autopilot-on` in the new session resumes exactly where it left off. No work is ever repeated.
+- **Crash recovery** — if a session crashes mid-story, the next boot detects orphaned worktrees, recovers committed work (pushes it), and cleans up stale state.
+
+### When it stops (and only when)
+
+The autopilot runs until the sprint is done or hits one of exactly 5 true blockers:
+
+1. A skill needs **original creative input** not in any project document (e.g., product vision for a PRD)
+2. A **new external dependency** is needed that isn't in the project
+3. **3 consecutive test failures** with no forward progress
+4. A **security vulnerability** requiring architectural decisions beyond the story scope
+5. **Conflicting acceptance criteria** that can't be resolved from project docs
+
+Everything else — it decides, documents the decision in one sentence, and moves on.
+
+### The git workflow in detail
+
+Controlled by `git.push.create_pr` in `_bmad-addons/modules/git/config.yaml`:
+
+**PR flow** (`create_pr: true`, default) — stories are pushed and PRs are created. No auto-merge. Code reaches `main` only after PR approval.
+
+```
+main ─────────────────────────────────────────────────────────
+  │                                          (artifacts only)
+  ├── story/1-1 ──→ push + PR #42 (→ main)
+  │        │
+  │        └── story/1-2 ──→ push + PR #43 (→ story/1-1)
+  │                 │
+  │                 └── story/1-3 ──→ push + PR #44 (→ story/1-2)
+  │
+  Epic 1 complete → retrospective
+  → "Ready to merge: PR #42, #43, #44"
+```
+
+When previous stories have pending PRs, the autopilot creates **stacked PRs** — each story branches from the previous story's branch and targets it. When a PR is merged on the platform, subsequent PRs automatically retarget.
+
+**Direct merge flow** (`create_pr: false`) — stories are merged to `main` immediately after push:
+
+```
+main ── story/1-1 ──→ merge ── story/1-2 ──→ merge ── story/1-3 ──→ merge
+```
+
+Each story is fully isolated in its own worktree. No half-finished code on `main`. The autopilot tracks git metadata in its own `git-status.yaml` (commit SHA, push status, PR URL, lint results) — it never modifies BMAD's `sprint-status.yaml`. Implementation artifacts (sprint status, story files, planning docs) are always committed to `main` after each story, regardless of merge strategy.
+
+See [`modules/git/branching-and-pr-strategy.md`](_bmad-addons/modules/git/branching-and-pr-strategy.md) for the full branching and PR decision matrix.
+
+---
+
+## Multi-Agent Intelligence
+
+Beyond the autopilot, the add-on includes 7 multi-agent skills that launch parallel subagents for tasks that benefit from diverse perspectives:
+
+### Parallel Code Review (`/bmad-ma-code-review`)
+
+Three independent reviewers run simultaneously on the same diff:
+
+| Agent | Perspective | Access |
+|-------|------------|--------|
+| **Blind Hunter** | Pure adversarial — finds bugs from code alone | Diff only, no project context |
+| **Edge Case Hunter** | Boundary conditions, race conditions, missing validation | Full codebase access |
+| **Acceptance Auditor** | Verifies every acceptance criterion is met | Diff + story spec |
+
+Results are triaged: duplicates merged, contradictions flagged, findings classified as PATCH / WARN / DISMISS.
+
+### Brownfield Analysis Pipeline
+
+> Codebase mapping inspired by [GSD's map-codebase](https://github.com/gsd-build/get-shit-done). Adapted with distinct output format, enriched agent prompts, and BMAD-specific downstream integration.
+
+For existing codebases, three skills chain together:
+
+**`/bmad-ma-codebase-map`** — 5 parallel agents scan the codebase simultaneously:
+- Stack Analyzer (languages, frameworks, versions)
+- Architecture Mapper (modules, patterns, data flow)
+- Quality Assessor (tests, CI/CD, conventions)
+- Concerns Hunter (TODOs, deprecated APIs, security issues, dead code)
+- Integration Mapper (external APIs, databases, env vars)
+
+**`/bmad-ma-assess`** — 3 parallel agents produce actionable findings:
+- Dependency Auditor (CVEs, outdated packages, upgrade paths)
+- Debt Classifier (prioritized tech debt with effort estimates)
+- Migration Analyzer (framework upgrade paths and phased roadmap)
+
+**`/bmad-ma-reverse-architect`** — 3 parallel agents extract architecture from code:
+- Component Mapper (module boundaries, dependency graph)
+- Data Flow Tracer (request lifecycle, state management)
+- Pattern Extractor (design patterns, conventions, error handling)
+
+Output: a BMAD-compatible `architecture.md` that feeds directly into `bmad-create-epics-and-stories`.
+
+### Migration Planning (`/bmad-ma-migrate`)
+
+A 12-step workflow for taking a codebase from one stack to another. 4 subagent fan-outs across the process:
+
+1. Validate prerequisites and get target stack from user
+2. Auto-recommend migration strategy (strangler fig / big bang / branch-by-abstraction / parallel run)
+3. **Parallel**: Stack Mapper + Dependency Analyzer produce compatibility matrix
+4. Design coexistence layer (old + new code running together)
+5. Build phased roadmap ordered by dependency graph
+6. Generate per-component migration cards with effort/risk
+7. Plan data migration (schema changes, dual-write, backfill)
+8. Design API compatibility (versioning, deprecation timeline)
+9. **Parallel**: Test Parity Analyzer maps old tests to new equivalents
+10. **Parallel**: Risk Assessor produces per-phase risk matrix with rollback triggers
+11. Generate BMAD-compatible epics for sprint planning
+12. Finalize migration plan, epics, and tracking artifacts
+
+### Research and Discussion
+
+**`/bmad-ma-research`** — Fan out research across multiple topics in parallel, each with web search access. Results synthesized into a unified report.
+
+**`/bmad-ma-party-mode`** — Launch 2-3 BMAD personas (architect, PM, QA, dev, etc.) as parallel agents debating a topic. Multiple rounds where personas respond to each other. Produces consensus points, disagreements, and action items.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install BMAD with the core method and Test Architect module
+npx bmad-method install --modules bmm,tea --tools claude-code --yes
+```
+
+This installs:
+- **BMM** (BMad Method) — the core development workflow with 34+ skills
+- **TEA** (Test Architect Enterprise) — risk-based test strategy, ATDD, CI quality gates, test framework scaffolding
+
+For interactive module selection (see all available modules):
+```bash
+npx bmad-method install
+```
+
+For multiple tools:
+```bash
+npx bmad-method install --modules bmm,tea --tools claude-code,cursor --yes
+```
+
+```bash
+# 2. Install the autopilot add-on (interactive tool selection)
+bash _bmad-addons/install.sh
+
+# Or specify tools directly:
+bash _bmad-addons/install.sh --tools claude-code,cursor
+
+# Or install for all supported tools:
+bash _bmad-addons/install.sh --tools all
+
+# 3. Start the autopilot in your IDE
+/bmad-autopilot-on
+```
+
+### BMAD Modules
+
+| Module | Code | Description |
+|--------|------|-------------|
+| **BMad Method** | `bmm` | Core development workflow — analysis, planning, implementation, review |
+| **Test Architect** | `tea` | Enterprise test strategy — ATDD, test design, CI setup, NFR assessment, traceability |
+
+The TEA module adds these skills to your toolkit:
+
+| Skill | Description |
+|-------|-------------|
+| `/bmad-testarch-test-design` | Risk-based test planning |
+| `/bmad-testarch-framework` | Initialize production-ready test framework (Playwright, Cypress) |
+| `/bmad-testarch-atdd` | Generate failing acceptance tests (TDD red phase) |
+| `/bmad-testarch-automate` | Expand test automation coverage |
+| `/bmad-testarch-ci` | Configure CI/CD quality pipeline with test execution |
+| `/bmad-testarch-nfr` | Non-functional requirements assessment (performance, security) |
+| `/bmad-testarch-test-review` | Quality audit with 0-100 scoring |
+| `/bmad-testarch-trace` | Coverage traceability matrix and gate decisions |
+| `/bmad-teach-me-testing` | Interactive testing education (7 sessions) |
+
+## Supported Tools
+
+The add-on uses the universal SKILL.md format — same skills work across all 9 tools:
+
+| Tool | Directory |
+|------|-----------|
+| Claude Code | `.claude/skills/` |
+| Cursor | `.cursor/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| Gemini CLI | `.gemini/skills/` |
+| Cline | `.cline/skills/` |
+| Roo Code | `.roo/skills/` |
+| Trae | `.trae/skills/` |
+| Kiro | `.kiro/skills/` |
+| GitHub Copilot | `.github/copilot/skills/` |
+
+```bash
+bash _bmad-addons/install.sh --tools claude-code,cursor,gemini-cli
+```
+
+## Git Platforms
+
+| Platform | CLI | Auto-Detect | API Fallback |
+|----------|-----|-------------|-------------|
+| GitHub | `gh` | `github.com` | No |
+| GitLab | `glab` | `gitlab.*` | No |
+| Bitbucket | `bb` | `bitbucket.org` | Yes (`BITBUCKET_TOKEN`) |
+| Gitea | `tea` | Explicit config | Yes (`GITEA_TOKEN` + `base_url`) |
+
+No CLI installed? The addon falls back to **git_only mode** (direct merge, no PRs).
+
+To explicitly choose between PR and direct merge regardless of platform:
+```yaml
+# _bmad-addons/modules/git/config.yaml
+git:
+  push:
+    create_pr: true   # PR flow (default) — push + PR, no auto-merge
+    create_pr: false  # Direct merge — merge to main after each story
+```
+
+## Supported Languages (Linting)
+
+| Language | Linters | Language | Linters |
+|----------|---------|----------|---------|
+| Python | ruff, flake8, pylint | Java | checkstyle, pmd |
+| JavaScript/TS | eslint, biome | C/C++ | cppcheck, clang-tidy |
+| Rust | cargo clippy | C# | dotnet format |
+| Go | golangci-lint | Swift | swiftlint |
+| Ruby | rubocop | PL/SQL | sqlfluff |
+| Kotlin | ktlint, detekt | PHP | phpstan, phpcs |
+
+First found wins per language. Multi-language projects (monorepos) lint all languages in one pass. See [Extending](docs/EXTENDING.md) to add more.
+
+## Requirements
+
+- [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) v6.2.0+
+- A supported AI code agent (see table above)
+- Git repository with at least one commit
+- Platform CLI for PR creation (optional — see table above)
+
+## Documentation
+
+- [Installation Guide](docs/INSTALLATION.md)
+- [Usage Guide](docs/USAGE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Configuration Reference](docs/CONFIGURATION.md)
+- [Extending (Platforms & Languages)](docs/EXTENDING.md)
+- [Contributing](docs/CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT

package/_bmad-addons/.secrets-allowlist

@@ -0,0 +1,26 @@
+# Patterns and paths exempt from secrets scanning
+# One pattern per line. Supports glob syntax.
+
+# Test files commonly contain mock secrets
+test/**
+tests/**
+**/test_*
+**/*_test.*
+**/*_spec.*
+spec/**
+
+# Example/template files
+*.example
+*.sample
+*.template
+.env.example
+.env.sample
+
+# Documentation
+docs/**
+*.md
+
+# Fixture/mock data
+**/fixtures/**
+**/mocks/**
+**/testdata/**

package/_bmad-addons/BMAD.md

@@ -0,0 +1,216 @@
+# BMAD Workflow — Mandatory for All AI Agents
+
+Always use the BMAD workflow for every story. Never skip steps. When unsure, invoke `bmad-help` first.
+
+---
+
+## Navigation & orientation
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-help` | First resort when unsure what to do next — analyzes current state and recommends the right skill or workflow |
+
+---
+
+## Autopilot & git workflow (add-on)
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-autopilot-on` | Start autonomous story execution with git branching, commits, and PRs |
+| `bmad-autopilot-off` | Disengage autopilot, show sprint + git status report |
+
+When the autopilot or git add-on is active:
+- **NEVER** use `git add -A` or `git add .` — always stage files explicitly by name
+- **NEVER** commit secrets, API keys, tokens, or credentials
+- Each story gets its own isolated worktree and branch (`story/<key>`)
+- Commits use conventional format: `feat(<epic>): <title> (<key>)`
+
+---
+
+## Full skill reference by lifecycle phase
+
+### Phase 0 — Project inception (new projects)
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-product-brief` | Start here for a new project — collaborative discovery of goals, constraints, users |
+| `bmad-create-prd` | Create a full Product Requirements Document from scratch |
+| `bmad-edit-prd` | Update or revise an existing PRD |
+| `bmad-validate-prd` | Validate a PRD against BMAD standards before moving to design |
+| `bmad-create-architecture` | Create technical architecture and solution design decisions |
+| `bmad-create-ux-design` | Plan UX patterns and design specifications |
+| `bmad-create-epics-and-stories` | Break PRD + architecture into epics and story list |
+| `bmad-generate-project-context` | Generate `project-context.md` with AI rules (run once after inception) |
+| `bmad-document-project` | Document an existing (brownfield) project to give AI agents context |
+
+### Phase 1 — Sprint planning (before development starts)
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-sprint-planning` | Generate `sprint-status.yaml` tracking file from epics list |
+| `bmad-sprint-status` | Check current sprint status and surface risks at any time |
+| `bmad-correct-course` | Manage significant scope or direction changes mid-sprint |
+
+### Phase 2 — Story development (the mandatory per-story loop)
+
+See **Mandatory sequence per story** section below.
+
+### Phase 3 — Epic close-out
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-retrospective` | Run after all stories in an epic are `done`; saves lessons, marks epic `done` |
+
+---
+
+## Quick path — for small changes without full story ceremony
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-quick-dev` | Implement any user intent (bug fix, tweak, refactor) directly — follows project conventions |
+
+> Use the quick path only for genuinely small, isolated changes. For anything touching multiple components or requiring E2E coverage, use the full story loop.
+
+---
+
+## Multi-agent skills (add-on)
+
+These launch parallel subagents for deeper, faster analysis:
+
+| Skill | Agents | When to use |
+|-------|--------|-------------|
+| `bmad-ma-code-review` | 3 | Parallel adversarial code review (Blind Hunter + Edge Case + Acceptance) |
+| `bmad-ma-codebase-map` | 5 | Brownfield codebase mapping (stack, architecture, quality, concerns, integrations) |
+| `bmad-ma-assess` | 3 | Tech debt assessment (dependency audit, debt classification, migration analysis) |
+| `bmad-ma-reverse-architect` | 3 | Extract architecture from existing code (components, data flow, patterns) |
+| `bmad-ma-migrate` | 4 | Full migration planning — 12 steps from current stack to target stack |
+| `bmad-ma-research` | N | Parallel research fan-out with web search |
+| `bmad-ma-party-mode` | 2-3 | Multi-persona discussion (architect, PM, QA, etc. debating in parallel) |
+
+### Brownfield analysis pipeline
+
+```
+bmad-ma-codebase-map → bmad-ma-assess → bmad-ma-reverse-architect → bmad-ma-migrate
+```
+
+Run `bmad-ma-codebase-map` first on any existing codebase. The other MA skills consume its outputs.
+
+---
+
+## Research & discovery skills
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-technical-research` | Research technologies, frameworks, or architectural trade-offs |
+| `bmad-domain-research` | Research a business domain or industry |
+| `bmad-market-research` | Research market competition and customers |
+| `bmad-brainstorming` | Facilitate structured ideation sessions |
+| `bmad-advanced-elicitation` | Push the model to reconsider and refine recent output |
+
+---
+
+## QA & test architecture skills
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-qa-generate-e2e-tests` | Generate E2E tests for existing features (retroactive coverage) |
+| `bmad-testarch-framework` | Initialize test framework (Playwright / Cypress) |
+| `bmad-testarch-atdd` | Generate failing acceptance tests (TDD cycle) |
+| `bmad-testarch-test-design` | Create system-level or epic-level test plans |
+| `bmad-testarch-nfr` | Assess non-functional requirements (performance, security, reliability) |
+| `bmad-testarch-ci` | Scaffold CI/CD quality pipeline with test execution |
+| `bmad-testarch-trace` | Generate traceability matrix and quality gate decisions |
+| `bmad-testarch-test-review` | Review test quality against best practices |
+| `bmad-testarch-automate` | Expand test automation coverage across the codebase |
+| `bmad-teach-me-testing` | Interactive testing education sessions |
+
+---
+
+## Review skills
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-code-review` | Full adversarial code review (3 layers) — mandatory step 5 of per-story loop |
+| `bmad-review-adversarial-general` | Cynical critical review of any artifact (specs, designs, docs) |
+| `bmad-review-edge-case-hunter` | Exhaustive edge-case and boundary analysis of code or specs |
+| `bmad-editorial-review-structure` | Structural editing of documents |
+| `bmad-editorial-review-prose` | Copy-editing for communication issues in documents |
+
+---
+
+## Agent role personas
+
+These skills activate an interactive agent persona. They stay in character until given an exit command.
+
+| Skill | Persona |
+|-------|---------|
+| `bmad-agent-pm` | Product Manager |
+| `bmad-agent-analyst` | Business Analyst |
+| `bmad-agent-architect` | Solution Architect |
+| `bmad-agent-ux-designer` | UX Designer |
+| `bmad-agent-dev` | Developer |
+| `bmad-agent-qa` | QA Engineer |
+| `bmad-agent-sm` | Scrum Master |
+| `bmad-agent-tech-writer` | Technical Writer |
+| `bmad-agent-quick-flow-solo-dev` | Rapid full-stack solo developer |
+| `bmad-party-mode` | All agents in one group discussion |
+
+---
+
+## Document utilities
+
+| Skill | When to use |
+|-------|-------------|
+| `bmad-shard-doc` | Split a large markdown document into organized smaller files |
+| `bmad-index-docs` | Generate or update an `index.md` for a docs folder |
+| `bmad-distillator` | Lossless LLM-optimized compression of source documents |
+
+---
+
+## Mandatory sequence per story
+
+| Step | Skill | sprint-status.yaml transition | Definition of Done |
+|------|-------|-------------------------------|--------------------|
+| 1 | `bmad-create-story` | → `ready-for-dev` | Story file exists, all sections complete |
+| 2 | `bmad-check-implementation-readiness` | (no change) | Readiness check passes with no blockers |
+| 3 | `bmad-dev-story` (RED) | → `in-progress` | Tests written and **confirmed failing** before any implementation |
+| 4 | `bmad-dev-story` (GREEN) | → `review` | All tests pass; pass count stated explicitly (e.g. "9/9 passed") |
+| 5 | `bmad-code-review` | (no change) | All review layers complete; findings triaged |
+| 6 | Apply `patch` findings + re-run tests | → `done` | All patch tasks completed, tests still green, pass count confirmed |
+| 7 | `bmad-retrospective` (per epic, after all stories done) | epic → `done` | Retrospective output saved; epic marked done |
+
+## Task list hygiene
+
+BMAD skills only update `_bmad-output/implementation-artifacts/sprint-status.yaml` — they do NOT update the Claude Code task list.
+
+The task list must always reflect the full BMAD work breakdown. Before starting a story, create a task for **each step** above. Keep the list granular enough that anyone can see exactly where work stands at a glance.
+
+Rules:
+- Create all step-tasks for a story **before** starting work on it
+- Mark each step-task `in_progress` when you begin it
+- Mark each step-task `completed` immediately when done — never batch
+- Do not start step N+1 until step N is `completed`
+- `sprint-status.yaml` is updated automatically by BMAD skills — do NOT edit it manually
+
+## Issue and patch tracking
+
+When tests fail **or** code review produces `patch` findings, each issue gets its own task:
+
+- Create one task per distinct issue / patch item (not one task for all issues)
+- Name it clearly: e.g. "Fix: `deleteTask` transaction not awaited" or "Patch P1: rollback missing on Ctrl+Down"
+- Mark it `in_progress` when fixing, `completed` only after the fix is applied **and the relevant test passes**
+- State the test result explicitly: "fixed — 10/10 passed"
+- Do not mark the parent step-task `completed` until all its issue/patch tasks are `completed`
+
+## Story file updates
+
+After `bmad-dev-story` completes, fill in the story file's `Dev Agent Record` section:
+- List all files changed
+- Note any non-obvious decisions or deviations from the spec
+- Record final test pass count
+
+## Test result transparency
+
+Every time tests are run, state the result explicitly in your response:
+- `N/N passed` — or — `N passed, M failed` with failure details
+- Never say "tests pass" without the count