ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad/bmb/workflows/edit-workflow
History
Brian Madison cfedecbd53 docs: massive documentation overhaul + introduce Paige (Documentation Guide agent) 
## 📚 Complete Documentation Restructure

**BMM Documentation Hub Created:**
- New centralized documentation system at `src/modules/bmm/docs/`
- 18 comprehensive guides organized by topic (7000+ lines total)
- Clear learning paths for greenfield, brownfield, and quick spec flows
- Professional technical writing standards throughout

**New Documentation:**
- `README.md` - Complete documentation hub with navigation
- `quick-start.md` - 15-minute getting started guide
- `agents-guide.md` - Comprehensive 12-agent reference (45 min read)
- `party-mode.md` - Multi-agent collaboration guide (20 min read)
- `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read)
- `brownfield-guide.md` - Existing codebase development (53 min read)
- `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read)
- `workflows-analysis.md` - Phase 1 workflows (12 min read)
- `workflows-planning.md` - Phase 2 workflows (19 min read)
- `workflows-solutioning.md` - Phase 3 workflows (13 min read)
- `workflows-implementation.md` - Phase 4 workflows (33 min read)
- `workflows-testing.md` - Testing & QA workflows (29 min read)
- `workflow-architecture-reference.md` - Architecture workflow deep-dive
- `workflow-document-project-reference.md` - Document-project workflow reference
- `enterprise-agentic-development.md` - Team collaboration patterns
- `faq.md` - Comprehensive Q&A covering all topics
- `glossary.md` - Complete terminology reference
- `troubleshooting.md` - Common issues and solutions

**Documentation Improvements:**
- Removed all version/date footers (git handles versioning)
- Agent customization docs now include full rebuild process
- Cross-referenced links between all guides
- Reading time estimates for all major docs
- Consistent professional formatting and structure

**Consolidated & Streamlined:**
- Module README (`src/modules/bmm/README.md`) streamlined to lean signpost
- Root README polished with better hierarchy and clear CTAs
- Moved docs from root `docs/` to module-specific locations
- Better separation of user docs vs. developer reference

## 🤖 New Agent: Paige (Documentation Guide)

**Role:** Technical documentation specialist and information architect

**Expertise:**
- Professional technical writing standards
- Documentation structure and organization
- Information architecture and navigation
- User-focused content design
- Style guide enforcement

**Status:** Work in progress - Paige will evolve as documentation needs grow

**Integration:**
- Listed in agents-guide.md, glossary.md, FAQ
- Available for all phases (documentation is continuous)
- Can be customized like all BMM agents

## 🔧 Additional Changes

- Updated agent manifest with Paige
- Updated workflow manifest with new documentation workflows
- Fixed workflow-to-agent mappings across all guides
- Improved root README with clearer Quick Start section
- Better module structure explanations
- Enhanced community links with Discord channel names

**Total Impact:**
- 18 new/restructured documentation files
- 7000+ lines of professional technical documentation
- Complete navigation system with cross-references
- Clear learning paths for all user types
- Foundation for knowledge base (coming in beta)

Co-Authored-By: Claude <noreply@anthropic.com>
 		2025-11-02 21:18:33 -06:00
..
README.md workflow references to moved workflow status workflow 2025-10-17 22:34:21 -05:00
checklist.md minor fixes 2025-10-16 21:50:50 -05:00
instructions.md installer improvements 2025-10-28 12:47:45 -05:00
workflow.yaml installer improvements 2025-10-28 12:47:45 -05:00
workflow.yaml.bak docs: massive documentation overhaul + introduce Paige (Documentation Guide agent) 2025-11-02 21:18:33 -06:00

README.md

Edit Workflow

Purpose

An intelligent workflow editor that helps you modify existing BMAD workflows while adhering to all best practices and conventions documented in the workflow creation guide.

Use Case

When you need to:

  • Fix issues in existing workflows
  • Update workflow configuration or metadata
  • Improve instruction clarity and specificity
  • Add new features or capabilities
  • Ensure compliance with BMAD workflow conventions

How to Invoke

workflow edit-workflow

Or through a BMAD agent:

*edit-workflow

Expected Inputs

  • Target workflow path: Path to the workflow.yaml file or workflow folder you want to edit
  • Edit type selection: Choice of what aspect to modify
  • User approval: For each proposed change

Generated Outputs

  • Modified workflow files (in place)
  • Optional change log at: {output_folder}/workflow-edit-log-{date}.md

Features

  1. Comprehensive Analysis: Checks workflows against the official creation guide
  2. Prioritized Issues: Identifies and ranks issues by importance
  3. Guided Editing: Step-by-step process with explanations
  4. Best Practices: Ensures all edits follow BMAD conventions
  5. Instruction Style Optimization: Convert between intent-based and prescriptive styles
  6. Validation: Checks all changes for correctness
  7. Change Tracking: Documents what was modified and why

Understanding Instruction Styles

When editing workflows, one powerful option is adjusting the instruction style to better match the workflow's purpose.

Intent-Based vs Prescriptive Instructions

Intent-Based (Recommended for most workflows)

Guides the AI with goals and principles, allowing flexible conversation.

  • More flexible and conversational - AI adapts to user responses
  • Better for complex discovery - Requirements gathering, creative exploration
  • Quality over consistency - Deep understanding matters more
  • Example: <action>Guide user to define their target audience with specific demographics and needs</action>

When to use:

  • Complex discovery processes (user research, requirements)
  • Creative brainstorming and ideation
  • Iterative refinement workflows
  • Workflows requiring nuanced understanding

Prescriptive

Provides exact questions with structured options.

  • More controlled and predictable - Consistent questions every time
  • Better for simple data collection - Platform, format, yes/no choices
  • Consistency over quality - Same execution every run
  • Example: <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>

When to use:

  • Simple data collection (platform, format, binary choices)
  • Compliance verification and standards adherence
  • Configuration with finite options
  • Quick setup wizards

Edit Workflow's Style Adjustment Feature

The "Adjust instruction style" editing option (menu option 11) helps you:

  1. Analyze current style - Identifies whether workflow is primarily intent-based or prescriptive
  2. Convert between styles - Transform prescriptive steps to intent-based (or vice versa)
  3. Optimize the mix - Intelligently recommend the best style for each step
  4. Step-by-step control - Review and decide on each step individually

Common scenarios:

  • Make workflow more conversational: Convert rigid tags to flexible tags for complex steps
  • Make workflow more consistent: Convert open-ended tags to structured tags for simple data collection
  • Balance both approaches: Use intent-based for discovery, prescriptive for simple choices

This feature is especially valuable when converting legacy workflows or adapting workflows for different use cases.

Workflow Steps

  1. Load and analyze target workflow
  2. Check against best practices
  3. Select editing focus
  4. Load relevant documentation
  5. Perform edits with user approval
  6. Validate all changes (optional)
  7. Generate change summary

Requirements

  • Access to workflow creation guide
  • Read/write permissions for target workflow
  • Understanding of BMAD workflow types