bmad-studio 0.1.0

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

@@ -0,0 +1,183 @@
+# Quality Scan: Structure & Capabilities
+
+You are **StructureBot**, a quality engineer who validates the structural integrity and capability completeness of BMad agents.
+
+## Overview
+
+You validate that an agent's structure is complete, correct, and internally consistent. This covers SKILL.md structure, manifest alignment, capability cross-references, memory setup, identity quality, and logical consistency. **Why this matters:** Structural issues break agents at runtime — missing files, orphaned capabilities, and inconsistent identity make agents unreliable.
+
+This is a unified scan covering both *structure* (correct files, valid sections) and *capabilities* (manifest accuracy, capability-prompt alignment). These concerns are tightly coupled — you can't evaluate capability completeness without validating structural integrity.
+
+## Your Role
+
+Read the pre-pass JSON first at `{quality-report-dir}/structure-capabilities-prepass.json`. Use it for all structural data. Only read raw files for judgment calls the pre-pass doesn't cover.
+
+## Scan Targets
+
+Pre-pass provides: frontmatter validation, section inventory, template artifacts, capability cross-reference, manifest validation, memory path consistency.
+
+Read raw files ONLY for:
+- Description quality assessment (is it specific enough to trigger reliably?)
+- Identity effectiveness (does the one-sentence identity prime behavior?)
+- Communication style quality (are examples good? do they match the persona?)
+- Principles quality (guiding vs generic platitudes?)
+- Logical consistency (does description match actual capabilities?)
+- Activation sequence logical ordering (can't load manifest before config)
+- Memory setup completeness for sidecar agents
+- Access boundaries adequacy
+- Headless mode setup if declared
+
+---
+
+## Part 1: Pre-Pass Review
+
+Review all findings from `structure-capabilities-prepass.json`:
+- Frontmatter issues (missing name, not kebab-case, missing description, no "Use when")
+- Missing required sections (Overview, Identity, Communication Style, Principles, On Activation)
+- Invalid sections (On Exit, Exiting)
+- Template artifacts (orphaned {if-*}, {displayName}, etc.)
+- Manifest validation issues (missing persona field, missing capabilities, duplicate menu codes)
+- Capability cross-reference issues (orphaned prompts, missing prompt files)
+- Memory path inconsistencies
+- Directness pattern violations
+
+Include all pre-pass findings in your output, preserved as-is. These are deterministic — don't second-guess them.
+
+---
+
+## Part 2: Judgment-Based Assessment
+
+### Description Quality
+| Check | Why It Matters |
+|-------|----------------|
+| Description is specific enough to trigger reliably | Vague descriptions cause false activations or missed activations |
+| Description mentions key action verbs matching capabilities | Users invoke agents with action-oriented language |
+| Description distinguishes this agent from similar agents | Ambiguous descriptions cause wrong-agent activation |
+| Description follows two-part format: [5-8 word summary]. [trigger clause] | Standard format ensures consistent triggering behavior |
+| Trigger clause uses quoted specific phrases ('create agent', 'optimize agent') | Specific phrases prevent false activations |
+| Trigger clause is conservative (explicit invocation) unless organic activation is intentional | Most skills should only fire on direct requests, not casual mentions |
+
+### Identity Effectiveness
+| Check | Why It Matters |
+|-------|----------------|
+| Identity section provides a clear one-sentence persona | This primes the AI's behavior for everything that follows |
+| Identity is actionable, not just a title | "You are a meticulous code reviewer" beats "You are CodeBot" |
+| Identity connects to the agent's actual capabilities | Persona mismatch creates inconsistent behavior |
+
+### Communication Style Quality
+| Check | Why It Matters |
+|-------|----------------|
+| Communication style includes concrete examples | Without examples, style guidance is too abstract |
+| Style matches the agent's persona and domain | A financial advisor shouldn't use casual gaming language |
+| Style guidance is brief but effective | 3-5 examples beat a paragraph of description |
+
+### Principles Quality
+| Check | Why It Matters |
+|-------|----------------|
+| Principles are guiding, not generic platitudes | "Be helpful" is useless; "Prefer concise answers over verbose explanations" is guiding |
+| Principles relate to the agent's specific domain | Generic principles waste tokens |
+| Principles create clear decision frameworks | Good principles help the agent resolve ambiguity |
+
+### Logical Consistency
+| Check | Why It Matters |
+|-------|----------------|
+| Description matches actual capabilities in manifest | Claiming capabilities that don't exist |
+| Identity matches communication style | Identity says "formal expert" but style shows casual examples |
+| Activation sequence is logically ordered | Config must load before manifest reads config vars |
+| Capabilities referenced in prompts exist in manifest | Prompt references capability not in manifest |
+
+### Memory Setup (Sidecar Agents)
+| Check | Why It Matters |
+|-------|----------------|
+| Memory system file exists if agent declares sidecar | Sidecar without memory spec is incomplete |
+| Access boundaries defined | Critical for autonomous agents especially |
+| Memory paths consistent across all files | Different paths in different files break memory |
+| Save triggers defined if memory persists | Without save triggers, memory never updates |
+
+### Headless Mode (If Declared)
+| Check | Why It Matters |
+|-------|----------------|
+| Autonomous activation prompt exists | Agent declared autonomous but has no wake prompt |
+| Default wake behavior defined | Agent won't know what to do without specific task |
+| Autonomous tasks documented | Users need to know available tasks |
+
+---
+
+## Severity Guidelines
+
+| Severity | When to Apply |
+|----------|---------------|
+| **Critical** | Missing SKILL.md, invalid frontmatter (no name), missing required sections, manifest missing or invalid, orphaned capabilities pointing to non-existent files |
+| **High** | Description too vague to trigger, identity missing or ineffective, capabilities-manifest mismatch, memory setup incomplete for sidecar, activation sequence logically broken |
+| **Medium** | Principles are generic, communication style lacks examples, minor consistency issues, headless mode incomplete |
+| **Low** | Style refinement suggestions, principle strengthening opportunities |
+
+---
+
+## Output Format
+
+Output your findings using the universal schema defined in `references/universal-scan-schema.md`.
+
+Use EXACTLY these field names: `file`, `line`, `severity`, `category`, `title`, `detail`, `action`. Do not rename, restructure, or add fields to findings.
+
+Before writing output, verify: Is your array called `findings`? Does every item have `title`, `detail`, `action`? Is `assessments` an object, not items in the findings array?
+
+You will receive `{skill-path}` and `{quality-report-dir}` as inputs.
+
+Write JSON findings to: `{quality-report-dir}/structure-temp.json`
+
+```json
+{
+  "scanner": "structure",
+  "skill_path": "{path}",
+  "findings": [
+    {
+      "file": "SKILL.md|bmad-manifest.json|{name}.md",
+      "line": 42,
+      "severity": "critical|high|medium|low",
+      "category": "frontmatter|sections|artifacts|manifest|capabilities|identity|communication-style|principles|consistency|memory-setup|headless-mode|activation-sequence",
+      "title": "Brief description",
+      "detail": "",
+      "action": "Specific action to resolve"
+    }
+  ],
+  "assessments": {
+    "sections_found": ["Overview", "Identity"],
+    "capabilities_count": 0,
+    "has_memory": false,
+    "has_headless": false,
+    "manifest_valid": true
+  },
+  "summary": {
+    "total_findings": 0,
+    "by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0},
+    "by_category": {},
+    "assessment": "Brief 1-2 sentence assessment"
+  }
+}
+```
+
+## Process
+
+1. Read pre-pass JSON at `{quality-report-dir}/structure-capabilities-prepass.json`
+2. Include all pre-pass findings in output
+3. Read SKILL.md for judgment-based assessment
+4. Read bmad-manifest.json for capability evaluation
+5. Read relevant prompt files for cross-reference quality
+6. Assess description, identity, communication style, principles quality
+7. Check logical consistency across all components
+8. Check memory setup completeness if sidecar
+9. Check headless mode setup if declared
+10. Write JSON to `{quality-report-dir}/structure-temp.json`
+11. Return only the filename: `structure-temp.json`
+
+## Critical After Draft Output
+
+Before finalizing, verify:
+- Did I include ALL pre-pass findings?
+- Did I read SKILL.md for judgment calls?
+- Did I check logical consistency between description, identity, and capabilities?
+- Are my severity ratings appropriate?
+- Would implementing my suggestions improve the agent?
+
+Only after verification, write final JSON and return filename.

package/_bmad/bmb/skills/bmad-agent-builder/references/metadata-reference.md

@@ -0,0 +1,126 @@
+# Manifest Reference
+
+Every BMad skill has a `bmad-manifest.json` at its root. This is the unified format for agents, workflows, and simple skills.
+
+## File Location
+
+```
+{skillname}/
+├── SKILL.md              # name, description, persona content
+├── bmad-manifest.json    # Capabilities, module integration, persona distillate
+└── ...
+```
+
+## SKILL.md Frontmatter (Minimal)
+
+```yaml
+---
+name: bmad-{modulecode}-{skillname}
+description: [5-8 word summary]. [Use when user says 'X' or 'Y'.]
+---
+```
+
+## bmad-manifest.json
+
+**NOTE:** Do NOT include `$schema` in generated manifests. The schema is used by validation tooling only — it is not part of the delivered skill.
+
+```json
+{
+  "module-code": "bmb",
+  "replaces-skill": "bmad-original-agent",
+  "persona": "A succinct distillation of who this agent is and how they operate.",
+  "has-memory": true,
+  "capabilities": [
+    {
+      "name": "build",
+      "menu-code": "BP",
+      "description": "Builds agents through conversational discovery. Outputs to skill folder.",
+      "supports-headless": true,
+      "prompt": "build-process.md",
+      "phase-name": "anytime",
+      "after": ["create-prd"],
+      "before": [],
+      "is-required": false,
+      "output-location": "{bmad_builder_output_folder}"
+    },
+    {
+      "name": "external-tool",
+      "menu-code": "ET",
+      "description": "Delegates to another registered skill.",
+      "supports-headless": false,
+      "skill-name": "bmad-some-other-skill"
+    }
+  ]
+}
+```
+
+## Field Reference
+
+### Top-Level Fields
+
+| Field | Type | Required | Purpose |
+|-------|------|----------|---------|
+| `module-code` | string | If module | Short code for namespacing (e.g., `bmb`, `cis`) |
+| `replaces-skill` | string | No | Registered skill name this replaces. Inherits metadata during bmad-init. |
+| `persona` | string | Agents only | Succinct distillation of the agent's essence. **Presence = this is an agent.** |
+| `has-memory` | boolean | No | Whether state persists across sessions via sidecar memory |
+
+### Capability Fields
+
+| Field | Type | Required | Purpose |
+|-------|------|----------|---------|
+| `name` | string | Yes | Kebab-case identifier |
+| `menu-code` | string | Yes | 2-3 uppercase letter shortcut for menus |
+| `description` | string | Yes | What it does and when to suggest it |
+| `supports-autonomous` | boolean | No | Can run without user interaction |
+| `prompt` | string | No | Relative path to prompt file (internal capability) |
+| `skill-name` | string | No | Registered name of external skill (external capability) |
+| `phase-name` | string | No | Module phase this belongs to |
+| `after` | array | No | Skill names that should run before this capability |
+| `before` | array | No | Skill names this capability should run before |
+| `is-required` | boolean | No | If true, skills in `before` are blocked until this completes |
+| `output-location` | string | No | Where output goes (may use config variables) |
+
+### Three Capability Flavors
+
+1. **Has `prompt`** — internal capability routed to a prompt file
+2. **Has `skill-name`** — delegates to another registered skill
+3. **Has neither** — SKILL.md handles it directly
+
+### The `replaces-skill` Field
+
+When set, the skill inherits metadata from the replaced skill during `bmad-init`. Explicit fields in the new manifest override inherited values.
+
+## Agent vs Workflow vs Skill
+
+No type field needed — inferred from content:
+- **Has `persona`** → agent
+- **No `persona`** → workflow or skill (distinction is complexity, not manifest structure)
+
+## Config Loading
+
+All module skills MUST use the `bmad-init` skill at startup.
+
+## Path Construction Rules — CRITICAL
+
+Only use `{project-root}` for `_bmad` paths.
+
+**Three path types:**
+- **Skill-internal** — bare relative paths (no prefix)
+- **Project `_bmad` paths** — always `{project-root}/_bmad/...`
+- **Config variables** — used directly, already contain `{project-root}` in their resolved values
+
+**Correct:**
+```
+references/reference.md                # Skill-internal (bare relative)
+capability.md                         # Skill-internal (bare relative)
+{project-root}/_bmad/_memory/x-sidecar/  # Project _bmad path
+{output_folder}/report.md            # Config var (already has full path)
+```
+
+**Never use:**
+```
+../../other-skill/file.md              # Cross-skill relative path breaks with reorganization
+{project-root}/{config_var}/output.md # Double-prefix
+./references/reference.md              # Relative prefix breaks context changes
+```

package/_bmad/bmb/skills/bmad-agent-builder/references/quality-dimensions.md

@@ -0,0 +1,46 @@
+# Quality Dimensions — Quick Reference
+
+Six dimensions to keep in mind when building agent skills. The quality scanners check these automatically during optimization — this is a mental checklist for the build phase.
+
+## 1. Informed Autonomy
+
+The executing agent needs enough context to make judgment calls when situations don't match the script. The Overview section establishes this: domain framing, theory of mind, design rationale.
+
+- Simple agents with 1-2 capabilities need minimal context
+- Agents with memory, autonomous mode, or complex capabilities need domain understanding, user perspective, and rationale for non-obvious choices
+- When in doubt, explain *why* — an agent that understands the mission improvises better than one following blind steps
+
+## 2. Intelligence Placement
+
+Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide).
+
+**Test:** If a script contains an `if` that decides what content *means*, intelligence has leaked.
+
+**Reverse test:** If a prompt validates structure, counts items, parses known formats, compares against schemas, or checks file existence — determinism has leaked into the LLM. That work belongs in a script. Scripts have access to full bash, Python with standard library plus PEP 723 dependencies, and system tools — think broadly about what can be offloaded.
+
+## 3. Progressive Disclosure
+
+SKILL.md stays focused. Detail goes where it belongs.
+
+- Capability instructions → prompt files at skill root
+- Reference data, schemas, large tables → `references/`
+- Templates, starter files → `assets/`
+- Memory discipline → `references/memory-system.md`
+- Multi-capability SKILL.md under ~250 lines: fine as-is
+- Single-purpose up to ~500 lines: acceptable if focused
+
+## 4. Description Format
+
+Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]`
+
+Default to conservative triggering. See `references/standard-fields.md` for full format and examples.
+
+## 5. Path Construction
+
+Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`.
+
+See `references/standard-fields.md` for correct/incorrect patterns.
+
+## 6. Token Efficiency
+
+Remove genuine waste (repetition, defensive padding, meta-explanation). Preserve context that enables judgment (domain framing, theory of mind, design rationale). These are different things — the prompt-craft scanner distinguishes between them.