ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

agent manifest generation, party mode uses it, and tea persona compression

Browse Source
This commit is contained in:
Brian Madison
2025-10-04 19:28:10 -05:00
parent bbb37a7a86
commit c7d76a3037
319 changed files with 39416 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
bmad/bmm/workflows/4-implementation/review-story/README.md Normal file
View File

@@ -0,0 +1,72 @@
# Review Story (Senior Developer Review)
Perform an AI-driven Senior Developer Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.
## What It Does
- Auto-discovers the target story or accepts an explicit `story_path`
- Verifies the story is in a reviewable state (e.g., Ready for Review/Review)
- Loads Story Context (from Dev Agent Record → Context Reference or auto-discovery)
- Locates the epic Tech Spec and relevant architecture/standards docs
- Uses MCP servers for best-practices and security references; falls back to web search
- Reviews implementation vs Acceptance Criteria, Tech Spec, and repo standards
- Evaluates code quality, security, and test coverage
- Appends a "Senior Developer Review (AI)" section to the story with findings and action items
- Optionally updates story Status based on outcome
## How to Invoke
- By workflow name (if supported):
- `workflow review-story`
- By path:
- `workflow {project-root}/bmad/bmm/workflows/4-implementation/review-story/workflow.yaml`
## Inputs and Variables
- `story_path` (optional): Explicit path to a story file
- `story_dir` (from config): `{project-root}/bmad/bmm/config.yaml` → `dev_story_location`
- `allow_status_values`: Defaults include `Ready for Review`, `Review`
- `auto_discover_context` (default: true)
- `auto_discover_tech_spec` (default: true)
- `tech_spec_glob_template`: `tech-spec-epic-{{epic_num}}*.md`
- `arch_docs_search_dirs`: Defaults to `docs/` and `outputs/`
- `enable_mcp_doc_search` (default: true)
- `enable_web_fallback` (default: true)
- `update_status_on_result` (default: false)
## Story Updates
- Appends a section titled: `Senior Developer Review (AI)` at the end
- Adds a Change Log entry: "Senior Developer Review notes appended"
- If enabled, updates `Status` based on outcome
## Persistence and Backlog
To ensure review findings become actionable work, the workflow can persist action items to multiple targets (configurable):
- Story tasks: Inserts unchecked items under `Tasks / Subtasks` in a "Review Follow-ups (AI)" subsection so `dev-story` can pick them up next.
- Story review section: Keeps a full list under "Senior Developer Review (AI) → Action Items".
- Backlog file: Appends normalized rows to `docs/backlog.md` (created if missing) for cross-cutting or longer-term improvements.
- Epic follow-ups: If an epic Tech Spec is found, appends to its `Post-Review Follow-ups` section.
Configure via `workflow.yaml` variables:
- `persist_action_items` (default: true)
- `persist_targets`: `story_tasks`, `story_review_section`, `backlog_file`, `epic_followups`
- `backlog_file` (default: `{project-root}/docs/backlog.md`)
- `update_epic_followups` (default: true)
- `epic_followups_section_title` (default: `Post-Review Follow-ups`)
Routing guidance:
- Put must-fix items to ship the story into the story’s tasks.
- Put same-epic but non-blocking improvements into the epic Tech Spec follow-ups.
- Put cross-cutting, future, or refactor work into the backlog file.
## Related Workflows
- `dev-story` — Implements tasks/subtasks and can act on review action items
- `story-context` — Generates Story Context for a single story
- `tech-spec` — Generates epic Tech Spec documents
_Part of the BMAD Method v6 — Implementation Phase_

12
bmad/bmm/workflows/4-implementation/review-story/backlog_template.md Normal file
View File

@@ -0,0 +1,12 @@
# Engineering Backlog
This backlog collects cross-cutting or future action items that emerge from reviews and planning.
Routing guidance:
- Use this file for non-urgent optimizations, refactors, or follow-ups that span multiple stories/epics.
- Must-fix items to ship a story belong in that story’s `Tasks / Subtasks`.
- Same-epic improvements may also be captured under the epic Tech Spec `Post-Review Follow-ups` section.
| Date | Story | Epic | Type | Severity | Owner | Status | Notes |
| ---- | ----- | ---- | ---- | -------- | ----- | ------ | ----- |

