bmad-studio 0.1.0

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

@@ -0,0 +1,282 @@
+# Quality Report: {agent-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 1-3 sentence narrative: agent persona/purpose (from enhancement-opportunities skill_understanding.purpose + agent-cohesion agent_identity), architecture quality, and most significant finding. Frame this as an agent assessment, not a workflow assessment. -->
+{executive-narrative}
+
+### Issues by Category
+
+| Category | Critical | High | Medium | Low |
+|----------|----------|------|--------|-----|
+| Structure & Capabilities | {n} | {n} | {n} | {n} |
+| Prompt Craft | {n} | {n} | {n} | {n} |
+| Execution Efficiency | {n} | {n} | {n} | {n} |
+| Path & Script Standards | {n} | {n} | {n} | {n} |
+| Agent Cohesion | {n} | {n} | {n} | {n} |
+| Creative | — | — | {n} | {n} |
+
+---
+
+## Agent Identity
+
+<!-- From agent-cohesion agent_identity block. -->
+
+- **Persona:** {persona-summary}
+- **Primary Purpose:** {primary-purpose}
+- **Capabilities:** {capability-count}
+
+---
+
+## Strengths
+
+*What this agent 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 and persona_context assessment
+  - enhancement-opportunities: bright_spots from each assessments.user_journeys[] entry
+  - structure: positive observations from assessments.metadata (e.g., memory setup present, headless mode configured)
+  Group by theme. Each strength should explain WHY it matters. -->
+
+{strengths-list}
+
+---
+
+{if-truly-broken}
+## Truly Broken or Missing
+
+*Issues that prevent the agent 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. Structure & Capabilities
+
+<!-- Source: structure-temp.json. Agent-specific: includes identity effectiveness, memory setup, headless mode, capability cross-references. -->
+
+{if-structure-metadata}
+**Agent Metadata:**
+- Sections found: {sections-list}
+- Capabilities: {capabilities-count}
+- Memory sidecar: {has-memory}
+- Headless mode: {has-headless}
+- Manifest valid: {manifest-valid}
+- Structure assessment: {structure-assessment}
+{/if-structure-metadata}
+
+<!-- List findings by severity: Critical > High > Medium > Low. Omit empty severity levels. -->
+
+{structure-findings}
+
+### 2. Prompt Craft
+
+<!-- Source: prompt-craft-temp.json. Agent-specific: includes persona_context assessment and persona-voice/communication-consistency categories. Remember: persona voice is INVESTMENT not waste for agents. -->
+
+**Agent Assessment:**
+- Agent type: {skill-type-assessment}
+- Overview quality: {overview-quality}
+- Progressive disclosure: {progressive-disclosure}
+- Persona context: {persona-context}
+- {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. Execution Efficiency
+
+<!-- Source: execution-efficiency-temp.json. Agent-specific: includes memory-loading category. -->
+
+{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}
+
+### 4. Path & Script Standards
+
+<!-- Source: path-standards-temp.json + scripts-temp.json -->
+
+{if-script-inventory}
+**Script Inventory:** {total-scripts} scripts ({by-type-breakdown}) | Missing tests: {missing-tests-list}
+{/if-script-inventory}
+
+{path-script-findings}
+
+### 5. Agent Cohesion
+
+<!-- Source: agent-cohesion-temp.json. This is the agent-specific section — persona-capability alignment, gaps, redundancies, coherence. -->
+
+{if-cohesion-analysis}
+**Cohesion Analysis:**
+
+<!-- Include only dimensions present in scanner output. -->
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Persona Alignment | {score} | {notes} |
+| Capability Completeness | {score} | {notes} |
+| Redundancy Level | {score} | {notes} |
+| External Integration | {score} | {notes} |
+| User Journey | {score} | {notes} |
+
+{if-consolidation-opportunities}
+**Consolidation Opportunities:**
+
+<!-- From cohesion_analysis.redundancy_level.consolidation_opportunities[]. Each: capabilities that overlap and how to combine. -->
+
+{consolidation-opportunities}
+{/if-consolidation-opportunities}
+{/if-cohesion-analysis}
+
+{cohesion-findings}
+
+{if-creative-suggestions}
+**Creative Suggestions:**
+
+<!-- From findings[] with severity="suggestion". Each: title, detail, action. -->
+
+{creative-suggestions}
+{/if-creative-suggestions}
+
+### 6. Creative (Edge-Case & Experience Innovation)
+
+<!-- Source: enhancement-opportunities-temp.json. These are advisory suggestions, not errors. -->
+
+**Agent 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 agent:*
+
+<!-- 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. This is especially important for agents which may need headless/autonomous operation. -->
+
+- **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}
+
+{if-script-opportunities}
+## Script Opportunities
+
+<!-- Source: script-opportunities-temp.json. These identify LLM work that could be deterministic scripts. -->
+
+**Existing Scripts:** {existing-scripts-list}
+
+<!-- For each finding: title, detail (includes determinism/complexity/savings narrative), action. -->
+
+{script-opportunity-findings}
+
+**Token Savings:** {total-estimated-token-savings} | Highest value: {highest-value-opportunity} | Prepass opportunities: {prepass-count}
+
+---
+{/if-script-opportunities}
+
+## 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. -->
+
+**Token Efficiency:**
+{token-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-agent-builder/assets/save-memory.md

@@ -0,0 +1,29 @@
+---
+name: save-memory
+description: Explicitly save current session context to memory
+menu-code: SM
+---
+
+# Save Memory
+
+Immediately persist the current session context to memory.
+
+## Process
+
+1. **Read current index.md** — Load existing context
+
+2. **Update with current session:**
+   - What we're working on
+   - Current state/progress
+   - Any new preferences or patterns discovered
+   - Next steps to continue
+
+3. **Write updated index.md** — Replace content with condensed, current version
+
+4. **Checkpoint other files if needed:**
+   - `patterns.md` — Add new patterns discovered
+   - `chronology.md` — Add session summary if significant
+
+## Output
+
+Confirm save with brief summary: "Memory saved. {brief-summary-of-what-was-updated}"

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

@@ -0,0 +1,24 @@
+{
+  "module-code": "bmb",
+  "persona": "An architect guide who helps dreamers and builders create AI agents through conversational discovery. Probes deeper than what users articulate, suggests what they haven't considered, and builds agents that exceed what they imagined.",
+  "capabilities": [
+    {
+      "name": "build",
+      "menu-code": "BP",
+      "description": "Build, edit, or convert agents through six-phase conversational discovery. Covers new agents, 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-agent-builder/bmad-skill-manifest.yaml

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

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

@@ -0,0 +1,199 @@
+---
+name: build-process
+description: Six-phase conversational discovery process for building BMad agents. Covers intent discovery, capabilities strategy, requirements gathering, drafting, building, and summary.
+---
+
+**Language:** Use `{communication_language}` for all output.
+
+# Build Process
+
+Build AI agents through six phases of conversational discovery. Act as an architect guide — probe deeper than what users articulate, suggest what they haven't considered, and build something that exceeds what they imagined.
+
+## Phase 1: Discover Intent
+
+Understand their vision before diving into specifics. Ask what they want to build and encourage detail.
+
+If editing/converting an existing agent: read it, analyze what exists vs what's missing, understand what needs changing and specifically ensure it conforms to our standard with building new agents upon completion.
+
+## Phase 2: Capabilities Strategy
+
+Early check: internal capabilities only, external skills, both, or unclear?
+
+**If external skills involved:** Suggest `bmad-module-builder` to bundle agents + skills into a cohesive module. Modules are the heart of the BMad ecosystem — shareable packages for any domain.
+
+**Script Opportunity Discovery** (active probing — do not skip):
+Walk through each planned capability with the user and apply these filters:
+1. "Does this operation 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)
+- Memory structure validation (required sections, path correctness)
+- Access boundary extraction and verification
+- Pre-processing for LLM capabilities (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 3, 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.
+
+If scripts are planned, the `scripts/` folder will be created. Scripts are invoked from prompts when needed, not run automatically.
+
+## Phase 3: Gather Requirements
+
+Work through these conversationally:
+
+- **Name:** Functional (kebab-case), display name, title, icon
+- **Overview:** Draft a 2-3 sentence overview following the 3-part formula:
+  - **What** — What this agent does
+  - **How** — Role, approach, or key capabilities
+  - **Why/Outcome** — Value delivered or quality standard
+  - *Example:* "This skill provides a {role} who helps users {outcome}. Act as {name} — {key quality}."
+- **Identity:** Who is this agent? How do they communicate? What guides their decisions?
+- **Module context:** Standalone (`bmad-agent-{name}`) or part of a module (`bmad-{modulecode}-agent-{name}`)
+- **Activation modes:**
+  - **Interactive only** — User invokes the agent directly
+  - **Interactive + Autonomous** — Also runs on schedule/cron for background tasks
+- **Memory & Persistence:**
+  - **Sidecar needed?** — What persists across sessions?
+  - **Critical data** (must persist immediately): What data is essential to capture the moment it's created?
+  - **Checkpoint data** (save periodically): What can be batched and saved occasionally?
+  - **Save triggers:** After which interactions should memory be updated?
+- **Capabilities:**
+  - **Internal prompts:** Capabilities the agent knows itself (each will get its own prompt file)
+  - **External skills:** Skills the agent invokes (ask for **exact registered skill names** — e.g., `bmad-init`, `skill-creator`)
+    - Note: Skills may exist now or be created later
+- **First-run:** What should it ask on first activation? (standalone only; module-based gets config from module's config.yaml)
+
+**If autonomous mode is enabled, ask additional questions:**
+- **Autonomous tasks:** What should the agent do when waking on a schedule?
+  - Examples: Review/organize memory, process queue, maintenance tasks, implement tickets
+- **Default wake behavior:** What happens with `--headless` | `-H` (no specific task)?
+- **Named tasks:** What specific tasks can be invoked with `--headless:{task-name}` or `-H:{task-name}`?
+
+- **Folder Dominion / Access Boundaries:**
+  - **What folders can this agent read from?** (e.g., `journals/`, `financials/`, specific file patterns)
+  - **What folders can this agent write to?** (e.g., output folders, log locations)
+  - **Are there any explicit deny zones?** (folders the agent must never touch)
+  - Store these boundaries in memory as the standard `access-boundaries` section (see memory-system template)
+
+**Key distinction:** Folder dominion (where things live) ≠ agent memory (what persists across sessions)
+
+- **Path Conventions** (CRITICAL for reliable agent behavior):
+  - **Memory location:** `{project-root}/_bmad/_memory/{skillName}-sidecar/`
+  - **Project artifacts:** `{project-root}/_bmad/...` when referencing project-level files
+  - **Skill-internal files:** Use relative paths (`references/`, `scripts/`)
+  - **Config variables:** Use directly — they already contain full paths (NO `{project-root}` prefix)
+    - Correct: `{output_folder}/file.md`
+    - Wrong: `{project-root}/{output_folder}/file.md` (double-prefix breaks resolution)
+  - **No absolute paths** (`/Users/...`) or relative prefixes (`./`, `../`)
+
+## Phase 4: Draft & Refine
+
+Once you have a cohesive idea, think one level deeper. Once you have done this, present a draft outline. 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 context:**
+- **If module-based:** Load `references/metadata-reference.md` — 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 2, even if no scripts were initially planned.
+
+When confirmed:
+
+1. Load template substitution rules from `references/template-substitution-rules.md` and apply
+
+2. Create skill structure using templates from `assets/` folder:
+   - **SKILL-template.md** — skill wrapper with full persona content embedded
+   - **init-template.md** — first-run setup (if sidecar)
+   - **memory-system.md** — memory (if sidecar, saved at root level)
+   - **autonomous-wake.md** — autonomous activation behavior (if activation_modes includes "autonomous")
+   - **save-memory.md** — explicit memory save capability (if sidecar enabled)
+
+3. **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 with agent identity
+   python3 scripts/manifest.py create {skill-path} \
+     --persona "Succinct distillation of who this agent is" \
+     --module-code {code}  # if part of a module \
+     --has-memory           # if sidecar needed
+
+   # Add each capability
+   # 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 need sequencing metadata (confirm with user):
+   # - phase-name: which module phase (e.g., "1-analysis", "2-design", "anytime")
+   # - after: array of skill names that should run before this (inputs/dependencies)
+   # - before: array of skill names this should run before (downstream consumers)
+   # - is-required: if true, skills in 'before' are blocked until this completes
+   # - description: 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." \
+     --phase-name anytime \
+     --after skill-a skill-b \
+     --before skill-c \
+     --is-required
+   ```
+
+4. **Folder structure:**
+```
+{skill-name}/
+├── SKILL.md               # Contains full persona content (agent.md embedded)
+├── bmad-manifest.json     # Capabilities, persona, memory, module integration
+├── init.md                # First-run setup (if sidecar)
+├── autonomous-wake.md     # Autonomous activation (if autonomous mode)
+├── save-memory.md         # Explicit memory save (if sidecar)
+├── {name}.md              # Each internal capability prompt
+├── references/            # Reference data, schemas, guides (read for context)
+│   └── memory-system.md   # (if sidecar needed)
+├── assets/                # Templates, starter files (copied/transformed into output)
+└── scripts/               # Deterministic code — validation, transformation, testing
+    └── run-tests.sh       # uvx-powered test runner (if python tests exist)
+```
+
+**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. Output to `bmad_builder_output_folder` from config, or `{project-root}/bmad-builder-creations/`
+
+6. **Lint gate** — run deterministic validation scripts:
+   ```bash
+   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
+
+## Phase 6: Summary
+
+Present what was built: location, structure, first-run behavior, capabilities. Ask if adjustments needed.
+
+**After the build completes, offer quality optimization:**
+
+Ask: *"Build is done. Would you like to run a Quality Scan to optimize the agent further?"*
+
+If yes, load `quality-optimizer.md` with `{scan_mode}=full` and the agent path.
+
+Remind them: BMad module system compliant. Use `bmad-init` skill to integrate into a project.