pig/pig-farm-controller
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

bmad初始化

Browse Source
This commit is contained in:
huang
2025-11-01 19:22:39 +08:00
parent 5b21dc0bd5
commit 426ae41f54
447 changed files with 80633 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
bmad/bmb/workflows/redoc/README.md Normal file
View File

@@ -0,0 +1,87 @@
# ReDoc - Reverse-Tree Documentation Engine
**Type:** Autonomous Action Workflow
**Module:** BMad Builder (bmb)
## Purpose
ReDoc is an intelligent documentation maintenance system for BMAD modules, workflows, and agents. It uses a reverse-tree approach (leaf folders first, then parent folders) to systematically generate and update README.md files with technical writer quality output.
The workflow understands BMAD conventions deeply and focuses documentation on distinctive features rather than explaining standard patterns, resulting in succinct, precise technical documentation.
## Key Features
- **Reverse-Tree Processing**: Documents from deepest folders up to module root, allowing child documentation to inform parent summaries
- **Convention-Aware**: Loads BMAD architecture patterns and only documents unique/distinctive aspects
- **Scalability**: Automatically creates catalog documents (WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md) for massive folders (>10 items)
- **Diff-Aware**: Tracks `last-redoc-date` frontmatter to enable change detection since last run
- **Autonomous**: Runs without user checkpoints unless clarification is genuinely required
- **Comprehensive**: Reads ALL files completely before generating documentation (no partial reads)
## Usage
Invoke with a target path:
```
workflow redoc
```
When prompted, provide one of:
- **Module path**: `bmad/bmm` (documents entire module: root, workflows, agents)
- **Workflows folder**: `bmad/bmm/workflows` (documents all workflows)
- **Agents folder**: `bmad/bmm/agents` (documents all agents)
- **Single workflow**: `bmad/bmm/workflows/product-brief` (documents one workflow)
- **Single agent**: `bmad/bmm/agents/prd-agent.md` (documents one agent)
## Inputs
### Required
- **target_path**: Path to module, folder, or specific component to document
### Knowledge Base (Auto-loaded)
- agent-architecture.md
- agent-command-patterns.md
- agent-types.md
- module-structure.md
- workflow-creation-guide.md
## Outputs
### Created/Updated Files
- **README.md**: At each documented level (workflow folders, agent folders, module root)
- **Catalog files**: WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md (for massive folders)
- **Frontmatter**: All READMEs include `last-redoc-date: <timestamp>`
### Summary Report
- Documentation coverage statistics
- List of files created/updated
- Any items requiring manual review
## Workflow Steps
1. **Initialize**: Load BMAD conventions and validate target
2. **Analyze Structure**: Build reverse-tree execution plan
3. **Process Leaves**: Document individual workflows/agents (deepest first)
4. **Process Folders**: Document workflow/agent collections with categorization
5. **Process Root**: Document module overview with links and highlights
6. **Validate**: Verify completeness and generate report
7. **Diff Analysis** (optional): Show changes since last redoc
8. **Complete**: Report success and suggest next steps
## Technical Details
- **Execution**: Autonomous with minimal user interaction
- **Quality**: Technical writer standards - succinct, precise, professional
- **Context-Aware**: Uses BMAD convention knowledge to highlight only distinctive features
- **Scalable**: Handles folders of any size with intelligent catalog creation
## Next Steps After Running
1. Review generated documentation for accuracy
2. If documenting a subfolder, run redoc on parent module to update references
3. Commit documentation updates with meaningful message

99
bmad/bmb/workflows/redoc/checklist.md Normal file
View File

