bmad-studio 0.1.0

package/_bmad/bmb/skills/bmad-agent-builder/references/template-substitution-rules.md

@@ -0,0 +1,72 @@
+# Template Substitution Rules
+
+When building the agent, you MUST apply these conditional blocks to the templates:
+
+## For Module-Based Agents
+
+- `{if-module}` ... `{/if-module}` → Keep the content inside
+- `{if-standalone}` ... `{/if-standalone}` → Remove the entire block including markers
+- `{custom-config-properties}` → Replace with comma-separated custom property names (e.g., `journal_folder, adventure_logs_folder`) or remove line if none
+- `{module-code-or-empty}` → Replace with module code (e.g., `cis-`) or empty string for standalone
+
+## For Standalone Agents
+
+- `{if-module}` ... `{/if-module}` → Remove the entire block including markers
+- `{if-standalone}` ... `{/if-standalone}` → Keep the content inside
+- `{custom-config-properties}` → Remove (not used for standalone)
+- `{module-code-or-empty}` → Empty string
+- `{custom-init-questions}` → Add user's additional questions here (remove placeholder if none)
+
+## For Agents With Sidecar (Memory)
+
+- `{if-sidecar}` ... `{/if-sidecar}` → Keep the content inside
+- `{if-no-sidecar}` ... `{/if-no-sidecar}` → Remove the entire block including markers
+
+## For Agents Without Sidecar
+
+- `{if-sidecar}` ... `{/if-sidecar}` → Remove the entire block including markers
+- `{if-no-sidecar}` ... `{/if-no-sidecar}` → Keep the content inside
+
+## External Skills
+
+- `{if-external-skills}` ... `{/if-external-skills}` → Keep if agent uses external skills, otherwise remove entire block
+- `{external-skills-list}` → Replace with bulleted list of exact skill names:
+  ```markdown
+  - `bmad-skill-name-one` — Description
+  - `bmad-skill-name-two` — Description
+  ```
+
+## Custom Init Questions
+
+Add user's additional questions to the init.md template, replacing `{custom-init-questions}` placeholder. Remove the placeholder line if no custom questions.
+
+## Path References
+
+All generated agents use these paths:
+- `init.md` — First-run setup
+- `{name}.md` — Individual capability prompts
+- `references/memory-system.md` — Memory discipline (if sidecar needed)
+- `bmad-manifest.json` — Capabilities and metadata with menu codes
+- `scripts/` — Python/shell scripts for deterministic operations (if needed)
+
+## Frontmatter Placeholders
+
+Replace all frontmatter placeholders in SKILL-template.md:
+- `{module-code-or-empty}` → Module code (e.g., `cis-`) or empty
+- `{agent-name}` → Agent functional name (kebab-case)
+- `{short phrase what agent does}` → One-line description
+- `{displayName}` → Friendly name
+- `{title}` → Role title
+- `{role}` → Functional role
+- `{skillName}` → Full skill name with module prefix
+- `{user_name}` → From config
+- `{communication_language}` → From config
+
+## Content Placeholders
+
+Replace all content placeholders with agent-specific values:
+- `{overview-template}` → Overview paragraph (2-3 sentences) following the 3-part formula (What, How, Why/Outcome)
+- `{One-sentence identity.}` → Brief identity statement
+- `{Who is this agent? One clear sentence.}` → Identity description
+- `{How does this agent communicate? Be specific with examples.}` → Communication style
+- `{Guiding principle 1/2/3}` → Agent's principles

package/_bmad/bmb/skills/bmad-agent-builder/references/universal-scan-schema.md

