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

234
bmad/bmm/workflows/4-implementation/story-context/README.md Normal file
View File

@@ -0,0 +1,234 @@
# Story Context Assembly Workflow
## Overview
Assembles a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story. Creates comprehensive development context for AI agents and developers working on specific stories.
## Key Features
- **Automated Context Discovery** - Scans documentation and codebase for relevant artifacts
- **XML Output Format** - Structured context optimized for LLM consumption
- **Dependency Detection** - Identifies frameworks, packages, and technical dependencies
- **Interface Mapping** - Locates existing APIs and interfaces to reuse
- **Testing Integration** - Includes testing standards and generates test ideas
- **Status Tracking** - Updates story status and maintains context references
## Usage
### Basic Invocation
```bash
workflow story-context
```
### With Specific Story
```bash
# Process specific story file
workflow story-context --input /path/to/story.md
# Using story path variable
workflow story-context --story_path "docs/stories/1.2.feature-name.md"
```
### Configuration
- **story_path**: Path to target story markdown file (defaults to latest.md)
- **auto_update_status**: Whether to automatically update story status (default: false)
## Workflow Structure
### Files Included
```
story-context/
├── workflow.yaml # Configuration and metadata
├── instructions.md # Step-by-step execution guide
├── context-template.xml # XML structure template
├── checklist.md # Validation criteria
└── README.md # This file
```
## Workflow Process
### Phase 1: Story Analysis (Steps 1-2)
- **Story Location**: Finds and loads target story markdown file
- **Content Parsing**: Extracts epic ID, story ID, title, acceptance criteria, and tasks
- **Template Initialization**: Creates initial XML context structure
- **User Story Extraction**: Parses "As a... I want... So that..." components
### Phase 2: Documentation Discovery (Step 3)
- **Keyword Analysis**: Identifies relevant terms from story content
- **Document Scanning**: Searches docs and module documentation
- **Authority Prioritization**: Prefers PRDs, architecture docs, and specs
- **Context Extraction**: Captures relevant sections with snippets
### Phase 3: Code Analysis (Step 4)
- **Symbol Search**: Finds relevant modules, functions, and components
- **Interface Identification**: Locates existing APIs and interfaces
- **Constraint Extraction**: Identifies development patterns and requirements
- **Reuse Opportunities**: Highlights existing code to leverage
### Phase 4: Dependency Analysis (Step 5)
- **Manifest Detection**: Scans for package.json, requirements.txt, go.mod, etc.
- **Framework Identification**: Identifies Unity, Node.js, Python, Go ecosystems
- **Version Tracking**: Captures dependency versions where available
- **Configuration Discovery**: Finds relevant project configurations
### Phase 5: Testing Context (Step 6)
- **Standards Extraction**: Identifies testing frameworks and patterns
- **Location Mapping**: Documents where tests should be placed
- **Test Ideas**: Generates initial test concepts for acceptance criteria
- **Framework Integration**: Links to existing test infrastructure
### Phase 6: Validation and Updates (Steps 7-8)
- **XML Validation**: Ensures proper structure and completeness
- **Status Updates**: Changes story status from Draft to ContextReadyDraft
- **Reference Tracking**: Adds context file reference to story document
- **Quality Assurance**: Validates against workflow checklist
## Output
### Generated Files
- **Primary output**: story-context-{epic_id}.{story_id}-{date}.xml
- **Story updates**: Modified original story file with context references
### Output Structure
```xml
<storyContext>
<story>
<basicInfo>
<epicId>...</epicId>
<storyId>...</storyId>
<title>...</title>
<status>...</status>
</basicInfo>
<userStory>
<asA>...</asA>
<iWant>...</iWant>
<soThat>...</soThat>
</userStory>
<acceptanceCriteria>
<criterion id="1">...</criterion>
</acceptanceCriteria>
<tasks>
<task>...</task>
</tasks>
</story>
<artifacts>
<docs>
<doc path="..." title="..." section="..." snippet="..."/>
</docs>
<code>
<file path="..." kind="..." symbol="..." lines="..." reason="..."/>
</code>
<dependencies>
<node>
<package name="..." version="..."/>
</node>
</dependencies>
</artifacts>
<interfaces>
<interface name="..." kind="..." signature="..." path="..."/>
</interfaces>
<constraints>
<constraint>...</constraint>
</constraints>
<tests>
<standards>...</standards>
<locations>
<location>...</location>
</locations>
<ideas>
<idea ac="1">...</idea>
</ideas>
</tests>
</storyContext>
```
## Requirements
- **Story File**: Valid story markdown with proper structure (epic.story.title.md format)
- **Repository Access**: Ability to scan documentation and source code
- **Documentation**: Project documentation in standard locations (docs/, src/, etc.)
## Best Practices
### Before Starting
1. **Ensure Story Quality**: Verify story has clear acceptance criteria and tasks
2. **Update Documentation**: Ensure relevant docs are current and discoverable
3. **Clean Repository**: Remove obsolete code that might confuse context assembly
### During Execution
1. **Review Extracted Context**: Verify that discovered artifacts are actually relevant
2. **Check Interface Accuracy**: Ensure identified APIs and interfaces are current
3. **Validate Dependencies**: Confirm dependency information matches project state
### After Completion
1. **Review XML Output**: Validate the generated context makes sense
2. **Test with Developer**: Have a developer review context usefulness
3. **Update Story Status**: Verify story status was properly updated
## Troubleshooting
### Common Issues
**Issue**: Context contains irrelevant or outdated information
- **Solution**: Review keyword extraction and document filtering logic
- **Check**: Ensure story title and acceptance criteria are specific and clear
**Issue**: Missing relevant code or interfaces
- **Solution**: Verify code search patterns and symbol extraction
- **Check**: Ensure relevant code follows project naming conventions
**Issue**: Dependency information is incomplete or wrong
- **Solution**: Check for multiple package manifests or unusual project structure
- **Check**: Verify dependency files are in expected locations and formats
## Customization
To customize this workflow:
1. **Modify Search Patterns**: Update instructions.md to adjust code and doc discovery
2. **Extend XML Schema**: Customize context-template.xml for additional context types
3. **Add Validation**: Extend checklist.md with project-specific quality criteria
4. **Configure Dependencies**: Adjust dependency detection for specific tech stacks
## Version History
- **v6.0.0** - XML-based context assembly with comprehensive artifact discovery
- Multi-ecosystem dependency detection
- Interface and constraint extraction
- Testing context integration
- Story status management
## Support
For issues or questions:
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
- Validate output using `checklist.md`
- Ensure story files follow expected markdown structure
- Check that repository structure supports automated discovery
---
_Part of the BMad Method v6 - BMM (Method) Module_

