bmad-studio 0.1.0

package/_bmad/bmb/skills/bmad-workflow-builder/references/complex-workflow-patterns.md

@@ -0,0 +1,523 @@
+# BMad Module Workflows
+
+Advanced patterns for BMad module workflows — long-running, multi-stage processes with progressive disclosure, config integration, and compaction survival.
+
+---
+
+## Workflow Persona: Facilitator Model
+
+BMad workflows treat the human operator as the expert. The agent's role is **facilitator**, not replacement.
+
+**Principles:**
+- Ask clarifying questions when requirements are ambiguous
+- Present options with trade-offs, don't assume preferences
+- Validate decisions before executing irreversible actions
+- The operator knows their domain; the workflow knows the process
+
+**Example voice:**
+```markdown
+## Discovery
+I found 3 API endpoints that could handle this. Which approach fits your use case?
+
+**Option A**: POST /bulk-import — Faster, but no validation until complete
+**Option B**: POST /validate + POST /import — Slower, but catches errors early
+**Option C**: Streaming import — Best of both, requires backend support
+
+Which would you prefer?
+```
+
+---
+
+## Config Reading and Integration
+
+Workflows MUST read config values using the `bmad-init` skill.
+
+### Config Loading Pattern
+
+**Invoke the skill with parameters:**
+```
+Use bmad-init skill:
+- module: {bmad-module-code}
+- vars: user_name:BMad,communication_language:English,document_output_language:English,output_folder:{project-root}/_bmad-output,{output-location-variable}:{default-output-path}
+```
+
+The skill returns JSON with config values. Store in memory as `{var_name}` for use in prompts.
+
+### Required Core Variables
+
+**Every module workflow MUST load these core variables:**
+- `user_name:BMad`
+- `communication_language:English`
+- `output_folder:{project-root}/_bmad-output`
+
+**Conditionally include:**
+- `document_output_language:English` — ONLY if workflow creates documents (check capability `output-location` field)
+- Output location variable from capability `output-location` — ONLY if specified in metadata
+
+**Example for BMB workflow (creates documents, has output var):**
+```
+vars: user_name:BMad,communication_language:English,document_output_language:English,output_folder:{project-root}/_bmad-output,bmad_builder_output_folder:{project-root}/bmad-builder-creations/
+```
+
+**Example for analysis workflow (no documents, has output var):**
+```
+vars: user_name:BMad,communication_language:English,output_folder:{project-root}/_bmad-output,analysis_output_folder:{project-root}/_bmad-output/analysis/
+```
+
+**Example for processing workflow (no documents, no output var):**
+```
+vars: user_name:BMad,communication_language:English,output_folder:{project-root}/_bmad-output
+```
+
+### Using Config Values in Prompts
+
+**Every prompt file MUST start with:**
+```markdown
+Language: {communication_language}
+Output Language: {document_output_language}  ← ONLY if workflow creates documents
+Output Location: {output-variable}           ← ONLY if capability output-location is defined
+```
+
+**Use throughout prompts:**
+```markdown
+"Creating documentation in {document_output_language}..."  ← ONLY if creates documents
+"Writing output to {bmad_builder_output_folder}/report.md" ← ONLY if has output var
+"Connecting to API at {my_module_api_url}..."
+```
+
+---
+
+## {project_root} Pattern for Portable Paths
+
+Artifacts MUST use `{project_root}` for paths so the skill works regardless of install location (user directory or project).
+
+### Path Pattern
+
+```
+{project_root}/docs/foo.md         → Correct (portable)
+./docs/foo.md                      → Wrong (breaks if skill in user dir)
+~/my-project/docs/foo.md           → Wrong (not portable)
+/bizarre/absolute/path/foo.md      → Wrong (not portable)
+```
+
+### Writing Artifacts
+
+```markdown
+1. Create the artifact at {project_root}/docs/architecture.md
+2. Update {project_root}/CHANGELOG.md with entry
+3. Copy template to {project_root}/.bmad-cache/template.md
+```
+
+### {project_root} Resolution
+
+`{project_root}` is automatically resolved to the directory where the workflow was launched. This ensures:
+- Skills work whether installed globally or per-project
+- Multiple projects can use the same skill without conflict
+- Artifact paths are always relative to the active project
+
+---
+
+## Long-Running Workflows: Compaction Survival
+
+Workflows that run long (many steps, large context) may trigger context compaction. Critical state MUST be preserved in output files.
+
+### The Document-Itself Pattern
+
+**The output document is the cache.** Write directly to the file you're creating, updating it progressively as the workflow advances.
+
+The document stores both content and context:
+- **YAML front matter** — paths to input files used (for recovery after compaction)
+- **Draft sections** — progressive content as it's built
+- **Status marker** — which stage is complete (for resumption)
+
+This avoids:
+- File collisions when working on multiple PRDs/research projects simultaneously
+- Extra `_bmad-cache` folder overhead
+- State synchronization complexity
+
+### Draft Document Structure
+
+```markdown
+---
+title: "Analysis: Research Topic"
+status: "analysis"  # discovery | planning | analysis | synthesis | polish
+inputs:
+  - "{project_root}/docs/brief.md"
+  - "{project_root}/data/sources.json"
+created: "2025-03-02T10:00:00Z"
+updated: "2025-03-02T11:30:00Z"
+---
+
+# Analysis: Research Topic
+
+## Discovery
+[content from stage 1...]
+
+## Analysis
+[content from stage 2...]
+
+---
+
+*Last updated: Stage 2 complete*
+```
+
+### Input Tracking Pattern
+
+**Stage 1: Initialize document with inputs**
+```markdown
+## Stage 1: Discovery
+1. Gather sources and identify input files
+2. Create output document with YAML front matter:
+```yaml
+---
+title: "{document_title}"
+status: "discovery"
+inputs:
+  - "{relative_path_to_input_1}"
+  - "{relative_path_to_input_2}"
+created: "{timestamp}"
+updated: "{timestamp}"
+---
+```
+3. Write discovery content to document
+4. Present summary to user
+```
+
+**Stage 2+: Reload context if compacted**
+```markdown
+## Stage Start: Analysis
+1. Read {output_doc_path}
+2. Parse YAML front matter for `inputs` list
+3. Re-read each input file to restore context
+4. Verify status indicates previous stage complete
+5. Proceed with analysis, updating document in place
+```
+
+```markdown
+## Stage 1: Research
+1. Gather sources
+2. **Write findings to {project_root}/docs/research-topic.md**
+3. Present summary to user
+
+## Stage 2: Analysis
+1. **Read {project_root}/docs/research-topic.md** (survives compaction)
+2. Analyze patterns
+3. **Append/insert analysis into the same file**
+
+## Stage 3: Synthesis
+1. Read the growing document
+2. Synthesize into final structure
+3. **Update the same file in place**
+
+## Stage 4: Final Polish
+1. Spawn a subagent to polish the completed document:
+   - Cohesion check
+   - Redundancy removal
+   - Contradiction detection and fixes
+   - Add TOC if long document
+2. Write final version to {project_root}/docs/research-topic.md
+```
+
+### When to Use This Pattern
+
+**Guided flows with long documents:** Always write updates to the document itself at each stage.
+
+**Yolo flows with multiple turns:** If the workflow takes multiple conversational turns, write to the output file progressively.
+
+**Single-pass yolo:** Can wait to write final output if the entire response fits in one turn.
+
+### Progressive Document Structure
+
+Each stage appends to or restructures the document:
+
+```markdown
+## Initial Stage
+# Document Title
+
+## Section 1: Initial Research
+[content...]
+
+---
+
+## Second Stage (reads file, appends)
+# Document Title
+
+## Section 1: Initial Research
+[existing content...]
+
+## Section 2: Analysis
+[new content...]
+
+---
+
+## Third Stage (reads file, restructures)
+# Document Title
+
+## Executive Summary
+[ synthesized from sections ]
+
+## Background
+[ section 1 content ]
+
+## Analysis
+[ section 2 content ]
+```
+
+### Final Polish Subagent
+
+At workflow completion, spawn a subagent for final quality pass:
+
+```markdown
+## Final Polish
+
+Launch a general-purpose agent with:
+```
+Task: Polish {output_file_path}
+
+Actions:
+1. Check cohesion - do sections flow logically?
+2. Find and remove redundancy
+3. Detect contradictions and fix them
+4. If document is >5 sections, add a TOC at the top
+5. Ensure consistent formatting and tone
+
+Write the polished version back to the same file.
+```
+
+### Compaction Recovery Pattern
+
+If context is compacted mid-workflow:
+```markdown
+## Recovery Check
+1. Read {output_doc_path}
+2. Parse YAML front matter:
+   - Check `status` for current stage
+   - Read `inputs` list to restore context
+3. Re-read all input files from `inputs`
+4. Resume from next stage based on status
+```
+
+### When NOT to Use This Pattern
+
+- **Short, single-turn outputs:** Just write once at the end
+- **Purely conversational workflows:** No persistent document needed
+- **Multiple independent artifacts:** Each gets its own file; write each directly
+
+---
+
+## Sequential Progressive Disclosure
+
+Place numbered prompt files at the skill root when:
+- Multi-phase workflow with ordered questions
+- Input of one phase affects the next
+- User requires specific sequence
+- Workflow is long-running and stages shouldn't be visible upfront
+
+### Prompt File Structure
+
+```
+my-workflow/
+├── SKILL.md
+├── 01-discovery.md           # Stage 1: Gather requirements, start output doc
+├── 02-planning.md            # Stage 2: Create plan (uses discovery output)
+├── 03-execution.md           # Stage 3: Execute (uses plan, updates output)
+├── 04-review.md              # Stage 4: Review and polish final output
+└── references/
+    └── stage-templates.md
+```
+
+### Progression Conditions
+
+Each prompt file specifies when to proceed:
+
+```markdown
+# 02-planning.md
+
+## Prerequisites
+- Discovery complete (output doc exists and has discovery section)
+- User approved scope (user confirmed: proceed)
+
+## On Activation
+1. Read the output doc to get discovery context
+2. Generate plan based on discovered requirements
+3. **Append/insert plan section into the output doc**
+4. Present plan summary to user
+
+## Progression Condition
+Proceed to execution stage when user confirms: "Proceed with plan" OR user provides modifications
+
+## On User Approval
+Route to 03-execution.md
+```
+
+### SKILL.md Routes to Prompt Files
+
+Main SKILL.md is minimal — just routing logic:
+
+```markdown
+## Workflow Entry
+
+1. Load config from {project-root}/_bmad/bmb/config.yaml
+
+2. Check if workflow in progress:
+   - If output doc exists (user specifies path or we prompt):
+     - Read doc to determine current stage
+     - Resume from last completed section
+   - Else: Start at 01-discovery.md
+
+3. Route to appropriate prompt file based on stage
+```
+
+### When NOT to Use Separate Prompt Files
+
+Keep inline in SKILL.md when:
+- Simple skill (session-long context fits)
+- Well-known domain tool usage
+- Single-purpose utility
+- All stages are independent or can be visible upfront
+
+---
+
+## Module Metadata Reference
+
+BMad module workflows require extended frontmatter metadata. See `references/metadata-reference.md` for the metadata template, field explanations, and comparisons between standalone skills and module workflows.
+
+---
+
+## Workflow Architecture Checklist
+
+Before finalizing a BMad module workflow, verify:
+
+- [ ] **Facilitator persona**: Does the workflow treat the operator as expert?
+- [ ] **Config integration**: Are language, output locations, and module props read and used?
+- [ ] **Portable paths**: All artifact paths use `{project_root}`?
+- [ ] **Continuous output**: Does each stage write to the output document directly (survives compaction)?
+- [ ] **Document-as-cache**: Output doc has YAML front matter with `status` and `inputs` for recovery?
+- [ ] **Input tracking**: Does front matter list relative paths to all input files used?
+- [ ] **Final polish**: Does workflow include a subagent polish step at the end?
+- [ ] **Progressive disclosure**: Are stages in prompt files at root with clear progression conditions?
+- [ ] **Metadata complete**: All bmad-* fields present and accurate?
+- [ ] **Recovery pattern**: Can the workflow resume by reading the output doc front matter?
+
+---
+
+## Example: Complete BMad Workflow Skeleton
+
+```
+my-module-workflow/
+├── SKILL.md                              # Routing + entry logic
+├── 01-discovery.md                       # Gather requirements
+├── 02-planning.md                        # Create plan
+├── 03-execution.md                       # Execute
+├── 04-review.md                          # Review results
+├── references/
+│   └── templates.md                      # Stage templates
+└── scripts/
+    └── validator.sh                      # Output validation
+```
+
+**SKILL.md** (minimal routing):
+```yaml
+---
+name: bmad-mymodule-workflow
+description: Complex multi-stage workflow for my module. Use when user requests to 'run my module workflow' or 'create analysis report'.
+---
+
+## Workflow Entry
+
+1. Use bmad-init skill (module: mm) — loads user_name, communication_language, document_output_language, output_folder, my_output_folder
+
+2. Ask user for output document path (or suggest {my_output_folder}/analysis-{timestamp}.md)
+
+3. Check if doc exists:
+   - If yes: read to determine current stage, resume
+   - If no: start at 01-discovery.md
+
+4. Route to appropriate prompt file based on stage
+```
+
+**01-discovery.md**:
+```markdown
+Language: {communication_language}
+Output Language: {document_output_language}
+Output Location: {my_output_folder}
+
+## Discovery
+
+1. What are we building?
+2. What are the constraints?
+3. What input files should we reference?
+
+**Create**: {output_doc_path} with:
+```markdown
+---
+title: "Analysis: {topic}"
+status: "discovery"
+inputs:
+  - "{relative_path_to_input_1}"
+  - "{relative_path_to_input_2}"
+created: "{timestamp}"
+updated: "{timestamp}"
+---
+
+# Analysis: {topic}
+
+## Discovery
+[findings...]
+
+---
+
+*Status: Stage 1 complete*
+```
+
+## Progression
+When complete → 02-planning.md
+```
+
+**02-planning.md**:
+```markdown
+Language: {communication_language}
+Output Language: {document_output_language}
+
+## Planning Start
+
+1. Read {output_doc_path}
+2. Parse YAML front matter — reload all `inputs` to restore context
+3. Verify status is "discovery"
+
+## Planning
+1. Generate plan based on discovery
+2. Update {output_doc_path}:
+   - Update status to "planning"
+   - Append planning section
+
+## Progression
+When complete → 03-execution.md
+```
+
+**04-review.md**:
+```markdown
+Language: {communication_language}
+Output Language: {document_output_language}
+
+## Final Polish
+
+1. Read the complete output doc
+2. Launch a general-purpose agent:
+```
+Task: Polish {output_doc_path}
+
+Actions:
+1. Check cohesion - do sections flow logically?
+2. Find and remove redundancy
+3. Detect contradictions and fix them
+4. If document is >5 sections, add a TOC at the top
+5. Ensure consistent formatting and tone
+6. Update YAML status to "complete" and remove draft markers
+
+Write the polished version back to the same file.
+```
+
+## Progression
+When complete → present final result to user
+```

package/_bmad/bmb/skills/bmad-workflow-builder/references/metadata-reference.md

@@ -0,0 +1,126 @@
+# Manifest Reference
+
+Every BMad skill has a `bmad-manifest.json` at its root. This is the unified format for agents, workflows, and simple skills.
+
+## File Location
+
+```
+{skillname}/
+├── SKILL.md              # name, description, workflow content
+├── bmad-manifest.json    # Capabilities, module integration
+└── ...
+```
+
+## SKILL.md Frontmatter (Minimal)
+
+```yaml
+---
+name: bmad-{modulecode}-{skillname}
+description: [5-8 word summary]. [Use when user says 'X' or 'Y'.]
+---
+```
+
+## bmad-manifest.json
+
+**NOTE:** Do NOT include `$schema` in generated manifests. The schema is used by validation tooling only — it is not part of the delivered skill.
+
+```json
+{
+  "module-code": "bmb",
+  "replaces-skill": "bmad-original-skill",
+  "has-memory": true,
+  "capabilities": [
+    {
+      "name": "build",
+      "menu-code": "BP",
+      "description": "Builds skills through conversational discovery. Outputs to skill folder.",
+      "supports-headless": true,
+      "prompt": "build-process.md",
+      "phase-name": "design",
+      "after": ["create-requirements"],
+      "before": ["quality-optimize"],
+      "is-required": true,
+      "output-location": "{bmad_builder_output_folder}"
+    },
+    {
+      "name": "validate",
+      "menu-code": "VL",
+      "description": "Runs validation checks and produces quality report.",
+      "supports-headless": true
+    }
+  ]
+}
+```
+
+## Field Reference
+
+### Top-Level Fields
+
+| Field | Type | Required | Purpose |
+|-------|------|----------|---------|
+| `module-code` | string | If module | Short code for namespacing (e.g., `bmb`, `cis`) |
+| `replaces-skill` | string | No | Registered skill name this replaces. Inherits metadata during bmad-init. |
+| `persona` | string | Agents only | Succinct distillation of the agent's essence. **Presence = this is an agent.** |
+| `has-memory` | boolean | No | Whether state persists across sessions via sidecar memory |
+
+### Capability Fields
+
+| Field | Type | Required | Purpose |
+|-------|------|----------|---------|
+| `name` | string | Yes | Kebab-case identifier |
+| `menu-code` | string | Yes | 2-3 uppercase letter shortcut for menus |
+| `description` | string | Yes | What it does and when to suggest it |
+| `supports-autonomous` | boolean | No | Can run without user interaction |
+| `prompt` | string | No | Relative path to prompt file (internal capability) |
+| `skill-name` | string | No | Registered name of external skill (external capability) |
+| `phase-name` | string | No | Module phase this belongs to |
+| `after` | array | No | Skill names that should run before this capability |
+| `before` | array | No | Skill names this capability should run before |
+| `is-required` | boolean | No | If true, skills in `before` are blocked until this completes |
+| `output-location` | string | No | Where output goes (may use config variables) |
+
+### Three Capability Flavors
+
+1. **Has `prompt`** — internal capability routed to a prompt file
+2. **Has `skill-name`** — delegates to another registered skill
+3. **Has neither** — SKILL.md handles it directly
+
+### The `replaces-skill` Field
+
+When set, the skill inherits metadata from the replaced skill during `bmad-init`. Explicit fields in the new manifest override inherited values.
+
+## Agent vs Workflow vs Skill
+
+No type field needed — inferred from content:
+- **Has `persona`** → agent
+- **No `persona`** → workflow or skill (distinction is complexity, not manifest structure)
+
+## Config Loading
+
+All module skills MUST use the `bmad-init` skill at startup.
+
+See `references/complex-workflow-patterns.md` for the config loading pattern.
+
+## Path Construction Rules — CRITICAL
+
+Only use `{project-root}` for `_bmad` paths.
+
+**Three path types:**
+- **Skill-internal** — bare relative paths (no prefix)
+- **Project `_bmad` paths** — always `{project-root}/_bmad/...`
+- **Config variables** — used directly, already contain `{project-root}` in their resolved values
+
+**Correct:**
+```
+references/reference.md                # Skill-internal (bare relative)
+stage-one.md                          # Skill-internal (prompt at root)
+{project-root}/_bmad/planning/prd.md  # Project _bmad path
+{planning_artifacts}/prd.md           # Config var (already has full path)
+```
+
+**Never use:**
+```
+../../other-skill/file.md              # Cross-skill relative path breaks with reorganization
+{project-root}/{config_var}/output.md # Double-prefix
+./references/reference.md              # Relative prefix breaks context changes
+```

package/_bmad/bmb/skills/bmad-workflow-builder/references/quality-dimensions.md

@@ -0,0 +1,45 @@
+# Quality Dimensions — Quick Reference
+
+Six dimensions to keep in mind when building skills. The quality scanners check these automatically during optimization — this is a mental checklist for the build phase.
+
+## 1. Informed Autonomy
+
+The executing agent needs enough context to make judgment calls when situations don't match the script. The Overview section establishes this: domain framing, theory of mind, design rationale.
+
+- Simple utilities need minimal context — input/output is self-explanatory
+- Interactive/complex workflows need domain understanding, user perspective, and rationale for non-obvious choices
+- When in doubt, explain *why* — an agent that understands the mission improvises better than one following blind steps
+
+## 2. Intelligence Placement
+
+Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide).
+
+**Test:** If a script contains an `if` that decides what content *means*, intelligence has leaked.
+
+**Reverse test:** If a prompt validates structure, counts items, parses known formats, compares against schemas, or checks file existence — determinism has leaked into the LLM. That work belongs in a script. Scripts have access to full bash, Python with standard library plus PEP 723 dependencies, and system tools — think broadly about what can be offloaded.
+
+## 3. Progressive Disclosure
+
+SKILL.md stays focused. Detail goes where it belongs.
+
+- Stage instructions → prompt files at skill root
+- Reference data, schemas, large tables → `references/`
+- Templates, config files → `assets/`
+- Multi-branch SKILL.md under ~250 lines: fine as-is
+- Single-purpose up to ~500 lines: acceptable if focused
+
+## 4. Description Format
+
+Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]`
+
+Default to conservative triggering. See `references/standard-fields.md` for full format and examples.
+
+## 5. Path Construction
+
+Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`.
+
+See `references/standard-fields.md` for correct/incorrect patterns.
+
+## 6. Token Efficiency
+
+Remove genuine waste (repetition, defensive padding, meta-explanation). Preserve context that enables judgment (domain framing, theory of mind, design rationale). These are different things — the prompt-craft scanner distinguishes between them.