feat: WIP create-docv2
This commit is contained in:
Brian Madison
296
common/utils/bmad-doc-template.md
Normal file
296
common/utils/bmad-doc-template.md
Normal 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.
|
||||
Reference in New Issue
Block a user