16
bmad/bmm/workflows/4-implementation/story-context/checklist.md Normal file
View File

@@ -0,0 +1,16 @@
# Story Context Assembly Checklist
```xml
<checklist id="bmad/bmm/workflows/4-implementation/story-context/checklist">
<item>Story fields (asA/iWant/soThat) captured</item>
<item>Acceptance criteria list matches story draft exactly (no invention)</item>
<item>Tasks/subtasks captured as task list</item>
<item>Relevant docs (5-15) included with path and snippets</item>
<item>Relevant code references included with reason and line hints</item>
<item>Interfaces/API contracts extracted if applicable</item>
<item>Constraints include applicable dev rules and patterns</item>
<item>Dependencies detected from manifests and frameworks</item>
<item>Testing standards and locations populated</item>
<item>XML structure follows story-context template format</item>
</checklist>
```

34
bmad/bmm/workflows/4-implementation/story-context/context-template.xml Normal file
View File

@@ -0,0 +1,34 @@
<story-context id="bmad/bmm/workflows/4-implementation/story-context/template" v="1.0">
<metadata>
<epicId>{{epic_id}}</epicId>
<storyId>{{story_id}}</storyId>
<title>{{story_title}}</title>
<status>{{story_status}}</status>
<generatedAt>{{date}}</generatedAt>
<generator>BMAD Story Context Workflow</generator>
<sourceStoryPath>{{story_path}}</sourceStoryPath>
</metadata>
<story>
<asA>{{as_a}}</asA>
<iWant>{{i_want}}</iWant>
<soThat>{{so_that}}</soThat>
<tasks>{{story_tasks}}</tasks>
</story>
<acceptanceCriteria>{{acceptance_criteria}}</acceptanceCriteria>
<artifacts>
<docs>{{docs_artifacts}}</docs>
<code>{{code_artifacts}}</code>
<dependencies>{{dependencies_artifacts}}</dependencies>
</artifacts>
<constraints>{{constraints}}</constraints>
<interfaces>{{interfaces}}</interfaces>
<tests>
<standards>{{test_standards}}</standards>
<locations>{{test_locations}}</locations>
<ideas>{{test_ideas}}</ideas>
</tests>
</story-context>

76
bmad/bmm/workflows/4-implementation/story-context/instructions.md Normal file
View File

