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

feat: WIP create-docv2

Browse Source
This commit is contained in:
Brian Madison
2025-07-06 00:10:00 -05:00
parent be9453f234
commit c107af0598
16 changed files with 4064 additions and 1916 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
common/tasks/create-doc2.md Normal file
View File

@@ -0,0 +1,208 @@
# Create Document from Template (YAML Driven)
## Purpose
Create documents using YAML templates to drive interactive, section-by-section collaboration between AI and user.
## Core Rules
1. **NEVER output YAML** - Final document contains only clean markdown
2. **Interactive by default** - Work section-by-section unless YOLO mode
3. **YAML template drives all behavior** - Parse template, follow instructions exactly
4. **Apply elicitation when specified** - Use advanced elicitation for marked sections
5. **Present sections cleanly** - Show content for review, then apply elicitation if flagged
## YAML Template Format
Templates are full YAML files with this structure:
```yaml
template:
id: template-name
name: Human Readable Name
output:
format: markdown
filename: docs/output.md
title: "{{variable}} Document Title"
sections:
- id: section-id
title: Section Title
instruction: "Detailed guidance for this section"
elicit: true
condition: "has ui"
choices:
repository: [Monorepo, Polyrepo]
```
## Processing Flow
### 1. Parse YAML Template
- Load template metadata (id, name, output settings)
- Extract `sections` list (required)
- Note any section with `elicit: true`, `condition: "text"`, `choices`, or `repeatable: true`
- Handle nested sections for complex document structure
- For repeatable sections, use the template structure defined in the section
### 2. Set User Preferences
**Interaction Mode:** Currently Interactive (type `#yolo` to toggle to YOLO mode)
**Output Location:** Confirm file output location from template (e.g., `docs/prd.md`). If environment doesn't support file writing (like web UI), will keep content in chat until complete.
### 3. Process Each Section
For each section in order:
**Interactive Mode:**
1. **Skip if condition unmet** - If `condition: "has ui"` and project has no UI, skip entirely
2. **Draft section content** - Use section `instruction` and handle choices/variables
3. **Handle repeatable sections** - If section has `repeatable: true`, generate multiple instances based on nested structure
4. **Present to user** - Show clean section content for review
5. **Provide detailed rationale** - Include thoughtful analysis highlighting (for example):
- Interesting or questionable decisions made
- Trade-offs and choices (what was chosen over alternatives and why)
- Areas that might need user attention or validation
- Key assumptions made during drafting
6. **Get user feedback** - Accept changes or proceed
7. **Apply elicitation if specified** - If `elicit: true`, present standardized 1-9 options:
- Option 1: Always "Proceed to next section"
- Options 2-9: MUST select 8 relevant methods from data/elicitation-methods (never create new ones)
- Include "Select 1-9 or just type your question/feedback:" to allow free chat
8. **Process elicitation results** - After user selects elicitation method, present results with options:
- Option 1: "Apply suggested changes and update section"
- Option 2: "Return to elicitation selection (2-9 options)"
- Free text: "Ask questions or follow-ups about this elicitation"
- Allow multiple elicitation rounds on same section
9. **Save to document** - If document-as-we-go mode, append approved content to file
10. **Continue to next section**
**YOLO Mode:**
- Process all sections at once, then present complete document
### 4. Final Output
- Present complete document with clean markdown only
- Save to file if specified
- No YAML, no template syntax, no processing instructions
## Section Types
**Simple section:**
```yaml
- id: requirements
title: Requirements
instruction: "Draft functional (FR1, FR2...) and non-functional (NFR1, NFR2...) requirements"
```
**Section with elicitation:**
```yaml
- id: technical-assumptions
title: Technical Assumptions
instruction: "Gather technical decisions that will guide the Architect"
elicit: true
choices:
architecture: [Monolith, Microservices, Serverless]
```
**Conditional section:**
```yaml
- id: ui-goals
title: User Interface Goals
instruction: "High-level UI/UX vision and design goals"
condition: "has ui requirements"
elicit: true
```
**Repeatable section with nested structure:**
```yaml
- id: epic-details
title: Epic {{epic_number}} {{epic_title}}
instruction: "Epic guidance with story and criteria requirements"
elicit: true
repeatable: true
sections:
- id: story
title: Story {{epic_number}}.{{story_number}} {{story_title}}
repeatable: true
template: "As a {{user_type}}, I want {{action}}, so that {{benefit}}."
sections:
- id: criteria
title: Acceptance Criteria
type: numbered-list
item_template: "{{criterion_number}}: {{criteria}}"
repeatable: true
```
## Elicitation Loop
When user selects an elicitation method (options 2-9), follow this pattern:
1. **Execute the selected elicitation method** from data/elicitation-methods
2. **Present results** with insights and suggestions
3. **Provide follow-up options:**
- **1. Apply suggested changes and update section**
- **2. Return to elicitation selection** (show 2-9 options again)
- **Free text: Ask questions or follow-ups about this elicitation**
4. **Allow multiple rounds** - User can run multiple elicitation methods on the same section
5. **Only proceed to next section** when user explicitly chooses option 1 from the main menu
## Output Modes
**Document-as-we-go (Recommended):**
- Each approved section gets written to the document file immediately
- User can see document building in real-time
- Protects against context loss or chat restart
- File always contains latest approved content
**Chat-only:**
- All content stays in chat memory until document is complete
- Full document presented at end
- Risk of losing work if context runs out
## Template Processing
1. **Load YAML template** - Parse template metadata and sections
2. **Set document title** - Use template.output.title with variables
3. **Process sections in order** - Handle conditions, repeatability, nesting
4. **Apply instructions** - Use section.instruction for guidance
5. **Handle variables** - Replace {{variable}} placeholders
6. **Process choices** - Present options from choices object
7. **Generate content** - Create markdown following section structure
## Error Prevention
**❌ Don't:**
- Show YAML in final output
- Skip conditional checks
- Ignore elicitation flags
- Output template syntax
- Apply elicitation before user approves elicitation content
**✅ Do:**
- Process sections in order
- Present clean content only
- Apply elicitation AFTER user approves section content
- Handle choice objects properly
- Generate repeatable sections dynamically
- Skip sections where conditions aren't met
- Save to document file when in document-as-we-go mode
## Key Improvements
- **YAML templates** provide much richer structure than front matter
- **Document-as-we-go** protects against context loss
- **Elicitation after approval** ensures quality content first
- **Structured choices** replace inline {choice1|choice2} syntax
- **Nested sections** support complex document hierarchies

