siesa-agents 2.1.40 → 2.1.41

package/bmad/bmm/data/documentation-standards.md

@@ -1,262 +1,262 @@
-# Technical Documentation Standards for BMAD
-
-**For Agent: Technical Writer**
-**Purpose: Concise reference for documentation creation and review**
-
----
-
-## CRITICAL RULES
-
-### Rule 1: CommonMark Strict Compliance
-
-ALL documentation MUST follow CommonMark specification exactly. No exceptions.
-
-### Rule 2: NO TIME ESTIMATES
-
-NEVER document time estimates, durations, or completion times for any workflow, task, or activity. This includes:
-
-- Workflow execution time (e.g., "30-60 min", "2-8 hours")
-- Task duration estimates
-- Reading time estimates
-- Implementation time ranges
-- Any temporal measurements
-
-Time varies dramatically based on:
-
-- Project complexity
-- Team experience
-- Tooling and environment
-- Context switching
-- Unforeseen blockers
-
-**Instead:** Focus on workflow steps, dependencies, and outputs. Let users determine their own timelines.
-
-### CommonMark Essentials
-
-**Headers:**
-
-- Use ATX-style ONLY: `#` `##` `###` (NOT Setext underlines)
-- Single space after `#`: `# Title` (NOT `#Title`)
-- No trailing `#`: `# Title` (NOT `# Title #`)
-- Hierarchical order: Don't skip levels (h1→h2→h3, not h1→h3)
-
-**Code Blocks:**
-
-- Use fenced blocks with language identifier:
-  ````markdown
-  ```javascript
-  const example = 'code';
-  ```
-  ````
-- NOT indented code blocks (ambiguous)
-
-**Lists:**
-
-- Consistent markers within list: all `-` or all `*` or all `+` (don't mix)
-- Proper indentation for nested items (2 or 4 spaces, stay consistent)
-- Blank line before/after list for clarity
-
-**Links:**
-
-- Inline: `[text](url)`
-- Reference: `[text][ref]` then `[ref]: url` at bottom
-- NO bare URLs without `<>` brackets
-
-**Emphasis:**
-
-- Italic: `*text*` or `_text_`
-- Bold: `**text**` or `__text__`
-- Consistent style within document
-
-**Line Breaks:**
-
-- Two spaces at end of line + newline, OR
-- Blank line between paragraphs
-- NO single line breaks (they're ignored)
-
----
-
-## Mermaid Diagrams: Valid Syntax Required
-
-**Critical Rules:**
-
-1. Always specify diagram type first line
-2. Use valid Mermaid v10+ syntax
-3. Test syntax before outputting (mental validation)
-4. Keep focused: 5-10 nodes ideal, max 15
-
-**Diagram Type Selection:**
-
-- **flowchart** - Process flows, decision trees, workflows
-- **sequenceDiagram** - API interactions, message flows, time-based processes
-- **classDiagram** - Object models, class relationships, system structure
-- **erDiagram** - Database schemas, entity relationships
-- **stateDiagram-v2** - State machines, lifecycle stages
-- **gitGraph** - Branch strategies, version control flows
-
-**Formatting:**
-
-````markdown
-```mermaid
-flowchart TD
-    Start[Clear Label] --> Decision{Question?}
-    Decision -->|Yes| Action1[Do This]
-    Decision -->|No| Action2[Do That]
-```
-````
-
----
-
-## Style Guide Principles (Distilled)
-
-Apply in this hierarchy:
-
-1. **Project-specific guide** (if exists) - always ask first
-2. **BMAD conventions** (this document)
-3. **Google Developer Docs style** (defaults below)
-4. **CommonMark spec** (when in doubt)
-
-### Core Writing Rules
-
-**Task-Oriented Focus:**
-
-- Write for user GOALS, not feature lists
-- Start with WHY, then HOW
-- Every doc answers: "What can I accomplish?"
-
-**Clarity Principles:**
-
-- Active voice: "Click the button" NOT "The button should be clicked"
-- Present tense: "The function returns" NOT "The function will return"
-- Direct language: "Use X for Y" NOT "X can be used for Y"
-- Second person: "You configure" NOT "Users configure" or "One configures"
-
-**Structure:**
-
-- One idea per sentence
-- One topic per paragraph
-- Headings describe content accurately
-- Examples follow explanations
-
-**Accessibility:**
-
-- Descriptive link text: "See the API reference" NOT "Click here"
-- Alt text for diagrams: Describe what it shows
-- Semantic heading hierarchy (don't skip levels)
-- Tables have headers
-- Emojis are acceptable if user preferences allow (modern accessibility tools support emojis well)
-
----
-
-## OpenAPI/API Documentation
-
-**Required Elements:**
-
-- Endpoint path and method
-- Authentication requirements
-- Request parameters (path, query, body) with types
-- Request example (realistic, working)
-- Response schema with types
-- Response examples (success + common errors)
-- Error codes and meanings
-
-**Quality Standards:**
-
-- OpenAPI 3.0+ specification compliance
-- Complete schemas (no missing fields)
-- Examples that actually work
-- Clear error messages
-- Security schemes documented
-
----
-
-## Documentation Types: Quick Reference
-
-**README:**
-
-- What (overview), Why (purpose), How (quick start)
-- Installation, Usage, Contributing, License
-- Under 500 lines (link to detailed docs)
-
-**API Reference:**
-
-- Complete endpoint coverage
-- Request/response examples
-- Authentication details
-- Error handling
-- Rate limits if applicable
-
-**User Guide:**
-
-- Task-based sections (How to...)
-- Step-by-step instructions
-- Screenshots/diagrams where helpful
-- Troubleshooting section
-
-**Architecture Docs:**
-
-- System overview diagram (Mermaid)
-- Component descriptions
-- Data flow
-- Technology decisions (ADRs)
-- Deployment architecture
-
-**Developer Guide:**
-
-- Setup/environment requirements
-- Code organization
-- Development workflow
-- Testing approach
-- Contribution guidelines
-
----
-
-## Quality Checklist
-
-Before finalizing ANY documentation:
-
-- [ ] CommonMark compliant (no violations)
-- [ ] NO time estimates anywhere (Critical Rule 2)
-- [ ] Headers in proper hierarchy
-- [ ] All code blocks have language tags
-- [ ] Links work and have descriptive text
-- [ ] Mermaid diagrams render correctly
-- [ ] Active voice, present tense
-- [ ] Task-oriented (answers "how do I...")
-- [ ] Examples are concrete and working
-- [ ] Accessibility standards met
-- [ ] Spelling/grammar checked
-- [ ] Reads clearly at target skill level
-
----
-
-## BMAD-Specific Conventions
-
-**File Organization:**
-
-- `README.md` at root of each major component
-- `docs/` folder for extensive documentation
-- Workflow-specific docs in workflow folder
-- Cross-references use relative paths
-
-**Frontmatter:**
-Use YAML frontmatter when appropriate:
-
-```yaml
----
-title: Document Title
-description: Brief description
-author: Author name
-date: YYYY-MM-DD
----
-```
-
-**Metadata:**
-
-- Always include last-updated date
-- Version info for versioned docs
-- Author attribution for accountability
-
----
-
-**Remember: This is your foundation. Follow these rules consistently, and all documentation will be clear, accessible, and maintainable.**
+# Technical Documentation Standards for BMAD
+
+**For Agent: Technical Writer**
+**Purpose: Concise reference for documentation creation and review**
+
+---
+
+## CRITICAL RULES
+
+### Rule 1: CommonMark Strict Compliance
+
+ALL documentation MUST follow CommonMark specification exactly. No exceptions.
+
+### Rule 2: NO TIME ESTIMATES
+
+NEVER document time estimates, durations, or completion times for any workflow, task, or activity. This includes:
+
+- Workflow execution time (e.g., "30-60 min", "2-8 hours")
+- Task duration estimates
+- Reading time estimates
+- Implementation time ranges
+- Any temporal measurements
+
+Time varies dramatically based on:
+
+- Project complexity
+- Team experience
+- Tooling and environment
+- Context switching
+- Unforeseen blockers
+
+**Instead:** Focus on workflow steps, dependencies, and outputs. Let users determine their own timelines.
+
+### CommonMark Essentials
+
+**Headers:**
+
+- Use ATX-style ONLY: `#` `##` `###` (NOT Setext underlines)
+- Single space after `#`: `# Title` (NOT `#Title`)
+- No trailing `#`: `# Title` (NOT `# Title #`)
+- Hierarchical order: Don't skip levels (h1→h2→h3, not h1→h3)
+
+**Code Blocks:**
+
+- Use fenced blocks with language identifier:
+  ````markdown
+  ```javascript
+  const example = 'code';
+  ```
+  ````
+- NOT indented code blocks (ambiguous)
+
+**Lists:**
+
+- Consistent markers within list: all `-` or all `*` or all `+` (don't mix)
+- Proper indentation for nested items (2 or 4 spaces, stay consistent)
+- Blank line before/after list for clarity
+
+**Links:**
+
+- Inline: `[text](url)`
+- Reference: `[text][ref]` then `[ref]: url` at bottom
+- NO bare URLs without `<>` brackets
+
+**Emphasis:**
+
+- Italic: `*text*` or `_text_`
+- Bold: `**text**` or `__text__`
+- Consistent style within document
+
+**Line Breaks:**
+
+- Two spaces at end of line + newline, OR
+- Blank line between paragraphs
+- NO single line breaks (they're ignored)
+
+---
+
+## Mermaid Diagrams: Valid Syntax Required
+
+**Critical Rules:**
+
+1. Always specify diagram type first line
+2. Use valid Mermaid v10+ syntax
+3. Test syntax before outputting (mental validation)
+4. Keep focused: 5-10 nodes ideal, max 15
+
+**Diagram Type Selection:**
+
+- **flowchart** - Process flows, decision trees, workflows
+- **sequenceDiagram** - API interactions, message flows, time-based processes
+- **classDiagram** - Object models, class relationships, system structure
+- **erDiagram** - Database schemas, entity relationships
+- **stateDiagram-v2** - State machines, lifecycle stages
+- **gitGraph** - Branch strategies, version control flows
+
+**Formatting:**
+
+````markdown
+```mermaid
+flowchart TD
+    Start[Clear Label] --> Decision{Question?}
+    Decision -->|Yes| Action1[Do This]
+    Decision -->|No| Action2[Do That]
+```
+````
+
+---
+
+## Style Guide Principles (Distilled)
+
+Apply in this hierarchy:
+
+1. **Project-specific guide** (if exists) - always ask first
+2. **BMAD conventions** (this document)
+3. **Google Developer Docs style** (defaults below)
+4. **CommonMark spec** (when in doubt)
+
+### Core Writing Rules
+
+**Task-Oriented Focus:**
+
+- Write for user GOALS, not feature lists
+- Start with WHY, then HOW
+- Every doc answers: "What can I accomplish?"
+
+**Clarity Principles:**
+
+- Active voice: "Click the button" NOT "The button should be clicked"
+- Present tense: "The function returns" NOT "The function will return"
+- Direct language: "Use X for Y" NOT "X can be used for Y"
+- Second person: "You configure" NOT "Users configure" or "One configures"
+
+**Structure:**
+
+- One idea per sentence
+- One topic per paragraph
+- Headings describe content accurately
+- Examples follow explanations
+
+**Accessibility:**
+
+- Descriptive link text: "See the API reference" NOT "Click here"
+- Alt text for diagrams: Describe what it shows
+- Semantic heading hierarchy (don't skip levels)
+- Tables have headers
+- Emojis are acceptable if user preferences allow (modern accessibility tools support emojis well)
+
+---
+
+## OpenAPI/API Documentation
+
+**Required Elements:**
+
+- Endpoint path and method
+- Authentication requirements
+- Request parameters (path, query, body) with types
+- Request example (realistic, working)
+- Response schema with types
+- Response examples (success + common errors)
+- Error codes and meanings
+
+**Quality Standards:**
+
+- OpenAPI 3.0+ specification compliance
+- Complete schemas (no missing fields)
+- Examples that actually work
+- Clear error messages
+- Security schemes documented
+
+---
+
+## Documentation Types: Quick Reference
+
+**README:**
+
+- What (overview), Why (purpose), How (quick start)
+- Installation, Usage, Contributing, License
+- Under 500 lines (link to detailed docs)
+
+**API Reference:**
+
+- Complete endpoint coverage
+- Request/response examples
+- Authentication details
+- Error handling
+- Rate limits if applicable
+
+**User Guide:**
+
+- Task-based sections (How to...)
+- Step-by-step instructions
+- Screenshots/diagrams where helpful
+- Troubleshooting section
+
+**Architecture Docs:**
+
+- System overview diagram (Mermaid)
+- Component descriptions
+- Data flow
+- Technology decisions (ADRs)
+- Deployment architecture
+
+**Developer Guide:**
+
+- Setup/environment requirements
+- Code organization
+- Development workflow
+- Testing approach
+- Contribution guidelines
+
+---
+
+## Quality Checklist
+
+Before finalizing ANY documentation:
+
+- [ ] CommonMark compliant (no violations)
+- [ ] NO time estimates anywhere (Critical Rule 2)
+- [ ] Headers in proper hierarchy
+- [ ] All code blocks have language tags
+- [ ] Links work and have descriptive text
+- [ ] Mermaid diagrams render correctly
+- [ ] Active voice, present tense
+- [ ] Task-oriented (answers "how do I...")
+- [ ] Examples are concrete and working
+- [ ] Accessibility standards met
+- [ ] Spelling/grammar checked
+- [ ] Reads clearly at target skill level
+
+---
+
+## BMAD-Specific Conventions
+
+**File Organization:**
+
+- `README.md` at root of each major component
+- `docs/` folder for extensive documentation
+- Workflow-specific docs in workflow folder
+- Cross-references use relative paths
+
+**Frontmatter:**
+Use YAML frontmatter when appropriate:
+
+```yaml
+---
+title: Document Title
+description: Brief description
+author: Author name
+date: YYYY-MM-DD
+---
+```
+
+**Metadata:**
+
+- Always include last-updated date
+- Version info for versioned docs
+- Author attribution for accountability
+
+---
+
+**Remember: This is your foundation. Follow these rules consistently, and all documentation will be clear, accessible, and maintainable.**

package/bmad/bmm/data/project-context-template.md

@@ -1,40 +1,40 @@
-# Project Brainstorming Context Template
-
-## Project Focus Areas
-
-This brainstorming session focuses on software and product development considerations:
-
-### Key Exploration Areas
-
-- **User Problems and Pain Points** - What challenges do users face?
-- **Feature Ideas and Capabilities** - What could the product do?
-- **Technical Approaches** - How might we build it?
-- **User Experience** - How will users interact with it?
-- **Business Model and Value** - How does it create value?
-- **Market Differentiation** - What makes it unique?
-- **Technical Risks and Challenges** - What could go wrong?
-- **Success Metrics** - How will we measure success?
-
-### Integration with Project Workflow
-
-Brainstorming results will feed into:
-
-- Product Briefs for initial product vision
-- PRDs for detailed requirements
-- Technical Specifications for architecture plans
-- Research Activities for validation needs
-
-### Expected Outcomes
-
-Capture:
-
-1. Problem Statements - Clearly defined user challenges
-2. Solution Concepts - High-level approach descriptions
-3. Feature Priorities - Categorized by importance and feasibility
-4. Technical Considerations - Architecture and implementation thoughts
-5. Next Steps - Actions needed to advance concepts
-6. Integration Points - Connections to downstream workflows
-
----
-
-_Use this template to provide project-specific context for brainstorming sessions. Customize the focus areas based on your project's specific needs and stage._
+# Project Brainstorming Context Template
+
+## Project Focus Areas
+
+This brainstorming session focuses on software and product development considerations:
+
+### Key Exploration Areas
+
+- **User Problems and Pain Points** - What challenges do users face?
+- **Feature Ideas and Capabilities** - What could the product do?
+- **Technical Approaches** - How might we build it?
+- **User Experience** - How will users interact with it?
+- **Business Model and Value** - How does it create value?
+- **Market Differentiation** - What makes it unique?
+- **Technical Risks and Challenges** - What could go wrong?
+- **Success Metrics** - How will we measure success?
+
+### Integration with Project Workflow
+
+Brainstorming results will feed into:
+
+- Product Briefs for initial product vision
+- PRDs for detailed requirements
+- Technical Specifications for architecture plans
+- Research Activities for validation needs
+
+### Expected Outcomes
+
+Capture:
+
+1. Problem Statements - Clearly defined user challenges
+2. Solution Concepts - High-level approach descriptions
+3. Feature Priorities - Categorized by importance and feasibility
+4. Technical Considerations - Architecture and implementation thoughts
+5. Next Steps - Actions needed to advance concepts
+6. Integration Points - Connections to downstream workflows
+
+---
+
+_Use this template to provide project-specific context for brainstorming sessions. Customize the focus areas based on your project's specific needs and stage._