@@ -0,0 +1,267 @@
+# Universal Scanner Output Schema
+
+All quality scanners — both LLM-based and deterministic lint scripts — MUST produce output conforming to this schema. No exceptions.
+
+## Top-Level Structure
+
+```json
+{
+  "scanner": "scanner-name",
+  "skill_path": "{path}",
+  "findings": [],
+  "assessments": {},
+  "summary": {
+    "total_findings": 0,
+    "by_severity": {},
+    "assessment": "1-2 sentence overall assessment"
+  }
+}
+```
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `scanner` | string | yes | Scanner identifier (e.g., `"workflow-integrity"`, `"prompt-craft"`) |
+| `skill_path` | string | yes | Absolute path to the skill being scanned |
+| `findings` | array | yes | ALL items — issues, strengths, suggestions, opportunities. Always an array, never an object |
+| `assessments` | object | yes | Scanner-specific structured analysis (cohesion tables, health metrics, user journeys, etc.). Free-form per scanner |
+| `summary` | object | yes | Aggregate counts and brief overall assessment |
+
+## Finding Schema (7 fields)
+
+Every item in `findings[]` has exactly these 7 fields:
+
+```json
+{
+  "file": "SKILL.md",
+  "line": 42,
+  "severity": "high",
+  "category": "frontmatter",
+  "title": "Brief headline of the finding",
+  "detail": "Full context — rationale, what was observed, why it matters",
+  "action": "What to do about it — fix, suggestion, or script to create"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | string | yes | Relative path to the affected file (e.g., `"SKILL.md"`, `"scripts/build.py"`). Empty string if not file-specific |
+| `line` | int\|null | no | Line number (1-based). `null` or `0` if not line-specific |
+| `severity` | string | yes | One of the severity values below |
+| `category` | string | yes | Scanner-specific category (e.g., `"frontmatter"`, `"token-waste"`, `"lint"`) |
+| `title` | string | yes | Brief headline (1 sentence). This is the primary display text |
+| `detail` | string | yes | Full context — fold rationale, observation, impact, nuance into one narrative. Empty string if title is self-explanatory |
+| `action` | string | yes | What to do — fix instruction, suggestion, or script to create. Empty string for strengths/notes |
+
+## Severity Values (complete enum)
+
+```
+critical | high | medium | low | high-opportunity | medium-opportunity | low-opportunity | suggestion | strength | note
+```
+
+**Routing rules:**
+- `critical`, `high` → "Truly Broken" section in report
+- `medium`, `low` → category-specific findings sections
+- `high-opportunity`, `medium-opportunity`, `low-opportunity` → enhancement/creative sections
+- `suggestion` → creative suggestions section
+- `strength` → strengths section (positive observations worth preserving)
+- `note` → informational observations, also routed to strengths
+
+## Assessment Sub-Structure Contracts
+
+The `assessments` object is free-form per scanner, but the HTML report renderer expects specific shapes for specific keys. These are the canonical formats.
+
+### user_journeys (enhancement-opportunities scanner)
+
+**Always an array of objects. Never an object keyed by persona.**
+
+```json
+"user_journeys": [
+  {
+    "archetype": "first-timer",
+    "summary": "Brief narrative of this user's experience",
+    "friction_points": ["moment 1", "moment 2"],
+    "bright_spots": ["what works well"]
+  }
+]
+```
+
+### autonomous_assessment (enhancement-opportunities scanner)
+
+```json
+"autonomous_assessment": {
+  "potential": "headless-ready|easily-adaptable|partially-adaptable|fundamentally-interactive",
+  "hitl_points": 3,
+  "auto_resolvable": 2,
+  "needs_input": 1,
+  "notes": "Brief assessment"
+}
+```
+
+### top_insights (enhancement-opportunities scanner)
+
+**Always an array of objects with title/detail/action (same shape as findings but without file/line/severity/category).**
+
+```json
+"top_insights": [
+  {
+    "title": "The key observation",
+    "detail": "Why it matters",
+    "action": "What to do about it"
+  }
+]
+```
+
+### cohesion_analysis (skill-cohesion / agent-cohesion scanner)
+
+```json
+"cohesion_analysis": {
+  "dimension_name": { "score": "strong|moderate|weak", "notes": "explanation" }
+}
+```
+
+Dimension names are scanner-specific (e.g., `stage_flow_coherence`, `persona_alignment`). The report renderer iterates all keys and renders a table row per dimension.
+
+### skill_identity / agent_identity (cohesion scanners)
+
+```json
+"skill_identity": {
+  "name": "skill-name",
+  "purpose_summary": "Brief characterization",
+  "primary_outcome": "What this skill produces"
+}
+```
+
+### skillmd_assessment (prompt-craft scanner)
+
+```json
+"skillmd_assessment": {
+  "overview_quality": "appropriate|excessive|missing",
+  "progressive_disclosure": "good|needs-extraction|monolithic",
+  "notes": "brief assessment"
+}
+```
+
+Agent variant adds `"persona_context": "appropriate|excessive|missing"`.
+
+### prompt_health (prompt-craft scanner)
+
+```json
+"prompt_health": {
+  "total_prompts": 3,
+  "with_config_header": 2,
+  "with_progression": 1,
+  "self_contained": 3
+}
+```
+
+### skill_understanding (enhancement-opportunities scanner)
+
+```json
+"skill_understanding": {
+  "purpose": "what this skill does",
+  "primary_user": "who it's for",
+  "assumptions": ["assumption 1", "assumption 2"]
+}
+```
+
+### stage_summary (workflow-integrity scanner)
+
+```json
+"stage_summary": {
+  "total_stages": 0,
+  "missing_stages": [],
+  "orphaned_stages": [],
+  "stages_without_progression": [],
+  "stages_without_config_header": []
+}
+```
+
+### metadata (structure scanner)
+
+Free-form key-value pairs. Rendered as a metadata block.
+
+### script_summary (scripts lint)
+
+```json
+"script_summary": {
+  "total_scripts": 5,
+  "by_type": {"python": 3, "shell": 2},
+  "missing_tests": ["script1.py"]
+}
+```
+
+### existing_scripts (script-opportunities scanner)
+
+Array of strings (script paths that already exist).
+
+## Complete Example
+
+```json
+{
+  "scanner": "workflow-integrity",
+  "skill_path": "/path/to/skill",
+  "findings": [
+    {
+      "file": "SKILL.md",
+      "line": 12,
+      "severity": "high",
+      "category": "frontmatter",
+      "title": "Missing required 'version' field in frontmatter",
+      "detail": "The SKILL.md frontmatter is missing the version field. This prevents the manifest generator from producing correct output and breaks version-aware consumers.",
+      "action": "Add 'version: 1.0.0' to the YAML frontmatter block"
+    },
+    {
+      "file": "build-process.md",
+      "line": null,
+      "severity": "strength",
+      "category": "design",
+      "title": "Excellent progressive disclosure pattern in build stages",
+      "detail": "Each stage provides exactly the context needed without front-loading information. This reduces token waste and improves LLM comprehension.",
+      "action": ""
+    },
+    {
+      "file": "SKILL.md",
+      "line": 45,
+      "severity": "medium-opportunity",
+      "category": "experience-gap",
+      "title": "No guidance for first-time users unfamiliar with build workflows",
+      "detail": "A user encountering this skill for the first time has no onboarding path. The skill assumes familiarity with stage-based workflows, which creates friction for newcomers.",
+      "action": "Add a 'Getting Started' section or link to onboarding documentation"
+    }
+  ],
+  "assessments": {
+    "stage_summary": {
+      "total_stages": 7,
+      "missing_stages": [],
+      "orphaned_stages": ["cleanup"]
+    }
+  },
+  "summary": {
+    "total_findings": 3,
+    "by_severity": {"high": 1, "medium-opportunity": 1, "strength": 1},
+    "assessment": "Well-structured skill with one critical frontmatter gap. Progressive disclosure is a notable strength."
+  }
+}
+```
+
+## DO NOT
+
+- **DO NOT** rename fields. Use exactly: `file`, `line`, `severity`, `category`, `title`, `detail`, `action`
+- **DO NOT** use `issues` instead of `findings` — the array is always called `findings`
+- **DO NOT** add fields to findings beyond the 7 defined above. Put scanner-specific structured data in `assessments`
+- **DO NOT** use separate arrays for strengths, suggestions, or opportunities — they go in `findings` with appropriate severity values
+- **DO NOT** change `user_journeys` from an array to an object keyed by persona name
+- **DO NOT** restructure assessment sub-objects — use the shapes defined above
+- **DO NOT** put free-form narrative data into `assessments` — that belongs in `detail` fields of findings or in `summary.assessment`
+
+## Self-Check Before Output
+
+Before writing your JSON output, verify:
+
+1. Is your array called `findings` (not `issues`, not `opportunities`)?
+2. Does every item in `findings` have all 7 fields: `file`, `line`, `severity`, `category`, `title`, `detail`, `action`?
+3. Are strengths in `findings` with `severity: "strength"` (not in a separate `strengths` array)?
+4. Are suggestions in `findings` with `severity: "suggestion"` (not in a separate `creative_suggestions` array)?
+5. Is `assessments` an object containing structured analysis data (not items that belong in findings)?
+6. Is `user_journeys` an array of objects (not an object keyed by persona)?
+7. Do `top_insights` items use `title`/`detail`/`action` (not `insight`/`suggestion`/`why_it_matters`)?

package/_bmad/bmb/skills/bmad-agent-builder/report-quality-scan-creator.md

@@ -0,0 +1,138 @@
+# Quality Scan Report Creator
+
+You are a master quality engineer tech writer agent QualityReportBot-9001. You create comprehensive, cohesive quality reports from multiple scanner outputs. You read all temporary JSON fragments, consolidate findings, remove duplicates, and produce a well-organized markdown report using the provided template. You are quality obsessed — nothing gets dropped. You will never attempt to fix anything — you are a writer, not a fixer.
+
+## Inputs
+
+- `{skill-path}` — Path to the agent being validated
+- `{quality-report-dir}` — Directory containing scanner temp files AND where to write the final report
+
+## Template
+
+Read `assets/quality-report-template.md` for the report structure. The template contains:
+- `{placeholder}` markers — replace with actual data
+- `{if-section}...{/if-section}` blocks — include only when data exists, omit entirely when empty
+- `<!-- comments -->` — inline guidance for what data to pull and from where; strip from final output
+
+## Process
+
+### Step 1: Ingest Everything
+
+1. Read `assets/quality-report-template.md`
+2. List ALL files in `{quality-report-dir}` — both `*-temp.json` (scanner findings) and `*-prepass.json` (structural metrics)
+3. Read EVERY JSON file
+
+### Step 2: Extract All Data Types
+
+All scanners now use the universal schema defined in `references/universal-scan-schema.md`. Scanner-specific data lives in `assessments{}`, not as top-level keys.
+
+For each scanner file, extract not just `findings` arrays but ALL of these data types:
+
+| Data Type | Where It Lives | Report Destination |
+|-----------|---------------|-------------------|
+| Issues/findings (severity: critical-low) | All scanner `findings[]` | Detailed Findings by Category |
+| Strengths (severity: "strength"/"note", category: "strength") | All scanners: findings where severity="strength" | Strengths section |
+| Agent identity | agent-cohesion `assessments.agent_identity` | Agent Identity section + Executive Summary |
+| Cohesion dimensional analysis | agent-cohesion `assessments.cohesion_analysis` | Cohesion Analysis table |
+| Consolidation opportunities | agent-cohesion `assessments.cohesion_analysis.redundancy_level.consolidation_opportunities` | Consolidation Opportunities in Cohesion |
+| Creative suggestions | `findings[]` with severity="suggestion" (no separate creative_suggestions array) | Creative Suggestions in Cohesion section |
+| Craft & agent assessment | prompt-craft `assessments.skillmd_assessment` (incl. `persona_context`), `assessments.prompt_health`, `summary.assessment` | Prompt Craft section header + Executive Summary |
+| Structure metadata | structure `assessments.metadata` (has_memory, has_headless, manifest_valid, etc.) | Structure & Capabilities section header |
+| User journeys | enhancement-opportunities `assessments.user_journeys[]` | User Journeys section |
+| Autonomous assessment | enhancement-opportunities `assessments.autonomous_assessment` | Autonomous Readiness section |
+| Skill understanding | enhancement-opportunities `assessments.skill_understanding` | Creative section header |
+| Top insights | enhancement-opportunities `assessments.top_insights[]` | Top Insights in Creative section |
+| Optimization opportunities | `findings[]` with severity ending in "-opportunity" (no separate opportunities array) | Optimization Opportunities in Efficiency section |
+| Script inventory & token savings | scripts `assessments.script_summary`, script-opportunities `summary` | Scripts sections |
+| Prepass metrics | `*-prepass.json` files | Context data points where useful |
+
+### Step 3: Populate Template
+
+Fill the template section by section, following the `<!-- comment -->` guidance in each. Key rules:
+
+- **Conditional sections:** Only include `{if-...}` blocks when the data exists. If a scanner didn't produce user_journeys, omit the entire User Journeys section.
+- **Empty severity levels:** Within a category, omit severity sub-headers that have zero findings.
+- **Persona voice:** When reporting prompt-craft findings, remember that persona voice is INVESTMENT for agents, not waste. Reflect the scanner's nuance field if present.
+- **Strip comments:** Remove all `<!-- ... -->` blocks from final output.
+
+### Step 4: Deduplicate
+
+- **Same issue, two scanners:** Keep ONE entry, cite both sources. Use the more detailed description.
+- **Same issue pattern, multiple files:** List once with all file:line references in a table.
+- **Issue + strength about same thing:** Keep BOTH — strength shows what works, issue shows what could be better.
+- **Overlapping creative suggestions:** Merge into the richer description.
+- **Routing:** "note"/"strength" severity → Strengths section. "suggestion" severity → Creative subsection. Do not mix these into issue lists.
+
+### Step 5: Verification Pass
+
+**This step is mandatory.** After populating the report, re-read every temp file and verify against this checklist:
+
+- [ ] Every finding from every `*-temp.json` findings[] array
+- [ ] Agent identity block (persona_summary, primary_purpose, capability_count)
+- [ ] All findings with severity="strength" from any scanner
+- [ ] All positive notes from prompt-craft (severity="note")
+- [ ] Cohesion analysis dimensional scores table (if present)
+- [ ] Consolidation opportunities from cohesion redundancy analysis
+- [ ] Craft assessment, skill type assessment, and persona context assessment
+- [ ] Structure metadata (sections_found, has_memory, has_headless, manifest_valid)
+- [ ] ALL user journeys with ALL friction_points and bright_spots per archetype
+- [ ] The autonomous_assessment block (all fields)
+- [ ] All findings with severity="suggestion" from cohesion scanners
+- [ ] All findings with severity ending in "-opportunity" from execution-efficiency
+- [ ] assessments.top_insights from enhancement-opportunities
+- [ ] Script inventory and token savings from script-opportunities
+- [ ] Skill understanding (purpose, primary_user, key_assumptions)
+- [ ] Prompt health summary from prompt-craft (if prompts exist)
+
+If any item was dropped, add it to the appropriate section before writing.
+
+### Step 6: Write and Return
+
+Write report to: `{quality-report-dir}/quality-report.md`
+
+Return JSON:
+
+```json
+{
+  "report_file": "{full-path-to-report}",
+  "summary": {
+    "total_issues": 0,
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0,
+    "strengths_count": 0,
+    "enhancements_count": 0,
+    "user_journeys_count": 0,
+    "overall_quality": "Excellent|Good|Fair|Poor",
+    "overall_cohesion": "cohesive|mostly-cohesive|fragmented|confused",
+    "craft_assessment": "brief summary from prompt-craft",
+    "truly_broken_found": true,
+    "truly_broken_count": 0
+  },
+  "by_category": {
+    "structure_capabilities": {"critical": 0, "high": 0, "medium": 0, "low": 0},
+    "prompt_craft": {"critical": 0, "high": 0, "medium": 0, "low": 0},
+    "execution_efficiency": {"critical": 0, "high": 0, "medium": 0, "low": 0},
+    "path_script_standards": {"critical": 0, "high": 0, "medium": 0, "low": 0},
+    "agent_cohesion": {"critical": 0, "high": 0, "medium": 0, "low": 0},
+    "creative": {"high_opportunity": 0, "medium_opportunity": 0, "low_opportunity": 0}
+  },
+  "high_impact_quick_wins": [
+    {"issue": "description", "file": "location", "effort": "low"}
+  ]
+}
+```
+
+## Scanner Reference
+
+| Scanner | Temp File | Primary Category |
+|---------|-----------|-----------------|
+| structure | structure-temp.json | Structure & Capabilities |
+| prompt-craft | prompt-craft-temp.json | Prompt Craft |
+| execution-efficiency | execution-efficiency-temp.json | Execution Efficiency |
+| path-standards | path-standards-temp.json | Path & Script Standards |
+| scripts | scripts-temp.json | Path & Script Standards |
+| script-opportunities | script-opportunities-temp.json | Script Opportunities |
+| agent-cohesion | agent-cohesion-temp.json | Agent Cohesion |
+| enhancement-opportunities | enhancement-opportunities-temp.json | Creative |

package/_bmad/bmb/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BMad Manifest Schema",
+  "description": "Unified schema for all BMad skill manifest files (agents, workflows, skills)",
+
+  "type": "object",
+
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema identifier",
+      "type": "string"
+    },
+
+    "module-code": {
+      "description": "Short code for the module this skill belongs to (e.g., bmb, cis). Omit for standalone skills.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+
+    "replaces-skill": {
+      "description": "Registered name of the BMad skill this replaces. Inherits metadata during bmad-init.",
+      "type": "string",
+      "minLength": 1
+    },
+
+    "persona": {
+      "description": "Succinct distillation of the agent's essence — who they are, how they operate, what drives them. Presence of this field indicates the skill is an agent. Useful for other skills/agents to understand who they're interacting with.",
+      "type": "string",
+      "minLength": 1
+    },
+
+    "has-memory": {
+      "description": "Whether this skill persists state across sessions via sidecar memory.",
+      "type": "boolean"
+    },
+
+    "capabilities": {
+      "description": "What this skill can do. Every skill has at least one capability.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "description": "Capability identifier (kebab-case)",
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "menu-code": {
+            "description": "2-3 uppercase letter shortcut for interactive menus",
+            "type": "string",
+            "pattern": "^[A-Z]{2,3}$"
+          },
+          "description": {
+            "description": "What this capability does and when to suggest it",
+            "type": "string"
+          },
+          "supports-headless": {
+            "description": "Whether this capability can run without user interaction",
+            "type": "boolean"
+          },
+
+          "prompt": {
+            "description": "Relative path to the prompt file for internal capabilities (e.g., build-process.md). Omit if handled by SKILL.md directly or if this is an external skill call.",
+            "type": "string"
+          },
+          "skill-name": {
+            "description": "Registered name of an external skill this capability delegates to. Omit for internal capabilities.",
+            "type": "string"
+          },
+
+          "phase-name": {
+            "description": "Which module phase this capability belongs to (e.g., planning, design, anytime). For module sequencing.",
+            "type": "string"
+          },
+          "after": {
+            "description": "Skill names that should ideally run before this capability. If is-required is true on those skills, they block this one.",
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "before": {
+            "description": "Skill names that this capability should ideally run before. Helps the module sequencer understand ordering.",
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "is-required": {
+            "description": "Whether this capability must complete before skills listed in its 'before' array can proceed.",
+            "type": "boolean"
+          },
+          "output-location": {
+            "description": "Where this capability writes its output. May contain config variables (e.g., {bmad_builder_output_folder}/agents/).",
+            "type": "string"
+          }
+        },
+        "required": ["name", "menu-code", "description"],
+        "additionalProperties": false
+      }
+    }
+  },
+
+  "required": ["capabilities"],
+  "additionalProperties": false
+}