@@ -0,0 +1,99 @@
# ReDoc Workflow Validation Checklist
## Initialization and Setup
- [ ] All BMAD convention documents loaded and understood
- [ ] Target path validated and exists
- [ ] Target type correctly identified (module/workflow/agent/folder)
- [ ] Documentation execution plan created with reverse-tree order
## File Analysis
- [ ] All files in target scope read completely (no offset/limit usage)
- [ ] Existing README.md files detected and last-redoc-date parsed
- [ ] Massive folders (>10 items) identified for catalog document creation
- [ ] Documentation depth levels calculated correctly
## Leaf-Level Documentation (Workflows)
- [ ] Each workflow's ALL files read: workflow.yaml, instructions.md, template.md, checklist.md
- [ ] README.md includes frontmatter with current last-redoc-date
- [ ] Description is 2-4 paragraphs of technical writer quality
- [ ] Focuses on DISTINCTIVE features, not BMAD boilerplate conventions
- [ ] Includes "Usage" section with invocation command
- [ ] Includes "Inputs" and "Outputs" sections where applicable
- [ ] Succinct and precise language used throughout
## Leaf-Level Documentation (Agents)
- [ ] Each agent file read completely including XML structure, commands, persona
- [ ] README.md includes frontmatter with current last-redoc-date
- [ ] Description is 1-3 paragraphs of technical writer quality
- [ ] Lists all available commands clearly
- [ ] Explains when to use this agent
- [ ] Highlights unique capabilities vs standard agent patterns
## Mid-Level Documentation (Folders)
- [ ] All child README.md files read before generating folder README
- [ ] Workflows categorized logically if massive folder (>10 items)
- [ ] Agents categorized by type if massive folder (>10 items)
- [ ] Catalog documents (WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md) created for massive folders
- [ ] Catalog documents include frontmatter with last-redoc-date
- [ ] Folder README.md references catalog if one exists
- [ ] Folder README.md is succinct (1-2 paragraphs + listings/links)
- [ ] Notable/commonly-used items highlighted
## Root Module Documentation
- [ ] Module config.yaml read and understood
- [ ] Workflows and agents folder READMEs read before creating root README
- [ ] Root README includes frontmatter with current last-redoc-date
- [ ] Module purpose clearly stated in 2-3 sentences
- [ ] Links to /workflows/README.md and /agents/README.md included
- [ ] 2-3 key workflows mentioned with context
- [ ] 2-3 key agents mentioned with context
- [ ] Configuration section highlights UNIQUE settings only
- [ ] Usage section explains invocation patterns
- [ ] BMAD convention knowledge applied (describes only distinctive aspects)
## Quality Standards
- [ ] All documentation uses proper BMAD terminology
- [ ] Technical writer quality: clear, concise, professional
- [ ] No placeholder text or generic descriptions remain
- [ ] All links are valid and correctly formatted
- [ ] Frontmatter syntax is correct and dates are current
- [ ] No redundant explanation of standard BMAD patterns
## Validation and Reporting
- [ ] All planned documentation items created/updated
- [ ] Frontmatter dates verified as current across all files
- [ ] File paths and internal links validated
- [ ] Summary report generated with counts and coverage
- [ ] Files skipped (if any) documented with reasons
## Git Diff Analysis (Optional Step)
- [ ] last-redoc-date timestamps extracted correctly
- [ ] Git log queried for changes since last redoc
- [ ] Modified files identified and reported
- [ ] Findings presented clearly to user
## Final Validation
- [ ] Documentation Coverage
- All README.md files in scope created/updated
- Catalog documents created where needed
- No documentation gaps identified
- [ ] Execution Quality
- Reverse-tree order followed (leaf → root)
- Autonomous execution (minimal user prompts)
- Only clarification questions asked when truly necessary
- [ ] Output Quality
- Technical precision maintained throughout
- Succinct descriptions (no verbose explanations)
- Professional documentation standards met

265
bmad/bmb/workflows/redoc/instructions.md Normal file
View File