@@ -0,0 +1,76 @@
<!-- BMAD BMM Story Context Assembly Instructions (v6) -->
```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 assembles a Story Context XML for a single user story by extracting ACs, tasks, relevant docs/code, interfaces, constraints, and testing guidance to support implementation.</critical>
<critical>Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery fails, HALT and request 'story_path' or 'story_dir'.</critical>
<workflow>
<step n="1" goal="Locate story and initialize output">
<action>If {{story_path}} provided and valid → use it; else auto-discover from {{story_dir}}.</action>
<action>Auto-discovery: read {{story_dir}} (dev_story_location). If invalid/missing or contains no .md files, ASK for a story file path or directory to scan.</action>
<action>If a directory is provided, list markdown files named "story-*.md" recursively; sort by last modified time; display top {{story_selection_limit}} with index, filename, path, modified time.</action>
<ask optional="true" if="{{non_interactive}} == false">"Select a story (1-{{story_selection_limit}}) or enter a path:"</ask>
<action>If {{non_interactive}} == true: choose the most recently modified story automatically. If none found, HALT with a clear message to provide 'story_path' or 'story_dir'. Else resolve selection into {{story_path}} and READ COMPLETE file.</action>
<action>Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content; parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes.</action>
<action>Extract user story fields (asA, iWant, soThat).</action>
<action>Initialize output by writing template to {default_output_file}.</action>
<template-output file="{default_output_file}">as_a</template-output>
<template-output file="{default_output_file}">i_want</template-output>
<template-output file="{default_output_file}">so_that</template-output>
</step>
<step n="2" goal="Collect relevant documentation">
<action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks<</action>
<action>Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
<template-output file="{default_output_file}">
Add artifacts.docs entries with {path, title, section, snippet} (NO invention)
</template-output>
</step>
<step n="3" goal="Analyze existing code, interfaces, and constraints">
<action>Search source tree for modules, files, and symbols matching story intent and AC keywords (controllers, services, components, tests).</action>
<action>Identify existing interfaces/APIs the story should reuse rather than recreate.</action>
<action>Extract development constraints from Dev Notes and architecture (patterns, layers, testing requirements).</action>
<template-output file="{default_output_file}">
Add artifacts.code entries with {path, kind, symbol, lines, reason}; include a brief reason explaining relevance to the story
Populate interfaces with any API/interface signatures that the developer must call (name, kind, signature, path)
Populate constraints with development rules extracted from Dev Notes and architecture (e.g., patterns, layers, testing requirements)
</template-output>
</step>
<step n="4" goal="Gather dependencies and frameworks">
<action>Detect dependency manifests and frameworks in the repo:
- Node: package.json (dependencies/devDependencies)
- Python: pyproject.toml/requirements.txt
- Go: go.mod
- Unity: Packages/manifest.json, Assets/, ProjectSettings/
- Other: list notable frameworks/configs found</action>
<template-output file="{default_output_file}">
Populate artifacts.dependencies with keys for detected ecosystems and their packages with version ranges where present
</template-output>
</step>
<step n="5" goal="Testing standards and ideas">
<action>From Dev Notes, architecture docs, testing docs, and existing tests, extract testing standards (frameworks, patterns, locations).</action>
<template-output file="{default_output_file}">
Populate tests.standards with a concise paragraph
Populate tests.locations with directories or glob patterns where tests live
Populate tests.ideas with initial test ideas mapped to acceptance criteria IDs
</template-output>
</step>
<step n="6" goal="Validate and save">
<action>Validate output XML structure and content.</action>
<invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
</step>
<step n="7" goal="Update story status and context reference">
<action>Open {{story_path}}; if Status == 'Draft' then set to 'ContextReadyDraft'; otherwise leave unchanged.</action>
<action>Under 'Dev Agent Record' → 'Context Reference' (create if missing), add or update a list item for {default_output_file}.</action>
<action>Save the story file.</action>
</step>
</workflow>
```

56
bmad/bmm/workflows/4-implementation/story-context/workflow.yaml Normal file
View File

@@ -0,0 +1,56 @@
# Story Context Creation Workflow
name: story-context
description: "Assemble a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story"
author: "BMad"
# Critical variables
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/story-context"
template: "{installed_path}/context-template.xml"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# Variables and inputs
variables:
story_path: "" # Explicit story path; auto-discovered if empty
auto_update_status: false
story_dir: "{config_source}:dev_story_location"
story_selection_limit: 10
tech_spec_search_dir: "{project-root}/docs"
tech_spec_glob_template: "tech-spec-epic-{{epic_id}}*.md"
non_interactive: true
# Output configuration
default_output_file: "{output_folder}/story-context-{{epic_id}}.{{story_id}}.xml"
# Recommended inputs
recommended_inputs:
- story_markdown: "Path to a story markdown file to build context for"
# Required tools
required_tools:
- list_files
- file_info
- read_file
- write_file
- create_directory
- glob
- search_repo
- parse_markdown
tags:
- context
- story
- planning
- bmad-v6
execution_hints:
interactive: false
autonomous: true
iterative: true