22
bmad/bmm/workflows/4-implementation/review-story/checklist.md Normal file
View File

@@ -0,0 +1,22 @@
# Senior Developer Review - Validation Checklist
- [ ] Story file loaded from `{{story_path}}`
- [ ] Story Status verified as one of: {{allow_status_values}}
- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
- [ ] Story Context located or warning recorded
- [ ] Epic Tech Spec located or warning recorded
- [ ] Architecture/standards docs loaded (as available)
- [ ] Tech stack detected and documented
- [ ] MCP doc search performed (or web fallback) and references captured
- [ ] Acceptance Criteria cross-checked against implementation
- [ ] File List reviewed and validated for completeness
- [ ] Tests identified and mapped to ACs; gaps noted
- [ ] Code quality review performed on changed files
- [ ] Security review performed on changed files and dependencies
- [ ] Outcome decided (Approve/Changes Requested/Blocked)
- [ ] Review notes appended under "Senior Developer Review (AI)"
- [ ] Change Log updated with review entry
- [ ] Status updated according to settings (if enabled)
- [ ] Story saved successfully
_Reviewer: {{user_name}} on {{date}}_

176
bmad/bmm/workflows/4-implementation/review-story/instructions.md Normal file
View File

@@ -0,0 +1,176 @@
# Senior Developer Review - Workflow Instructions
```xml
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
<critical>This workflow performs a Senior Developer Review on a story flagged Ready for Review, appends structured review notes, and can update the story status based on the outcome.</critical>
<critical>Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery of the target story fails, HALT with a clear message to provide 'story_path' or 'story_dir'.</critical>
<critical>Only modify the story file in these areas: Status (optional per settings), Dev Agent Record (Completion Notes), File List (if corrections are needed), Change Log, and the appended "Senior Developer Review (AI)" section at the end of the document.</critical>
<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
<workflow>
<step n="1" goal="Locate story and verify review status">
<action>If {{story_path}} was provided → use it. Else auto-discover from {{story_dir}} by listing files matching pattern: "story-*.md" (recursive), sort by last modified (newest first), present top {{story_selection_limit}}.</action>
<ask optional="true" if="{{non_interactive}} == false">Select a story (1-{{story_selection_limit}}) or enter a path:</ask>
<action>Resolve {{story_path}} and read the COMPLETE file.</action>
<action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available.</action>
<action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log.</action>
<check>If Status is not one of {{allow_status_values}} → HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent).</check>
<check>If story cannot be read → HALT.</check>
</step>
<step n="2" goal="Resolve context and specification inputs">
<action>Locate Story Context: Under Dev Agent Record → Context Reference, read referenced path(s). If missing and {{auto_discover_context}}: search {{output_folder}} for files named "story-context-{{epic_num}}.{{story_num}}*.xml"; pick the most recent.</action>
<check>If no context found → Continue but record a WARNING in review notes: "No Story Context found".</check>
<action>Locate Epic Tech Spec: If {{auto_discover_tech_spec}}, search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}); else use provided input.</action>
<check>If no tech spec found → Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}".</check>
<action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect any testing, coding standards, security, and architectural patterns.</action>
</step>
<step n="3" goal="Detect tech stack and establish best-practice reference set">
<action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
<action>If {{enable_mcp_doc_search}} and MCP servers are available → Use them to search for up-to-date best practices, security advisories, and framework-specific guidance relevant to the detected stack and the story's domain.</action>
<action>If MCP is unavailable or insufficient and {{enable_web_fallback}} → Perform targeted web searches and fetch authoritative references (framework docs, OWASP, language style guides). Prefer official documentation and widely-recognized standards.</action>
<action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
</step>
<step n="4" goal="Assess implementation against acceptance criteria and specs">
<action>From the story, read Acceptance Criteria and Tasks/Subtasks with their completion state.</action>
<action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
<action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
<action>For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly.</action>
<check>If critical architecture constraints are violated (e.g., layering, dependency rules) → flag as High severity finding.</check>
</step>
<step n="5" goal="Perform code quality and risk review">
<action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
<action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, unvalidated redirects, CORS misconfig, dependency vulnerabilities (based on manifests).</action>
<action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
<action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
</step>
<step n="6" goal="Decide review outcome and prepare notes">
<action>Determine outcome: Approve, Changes Requested, or Blocked.</action>
<action>Prepare a structured review report with sections: Summary, Outcome, Key Findings (by severity), Acceptance Criteria Coverage, Test Coverage and Gaps, Architectural Alignment, Security Notes, Best-Practices and References, Action Items.</action>
<action>For Action Items, use imperative phrasing and map each to related ACs or files. Include suggested owners if clear.</action>
</step>
<step n="7" goal="Append review to story and update metadata">
<action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
<action>Insert subsections:
- Reviewer: {{user_name}}
- Date: {{date}}
- Outcome: (Approve | Changes Requested | Blocked)
- Summary
- Key Findings
- Acceptance Criteria Coverage
- Test Coverage and Gaps
- Architectural Alignment
- Security Notes
- Best-Practices and References (with links)
- Action Items
</action>
<action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
<action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
<action>Save the story file.</action>
</step>
<step n="8" goal="Persist action items to tasks/backlog/epic">
<action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
<action if="{{persist_action_items}} == true and 'story_tasks' in {{persist_targets}}">
Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
</action>
<ask optional="true" if="{{non_interactive}} == false">Confirm adding follow-ups into story Tasks/Subtasks. Proceed?</ask>
<action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
</action>
<action if="{{persist_action_items}} == true and ('epic_followups' in {{persist_targets}} or {{update_epic_followups}} == true)">
If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}.
</action>
<action>Save modified files.</action>
<action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
</step>
<step n="9" goal="Validation and completion">
<invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.xml</invoke-task>
<action>Report workflow completion.</action>
</step> <step n="1" goal="Locate story and verify review status">
<action>If {{story_path}} was provided → use it. Else auto-discover from {{story_dir}} by listing files matching pattern: "story-*.md" (recursive), sort by last modified (newest first), present top {{story_selection_limit}}.</action>
<ask optional="true" if="{{non_interactive}} == false">Select a story (1-{{story_selection_limit}}) or enter a path:</ask>
<action>Resolve {{story_path}} and read the COMPLETE file.</action>
<action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available.</action>
<action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log.</action>
<check>If Status is not one of {{allow_status_values}} → HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent).</check>
<check>If story cannot be read → HALT.</check>
</step>
<step n="2" goal="Resolve context and specification inputs">
<action>Locate Story Context: Under Dev Agent Record → Context Reference, read referenced path(s). If missing and {{auto_discover_context}}: search {{output_folder}} for files named "story-context-{{epic_num}}.{{story_num}}*.xml"; pick the most recent.</action>
<check>If no context found → Continue but record a WARNING in review notes: "No Story Context found".</check>
<action>Locate Epic Tech Spec: If {{auto_discover_tech_spec}}, search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}); else use provided input.</action>
<check>If no tech spec found → Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}".</check>
<action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect any testing, coding standards, security, and architectural patterns.</action>
</step>
<step n="3" goal="Detect tech stack and establish best-practice reference set">
<action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
<action>If {{enable_mcp_doc_search}} and MCP servers are available → Use them to search for up-to-date best practices, security advisories, and framework-specific guidance relevant to the detected stack and the story's domain.</action>
<action>If MCP is unavailable or insufficient and {{enable_web_fallback}} → Perform targeted web searches and fetch authoritative references (framework docs, OWASP, language style guides). Prefer official documentation and widely-recognized standards.</action>
<action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
</step>
<step n="4" goal="Assess implementation against acceptance criteria and specs">
<action>From the story, read Acceptance Criteria and Tasks/Subtasks with their completion state.</action>
<action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
<action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
<action>For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly.</action>
<check>If critical architecture constraints are violated (e.g., layering, dependency rules) → flag as High severity finding.</check>
</step>
<step n="5" goal="Perform code quality and risk review">
<action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
<action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, unvalidated redirects, CORS misconfig, dependency vulnerabilities (based on manifests).</action>
<action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
<action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
</step>
<step n="6" goal="Decide review outcome and prepare notes">
<action>Determine outcome: Approve, Changes Requested, or Blocked.</action>
<action>Prepare a structured review report with sections: Summary, Outcome, Key Findings (by severity), Acceptance Criteria Coverage, Test Coverage and Gaps, Architectural Alignment, Security Notes, Best-Practices and References, Action Items.</action>
<action>For Action Items, use imperative phrasing and map each to related ACs or files. Include suggested owners if clear.</action>
</step>
<step n="7" goal="Append review to story and update metadata">
<action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
<action>Insert subsections:
- Reviewer: {{user_name}}
- Date: {{date}}
- Outcome: (Approve | Changes Requested | Blocked)
- Summary
- Key Findings
- Acceptance Criteria Coverage
- Test Coverage and Gaps
- Architectural Alignment
- Security Notes
- Best-Practices and References (with links)
- Action Items
</action>
<action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
<action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
<action>Save the story file.</action>
</step>
<step n="8" goal="Follow-up options" optional="true">
<action>If action items are straightforward and within safety bounds, ASK whether to create corresponding unchecked items under "Tasks / Subtasks" so the `dev-story` workflow can implement them next. If approved, append them under an Action Items subsection.</action>
<action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
</step>
<step n="9" goal="Validation and completion">
<invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.xml</invoke-task>
<action>Report workflow completion.</action>
</step>
</workflow>
```

