bmad-studio 0.1.0 → 0.2.0

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

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

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

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

@@ -1,103 +0,0 @@
-{
-  "$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
-}