296
common/utils/bmad-doc-template.md Normal file
View File

@@ -0,0 +1,296 @@
# BMad Document Template Specification
## Overview
BMad document templates are defined in YAML format to drive interactive document generation and agent interaction. Templates separate structure definition from content generation, making them both human and LLM-agent-friendly.
## Template Structure
```yaml
template:
id: template-identifier
name: Human Readable Template Name
version: 1.0
output:
format: markdown
filename: default-path/to/{{filename}}.md
title: "{{variable}} Document Title"
workflow:
mode: interactive
elicitation: advanced-elicitation
sections:
- id: section-id
title: Section Title
instruction: |
Detailed instructions for the LLM on how to handle this section
# ... additional section properties
```
## Core Fields
### Template Metadata
- **id**: Unique identifier for the template
- **name**: Human-readable name displayed in UI
- **version**: Template version for tracking changes
- **output.format**: Default "markdown" for document templates
- **output.filename**: Default output file path (can include variables)
- **output.title**: Document title (becomes H1 in markdown)
### Workflow Configuration
- **workflow.mode**: Default interaction mode ("interactive" or "yolo")
- **workflow.elicitation**: Elicitation task to use ("advanced-elicitation")
## Section Properties
### Required Fields
- **id**: Unique section identifier
- **title**: Section heading text
- **instruction**: Detailed guidance for LLM on handling this section
### Optional Fields
#### Content Control
- **type**: Content type hint for structured sections
- **template**: Fixed template text for section content
- **item_template**: Template for repeatable items within section
- **prefix**: Prefix for numbered items (e.g., "FR", "NFR")
#### Behavior Flags
- **elicit**: Boolean - Apply elicitation after section rendered
- **repeatable**: Boolean - Section can be repeated multiple times
- **condition**: String - Condition for including section (e.g., "has ui requirements")
#### Content Guidance
- **examples**: Array of example content (not included in output)
- **choices**: Object with choice options for common decisions
- **placeholder**: Default placeholder text
#### Structure
- **sections**: Array of nested child sections
## Supported Types
### Content Types
- **bullet-list**: Unordered list items
- **numbered-list**: Ordered list with optional prefix
- **paragraphs**: Free-form paragraph text
- **table**: Structured table data
- **code-block**: Code or configuration blocks
- **template-text**: Fixed template with variable substitution
- **mermaid**: Mermaid diagram with specified type and details
### Special Types
- **repeatable-container**: Container for multiple instances
- **conditional-block**: Content shown based on conditions
- **choice-selector**: Present choices to user
## Advanced Features
### Variable Substitution
Use `{{variable_name}}` in titles, templates, and content:
```yaml
title: "Epic {{epic_number}} {{epic_title}}"
template: "As a {{user_type}}, I want {{action}}, so that {{benefit}}."
```
### Conditional Sections
```yaml
- id: ui-section
title: User Interface Design
condition: Project has UX/UI Requirements
instruction: Only include if project has UI components
```
### Choice Integration
```yaml
choices:
architecture: [Monolith, Microservices, Serverless]
testing: [Unit Only, Unit + Integration, Full Pyramid]
```
### Mermaid Diagrams
```yaml
- id: system-architecture
title: System Architecture Diagram
type: mermaid
instruction: Create a system architecture diagram showing key components and data flow
mermaid_type: flowchart
details: |
Show the following components:
- User interface layer
- API gateway
- Core services
- Database layer
- External integrations
```
**Supported mermaid_type values:**
**Core Diagram Types:**
- `flowchart` - Flow charts and process diagrams
- `sequenceDiagram` - Sequence diagrams for interactions
- `classDiagram` - Class relationship diagrams (UML)
- `stateDiagram` - State transition diagrams
- `erDiagram` - Entity relationship diagrams
- `gantt` - Gantt charts for timelines
- `pie` - Pie charts for data visualization
**Advanced Diagram Types:**
- `journey` - User journey maps
- `mindmap` - Mindmaps for brainstorming
- `timeline` - Timeline diagrams for chronological events
- `quadrantChart` - Quadrant charts for data categorization
- `xyChart` - XY charts (bar charts, line charts)
- `sankey` - Sankey diagrams for flow visualization
**Specialized Types:**
- `c4Context` - C4 context diagrams (experimental)
- `requirement` - Requirement diagrams
- `packet` - Network packet diagrams
- `block` - Block diagrams
- `kanban` - Kanban boards
### Repeatable Sections
```yaml
- id: epic-details
title: Epic {{epic_number}} {{epic_title}}
repeatable: true
sections:
- id: story
title: Story {{epic_number}}.{{story_number}} {{story_title}}
repeatable: true
sections:
- id: criteria
title: Acceptance Criteria
type: numbered-list
item_template: "{{criterion_number}}: {{criteria}}"
repeatable: true
```
### Examples with Code Blocks
````yaml
examples:
- "FR6: The system must authenticate users within 2 seconds"
- |
```mermaid
sequenceDiagram
participant User
participant API
participant DB
User->>API: POST /login
API->>DB: Validate credentials
DB-->>API: User data
API-->>User: JWT token
```
- |
**Architecture Decision Record**
**Decision**: Use PostgreSQL for primary database
**Rationale**: ACID compliance and JSON support needed
**Consequences**: Requires database management expertise
````
## Section Hierarchy
Templates define the complete document structure starting with the first H2 - each level in is the next H#:
```yaml
sections:
- id: overview
title: Project Overview
sections:
- id: goals
title: Goals
- id: scope
title: Scope
sections:
- id: in-scope
title: In Scope
- id: out-scope
title: Out of Scope
```
## Processing Flow
1. **Parse Template**: Load and validate YAML structure
2. **Initialize Workflow**: Set interaction mode and elicitation
3. **Process Sections**: Handle each section in order:
- Check conditions
- Apply instructions
- Generate content
- Handle choices and variables
- Apply elicitation if specified
- Process nested sections
4. **Generate Output**: Create clean markdown document
## Best Practices
### Template Design
- Keep instructions clear and specific
- Use examples for complex content
- Structure sections logically
- Include all necessary guidance for LLM
### Content Instructions
- Be explicit about expected format
- Include reasoning for decisions
- Specify interaction patterns
- Reference other documents when needed
### Variable Naming
- Use descriptive variable names
- Follow consistent naming conventions
- Document expected variable values
### Examples Usage
- Provide concrete examples for complex sections
- Include both simple and complex cases
- Use realistic project scenarios
- Include code blocks and diagrams when helpful
## Validation
Templates should be validated for:
- Valid YAML syntax
- Required fields present
- Consistent section IDs
- Proper nesting structure
- Valid variable references
## Migration from Legacy
When converting from markdown+frontmatter templates:
1. Extract embedded `[[LLM:]]` instructions to `instruction` fields
2. Convert `<<REPEAT>>` blocks to `repeatable: true` sections
3. Extract `^^CONDITIONS^^` to `condition` fields
4. Move `@{examples}` to `examples` arrays
5. Convert `{{placeholders}}` to proper variable syntax
This specification ensures templates are both human-readable and machine-processable while maintaining the flexibility needed for complex document generation.