bmad-studio 0.1.0

package/_bmad/bmb/skills/bmad-workflow-builder/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: bmad-workflow-builder
+description: Builds workflows and skills through conversational discovery and validates existing ones. Use when the user requests to "build a workflow", "modify a workflow", "quality check workflow", or "optimize skill".
+argument-hint: "--headless or -H to not prompt user, initial input for create, path to existing skill with keywords optimize, edit, validate"
+---
+
+# Workflow & Skill Builder
+
+## Overview
+
+This skill helps you build AI workflows and skills through conversational discovery and iterative refinement. Act as an architect guide, walking users through six phases: intent discovery, skill type classification, requirements gathering, drafting, building, and testing. Your output is a complete skill structure — from simple composable utilities to complex multi-stage workflows — ready to integrate into the BMad Method ecosystem.
+
+## Vision: Build More, Architect Dreams
+
+You're helping dreamers, builders, doers, and visionaries create the AI workflows and skills of their dreams.
+
+**What they're building:**
+
+Workflows and skills are **processes, tools, and composable building blocks** — and some may benefit from personality or tone guidance when it serves the user experience. A workflow automates multi-step processes. A skill provides reusable capabilities. They range from simple input/output utilities to complex multi-stage workflows with progressive disclosure. This builder itself is a perfect example of a complex workflow — multi-stage with routing, config integration, and the ability to perform different actions with human in the loop and autonomous modes if desired based on the clear intent of the input or conversation!
+
+**The bigger picture:**
+
+These workflows become part of the BMad Method ecosystem. If the user with your guidance can describe it, you can build it.
+
+**Your output:** A skill structure ready to integrate into a module or use standalone.
+
+## On Activation
+
+1. Invoke the `bmad-init` skill to get the config variables for the skill — store as `{var-name}` for all vars returned. If the skill does not exist, do your best to infer the users name and language. Greet user as `{user_name}` with a dream builder's enthusiasm — this will be fun! Always use `{communication_language}` for all communications.
+
+2. Detect user's intent from their request:
+
+**Autonomous/Headless Mode Detection:** If the user passes `--headless` or `-H` flags, or if their intent clearly indicates non-interactive execution, set `{headless_mode}=true` and pass to all sub-prompts.
+
+3. Route by intent — see Quick Reference below, or read the capability descriptions that follow.
+
+## Build Process
+
+This is the core creative path — where workflow and skill ideas become reality. Through six phases of conversational discovery, you guide users from a rough vision to a complete, tested skill structure. This covers building new workflows/skills from scratch, converting non-compliant formats, editing existing ones, and applying improvements or fixes.
+
+Workflows and skills span three types: simple utilities (composable building blocks), simple workflows (single-file processes), and complex workflows (multi-stage with routing and progressive disclosure). The build process includes a lint gate for structural validation. When building or modifying skills that include scripts, unit tests are created alongside the scripts and run as part of validation.
+
+Load `build-process.md` to begin.
+
+## Quality Optimizer
+
+For workflows/skills that already work but could work *better*. This is comprehensive validation and performance optimization — structure compliance, prompt craft, execution efficiency, workflow integrity, enhancement opportunities, and more. Uses deterministic lint scripts for instant structural checks and LLM scanner subagents for judgment-based analysis, all run in parallel.
+
+Run this anytime you want to assess and improve an existing skill's quality.
+
+Load `quality-optimizer.md` — it orchestrates everything including scan modes, autonomous handling, and remediation options.
+
+---
+
+## Quick Reference
+
+| Intent | Trigger Phrases | Route |
+|--------|----------------|-------|
+| **Build** | "build/create/design/convert/edit/fix a workflow/skill/tool" | Load `build-process.md` |
+| **Quality Optimize** | "quality check", "validate", "review/optimize/improve workflow/skill" | Load `quality-optimizer.md` |
+| **Unclear** | — | Present the two options above and ask |
+
+Pass `{headless_mode}` flag to all routes. Use TodoList tool to track progress through multi-step flows. Use AskUserQuestion tool when structuring questions for users. Use subagents for parallel work (quality scanners, web research or document review).
+
+Help the user create amazing Workflows and tools!

package/_bmad/bmb/skills/bmad-workflow-builder/assets/SKILL-template.md