99
bmad/bmm/workflows/4-implementation/review-story/workflow.yaml Normal file
View File

@@ -0,0 +1,99 @@
# Review Story Workflow
name: review-story
description: "Perform a Senior Developer Review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story."
author: "BMad"
# Critical variables from config
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
date: system-generated
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/review-story"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# This is an action workflow (no output template document)
template: false
# Variables (can be provided by caller)
variables:
story_path: "" # Explicit path to a story markdown file
story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
story_selection_limit: 10
allow_status_values: |
- Ready for Review
- Review
auto_discover_context: true
auto_discover_tech_spec: true
tech_spec_search_dir: "{project-root}/docs"
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
arch_docs_search_dirs: |
- "{project-root}/docs"
- "{output_folder}"
arch_docs_file_names: |
- prd.md
- epics.md
- high-level-architecture.md
- tech-stack.md
- unified-project-structure.md
- coding-standards.md
- testing-strategy.md
- security-guidelines.md
- backend-architecture.md
- frontend-architecture.md
- data-models.md
- database-schema.md
- rest-api-spec.md
- external-apis.md
enable_mcp_doc_search: true # Prefer enabled MCP servers for doc/best-practice lookup
enable_web_fallback: true # Fallback to web search/read-url if MCP not available
update_status_on_result: false # If true, update story Status based on review outcome
status_on_approve: "Done"
status_on_changes_requested: "InProgress"
# Persistence controls for review action items and notes
persist_action_items: true
# Valid targets: story_tasks, story_review_section, backlog_file, epic_followups
persist_targets: |
- story_review_section
- story_tasks
- backlog_file
- epic_followups
backlog_file: "{project-root}/docs/backlog.md"
update_epic_followups: true
epic_followups_section_title: "Post-Review Follow-ups"
create_github_issues: false
non_interactive: true
# Recommended inputs
recommended_inputs:
- story_markdown: "Path to the story markdown file flagged Ready for Review"
- tech_spec: "Epic technical specification document (auto-discovered if omitted)"
- story_context: "Story Context XML/JSON path (auto-discovered if omitted)"
# Required tools (conceptual; executor should provide equivalents)
required_tools:
- list_files
- file_info
- read_file
- write_file
- search_repo
- parse_markdown
- glob
- mcp_doc_search # Use available MCP servers to search docs/best-practices
- web_search # Fallback research
- read_url # Fetch references
tags:
- review
- code-review
- quality
- testing
- bmad-v6
execution_hints:
interactive: false # Minimize prompts; intended to run deterministically
autonomous: true # Proceed without user input unless blocked
iterative: true