bmad-studio 0.1.0 → 0.2.0

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

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

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

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