@@ -0,0 +1,265 @@
# ReDoc Workflow Instructions
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {project-root}/src/modules/bmb/workflows/redoc/workflow.yaml</critical>
<critical>Communicate in {communication_language} throughout the documentation process</critical>
<critical>This is an AUTONOMOUS workflow - minimize user interaction unless clarification is absolutely required</critical>
<critical>IMPORTANT: Process ONE document at a time to avoid token limits. Each README should be created individually, not batched.</critical>
<critical>When using Task tool with sub-agents: Only request ONE workflow or agent documentation per invocation to prevent token overflow.</critical>
<workflow>
<step n="1" goal="Load BMAD conventions and initialize">
<action>Load ALL BMAD convention documents from {bmad_conventions}:
- agent_architecture.md - Understand agent XML structure and patterns
- agent_command_patterns.md - Command syntax and activation patterns
- agent_types.md - Standard agent categories and purposes
- module_structure.md - Module organization and folder conventions
- workflow_guide.md - Workflow structure and best practices
</action>
<action>Internalize these conventions so you can:
- Recognize standard patterns vs unique implementations
- Describe only what's distinctive about each component
- Use proper terminology consistently
- Write with technical precision
</action>
<action>Get target path from user:
- Ask: "What do you want to document? (module path, workflow path, agent path, or folder path)"
- Store as {{target_path}}
</action>
<action>Validate target path exists and determine target type:
- Module root (contains config.yaml, /workflows, /agents folders)
- Workflows folder (contains multiple workflow folders)
- Agents folder (contains multiple agent .md files)
- Single workflow folder (contains workflow.yaml)
- Single agent file (.md)
</action>
<action>Store target type as {{target_type}} for conditional processing</action>
</step>
<step n="2" goal="Analyze directory structure and existing documentation">
<action>Build complete tree structure of {{target_path}} using Glob and file system tools</action>
<action>Identify all documentation points:
- List all folders requiring README.md files
- Detect existing README.md files
- Parse frontmatter from existing READMEs to extract last-redoc-date
- Calculate documentation depth (how many levels deep)
</action>
<action>Create documentation map with execution order (deepest → shallowest):
- Level 0 (deepest): Individual workflow folders, individual agent files
- Level 1: /workflows folder, /agents folder
- Level 2 (root): Module root README.md
</action>
<action>Detect "massive folders" requiring child catalog documents:
- Threshold: >10 items or complex categorization needed
- Mark folders for catalog document creation (e.g., WORKFLOWS-CATALOG.md, AGENTS-CATALOG.md)
</action>
<critical>Store execution order as {{doc_execution_plan}} - this ensures reverse-tree processing</critical>
</step>
<step n="3" goal="Process leaf-level documentation" repeat="for-each-leaf-item">
<critical>TOKEN LIMIT WARNING: Process ONE item at a time to prevent token overflow issues.</critical>
<critical>If using Task tool with sub-agents: NEVER batch multiple workflows/agents in a single invocation.</critical>
<critical>Each README creation should be a separate operation with its own file save.</critical>
<critical>Sequential processing is MANDATORY - do not attempt parallel documentation generation.</critical>
<action>For each individual workflow folder in execution plan (PROCESS ONE AT A TIME):
1. Read ALL files completely:
- workflow.yaml (metadata, purpose, configuration)
- instructions.md (step structure, goals)
- template.md (output structure) if exists
- checklist.md (validation criteria) if exists
- Any supporting data files
2. Synthesize understanding:
- Core purpose and use case
- Input requirements
- Output produced
- Unique characteristics (vs standard BMAD workflow patterns)
- Key steps or special features
3. Generate/update README.md:
- Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
- Write 2-4 paragraph technical description
- Include "Usage" section with invocation command
- Include "Inputs" section if applicable
- Include "Outputs" section
- Be succinct and precise - technical writer quality
- Focus on DISTINCTIVE features, not boilerplate
4. Save README.md to workflow folder
<critical>If multiple workflows need documentation, process them SEQUENTIALLY not in parallel. Each workflow gets its own complete processing cycle.</critical>
</action>
<action>For each individual agent file in execution plan (PROCESS ONE AT A TIME):
1. Read agent definition file completely:
- XML structure and metadata
- Commands and their purposes
- Activation patterns
- Persona and communication style
- Critical actions and workflows invoked
2. Synthesize understanding:
- Agent purpose and role
- Available commands
- When to use this agent
- Unique capabilities
3. Generate/update README.md (or agent-name-README.md if in shared folder):
- Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
- Write 1-3 paragraph technical description
- Include "Commands" section listing available commands
- Include "Usage" section
- Focus on distinctive features
4. Save README.md
</action>
<action if="clarification needed about purpose or unique features">Ask user briefly, then continue</action>
</step>
<step n="4" goal="Process mid-level folder documentation" if="target_type requires folder docs">
<action>For /workflows folder:
1. Read ALL workflow README.md files created in Step 3
2. Categorize workflows by purpose/type if folder is massive (>10 workflows):
- Document generation workflows
- Action workflows
- Meta-workflows
- Interactive workflows
3. If massive folder detected:
- Create WORKFLOWS-CATALOG.md with categorized listings
- Each entry: workflow name, 1-sentence description, link to folder
- Add frontmatter with last-redoc-date
4. Generate/update /workflows/README.md:
- Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
- High-level summary of workflow collection
- If catalog exists: reference it
- If not massive: list all workflows with brief descriptions and links
- Highlight notable or commonly-used workflows
- Keep succinct (1-2 paragraphs + list)
5. Save README.md
</action>
<action>For /agents folder:
1. Read ALL agent README.md files
2. Categorize agents by type if massive folder (>10 agents):
- Task agents
- Meta agents
- Specialized agents
- Utility agents
3. If massive folder detected:
- Create AGENTS-CATALOG.md with categorized listings
- Each entry: agent name, 1-sentence description, link
- Add frontmatter with last-redoc-date
4. Generate/update /agents/README.md:
- Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
- High-level summary of agent collection
- If catalog exists: reference it
- If not massive: list all agents with brief descriptions
- Highlight key agents and their purposes
- Keep succinct
5. Save README.md
</action>
</step>
<step n="5" goal="Process root module documentation" if="target_type is module root">
<action>For module root README.md:
1. Read module config.yaml for metadata and configuration
2. Read /workflows/README.md and /agents/README.md created in Step 4
3. Identify module's unique purpose within BMAD ecosystem
4. Generate/update module README.md:
- Add frontmatter: `---\nlast-redoc-date: {{date}}\n---\n`
Structure:
- # Module Name
- **Purpose**: 2-3 sentence high-level module purpose
- **Overview**: 1-2 paragraphs describing what this module provides
- ## Workflows
- Link to /workflows/README.md with 1-sentence summary
- Mention count and highlight 2-3 key workflows
- ## Agents
- Link to /agents/README.md with 1-sentence summary
- Mention count and highlight 2-3 key agents
- ## Configuration
- Notable config.yaml settings if unique/important
- Reference paths and conventions
- ## Usage
- How to invoke workflows or agents from this module
- Prerequisites if any
Focus on UNIQUE aspects using BMAD convention knowledge:
- Don't explain standard BMAD patterns
- Highlight what makes THIS module distinctive
- Use proper BMAD terminology
5. Save README.md to module root
</action>
</step>
<step n="6" goal="Validation and summary report">
<action>Verify all planned documentation was created/updated:
- Check each item in {{doc_execution_plan}}
- Confirm frontmatter dates are current
- Validate file paths and links
</action>
<action>Generate summary report showing:
- Target documented: {{target_path}}
- Target type: {{target_type}}
- Documentation files created/updated (count and list)
- Any catalog files created
- Files skipped or requiring manual review (if any)
- Coverage: X% of items documented
- Processing notes: Confirm sequential processing was used to avoid token limits
</action>
<action>Display summary to user</action>
</step>
<step n="7" goal="Optional git diff analysis" optional="true">
<ask>Would you like to see what changed since the last redoc run? [y/n]</ask>
<action if="user_response == 'y'">
For each README with last-redoc-date frontmatter:
1. Extract last-redoc-date timestamp
2. Use git log to find files modified since that date in the documented folder
3. Highlight files that changed but may need documentation updates
4. Report findings to user
</action>
</step>
<step n="8" goal="Completion">
<action>Confirm to {user_name} in {communication_language} that autonomous workflow execution is complete</action>
<action>Provide path to all updated documentation</action>
<action>Suggest next steps if needed</action>
</step>
</workflow>

