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/docs/diagrams/README.md

258 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# BMM Workflow Diagram
This directory contains the BMM (BMad Method) workflow diagram and tools for generating it.
## Files
| File | Description |
| ---------------------------------- | --------------------------------------------------- |
| `workflow-manifest.yaml` | Workflow structure manifest (source of truth) |
| `generate-manifest.md` | Agentic prompt to generate/update manifest |
| `bmm-workflow.d2` | D2 source diagram |
| `bmm-workflow.svg` | Vector output (74KB) |
| `bmm-workflow.png` | Standard PNG (1600×1502, 257KB) |
| `bmm-workflow-print.png` | High-res for Nano-Banana input (4000×3755, 732KB) |
| `bmm-workflow-vintage.jpg` | Print-ready vintage version (2144×1984, 1.1MB) |
| `bmm-workflow-vintage-web.jpg` | Web-optimized vintage (1400×1296, 281KB) |
| `generate-bmm-workflow-diagram.md` | Generation prompt for Claude |
| `gracefully-age.prompt.md` | Nano-Banana Pro prompt for vintage treatment |
| `post-process-svg.py` | SVG post-processing (labels, title, legend, footer) |
| `red-herring.png` | Fish stamp asset |
| `fonts/` | ShareTechMono font files |
## Workflow Manifest System
The workflow manifest (`workflow-manifest.yaml`) is the **source of truth** for BMM workflow structure. It contains:
- All workflows organized by phase
- Workflow connections and dependencies
- Decision points (e.g., "Has UI?")
- Feedback loops (e.g., code review → dev)
- Cross-phase connections
- Output file patterns
### Generating/Updating the Manifest
Use the `generate-manifest.md` agentic prompt to create or update the manifest:
1. Feed `generate-manifest.md` to an agentic LLM (Claude, Gemini, etc.)
2. The agent will:
- Scan `src/modules/bmm/workflows/` for all workflows
- Extract workflow names, descriptions, and outputs from `workflow.yaml` files
- Build the manifest with all connections and dependencies
- Compare with existing manifest (if present)
- **HARD STOP** if Quick Flow changes detected
- Prompt for approval if main workflow changes detected
- Write updated manifest to `workflow-manifest.yaml`
### When to Regenerate
Regenerate the manifest when:
- Adding new workflows
- Removing workflows
- Changing workflow outputs
- Changing workflow connections or dependencies
- Updating Quick Flow workflows (requires careful review)
### Change Detection
The manifest system includes intelligent change detection:
- **Quick Flow changes**: HARD STOP - these are critical paths
- **Main workflow changes**: User approval required
- **No changes**: Proceeds silently
## Generation Pipeline
### Step 1: Generate Base Diagram
Run the generation prompt with Claude:
```bash
# Claude will read generate-bmm-workflow-diagram.md and:
# 1. Analyze BMM workflow structure
# 2. Generate/update bmm-workflow.d2
# 3. Run d2 to create SVG
# 4. Post-process SVG
# 5. Convert to PNG
```
Or manually:
```bash
# Generate SVG from D2
d2 --font-regular=fonts/ShareTechMono-Regular.ttf \
--font-bold=fonts/ShareTechMono-Regular.ttf \
bmm-workflow.d2 bmm-workflow-technical.svg
# Post-process (shrink labels, outline title, add legend/footer/stamp)
python3 post-process-svg.py
# Convert to standard PNG
rsvg-convert bmm-workflow.svg -w 1600 -o bmm-workflow.png
# Convert to high-res PNG for Nano-Banana
rsvg-convert bmm-workflow.svg -w 4000 -o bmm-workflow-print.png
# Clean up
rm bmm-workflow-technical.svg
```
### Step 2: Vintage Treatment with Nano-Banana Pro
1. Go to [Nano-Banana Pro](https://nanobanana.org/) or use via Pixlr/Recraft
2. Upload `bmm-workflow-print.png` (the 4000px version)
3. Use the prompt from `gracefully-age.prompt.md`:
- Applies aged paper texture, fold creases, coffee stains
- Adds ink bleed and printing artifacts
- Preserves all text, boxes, and arrows exactly
- Does NOT apply sepia/fading (original colors are already vintage-toned)
4. Download the result (will be named something like `Gemini_Generated_Image_*.png`)
### Step 3: Remove the Watermark
Nano-Banana Pro adds a 4-pointed star watermark in the lower-right corner. Remove it:
```bash
# Set input file (adjust filename as needed)
INPUT=~/Downloads/Gemini_Generated_Image_XXXXX.png
# Find the watermark location (it's near the fish, bottom-right)
# The watermark is approximately at position (1950-2060, 1790-1900)
# Remove watermark by patching with nearby paper texture
magick "$INPUT" \
\( -clone 0 -crop 120x120+1950+1680 +repage \
\( -size 120x120 xc:black -fill white -draw "circle 60,60 60,5" -blur 0x12 \) \
-alpha off -compose CopyOpacity -composite \) \
-geometry +1950+1795 -compose over -composite \
bmm-workflow-vintage-clean.png
```
**How this works:**
- Crops a 120×120 patch of clean paper texture from above the watermark (at +1950+1680)
- Creates a circular feathered mask to blend edges
- Composites the patch over the watermark location (+1950+1795)
**Verify the fix:**
```bash
# Crop the corner to check
magick bmm-workflow-vintage-clean.png -crop 600x600+1544+1384 /tmp/check.png
open /tmp/check.png # or use any image viewer
```
The fish should be intact, watermark gone, no visible patch edges.
### Step 4: Fix the Legend
Nano-Banana garbles the small text in the legend. Fix by:
1. Covering the garbled text with vintage paper texture
2. Applying clean text with darken blend (preserves texture, shows text)
```bash
# Extract legend content from original (without outer borders)
magick bmm-workflow-print.png -crop 1600x450+1950+250 /tmp/legend-orig.png
magick /tmp/legend-orig.png -shave 25x25 /tmp/legend-content.png
# Scale to match Nano-Banana output
magick /tmp/legend-content.png -resize 831x211! /tmp/legend-content-scaled.png
# Sample clean paper texture (find an empty area - e.g., right of title)
magick bmm-workflow-vintage-clean.png -crop 100x100+900+120 /tmp/texture-patch.png
# Tile texture to cover legend area
magick /tmp/texture-patch.png -write mpr:tile +delete \
-size 850x220 tile:mpr:tile /tmp/texture-tiled.png
# Cover garbled legend with tiled texture
magick bmm-workflow-vintage-clean.png \
/tmp/texture-tiled.png -geometry +1055+143 -composite \
/tmp/vintage-erased.png
# Apply clean text with darken blend (white becomes transparent)
magick /tmp/vintage-erased.png \
/tmp/legend-content-scaled.png \
-geometry +1059+147 -compose darken -composite \
bmm-workflow-vintage-fixed.png
```
**Verify:**
```bash
magick bmm-workflow-vintage-fixed.png -crop 700x350+900+80 /tmp/legend-check.png
open /tmp/legend-check.png
```
The legend should have clean text on vintage paper texture, with box borders preserved.
### Step 5: Create Final Versions
```bash
# Print version (JPEG, 92% quality)
magick bmm-workflow-vintage-fixed.png \
-quality 92 \
bmm-workflow-vintage.jpg
# Web version (1400px wide, 85% quality)
magick bmm-workflow-vintage-fixed.png \
-resize 1400x \
-quality 85 \
bmm-workflow-vintage-web.jpg
# Clean up
rm bmm-workflow-vintage-clean.png bmm-workflow-vintage-fixed.png
```
**File sizes:**
- Print: ~1.1MB (2144×1984 at 92% JPEG)
- Web: ~280KB (1400×1296 at 85% JPEG)
## Troubleshooting
### Watermark in wrong position
The watermark location varies slightly between Nano-Banana runs. To find it:
```bash
# Create a corner crop to locate the watermark
magick input.png -crop 600x600+1544+1384 /tmp/corner.png
open /tmp/corner.png
```
Look for the 4-pointed star shape near the fish. Adjust the patch coordinates accordingly.
### Patch is visible
If the patched area looks different from surroundings:
- Sample texture from a different location (try areas with similar color/texture)
- Increase blur radius for softer blending
- Use a smaller patch size
### Colors too dark/faded after Nano-Banana
The prompt in `gracefully-age.prompt.md` explicitly tells Nano-Banana NOT to apply sepia/fading since our original colors are already vintage-toned. If results are too dark, emphasize this more in the prompt.
### Legend position is off
The legend position depends on the Nano-Banana output dimensions. If dimensions differ from 2144×1984:
1. Calculate new scale factors: `new_width/4000` and `new_height/3755`
2. Adjust crop position: `1950 * width_scale`, `250 * height_scale`
3. Adjust legend size: `1600 * width_scale`, `450 * height_scale`
## Dependencies
- [D2](https://d2lang.com/) - Diagram scripting language
- [rsvg-convert](https://wiki.gnome.org/Projects/LibRsvg) - SVG to PNG conversion
- [ImageMagick](https://imagemagick.org/) (magick command) - Image manipulation
- Python 3 - For post-processing scripts
View Git Blame Copy Permalink