@@ -0,0 +1,117 @@
+---
+name: bmad-{module-code-or-empty}{skill-name}
+description: {skill-description} # Format: [5-8 word summary]. [trigger phrase, e.g. Use when user says "create xyz"]
+---
+
+# {skill-name}
+
+## Overview
+
+{overview-template}
+
+{if-simple-utility}
+## Input
+
+{input-format-description}
+
+## Process
+
+{processing-steps}
+
+## Output
+
+{output-format-description}
+{/if-simple-utility}
+
+{if-simple-workflow}
+Act as {role-guidance}.
+
+## On Activation
+
+{if-bmad-init}
+1. **Load config via bmad-init skill** — Store all returned vars for use:
+   - Use `{user_name}` from config for greeting
+   - Use `{communication_language}` for all communications
+   {if-creates-docs}- Use `{document_output_language}` for output documents{/if-creates-docs}
+
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`
+{/if-bmad-init}
+
+3. **Proceed to workflow steps below**
+
+## Workflow Steps
+
+### Step 1: {step-1-name}
+{step-1-instructions}
+
+### Step 2: {step-2-name}
+{step-2-instructions}
+
+### Step 3: {step-3-name}
+{step-3-instructions}
+{/if-simple-workflow}
+
+{if-complex-workflow}
+Act as {role-guidance}.
+
+{if-headless}
+## Activation Mode Detection
+
+**Check activation context immediately:**
+
+1. **Headless mode**: If the user passes `--headless` or `-H` flags, or if their intent clearly indicates non-interactive execution:
+   - Skip questions, proceed with safe defaults, output structured results
+   - If `--headless:{task-name}` → run that specific task headless mode
+   - If just `--headless` → run default headless behavior
+
+2. **Interactive mode** (default): Proceed to `## On Activation` section below
+{/if-headless}
+
+## On Activation
+
+{if-bmad-init}
+1. **Load config via bmad-init skill** — Store all returned vars for use:
+   - Use `{user_name}` from config for greeting
+   - Use `{communication_language}` for all communications
+   {if-creates-docs}- Use `{document_output_language}` for output documents{/if-creates-docs}
+   - Store any other config variables as `{var-name}` and use appropriately
+
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`
+{/if-bmad-init}
+
+3. **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 stage
+   - Else: Start at `01-{stage-1-name}.md`
+
+4. **Route to appropriate stage** based on progress
+
+{if-headless}
+**Headless mode routing:**
+- Default: Run all stages sequentially with safe defaults
+- Named task: Execute specific stage or task
+- Output structured JSON results when complete
+{/if-headless}
+
+## Stages
+
+| # | Stage | Purpose | Prompt |
+|---|-------|---------|--------|
+| 1 | {stage-1-name} | {stage-1-purpose} | `01-{stage-1-name}.md` |
+| 2 | {stage-2-name} | {stage-2-purpose} | `02-{stage-2-name}.md` |
+{/if-complex-workflow}
+
+{if-external-skills}
+## External Skills
+
+This workflow uses:
+{external-skills-list}
+{/if-external-skills}
+
+{if-scripts}
+## Scripts
+
+Available scripts in `scripts/`:
+- `{script-name}` — {script-description}
+{/if-scripts}

package/_bmad/bmb/skills/bmad-workflow-builder/assets/quality-report-template.md

@@ -0,0 +1,260 @@
+# Quality Report: {skill-name}
+
+**Scanned:** {timestamp}
+**Skill Path:** {skill-path}
+**Report:** {report-file-path}
+**Performed By** QualityReportBot-9001 and {user_name}
+
+## Executive Summary
+
+- **Total Issues:** {total-issues}
+- **Critical:** {critical} | **High:** {high} | **Medium:** {medium} | **Low:** {low}
+- **Overall Quality:** {Excellent|Good|Fair|Poor}
+- **Overall Cohesion:** {cohesion-score}
+- **Craft Assessment:** {craft-assessment}
+
+<!-- Synthesize a 1-3 sentence narrative: skill purpose (from enhancement-opportunities skill_understanding.purpose), architecture quality highlights, and most significant finding. -->
+{executive-narrative}
+
+### Issues by Category
+
+| Category | Critical | High | Medium | Low |
+|----------|----------|------|--------|-----|
+| Structural | {n} | {n} | {n} | {n} |
+| Prompt Craft | {n} | {n} | {n} | {n} |
+| Cohesion | {n} | {n} | {n} | {n} |
+| Efficiency | {n} | {n} | {n} | {n} |
+| Quality | {n} | {n} | {n} | {n} |
+| Scripts | {n} | {n} | {n} | {n} |
+| Creative | — | — | {n} | {n} |
+
+---
+
+## Strengths
+
+*What this skill does well — preserve these during optimization:*
+
+<!-- Collect from ALL of these sources:
+  - All scanners: findings[] with severity="strength" or category="strength"
+  - prompt-craft: findings where severity="note" and observation is positive
+  - prompt-craft: positive aspects from assessments.skillmd_assessment.notes
+  - enhancement-opportunities: bright_spots from each assessments.user_journeys[] entry
+  Group by theme. Each strength should explain WHY it matters. -->
+
+{strengths-list}
+
+---
+
+{if-truly-broken}
+## Truly Broken or Missing
+
+*Issues that prevent the workflow/skill from working correctly:*
+
+<!-- Every CRITICAL and HIGH severity issue from ALL scanners. Maximum detail: description, affected files/lines, fix instructions. These are the most actionable part of the report. -->
+
+{truly-broken-findings}
+
+---
+{/if-truly-broken}
+
+## Detailed Findings by Category
+
+### 1. Structural
+
+<!-- Source: workflow-integrity-temp.json -->
+
+{if-stage-summary}
+**Stage Summary:** {total-stages} stages | Missing: {missing-stages} | Orphaned: {orphaned-stages}
+{/if-stage-summary}
+
+<!-- List findings by severity: Critical > High > Medium > Low. Omit empty severity levels. -->
+
+{structural-findings}
+
+### 2. Prompt Craft
+
+<!-- Source: prompt-craft-temp.json -->
+
+**Skill Assessment:**
+- Overview quality: {overview-quality}
+- Progressive disclosure: {progressive-disclosure}
+- {skillmd-assessment-notes}
+
+{if-prompt-health}
+**Prompt Health:** {prompts-with-config-header}/{total-prompts} with config header | {prompts-with-progression}/{total-prompts} with progression conditions | {prompts-self-contained}/{total-prompts} self-contained
+{/if-prompt-health}
+
+{prompt-craft-findings}
+
+### 3. Cohesion
+
+<!-- Source: skill-cohesion-temp.json -->
+
+{if-cohesion-analysis}
+**Cohesion Analysis:**
+
+<!-- Include only dimensions present in scanner output. -->
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Stage Flow Coherence | {score} | {notes} |
+| Purpose Alignment | {score} | {notes} |
+| Complexity Appropriateness | {score} | {notes} |
+| Stage Completeness | {score} | {notes} |
+| Redundancy Level | {score} | {notes} |
+| Dependency Graph | {score} | {notes} |
+| Output Location Alignment | {score} | {notes} |
+| User Journey | {score} | {notes} |
+{/if-cohesion-analysis}
+
+{cohesion-findings}
+
+{if-creative-suggestions}
+**Creative Suggestions:**
+
+<!-- From findings[] with severity="suggestion". Each: title, detail, action. -->
+
+{creative-suggestions}
+{/if-creative-suggestions}
+
+### 4. Efficiency
+
+<!-- Source: execution-efficiency-temp.json -->
+
+{efficiency-issue-findings}
+
+{if-efficiency-opportunities}
+**Optimization Opportunities:**
+
+<!-- From findings[] with severity ending in -opportunity. Each: title, detail (includes type/savings narrative), action. -->
+
+{efficiency-opportunities}
+{/if-efficiency-opportunities}
+
+### 5. Quality
+
+<!-- Source: path-standards-temp.json, scripts-temp.json -->
+
+{quality-findings}
+
+### 6. Scripts
+
+<!-- Source: scripts-temp.json AND script-opportunities-temp.json. Merge and deduplicate across both. -->
+
+{if-script-inventory}
+**Script Inventory:** {total-scripts} scripts ({by-type-breakdown}) | Missing tests: {missing-tests-list}
+{/if-script-inventory}
+
+{script-issue-findings}
+
+{if-script-opportunities}
+**Script Opportunity Findings:**
+
+<!-- From script-opportunities-temp.json findings[]. These identify LLM work that should be scripts.
+     Each: title, detail (includes determinism/complexity/savings narrative), action. -->
+
+{script-opportunities}
+
+**Token Savings:** {total-estimated-token-savings} | Highest value: {highest-value-opportunity} | Prepass opportunities: {prepass-count}
+{/if-script-opportunities}
+
+### 7. Creative (Edge-Case & Experience Innovation)
+
+<!-- Source: enhancement-opportunities-temp.json. These are advisory suggestions, not errors. -->
+
+**Skill Understanding:**
+- **Purpose:** {skill-purpose}
+- **Primary User:** {primary-user}
+- **Key Assumptions:**
+{key-assumptions-list}
+
+**Enhancement Findings:**
+
+<!-- Organize by: high-opportunity > medium-opportunity > low-opportunity.
+     Each: title, detail, action. -->
+
+{enhancement-findings}
+
+{if-top-insights}
+**Top Insights:**
+
+<!-- From enhancement-opportunities assessments.top_insights[]. These are the synthesized highest-value observations.
+     Each: title, detail, action. -->
+
+{top-insights}
+{/if-top-insights}
+
+---
+
+{if-user-journeys}
+## User Journeys
+
+*How different user archetypes experience this skill:*
+
+<!-- From enhancement-opportunities user_journeys[]. Reproduce EVERY archetype fully. -->
+
+### {archetype-name}
+
+{journey-summary}
+
+**Friction Points:**
+{friction-points-list}
+
+**Bright Spots:**
+{bright-spots-list}
+
+<!-- Repeat for ALL archetypes. Do not skip any. -->
+
+---
+{/if-user-journeys}
+
+{if-autonomous-assessment}
+## Autonomous Readiness
+
+<!-- From enhancement-opportunities autonomous_assessment. Include ALL fields. -->
+
+- **Overall Potential:** {overall-potential}
+- **HITL Interaction Points:** {hitl-count}
+- **Auto-Resolvable:** {auto-resolvable-count}
+- **Needs Input:** {needs-input-count}
+- **Suggested Output Contract:** {output-contract}
+- **Required Inputs:** {required-inputs-list}
+- **Notes:** {assessment-notes}
+
+---
+{/if-autonomous-assessment}
+
+## Quick Wins (High Impact, Low Effort)
+
+<!-- Pull from ALL scanners: findings where fix effort is trivial/low but impact is meaningful. -->
+
+| Issue | File | Effort | Impact |
+|-------|------|--------|--------|
+{quick-wins-rows}
+
+---
+
+## Optimization Opportunities
+
+<!-- Synthesize across scanners — not a copy of findings but a narrative of improvement themes. -->
+
+**Prompt Craft:**
+{prompt-optimization-narrative}
+
+**Performance:**
+{performance-optimization-narrative}
+
+**Maintainability:**
+{maintainability-optimization-narrative}
+
+---
+
+## Recommendations
+
+<!-- Rank by: severity first, then breadth of impact, then effort (prefer low-effort). Up to 5. -->
+
+1. {recommendation-1}
+2. {recommendation-2}
+3. {recommendation-3}
+4. {recommendation-4}
+5. {recommendation-5}

package/_bmad/bmb/skills/bmad-workflow-builder/bmad-manifest.json

@@ -0,0 +1,23 @@
+{
+  "module-code": "bmb",
+  "capabilities": [
+    {
+      "name": "build",
+      "menu-code": "BP",
+      "description": "Build, edit, or convert workflows and skills through six-phase conversational discovery. Covers new skills, format conversion, edits, and fixes.",
+      "supports-headless": true,
+      "prompt": "build-process.md",
+      "phase-name": "anytime",
+      "output-location": "{bmad_builder_output_folder}"
+    },
+    {
+      "name": "quality-optimize",
+      "menu-code": "QO",
+      "description": "Comprehensive validation and optimization using lint scripts and LLM scanner subagents. Structure, prompt craft, efficiency, and more.",
+      "supports-headless": true,
+      "prompt": "quality-optimizer.md",
+      "phase-name": "anytime",
+      "output-location": "{bmad_builder_reports}"
+    }
+  ]
+}

package/_bmad/bmb/skills/bmad-workflow-builder/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/_bmad/bmb/skills/bmad-workflow-builder/build-process.md

@@ -0,0 +1,208 @@
+---
+name: build-process
+description: Six-phase conversational discovery process for building BMad workflows and skills. Covers intent discovery, skill type classification, requirements gathering, drafting, building, and summary.
+---
+
+**Language:** Use `{communication_language}` for all output.
+
+# Build Process
+
+Build workflows and skills through six phases of conversational discovery. Act as an architect guide — help users articulate their vision completely, classify the right skill type, and build something that exceeds what they imagined.
+
+## Phase 1: Discover Intent
+
+Understand their vision before diving into specifics. Let them describe what they want to build, encourage them to be as detailed as possible including edge cases, variants, tone and persona of the workflow if needed, tools or other skills.
+
+**Input flexibility:** Accept input in any format:
+- Existing BMad workflow/skill path → read, analyze, determine if editing or converting
+- Rough idea or description → guide through discovery
+- Code, documentation, API specs → extract intent and requirements
+- Non-BMad skill/tool → convert to BMad-compliant structure
+
+If editing/converting an existing skill: read it, analyze what exists vs what's missing, ensure BMad standard conformance.
+
+Remember, the best user experience for this process is you conversationally allowing the user to give us info in this stage and you being able to confirm or suggest for them most of what you need for Phase 2 and 3.
+For Phase 2 and 3 that follow, adapt to what you already know that the user has given you so far, since they just brain dumped and gave you a lot of information
+
+## Phase 2: Classify Skill Type
+
+Ask upfront:
+- Will this be part of a module? If yes:
+   - What's the module code? (so we can configure properly)
+   - What other skills will it use from the core or specified module, we need the name, inputs, and output so we know how to integrate it? (bmad-init is default unless explicitly opted out, other skills should be either core skills or skills that will be part of the module)
+   - What are the variable names it will have access to that it needs to use? (variables can be use for things like choosing various paths in the skill, adjusting output styles, configuring output locations, tool availability, and anything that could be configurable by a user)
+
+Load `references/classification-reference.md` for the full decision tree, classification signals, and module context rules. Use it to classify:
+
+1. Composable building block with clear input/output and generally will use scripts either inline or in the scripts folder? → **Simple Utility**
+2. Fits in a single SKILL.md, may have some resources and a prompt, but generally not very complex. Human in the Loop and Autonomous abilities? → **Simple Workflow**
+   - **Headless mode?** Should this workflow support `--headless` invocation? (If it produces an artifact, headless mode may be valuable)
+3. Needs multiple stages and branches, may be long-running, uses progressive disclosure with prompts and resources, usually Human in the Loop with multiple paths and prompts? → **Complex Workflow**
+
+For Complex Workflows, also ask:
+- **Headless mode?** Should this workflow support `--headless` invocation?
+
+Present classification with reasoning. This determines template and structure.
+
+## Phase 3: Gather Requirements
+
+Work through conversationally, adapted per skill type, so you can either glean from the user or suggest based on their narrative.
+
+**All types — Common fields:**
+- **Name:** kebab-case. If module: `bmad-{modulecode}-{skillname}`. If standalone: `bmad-{skillname}`
+- **Description:** Two parts: [5-8 word summary of what it does]. [Use when user says 'specific phrase' or 'specific phrase'.] — Default to explicit invocation (conservative triggering) unless user specifies organic/reactive activation. See `references/standard-fields.md` for format details and examples.
+- **Overview:** 3-part formula (What/How/Why-Outcome). For interactive or complex skills, also include brief domain framing (what concepts does this skill operate on?) and theory of mind (who is the user and what might they not know?). These give the executing agent enough context to make judgment calls when situations don't match the script.
+- **Role guidance:** Brief "Act as a [role/expert]" statement to prime the model for the right domain expertise and tone
+- **Design rationale:** Any non-obvious choices the executing agent should understand? (e.g., "We interview before building because users rarely know their full requirements upfront")
+- **Module context:** Already determined in Phase 2
+- **External skills used:** Which skills does this invoke?
+- **Script Opportunity Discovery** (active probing — do not skip):
+  Walk through each planned step/stage with the user and apply these filters:
+  1. "Does this step have clear pass/fail criteria?" → Script candidate
+  2. "Could this run without LLM judgment — no interpretation, no creativity, no ambiguity?" → Strong script candidate
+  3. "Does it validate, transform, count, parse, format-convert, compare against a schema, or check structure?" → Almost certainly a script
+
+  **Common script-worthy operations:**
+  - Schema/format validation (JSON, YAML, frontmatter, file structure)
+  - Data extraction and transformation (parsing, restructuring, field mapping)
+  - Counting, aggregation, and metric collection (token counts, file counts, summary stats)
+  - File/directory structure checks (existence, naming conventions, required files)
+  - Pattern matching against known standards (path conventions, naming rules)
+  - Comparison operations (diff, version compare, before/after, cross-reference checking)
+  - Dependency graphing (parsing imports, references, manifest entries)
+  - Template artifact detection (orphaned placeholders, unresolved variables)
+  - Pre-processing for LLM steps (extract compact metrics from large files so the LLM works from structured data, not raw content)
+  - Post-processing validation (verify LLM output conforms to expected schema/structure)
+
+  **Present your script plan**: Before moving to Phase 4, explicitly tell the user which operations you plan to implement as scripts vs. prompts, with one-line reasoning for each. Ask if they agree or want to adjust.
+- **Creates output documents?** If yes, will use `{document_output_language}` from config
+**Simple Utility additional fields:**
+- **Input format:** What does it accept?
+- **Output format:** What does it return?
+- **Standalone?** Opt out of bmad-init? (Makes it a truly standalone building block)
+- **Composability:** How might this be used by other skills/workflows?
+- **Script needs:** What scripts does the utility require?
+
+**Simple Workflow additional fields:**
+- **Steps:** Numbered steps (inline in SKILL.md)
+- **Tools used:** What tools/CLIs/scripts does it use?
+- **Output:** What does it produce?
+- **Config variables:** What config vars beyond core does it need?
+
+**Complex Workflow additional fields:**
+- **Stages:** Named numbered stages with purposes
+- **Stage progression conditions:** When does each stage complete?
+- **Headless mode:** If yes, what should headless execution do? Default behavior? Named tasks?
+- **Config variables:** Core + module-specific vars needed
+- **Output artifacts:** What does this create? (output-location)
+- **Dependencies:** What must run before this? What does it use? (after/before arrays)
+
+**Module capability metadata (if part of a module):**
+For each capability, confirm these with the user — they determine how the module's help system presents and sequences the skill:
+- **phase-name:** Which module phase does this belong to? (e.g., "1-analysis", "2-design", "3-build", "anytime")
+- **after:** Array of skill names that should ideally run before this one. Ask: "What does this skill use as input? What should have already run?" (e.g., `["brainstorming", "perform-research"]`)
+- **before:** Array of skill names this should run before. Ask: "What downstream skills consume this skill's output?" (e.g., `["create-prd"]`)
+- **is-required:** If true, skills in the `before` array are blocked until this completes. If false, the ordering is a suggestion (nice-to-have input, not a hard dependency).
+- **description (capability):** Keep this VERY short — a single sentence describing what it produces, not how it works. This is what the LLM help system shows users. (e.g., "Produces executive product brief and optional LLM distillate for PRD input.")
+
+**Path conventions (CRITICAL):**
+- Skill-internal files use bare relative paths: `references/`, `scripts/`, and prompt files at root
+- Only `_bmad` paths get `{project-root}` prefix: `{project-root}/_bmad/...`
+- Config variables used directly — they already contain `{project-root}` (no double-prefix)
+
+## Phase 4: Draft & Refine
+
+Once you have a cohesive idea, think one level deeper, clarify with the user any gaps in logic or understanding. Create and present a plan. Point out vague areas. Ask what else is needed. Iterate until they say they're ready.
+
+## Phase 5: Build
+
+**Always load these before building:**
+- Load `references/standard-fields.md` — field definitions, description format, path rules
+- Load `references/skill-best-practices.md` — authoring patterns (freedom levels, templates, anti-patterns)
+- Load `references/quality-dimensions.md` — quick mental checklist for build quality
+
+**Load based on skill type:**
+- **If Complex Workflow:** Load `references/complex-workflow-patterns.md` — compaction survival, document-as-cache pattern, config integration, facilitator model, progressive disclosure with prompt files at root. This is essential for building workflows that survive long-running sessions.
+- **If module-based (any type):** Load `references/metadata-reference.md` — bmad-manifest.json field definitions, module metadata structure, config loading requirements.
+- **Always load** `references/script-opportunities-reference.md` — script opportunity spotting guide, catalog, and output standards. Use this to identify additional script opportunities not caught in Phase 3, even if no scripts were initially planned.
+
+When confirmed:
+
+1. Load template substitution rules from `references/template-substitution-rules.md` and apply
+
+2. Load unified template: `assets/SKILL-template.md`
+   - Apply skill-type conditionals (`{if-complex-workflow}`, `{if-simple-workflow}`, `{if-simple-utility}`) to keep only relevant sections
+
+3. **Progressive disclosure:** Keep SKILL.md focused on Overview, activation, and routing. Detailed stage instructions go in prompt files at the skill root. Reference data, schemas, and large tables go in `references/`. Multi-branch SKILL.md under ~250 lines is fine as-is; single-purpose up to ~500 lines if genuinely needed.
+
+4. Generate folder structure and include only what is needed for the specific skill:
+**Skill Source Tree:**
+```
+{skill-name}/
+├── SKILL.md           # name (same as folder name), description
+├── bmad-manifest.json # Capabilities, module integration, optional persona/memory
+├── *.md               # Prompt files and subagent definitions at root
+├── references/        # Reference data, schemas, guides (read for context)
+├── assets/            # Templates, starter files (copied/transformed into output)
+├── scripts/           # Deterministic code — validation, transformation, testing
+│   └── tests/         # All scripts need unit tests
+```
+
+**What goes where:**
+| Location | Contains | LLM relationship |
+|----------|----------|-----------------|
+| **Root `.md` files** | Prompt/instruction files, subagent definitions | LLM **loads and executes** these as instructions — they are extensions of SKILL.md |
+| **`references/`** | Reference data, schemas, tables, examples, guides | LLM **reads for context** — informational, not executable |
+| **`assets/`** | Templates, starter files, boilerplate | LLM **copies/transforms** these into output — not for reasoning |
+| **`scripts/`** | Python, shell scripts with tests | LLM **invokes** these — deterministic operations that don't need judgment |
+
+Only create subfolders that are needed — most skills won't need all four.
+
+5. **Generate bmad-manifest.json** — Use `scripts/manifest.py` (validation is automatic on every write). **IMPORTANT:** The generated manifest must NOT include a `$schema` field — the schema is used for validation tooling only and is not part of the delivered skill.
+   ```bash
+   # Create manifest
+   python3 scripts/manifest.py create {skill-path} \
+     --module-code {code}  # if part of a module \
+     --has-memory           # if state persists across sessions
+
+   # Add each capability (even single-purpose skills get one)
+   # NOTE: capability description must be VERY short — what it produces, not how it works
+   python3 scripts/manifest.py add-capability {skill-path} \
+     --name {name} --menu-code {MC} --description "Short: what it produces." \
+     --supports-autonomous \
+     --prompt {name}.md               # internal capability
+     # OR --skill-name {skill}       # external skill
+     # omit both if SKILL.md handles it directly
+     # Module capabilities also need:
+     --phase-name {phase}            # which module phase
+     --after skill-a skill-b         # skills that should run before this
+     --before skill-c skill-d        # skills this should run before
+     --is-required                   # if must complete before 'before' skills proceed
+     --output-location "{var}"       # where output goes
+   ```
+
+6. Output to {`bmad_builder_output_folder`}
+
+7. **Lint gate** — run deterministic validation scripts:
+   ```bash
+   # Run both in parallel — they are independent
+   python3 scripts/scan-path-standards.py {skill-path}
+   python3 scripts/scan-scripts.py {skill-path}
+   ```
+   - If any script returns critical issues: fix them before proceeding
+   - If only warnings/medium: note them but proceed
+   - These are structural checks — broken paths and script standards issues should be resolved before shipping
+
+## Phase 6: Summary
+
+Present what was built: location, structure, capabilities. Include lint results. Ask if adjustments needed.
+
+If scripts exist, also run unit tests.
+
+**Remind user to commit** working version before optimization.
+
+**Offer quality optimization:**
+
+Ask: *"Build is done. Would you like to run a Quality Scan to optimize further?"*
+
+If yes, load `quality-optimizer.md` with `{scan_mode}=full` and the skill path.