33
bmad/bmb/workflows/redoc/workflow.yaml Normal file
View File

@@ -0,0 +1,33 @@
# ReDoc - Reverse-Tree Documentation Engine
name: "redoc"
description: "Autonomous documentation system that maintains module, workflow, and agent documentation using a reverse-tree approach (leaf folders first, then parents). Understands BMAD conventions and produces technical writer quality output."
author: "BMad"
# Critical variables
config_source: "{project-root}/bmad/bmb/config.yaml"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
# Required knowledge base - BMAD conventions and patterns
bmad_conventions:
agent_architecture: "{project-root}/src/modules/bmb/workflows/create-agent/agent-architecture.md"
agent_command_patterns: "{project-root}/src/modules/bmb/workflows/create-agent/agent-command-patterns.md"
agent_types: "{project-root}/src/modules/bmb/workflows/create-agent/agent-types.md"
module_structure: "{project-root}/src/modules/bmb/workflows/create-module/module-structure.md"
workflow_guide: "{project-root}/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md"
# Runtime inputs
target_path: "" # User specifies: module path, workflow path, agent path, or folder path
# Module path and component files
installed_path: "{project-root}/src/modules/bmb/workflows/redoc"
template: false # Action workflow - updates files in place
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# Configuration
autonomous: true # Runs without user checkpoints unless clarification needed
standalone: true
# Web bundle configuration