bmad-studio 0.1.0 → 0.2.0

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

@@ -1,523 +0,0 @@
-# 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

@@ -1,126 +0,0 @@
-# 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

@@ -1,45 +0,0 @@
-# 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.