From 8d3c301d1eb8b7047c7d17a1d27cbde0b4812921 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 29 Mar 2026 01:38:54 -0500 Subject: [PATCH 1/3] feat: add bmad-module-builder skill with ideation, creation, and validation New skill (bmad-module-builder) with three capabilities: - Ideate Module (IM): facilitative brainstorming for module planning - Create Module (CM): scaffold setup skill into existing skills folder - Validate Module (VM): structural and quality validation of module setup Includes scaffold script with tests, setup-skill-template assets, resumable plan document template, and embedded brainstorming techniques. Documentation updates: - New explanation doc: what-are-modules.md (architecture, memory patterns) - New tutorial: build-your-first-module.md (full Diataxis tutorial) - Updated builder-commands.md with Module Builder reference - Updated module-configuration.md (replaced Upcoming Tooling section) - Updated help CSVs with IM, CM, VM entries --- .claude-plugin/marketplace.json | 2 +- docs/explanation/index.md | 1 + docs/explanation/module-configuration.md | 24 +- docs/explanation/what-are-modules.md | 100 +++++ docs/reference/builder-commands.md | 93 +++- docs/tutorials/build-your-first-module.md | 176 ++++++++ docs/tutorials/index.md | 8 +- .../bmad-builder-setup/assets/module-help.csv | 5 +- skills/bmad-module-builder/SKILL.md | 32 ++ .../assets/module-plan-template.md | 94 ++++ .../assets/setup-skill-template/SKILL.md | 76 ++++ .../assets/module-help.csv | 1 + .../setup-skill-template/assets/module.yaml | 7 + .../scripts/cleanup-legacy.py | 259 +++++++++++ .../scripts/merge-config.py | 408 ++++++++++++++++++ .../scripts/merge-help-csv.py | 220 ++++++++++ .../references/create-module.md | 122 ++++++ .../references/ideate-module.md | 122 ++++++ .../references/validate-module.md | 53 +++ .../scripts/scaffold-setup-skill.py | 124 ++++++ .../tests/test-scaffold-setup-skill.py | 223 ++++++++++ .../scripts/tests/test-validate-module.py | 202 +++++++++ .../scripts/validate-module.py | 242 +++++++++++ skills/module-help.csv | 5 +- 24 files changed, 2585 insertions(+), 14 deletions(-) create mode 100644 docs/explanation/what-are-modules.md create mode 100644 docs/tutorials/build-your-first-module.md create mode 100644 skills/bmad-module-builder/SKILL.md create mode 100644 skills/bmad-module-builder/assets/module-plan-template.md create mode 100644 skills/bmad-module-builder/assets/setup-skill-template/SKILL.md create mode 100644 skills/bmad-module-builder/assets/setup-skill-template/assets/module-help.csv create mode 100644 skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml create mode 100755 skills/bmad-module-builder/assets/setup-skill-template/scripts/cleanup-legacy.py create mode 100755 skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-config.py create mode 100755 skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-help-csv.py create mode 100644 skills/bmad-module-builder/references/create-module.md create mode 100644 skills/bmad-module-builder/references/ideate-module.md create mode 100644 skills/bmad-module-builder/references/validate-module.md create mode 100644 skills/bmad-module-builder/scripts/scaffold-setup-skill.py create mode 100644 skills/bmad-module-builder/scripts/tests/test-scaffold-setup-skill.py create mode 100644 skills/bmad-module-builder/scripts/tests/test-validate-module.py create mode 100644 skills/bmad-module-builder/scripts/validate-module.py diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 02cd2d3..e5ec377 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "bmad-builder", "source": "./", "description": "Build AI agents and workflows from a conversation. Three skills — Agent Builder, Workflow Builder, and Setup — guide you from idea to production-ready skill structure with built-in quality optimization. Part of the BMad Method ecosystem.", - "version": "1.1.0", + "version": "1.2.0", "author": { "name": "Brian (BMad) Madison" }, diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 595cde1..0bddb26 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -12,6 +12,7 @@ Create world-class AI agents and workflows with the BMad Builder. | **[What Are Skills](/explanation/what-are-skills.md)** | The universal building block for everything BMad produces | | **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities and memory | | **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes and utilities | +| **[What Are Modules](/explanation/what-are-modules.md)** | How agents and workflows combine into installable, configurable modules | | **[Module Configuration](/explanation/module-configuration.md)** | How modules handle user configuration and help registration through a setup skill | ## Design Patterns diff --git a/docs/explanation/module-configuration.md b/docs/explanation/module-configuration.md index 8aff28b..698c00c 100644 --- a/docs/explanation/module-configuration.md +++ b/docs/explanation/module-configuration.md @@ -116,15 +116,23 @@ Configuration is for **basic, project-level settings** — output folders, langu Extensive workflow customization — step overrides, conditional branching, template selection — is a separate concern and will be covered in a dedicated document. -## Upcoming Tooling +## Creating a Module with the Module Builder -A module scaffolding tool is planned that will generate the setup skill as part of module creation, along with the marketplace manifest format. Until then, use the BMad Builder module's setup skill as a reference implementation. +The **Module Builder** (`bmad-module-builder`) automates module creation. It offers three capabilities: -Once available, you will be able to generate a setup skill from your existing collection of agents, workflows, and skills with a prompt like: +| Capability | Menu Code | What It Does | +| ---------- | --------- | ------------ | +| **Ideate Module** | IM | Brainstorm and plan a module through facilitative discovery — produces a plan document | +| **Create Module** | CM | Scaffold a setup skill into an existing folder of built skills | +| **Validate Module** | VM | Check that a module's setup skill is complete, accurate, and properly registered | -:::note[Example] -"Create a setup skill for my module in `./my-module-skills/` that mirrors `bmad-builder-setup` — with its own module name and code (my cool module, mcm), config variables for output folder locations, and help entries inferred from the existing skills in the folder." -::: +**Typical workflow:** + +1. Run **Ideate Module (IM)** to brainstorm and plan your module +2. Build each skill using the **Agent Builder (BA)** or **Workflow Builder (BW)** +3. Run **Create Module (CM)** to scaffold the setup skill into your skills folder +4. Run **Validate Module (VM)** to verify everything is wired correctly + +The Create Module path reads every skill in your folder, walks you through defining the module identity and capability entries, then generates a complete setup skill with `module.yaml`, `module-help.csv`, and all supporting scripts. -A decent LLM will clone the entire `bmad-builder-setup` skill components amd structure — SKILL.md, scripts, tests — updating only the skill name, description, and the two asset files (`module.yaml` and `module-help.csv`) to reflect your module. -Take the time to ensure the description that triggers it is correct, along with the module.yaml and module-help.csv +See **[What Are Modules](/explanation/what-are-modules.md)** for concepts and architecture decisions, or the **[Builder Commands Reference](/reference/builder-commands.md)** for detailed capability documentation. diff --git a/docs/explanation/what-are-modules.md b/docs/explanation/what-are-modules.md new file mode 100644 index 0000000..9d0c717 --- /dev/null +++ b/docs/explanation/what-are-modules.md @@ -0,0 +1,100 @@ +--- +title: "What Are BMad Modules?" +description: How agents and workflows combine into installable, configurable modules within the BMad ecosystem +--- + +BMad modules package related agents and workflows into a cohesive, installable unit with shared configuration and help system registration. + +## What a Module Contains + +A module is a folder of skills — agents and/or workflows — plus a **setup skill** that handles installation and configuration. + +| Component | Purpose | +| --------- | ------- | +| **Skills** | The agents and workflows that deliver the module's capabilities | +| **Setup skill** | Collects user preferences, writes config, registers capabilities with the help system | +| **module.yaml** | Declares module identity and configurable variables | +| **module-help.csv** | Lists every capability users can discover and invoke | + +The setup skill is the only required infrastructure. Everything else is just well-built skills that happen to work together. + +## Agent vs. Workflow vs. Both + +The first architecture decision when planning a module is whether to use a single agent, multiple workflows, or a combination. + +| Architecture | When It Fits | Trade-offs | +| ------------ | ------------ | ---------- | +| **Single agent with capabilities** | All capabilities serve the same user journey and benefit from shared context | Simpler to maintain, better memory continuity, seamless UX. Can feel monolithic if capabilities are unrelated | +| **Multiple workflows** | Capabilities serve different user journeys or require different tools | Each workflow is focused and composable. Users switch between skills explicitly | +| **Hybrid** | Some capabilities need persistent persona/memory while others are procedural | Best of both worlds but more skills to build and maintain | + +:::tip[Agent-First Thinking] +Many users default to building multiple single-purpose agents. Consider whether one agent with rich internal capabilities and routing would serve users better. A single agent accumulates context, maintains memory across interactions, and provides a more seamless experience. +::: + +## Multi-Agent Modules and Memory + +Modules with multiple agents introduce a memory architecture decision. Every BMad agent has its own **sidecar memory** — a personal folder where it stores user preferences, learned patterns, session history, and domain-specific data. In a multi-agent module, you also need to decide whether agents should share memory. + +| Pattern | When It Fits | +| ------- | ------------ | +| **Personal sidecars only** | Agents have distinct domains with minimal overlap | +| **Personal + shared module sidecar** | Agents have their own context but also learn shared things about the user or project | +| **Shared sidecar only** | All agents serve the same domain — consider whether a single agent is the better design | + +**Example:** A social creative module with a podcast expert, a viral video expert, and a blog expert. Each agent remembers the specifics of what it has done with the user — episode topics, video formats, blog themes. But they all also learn about the user's communication style, favorite catchphrases, content preferences, and brand voice. This shared knowledge lives in a module-level sidecar that every agent reads from and contributes to. + +Each agent should still be self-contained with its own capabilities, even if this means duplicating some common functionality. A podcast expert that can independently handle a full session without needing the blog expert is better than one that depends on shared state to function. + +See **[What Are BMad Agents](/explanation/what-are-bmad-agents.md)** for details on how agent memory and sidecars work. + +## Standalone vs. Expansion Modules + +| Type | Description | +| ---- | ----------- | +| **Standalone** | Provides complete, independent value. Does not depend on another module being installed | +| **Expansion** | Extends an existing module with new capabilities. Should still provide utility even if the parent module is not installed | + +Expansion modules can reference the parent module's capabilities in their help CSV ordering (before/after fields). This lets a new capability slot into the parent module's natural workflow sequence. + +Even expansion modules should be designed to work independently — the parent module being absent should degrade gracefully, not break the expansion. + +## Configuration and Registration + +Modules register with a project through three files in `{project-root}/_bmad/`: + +| File | Purpose | +| ---- | ------- | +| `config.yaml` | Shared settings committed to git — module section keyed by module code | +| `config.user.yaml` | Personal settings (gitignored) — user name, language preferences | +| `module-help.csv` | Capability registry — one row per action users can discover | + +Not every module needs configuration. If skills work with sensible defaults, the setup skill can focus purely on help registration. See **[Module Configuration](/explanation/module-configuration.md)** for details on when configuration adds value. + +## External Dependencies + +Some modules depend on tools outside the BMad ecosystem. + +| Dependency Type | Examples | +| --------------- | -------- | +| **CLI tools** | `docker`, `terraform`, `ffmpeg` | +| **MCP servers** | Custom or third-party Model Context Protocol servers | +| **Web services** | APIs that require credentials or configuration | + +When a module has external dependencies, the setup skill should check for their presence and guide users through installation or configuration. + +## UI and Visualization + +Modules can include user interfaces — dashboards, progress views, interactive visualizations, or even full web applications. A UI skill might show shared progress across the module's capabilities, provide a visual map of how skills relate, or offer an interactive way to navigate the module's features. + +Not every module needs a UI. But for complex modules with many capabilities, a visual layer can make the experience significantly more accessible. + +## Building a Module + +The Module Builder (`bmad-module-builder`) provides three capabilities for the module lifecycle: + +1. **Ideate Module (IM)** — Brainstorm and plan through creative facilitation +2. **Create Module (CM)** — Scaffold the setup skill into your skills folder +3. **Validate Module (VM)** — Verify structural integrity and entry quality + +See the **[Builder Commands Reference](/reference/builder-commands.md)** for detailed documentation on each capability. diff --git a/docs/reference/builder-commands.md b/docs/reference/builder-commands.md index 0d64e3a..3811f02 100644 --- a/docs/reference/builder-commands.md +++ b/docs/reference/builder-commands.md @@ -1,9 +1,9 @@ --- title: "Builder Commands Reference" -description: Complete reference for all capabilities, modes, and paths available in the Agent Builder and Workflow Builder +description: Complete reference for all capabilities, modes, and paths available in the Agent Builder, Workflow Builder, and Module Builder --- -Reference for the two core BMad Builder skills — the Agent Builder (`bmad-agent-builder`) and the Workflow Builder (`bmad-workflow-builder`). Both share the same two capabilities but apply them to different skill types. +Reference for the three core BMad Builder skills — the Agent Builder (`bmad-agent-builder`), the Workflow Builder (`bmad-workflow-builder`), and the Module Builder (`bmad-module-builder`). ## Capabilities Overview @@ -177,6 +177,92 @@ Not every suggestion should be applied. The optimizer communicates these decisio - **Prefer scripting** for deterministic operations; **prefer prompting** for creative or judgment-based tasks - **Reject changes** that flatten personality unless a neutral tone is explicitly wanted +## Module Builder + +The Module Builder (`bmad-module-builder`) handles module-level planning, scaffolding, and validation. It operates at a higher level than the Agent and Workflow Builders — it orchestrates what those builders produce into a cohesive, installable module. + +### Capabilities Overview + +| Capability | Menu Code | What It Does | +| ---------- | --------- | ------------ | +| **Ideate Module** | IM | Brainstorm and plan a module through creative facilitation | +| **Create Module** | CM | Scaffold a setup skill into an existing folder of built skills | +| **Validate Module** | VM | Check structural integrity and entry quality of a module's setup skill | + +### Ideate Module (IM) + +A facilitative brainstorming session that helps you envision your module from scratch. The builder acts as a creative collaborator — drawing out ideas, exploring possibilities, and guiding you toward the right architecture. + +| Aspect | Detail | +| ------ | ------ | +| **Interaction** | Interactive only — no headless mode | +| **Input** | An idea or rough description | +| **Output** | Plan document saved to `{bmad_builder_reports}` | + +**What it covers:** + +- Problem space exploration and creative brainstorming +- Architecture decision — single agent with capabilities vs. multiple skills vs. hybrid +- Standalone module or expansion of an existing module +- External dependencies (CLI tools, MCP servers) +- UI and visualization opportunities +- Setup skill extensions beyond configuration +- Per-skill capability definitions with help CSV metadata +- Configuration variables and sensible defaults + +The plan document uses a resumable template with YAML frontmatter, so long brainstorming sessions survive context compaction. + +**After ideation:** Build each planned skill using the Agent Builder (BA) or Workflow Builder (BW), then return to Create Module (CM) to scaffold the module. + +### Create Module (CM) + +Takes an existing folder of built skills and scaffolds a setup skill that makes it an installable BMad module. Supports `--headless` / `-H`. + +| Aspect | Detail | +| ------ | ------ | +| **Interaction** | Guided or headless | +| **Input** | Path to a skills folder, optional plan document | +| **Output** | Setup skill (`bmad-{code}-setup/`) added to the skills folder | + +**What it does:** + +1. Reads every SKILL.md in the folder to understand each skill +2. Collects module identity (name, code, description, version, greeting) +3. Defines help CSV entries — capabilities, menu codes, ordering, relationships +4. Captures configuration variables and external dependencies +5. Scaffolds the setup skill with generated `module.yaml` and `module-help.csv` + +The scaffolded setup skill includes merge scripts, cleanup scripts, and a generic SKILL.md — only the asset files are customized per module. + +### Validate Module (VM) + +Verifies that a module's setup skill is complete and accurate. Combines a deterministic validation script with LLM-based quality assessment. + +| Aspect | Detail | +| ------ | ------ | +| **Interaction** | Interactive | +| **Input** | Path to the module's skills folder | +| **Output** | Validation report | + +**Structural checks** (script-driven): + +| Check | What It Catches | +| ----- | --------------- | +| Setup skill structure | Missing SKILL.md, module.yaml, or module-help.csv | +| Coverage | Skills without CSV entries, orphan entries for nonexistent skills | +| Menu codes | Duplicate codes across the module | +| References | Before/after fields pointing to nonexistent capabilities | +| Required fields | Missing skill name, display name, menu code, or description in CSV rows | +| module.yaml | Missing code, name, or description | + +**Quality assessment** (LLM-driven): + +- Description accuracy — does each entry match what the skill actually does? +- Description quality — concise, action-oriented, specific, not overly verbose +- Completeness — are all distinct capabilities registered as separate rows? +- Ordering — do before/after relationships make sense? +- Menu codes — are they intuitive and memorable? + ## Trigger Phrases | Intent | Phrases | Builder | Route | @@ -189,3 +275,6 @@ Not every suggestion should be applied. The optimizer communicates these decisio | Convert | "convert this to a BMad skill" | Workflow | `prompts/build-process.md` | | Optimize | "quality check/validate/optimize/review agent" | Agent | `prompts/quality-optimizer.md` | | Optimize | "quality check/validate/optimize/review workflow/skill" | Workflow | `prompts/quality-optimizer.md` | +| Ideate | "ideate module/plan a module/brainstorm a module" | Module | `./references/ideate-module.md` | +| Create | "create module/build a module/scaffold a module" | Module | `./references/create-module.md` | +| Validate | "validate module/check module" | Module | `./references/validate-module.md` | diff --git a/docs/tutorials/build-your-first-module.md b/docs/tutorials/build-your-first-module.md new file mode 100644 index 0000000..3987181 --- /dev/null +++ b/docs/tutorials/build-your-first-module.md @@ -0,0 +1,176 @@ +--- +title: "Build Your First Module" +description: Create a complete BMad module from idea to installable package using the Module Builder +--- + +Walk through the complete module lifecycle — from brainstorming an idea to scaffolding an installable BMad module with help registration and configuration. + +## What You'll Learn + +- How to plan a module using the Ideate Module (IM) capability +- When to use a single agent vs. multiple workflows +- How to build individual skills with the Agent and Workflow Builders +- How to scaffold a setup skill with Create Module (CM) +- How to validate your module with Validate Module (VM) + +:::note[Prerequisites] +- BMad Builder module installed in your project (`bmad-builder-setup`) +- Familiarity with what agents and workflows are — see **[What Are Agents](/explanation/what-are-bmad-agents.md)** and **[What Are Workflows](/explanation/what-are-workflows.md)** +::: + +:::tip[Quick Path] +Already have your skills built? Skip to **Step 3: Scaffold the Module** to package them. Just need to validate an existing module? Jump to **Step 4: Validate**. +::: + +## Understanding Modules + +A BMad module is a folder of skills (agents and/or workflows) plus a setup skill that handles installation. The setup skill collects configuration, registers capabilities with the help system, and makes the module discoverable. + +| Component | What It Does | +| --------- | ------------ | +| **Your skills** | Agents and workflows that deliver the module's value | +| **Setup skill** | Generated infrastructure — config collection, help registration | +| **module.yaml** | Module identity and configurable variables | +| **module-help.csv** | Capability entries for the help system | + +See **[What Are Modules](/explanation/what-are-modules.md)** for architecture decisions and design patterns. + +## Step 1: Plan Your Module + +Start with the Ideate Module capability to brainstorm and plan. + +:::note[Example] +**You:** "I want to ideate a module" + +**Builder:** Starts a creative brainstorming session — exploring what the module could do, who it's for, and how capabilities should be organized. +::: + +The ideation session covers: + +| Topic | What You'll Decide | +| ----- | ------------------ | +| **Vision** | Problem space, target users, core value | +| **Architecture** | Single agent, multiple workflows, or hybrid | +| **Memory** | For multi-agent modules: personal sidecars, shared module memory, or both | +| **Module type** | Standalone or expansion of another module | +| **Skills** | Each planned skill's purpose, capabilities, and relationships | +| **Configuration** | Custom install questions and variables | +| **Dependencies** | External CLI tools, MCP servers, web services | + +The output is a **plan document** saved to your reports folder. This document captures everything you discussed and serves as a blueprint for building each skill. + +## Step 2: Build Your Skills + +With your plan in hand, build each skill individually. + +| Skill Type | Builder | Menu Code | +| ---------- | ------- | --------- | +| Agent | Agent Builder | BA | +| Workflow or utility | Workflow Builder | BW | + +Share the plan document as context when building each skill — it helps the builder understand the bigger picture and how the skill fits into the module. + +:::caution[Build Before Packaging] +Build and test each skill before scaffolding the module. The Create Module step reads your finished skills to generate accurate help entries. +::: + +## Step 3: Scaffold the Module + +Once all skills are built, run Create Module (CM) to scaffold the setup skill. + +:::note[Example] +**You:** "I want to create a module" or provide the path to your skills folder. + +**Builder:** Reads every skill, asks about module identity and capability ordering, then scaffolds the setup skill. +::: + +The builder generates: + +``` +your-skills-folder/ +├── bmad-{code}-setup/ # Generated setup skill +│ ├── SKILL.md # Setup instructions +│ ├── scripts/ # Config merge and cleanup scripts +│ │ ├── merge-config.py +│ │ ├── merge-help-csv.py +│ │ └── cleanup-legacy.py +│ └── assets/ +│ ├── module.yaml # Your module's identity and config vars +│ └── module-help.csv # Your module's capability entries +├── your-agent-skill/ +├── your-workflow-skill/ +└── ... +``` + +## Step 4: Validate + +Run Validate Module (VM) to check that everything is wired correctly. + +:::note[Example] +**You:** "Validate my module at ./my-skills-folder" + +**Builder:** Runs structural checks and quality assessment, then reports findings. +::: + +| Check Type | What It Catches | +| ---------- | --------------- | +| **Structural** | Missing files, orphan entries, duplicate menu codes, broken references | +| **Quality** | Inaccurate descriptions, missing capabilities, poor entry quality | + +Fix any findings and re-validate until clean. + +## What You've Accomplished + +``` +your-module/ +├── bmad-{code}-setup/ # Installable setup skill +│ ├── SKILL.md +│ ├── scripts/ +│ └── assets/ +│ ├── module.yaml # Module identity +│ └── module-help.csv # Capability registry +├── skill-one/ # Your built skills +├── skill-two/ +└── ... +``` + +Your module is now a complete, distributable BMad module. To install it in any project, users run the setup skill. + +## Quick Reference + +| Capability | Menu Code | When to Use | +| ---------- | --------- | ----------- | +| Ideate Module | IM | Planning a new module from scratch | +| Build an Agent | BA | Building an agent skill for the module | +| Build a Workflow | BW | Building a workflow skill for the module | +| Create Module | CM | Scaffolding the setup skill after skills are built | +| Validate Module | VM | Checking the module is complete and accurate | + +## Common Questions + +### Do I need to ideate before creating? + +No. If you already know what your module should contain and have built the skills, skip straight to Create Module (CM). Ideation is for when you're starting from an idea and want help planning. + +### Can I add skills to a module later? + +Yes. Build the new skill, then re-run Create Module (CM) on the folder. The scaffolding uses an anti-zombie pattern — it replaces the existing setup skill cleanly. + +### What if my module only has one skill? + +A single agent or workflow can still be a module. The setup skill provides configuration and help registration. For very simple cases, a standalone skill with self-registration may be a better fit — see the agent or workflow builder for that pattern. + +### Can my module extend another module? + +Yes. During ideation or creation, specify that your module is an expansion. Your help CSV entries can reference the parent module's capabilities in their before/after ordering fields. + +## Getting Help + +- **[What Are Modules](/explanation/what-are-modules.md)** — Concepts and architecture decisions +- **[Module Configuration](/explanation/module-configuration.md)** — Setup skill internals and config patterns +- **[Builder Commands Reference](/reference/builder-commands.md)** — Full capability documentation +- **[Discord](https://discord.gg/gk8jAdXWmj)** — Community support + +:::tip[Key Takeaways] +Plan first with Ideate Module (IM), build individual skills with the Agent and Workflow Builders, scaffold with Create Module (CM), and verify with Validate Module (VM). The setup skill handles the rest — config collection, help registration, and making your module installable. +::: diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 139af75..706458c 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -5,4 +5,10 @@ description: Learn BMad Builder through hands-on examples # Tutorials -Step-by-step tutorials for building with the BMad Builder are coming soon. In the meantime, see the **[Explanation docs](/explanation/)** for concepts and design patterns, or the **[Builder Commands Reference](/reference/builder-commands.md)** for a complete overview of what the builders can do. +Hands-on tutorials for building with the BMad Builder. + +| Tutorial | Description | +| -------- | ----------- | +| **[Build Your First Module](/tutorials/build-your-first-module.md)** | Plan, build, scaffold, and validate a complete BMad module | + +For concepts and design patterns, see the **[Explanation docs](/explanation/)**. For capability details, see the **[Builder Commands Reference](/reference/builder-commands.md)**. diff --git a/skills/bmad-builder-setup/assets/module-help.csv b/skills/bmad-builder-setup/assets/module-help.csv index aa6f460..9687012 100644 --- a/skills/bmad-builder-setup/assets/module-help.csv +++ b/skills/bmad-builder-setup/assets/module-help.csv @@ -3,4 +3,7 @@ BMad Builder,bmad-builder-setup,Setup Builder Module,SB,"Install or update BMad BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, convert, or fix an agent skill.",build-process,"[-H] [description | path]",anytime,,bmad-agent-builder:quality-optimizer,false,output_folder,agent skill BMad Builder,bmad-agent-builder,Optimize an Agent,OA,Validate and optimize an existing agent skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, convert, or fix a workflow or utility skill.",build-process,"[-H] [description | path]",anytime,,bmad-workflow-builder:quality-optimizer,false,output_folder,workflow skill -BMad Builder,bmad-workflow-builder,Optimize a Workflow,OW,Validate and optimize an existing workflow or utility skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report \ No newline at end of file +BMad Builder,bmad-workflow-builder,Optimize a Workflow,OW,Validate and optimize an existing workflow or utility skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report +BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,,anytime,,bmad-module-builder:create-module,false,bmad_builder_reports,module plan +BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold a setup skill into an existing folder of built skills, making it an installable BMad module.",create-module,"[-H] [path]",anytime,bmad-module-builder:ideate-module,,false,bmad_builder_output_folder,setup skill +BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's setup skill is complete, accurate, and all capabilities are properly registered.",validate-module,[path],anytime,bmad-module-builder:create-module,,false,bmad_builder_reports,validation report \ No newline at end of file diff --git a/skills/bmad-module-builder/SKILL.md b/skills/bmad-module-builder/SKILL.md new file mode 100644 index 0000000..a7711ac --- /dev/null +++ b/skills/bmad-module-builder/SKILL.md @@ -0,0 +1,32 @@ +--- +name: bmad-module-builder +description: Plans, creates, and validates BMad modules. Use when the user requests to 'ideate module', 'plan a module', 'create module', 'build a module', or 'validate module'. +--- + +# BMad Module Builder + +## Overview + +This skill helps you bring BMad modules to life — from the first spark of an idea to a fully scaffolded, installable module. It offers three paths: + +- **Ideate Module (IM)** — A creative brainstorming session that helps you imagine what your module could be, decide on the right architecture (agent vs. workflow vs. both), and produce a detailed plan document. The plan then guides you through building each piece with the Agent Builder and Workflow Builder. +- **Create Module (CM)** — Takes an existing folder of built skills and scaffolds the setup infrastructure (module.yaml, module-help.csv, setup skill) that makes it a proper installable BMad module. Supports `--headless` / `-H`. +- **Validate Module (VM)** — Checks that a module's setup skill is complete and correct — every skill has its capabilities registered, entries are accurate and well-crafted, and structural integrity is sound. + +**Args:** Accepts `--headless` / `-H` for CM path only, an initial description for IM, or a path to a skills folder for CM/VM. + +## On Activation + +Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` (root level and `bmb` section). If config is missing, let the user know `bmad-builder-setup` can configure the module at any time. Use sensible defaults for anything not configured. + +Detect user's intent: + +- **Ideate / Plan** keywords or no path argument → Load `./references/ideate-module.md` +- **Create / Scaffold** keywords or a folder path → Load `./references/create-module.md` +- **Validate / Check** keywords → Load `./references/validate-module.md` +- **Unclear** → Present options: + - **Ideate Module (IM)** — "I have an idea for a module and want to brainstorm and plan it" + - **Create Module (CM)** — "I've already built my skills and want to package them as a module" + - **Validate Module (VM)** — "I want to check that my module's setup skill is complete and correct" + +If `--headless` or `-H` is passed, route to CM with headless mode. diff --git a/skills/bmad-module-builder/assets/module-plan-template.md b/skills/bmad-module-builder/assets/module-plan-template.md new file mode 100644 index 0000000..33821a6 --- /dev/null +++ b/skills/bmad-module-builder/assets/module-plan-template.md @@ -0,0 +1,94 @@ +--- +title: "Module Plan" +status: "ideation" +module_name: "" +module_code: "" +architecture: "" +standalone: true +expands_module: "" +skills_planned: [] +config_variables: [] +created: "" +updated: "" +--- + +# Module Plan + +## Vision + + + +## Architecture Decision + + + +## User Experience + + + +## Skills + + + +### {skill-name} + +**Type:** {agent | workflow} +**Purpose:** + +**Capabilities:** + +| Display Name | Menu Code | Description | Action | Args | Phase | After | Before | Required | Output Location | Outputs | +|---|---|---|---|---|---|---|---|---|---|---| +| | | | | | | | | | | | + +**Design Notes:** + +## Memory Architecture + + + + + +## Configuration + +| Variable | Prompt | Default | Result Template | User Setting | +|---|---|---|---|---| +| | | | | | + + + +## External Dependencies + + + + +## UI and Visualization + + + + +## Setup Extensions + + + + +## Integration + + + + +## Creative Use Cases + + + +## Ideas Captured + + + +## Build Roadmap + + + +**Next steps:** +1. Build each skill using **Build an Agent (BA)** or **Build a Workflow (BW)** — share this plan document as context +2. When all skills are built, return to **Create Module (CM)** to scaffold the module infrastructure diff --git a/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md b/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md new file mode 100644 index 0000000..326c3db --- /dev/null +++ b/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md @@ -0,0 +1,76 @@ +--- +name: {setup-skill-name} +description: Sets up {module-name} module in a project. Use when the user requests to 'install {module-code} module', 'configure {module-name}', or 'setup {module-name}'. +--- + +# Module Setup + +## Overview + +Installs and configures a BMad module into a project. Module identity (name, code, version) comes from `./assets/module.yaml`. Collects user preferences and writes them to three files: + +- **`{project-root}/_bmad/config.yaml`** — shared project config: core settings at root (e.g. `output_folder`, `document_output_language`) plus a section per module with metadata and module-specific values. User-only keys (`user_name`, `communication_language`) are **never** written here. +- **`{project-root}/_bmad/config.user.yaml`** — personal settings intended to be gitignored: `user_name`, `communication_language`, and any module variable marked `user_setting: true` in `./assets/module.yaml`. These values live exclusively here. +- **`{project-root}/_bmad/module-help.csv`** — registers module capabilities for the help system. + +Both config scripts use an anti-zombie pattern — existing entries for this module are removed before writing fresh ones, so stale values never persist. + +`{project-root}` is a **literal token** in config values — never substitute it with an actual path. It signals to the consuming LLM that the value is relative to the project root, not the skill root. + +## On Activation + +1. Read `./assets/module.yaml` for module metadata and variable definitions (the `code` field is the module identifier) +2. Check if `{project-root}/_bmad/config.yaml` exists — if a section matching the module's code is already present, inform the user this is an update +3. Check for per-module configuration at `{project-root}/_bmad/{module-code}/config.yaml` and `{project-root}/_bmad/core/config.yaml`. If either file exists: + - If `{project-root}/_bmad/config.yaml` does **not** yet have a section for this module: this is a **fresh install**. Inform the user that installer config was detected and values will be consolidated into the new format. + - If `{project-root}/_bmad/config.yaml` **already** has a section for this module: this is a **legacy migration**. Inform the user that legacy per-module config was found alongside existing config, and legacy values will be used as fallback defaults. + - In both cases, per-module config files and directories will be cleaned up after setup. + +If the user provides arguments (e.g. `accept all defaults`, `--headless`, or inline values like `user name is BMad, I speak Swahili`), map any provided values to config keys, use defaults for the rest, and skip interactive prompting. Still display the full confirmation summary at the end. + +## Collect Configuration + +Ask the user for values. Show defaults in brackets. Present all values together so the user can respond once with only the values they want to change (e.g. "change language to Swahili, rest are fine"). Never tell the user to "press enter" or "leave blank" — in a chat interface they must type something to respond. + +**Default priority** (highest wins): existing new config values > legacy config values > `./assets/module.yaml` defaults. When legacy configs exist, read them and use matching values as defaults instead of `module.yaml` defaults. Only keys that match the current schema are carried forward — changed or removed keys are ignored. + +**Core config** (only if no core keys exist yet): `user_name` (default: BMad), `communication_language` and `document_output_language` (default: English — ask as a single language question, both keys get the same answer), `output_folder` (default: `{project-root}/_bmad-output`). Of these, `user_name` and `communication_language` are written exclusively to `config.user.yaml`. The rest go to `config.yaml` at root and are shared across all modules. + +**Module config**: Read each variable in `./assets/module.yaml` that has a `prompt` field. Ask using that prompt with its default value (or legacy value if available). + +## Write Files + +Write a temp JSON file with the collected answers structured as `{"core": {...}, "module": {...}}` (omit `core` if it already exists). Then run both scripts — they can run in parallel since they write to different files: + +```bash +python3 ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad" +python3 ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code {module-code} +``` + +Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop. The scripts automatically read legacy config values as fallback defaults, then delete the legacy files after a successful merge. Check `legacy_configs_deleted` and `legacy_csvs_deleted` in the output to confirm cleanup. + +Run `./scripts/merge-config.py --help` or `./scripts/merge-help-csv.py --help` for full usage. + +## Create Output Directories + +After writing config, create any output directories that were configured. For filesystem operations only (such as creating directories), resolve the `{project-root}` token to the actual project root and create each path-type value from `config.yaml` that does not yet exist — this includes `output_folder` and any module variable whose value starts with `{project-root}/`. The paths stored in the config files must continue to use the literal `{project-root}` token; only the directories on disk should use the resolved paths. Use `mkdir -p` or equivalent to create the full path. + +## Cleanup Legacy Directories + +After both merge scripts complete successfully, remove the installer's package directories. Skills and agents in these directories are already installed at `.claude/skills/` — the `_bmad/` directory should only contain config files. + +```bash +python3 ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code {module-code} --also-remove _config --skills-dir "{project-root}/.claude/skills" +``` + +The script verifies that every skill in the legacy directories exists at `.claude/skills/` before removing anything. Directories without skills (like `_config/`) are removed directly. If the script exits non-zero, surface the error and stop. Missing directories (already cleaned by a prior run) are not errors — the script is idempotent. + +Check `directories_removed` and `files_removed_count` in the JSON output for the confirmation step. Run `./scripts/cleanup-legacy.py --help` for full usage. + +## Confirm + +Use the script JSON output to display what was written — config values set (written to `config.yaml` at root for core, module section for module values), user settings written to `config.user.yaml` (`user_keys` in result), help entries added, fresh install vs update. If legacy files were deleted, mention the migration. If legacy directories were removed, report the count and list (e.g. "Cleaned up 106 installer package files from bmb/, core/, _config/ — skills are installed at .claude/skills/"). Then display the `module_greeting` from `./assets/module.yaml` to the user. + +## Outcome + +Once the user's `user_name` and `communication_language` are known (from collected input, arguments, or existing config), use them consistently for the remainder of the session: address the user by their configured name and communicate in their configured `communication_language`. diff --git a/skills/bmad-module-builder/assets/setup-skill-template/assets/module-help.csv b/skills/bmad-module-builder/assets/setup-skill-template/assets/module-help.csv new file mode 100644 index 0000000..27dcad6 --- /dev/null +++ b/skills/bmad-module-builder/assets/setup-skill-template/assets/module-help.csv @@ -0,0 +1 @@ +module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs diff --git a/skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml b/skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml new file mode 100644 index 0000000..58d49ae --- /dev/null +++ b/skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml @@ -0,0 +1,7 @@ +code: +name: "" +description: "" +module_version: 1.0.0 +default_selected: false +module_greeting: > + diff --git a/skills/bmad-module-builder/assets/setup-skill-template/scripts/cleanup-legacy.py b/skills/bmad-module-builder/assets/setup-skill-template/scripts/cleanup-legacy.py new file mode 100755 index 0000000..fc12f40 --- /dev/null +++ b/skills/bmad-module-builder/assets/setup-skill-template/scripts/cleanup-legacy.py @@ -0,0 +1,259 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.9" +# dependencies = [] +# /// +"""Remove legacy module directories from _bmad/ after config migration. + +After merge-config.py and merge-help-csv.py have migrated config data and +deleted individual legacy files, this script removes the now-redundant +directory trees. These directories contain skill files that are already +installed at .claude/skills/ (or equivalent) — only the config files at +_bmad/ root need to persist. + +When --skills-dir is provided, the script verifies that every skill found +in the legacy directories exists at the installed location before removing +anything. Directories without skills (like _config/) are removed directly. + +Exit codes: 0=success (including nothing to remove), 1=validation error, 2=runtime error +""" + +import argparse +import json +import shutil +import sys +from pathlib import Path + + +def parse_args(): + parser = argparse.ArgumentParser( + description="Remove legacy module directories from _bmad/ after config migration." + ) + parser.add_argument( + "--bmad-dir", + required=True, + help="Path to the _bmad/ directory", + ) + parser.add_argument( + "--module-code", + required=True, + help="Module code being cleaned up (e.g. 'bmb')", + ) + parser.add_argument( + "--also-remove", + action="append", + default=[], + help="Additional directory names under _bmad/ to remove (repeatable)", + ) + parser.add_argument( + "--skills-dir", + help="Path to .claude/skills/ — enables safety verification that skills " + "are installed before removing legacy copies", + ) + parser.add_argument( + "--verbose", + action="store_true", + help="Print detailed progress to stderr", + ) + return parser.parse_args() + + +def find_skill_dirs(base_path: str) -> list: + """Find directories that contain a SKILL.md file. + + Walks the directory tree and returns the leaf directory name for each + directory containing a SKILL.md. These are considered skill directories. + + Returns: + List of skill directory names (e.g. ['bmad-agent-builder', 'bmad-builder-setup']) + """ + skills = [] + root = Path(base_path) + if not root.exists(): + return skills + for skill_md in root.rglob("SKILL.md"): + skills.append(skill_md.parent.name) + return sorted(set(skills)) + + +def verify_skills_installed( + bmad_dir: str, dirs_to_check: list, skills_dir: str, verbose: bool = False +) -> list: + """Verify that skills in legacy directories exist at the installed location. + + Scans each directory in dirs_to_check for skill folders (containing SKILL.md), + then checks that a matching directory exists under skills_dir. Directories + that contain no skills (like _config/) are silently skipped. + + Returns: + List of verified skill names. + + Raises SystemExit(1) if any skills are missing from skills_dir. + """ + all_verified = [] + missing = [] + + for dirname in dirs_to_check: + legacy_path = Path(bmad_dir) / dirname + if not legacy_path.exists(): + continue + + skill_names = find_skill_dirs(str(legacy_path)) + if not skill_names: + if verbose: + print( + f"No skills found in {dirname}/ — skipping verification", + file=sys.stderr, + ) + continue + + for skill_name in skill_names: + installed_path = Path(skills_dir) / skill_name + if installed_path.is_dir(): + all_verified.append(skill_name) + if verbose: + print( + f"Verified: {skill_name} exists at {installed_path}", + file=sys.stderr, + ) + else: + missing.append(skill_name) + if verbose: + print( + f"MISSING: {skill_name} not found at {installed_path}", + file=sys.stderr, + ) + + if missing: + error_result = { + "status": "error", + "error": "Skills not found at installed location", + "missing_skills": missing, + "skills_dir": str(Path(skills_dir).resolve()), + } + print(json.dumps(error_result, indent=2)) + sys.exit(1) + + return sorted(set(all_verified)) + + +def count_files(path: Path) -> int: + """Count all files recursively in a directory.""" + count = 0 + for item in path.rglob("*"): + if item.is_file(): + count += 1 + return count + + +def cleanup_directories( + bmad_dir: str, dirs_to_remove: list, verbose: bool = False +) -> tuple: + """Remove specified directories under bmad_dir. + + Returns: + (removed, not_found, total_files_removed) tuple + """ + removed = [] + not_found = [] + total_files = 0 + + for dirname in dirs_to_remove: + target = Path(bmad_dir) / dirname + if not target.exists(): + not_found.append(dirname) + if verbose: + print(f"Not found (skipping): {target}", file=sys.stderr) + continue + + if not target.is_dir(): + if verbose: + print(f"Not a directory (skipping): {target}", file=sys.stderr) + not_found.append(dirname) + continue + + file_count = count_files(target) + if verbose: + print( + f"Removing {target} ({file_count} files)", + file=sys.stderr, + ) + + try: + shutil.rmtree(target) + except OSError as e: + error_result = { + "status": "error", + "error": f"Failed to remove {target}: {e}", + "directories_removed": removed, + "directories_failed": dirname, + } + print(json.dumps(error_result, indent=2)) + sys.exit(2) + + removed.append(dirname) + total_files += file_count + + return removed, not_found, total_files + + +def main(): + args = parse_args() + + bmad_dir = args.bmad_dir + module_code = args.module_code + + # Build the list of directories to remove + dirs_to_remove = [module_code, "core"] + args.also_remove + # Deduplicate while preserving order + seen = set() + unique_dirs = [] + for d in dirs_to_remove: + if d not in seen: + seen.add(d) + unique_dirs.append(d) + dirs_to_remove = unique_dirs + + if args.verbose: + print(f"Directories to remove: {dirs_to_remove}", file=sys.stderr) + + # Safety check: verify skills are installed before removing + verified_skills = None + if args.skills_dir: + if args.verbose: + print( + f"Verifying skills installed at {args.skills_dir}", + file=sys.stderr, + ) + verified_skills = verify_skills_installed( + bmad_dir, dirs_to_remove, args.skills_dir, args.verbose + ) + + # Remove directories + removed, not_found, total_files = cleanup_directories( + bmad_dir, dirs_to_remove, args.verbose + ) + + # Build result + result = { + "status": "success", + "bmad_dir": str(Path(bmad_dir).resolve()), + "directories_removed": removed, + "directories_not_found": not_found, + "files_removed_count": total_files, + } + + if args.skills_dir: + result["safety_checks"] = { + "skills_verified": True, + "skills_dir": str(Path(args.skills_dir).resolve()), + "verified_skills": verified_skills, + } + else: + result["safety_checks"] = None + + print(json.dumps(result, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-config.py b/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-config.py new file mode 100755 index 0000000..6ee0ac7 --- /dev/null +++ b/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-config.py @@ -0,0 +1,408 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.9" +# dependencies = ["pyyaml"] +# /// +"""Merge module configuration into shared _bmad/config.yaml and config.user.yaml. + +Reads a module.yaml definition and a JSON answers file, then writes or updates +the shared config.yaml (core values at root + module section) and config.user.yaml +(user_name, communication_language, plus any module variable with user_setting: true). +Uses an anti-zombie pattern for the module section in config.yaml. + +Legacy migration: when --legacy-dir is provided, reads old per-module config files +from {legacy-dir}/{module-code}/config.yaml and {legacy-dir}/core/config.yaml. +Matching values serve as fallback defaults (answers override them). After a +successful merge, the legacy config.yaml files are deleted. Only the current +module and core directories are touched — other module directories are left alone. + +Exit codes: 0=success, 1=validation error, 2=runtime error +""" + +import argparse +import json +import sys +from pathlib import Path + +try: + import yaml +except ImportError: + print("Error: pyyaml is required (PEP 723 dependency)", file=sys.stderr) + sys.exit(2) + + +def parse_args(): + parser = argparse.ArgumentParser( + description="Merge module config into shared _bmad/config.yaml with anti-zombie pattern." + ) + parser.add_argument( + "--config-path", + required=True, + help="Path to the target _bmad/config.yaml file", + ) + parser.add_argument( + "--module-yaml", + required=True, + help="Path to the module.yaml definition file", + ) + parser.add_argument( + "--answers", + required=True, + help="Path to JSON file with collected answers", + ) + parser.add_argument( + "--user-config-path", + required=True, + help="Path to the target _bmad/config.user.yaml file", + ) + parser.add_argument( + "--legacy-dir", + help="Path to _bmad/ directory to check for legacy per-module config files. " + "Matching values are used as fallback defaults, then legacy files are deleted.", + ) + parser.add_argument( + "--verbose", + action="store_true", + help="Print detailed progress to stderr", + ) + return parser.parse_args() + + +def load_yaml_file(path: str) -> dict: + """Load a YAML file, returning empty dict if file doesn't exist.""" + file_path = Path(path) + if not file_path.exists(): + return {} + with open(file_path, "r", encoding="utf-8") as f: + content = yaml.safe_load(f) + return content if content else {} + + +def load_json_file(path: str) -> dict: + """Load a JSON file.""" + with open(path, "r", encoding="utf-8") as f: + return json.load(f) + + +# Keys that live at config root (shared across all modules) +_CORE_KEYS = frozenset( + {"user_name", "communication_language", "document_output_language", "output_folder"} +) + + +def load_legacy_values( + legacy_dir: str, module_code: str, module_yaml: dict, verbose: bool = False +) -> tuple[dict, dict, list]: + """Read legacy per-module config files and return core/module value dicts. + + Reads {legacy_dir}/core/config.yaml and {legacy_dir}/{module_code}/config.yaml. + Only returns values whose keys match the current schema (core keys or module.yaml + variable definitions). Other modules' directories are not touched. + + Returns: + (legacy_core, legacy_module, files_found) where files_found lists paths read. + """ + legacy_core: dict = {} + legacy_module: dict = {} + files_found: list = [] + + # Read core legacy config + core_path = Path(legacy_dir) / "core" / "config.yaml" + if core_path.exists(): + core_data = load_yaml_file(str(core_path)) + files_found.append(str(core_path)) + for k, v in core_data.items(): + if k in _CORE_KEYS: + legacy_core[k] = v + if verbose: + print(f"Legacy core config: {list(legacy_core.keys())}", file=sys.stderr) + + # Read module legacy config + mod_path = Path(legacy_dir) / module_code / "config.yaml" + if mod_path.exists(): + mod_data = load_yaml_file(str(mod_path)) + files_found.append(str(mod_path)) + for k, v in mod_data.items(): + if k in _CORE_KEYS: + # Core keys duplicated in module config — only use if not already set + if k not in legacy_core: + legacy_core[k] = v + elif k in module_yaml and isinstance(module_yaml[k], dict): + # Module-specific key that matches a current variable definition + legacy_module[k] = v + if verbose: + print( + f"Legacy module config: {list(legacy_module.keys())}", file=sys.stderr + ) + + return legacy_core, legacy_module, files_found + + +def apply_legacy_defaults(answers: dict, legacy_core: dict, legacy_module: dict) -> dict: + """Apply legacy values as fallback defaults under the answers. + + Legacy values fill in any key not already present in answers. + Explicit answers always win. + """ + merged = dict(answers) + + if legacy_core: + core = merged.get("core", {}) + filled_core = dict(legacy_core) # legacy as base + filled_core.update(core) # answers override + merged["core"] = filled_core + + if legacy_module: + mod = merged.get("module", {}) + filled_mod = dict(legacy_module) # legacy as base + filled_mod.update(mod) # answers override + merged["module"] = filled_mod + + return merged + + +def cleanup_legacy_configs( + legacy_dir: str, module_code: str, verbose: bool = False +) -> list: + """Delete legacy config.yaml files for this module and core only. + + Returns list of deleted file paths. + """ + deleted = [] + for subdir in (module_code, "core"): + legacy_path = Path(legacy_dir) / subdir / "config.yaml" + if legacy_path.exists(): + if verbose: + print(f"Deleting legacy config: {legacy_path}", file=sys.stderr) + legacy_path.unlink() + deleted.append(str(legacy_path)) + return deleted + + +def extract_module_metadata(module_yaml: dict) -> dict: + """Extract non-variable metadata fields from module.yaml.""" + meta = {} + for k in ("name", "description"): + if k in module_yaml: + meta[k] = module_yaml[k] + meta["version"] = module_yaml.get("module_version") # null if absent + if "default_selected" in module_yaml: + meta["default_selected"] = module_yaml["default_selected"] + return meta + + +def apply_result_templates( + module_yaml: dict, module_answers: dict, verbose: bool = False +) -> dict: + """Apply result templates from module.yaml to transform raw answer values. + + For each answer, if the corresponding variable definition in module.yaml has + a 'result' field, replaces {value} in that template with the answer. Skips + the template if the answer already contains '{project-root}' to prevent + double-prefixing. + """ + transformed = {} + for key, value in module_answers.items(): + var_def = module_yaml.get(key) + if ( + isinstance(var_def, dict) + and "result" in var_def + and "{project-root}" not in str(value) + ): + template = var_def["result"] + transformed[key] = template.replace("{value}", str(value)) + if verbose: + print( + f"Applied result template for '{key}': {value} → {transformed[key]}", + file=sys.stderr, + ) + else: + transformed[key] = value + return transformed + + +def merge_config( + existing_config: dict, + module_yaml: dict, + answers: dict, + verbose: bool = False, +) -> dict: + """Merge answers into config, applying anti-zombie pattern. + + Args: + existing_config: Current config.yaml contents (may be empty) + module_yaml: The module definition + answers: JSON with 'core' and/or 'module' keys + verbose: Print progress to stderr + + Returns: + Updated config dict ready to write + """ + config = dict(existing_config) + module_code = module_yaml.get("code") + + if not module_code: + print("Error: module.yaml must have a 'code' field", file=sys.stderr) + sys.exit(1) + + # Migrate legacy core: section to root + if "core" in config and isinstance(config["core"], dict): + if verbose: + print("Migrating legacy 'core' section to root", file=sys.stderr) + config.update(config.pop("core")) + + # Strip user-only keys from config — they belong exclusively in config.user.yaml + for key in _CORE_USER_KEYS: + if key in config: + if verbose: + print(f"Removing user-only key '{key}' from config (belongs in config.user.yaml)", file=sys.stderr) + del config[key] + + # Write core values at root (global properties, not nested under "core") + # Exclude user-only keys — those belong exclusively in config.user.yaml + core_answers = answers.get("core") + if core_answers: + shared_core = {k: v for k, v in core_answers.items() if k not in _CORE_USER_KEYS} + if shared_core: + if verbose: + print(f"Writing core config at root: {list(shared_core.keys())}", file=sys.stderr) + config.update(shared_core) + + # Anti-zombie: remove existing module section + if module_code in config: + if verbose: + print( + f"Removing existing '{module_code}' section (anti-zombie)", + file=sys.stderr, + ) + del config[module_code] + + # Build module section: metadata + variable values + module_section = extract_module_metadata(module_yaml) + module_answers = apply_result_templates( + module_yaml, answers.get("module", {}), verbose + ) + module_section.update(module_answers) + + if verbose: + print( + f"Writing '{module_code}' section with keys: {list(module_section.keys())}", + file=sys.stderr, + ) + + config[module_code] = module_section + + return config + + +# Core keys that are always written to config.user.yaml +_CORE_USER_KEYS = ("user_name", "communication_language") + + +def extract_user_settings(module_yaml: dict, answers: dict) -> dict: + """Collect settings that belong in config.user.yaml. + + Includes user_name and communication_language from core answers, plus any + module variable whose definition contains user_setting: true. + """ + user_settings = {} + + core_answers = answers.get("core", {}) + for key in _CORE_USER_KEYS: + if key in core_answers: + user_settings[key] = core_answers[key] + + module_answers = answers.get("module", {}) + for var_name, var_def in module_yaml.items(): + if isinstance(var_def, dict) and var_def.get("user_setting") is True: + if var_name in module_answers: + user_settings[var_name] = module_answers[var_name] + + return user_settings + + +def write_config(config: dict, config_path: str, verbose: bool = False) -> None: + """Write config dict to YAML file, creating parent dirs as needed.""" + path = Path(config_path) + path.parent.mkdir(parents=True, exist_ok=True) + + if verbose: + print(f"Writing config to {path}", file=sys.stderr) + + with open(path, "w", encoding="utf-8") as f: + yaml.dump( + config, + f, + default_flow_style=False, + allow_unicode=True, + sort_keys=False, + ) + + +def main(): + args = parse_args() + + # Load inputs + module_yaml = load_yaml_file(args.module_yaml) + if not module_yaml: + print(f"Error: Could not load module.yaml from {args.module_yaml}", file=sys.stderr) + sys.exit(1) + + answers = load_json_file(args.answers) + existing_config = load_yaml_file(args.config_path) + + if args.verbose: + exists = Path(args.config_path).exists() + print(f"Config file exists: {exists}", file=sys.stderr) + if exists: + print(f"Existing sections: {list(existing_config.keys())}", file=sys.stderr) + + # Legacy migration: read old per-module configs as fallback defaults + legacy_files_found = [] + if args.legacy_dir: + module_code = module_yaml.get("code", "") + legacy_core, legacy_module, legacy_files_found = load_legacy_values( + args.legacy_dir, module_code, module_yaml, args.verbose + ) + if legacy_core or legacy_module: + answers = apply_legacy_defaults(answers, legacy_core, legacy_module) + if args.verbose: + print("Applied legacy values as fallback defaults", file=sys.stderr) + + # Merge and write config.yaml + updated_config = merge_config(existing_config, module_yaml, answers, args.verbose) + write_config(updated_config, args.config_path, args.verbose) + + # Merge and write config.user.yaml + user_settings = extract_user_settings(module_yaml, answers) + existing_user_config = load_yaml_file(args.user_config_path) + updated_user_config = dict(existing_user_config) + updated_user_config.update(user_settings) + if user_settings: + write_config(updated_user_config, args.user_config_path, args.verbose) + + # Legacy cleanup: delete old per-module config files + legacy_deleted = [] + if args.legacy_dir: + legacy_deleted = cleanup_legacy_configs( + args.legacy_dir, module_yaml["code"], args.verbose + ) + + # Output result summary as JSON + module_code = module_yaml["code"] + result = { + "status": "success", + "config_path": str(Path(args.config_path).resolve()), + "user_config_path": str(Path(args.user_config_path).resolve()), + "module_code": module_code, + "core_updated": bool(answers.get("core")), + "module_keys": list(updated_config.get(module_code, {}).keys()), + "user_keys": list(user_settings.keys()), + "legacy_configs_found": legacy_files_found, + "legacy_configs_deleted": legacy_deleted, + } + print(json.dumps(result, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-help-csv.py b/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-help-csv.py new file mode 100755 index 0000000..04469ef --- /dev/null +++ b/skills/bmad-module-builder/assets/setup-skill-template/scripts/merge-help-csv.py @@ -0,0 +1,220 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.9" +# dependencies = [] +# /// +"""Merge module help entries into shared _bmad/module-help.csv. + +Reads a source CSV with module help entries and merges them into a target CSV. +Uses an anti-zombie pattern: all existing rows matching the source module code +are removed before appending fresh rows. + +Legacy cleanup: when --legacy-dir and --module-code are provided, deletes old +per-module module-help.csv files from {legacy-dir}/{module-code}/ and +{legacy-dir}/core/. Only the current module and core are touched. + +Exit codes: 0=success, 1=validation error, 2=runtime error +""" + +import argparse +import csv +import json +import sys +from io import StringIO +from pathlib import Path + +# CSV header for module-help.csv +HEADER = [ + "module", + "agent-name", + "skill-name", + "display-name", + "menu-code", + "capability", + "args", + "description", + "phase", + "after", + "before", + "required", + "output-location", + "outputs", + "", # trailing empty column from trailing comma +] + + +def parse_args(): + parser = argparse.ArgumentParser( + description="Merge module help entries into shared _bmad/module-help.csv with anti-zombie pattern." + ) + parser.add_argument( + "--target", + required=True, + help="Path to the target _bmad/module-help.csv file", + ) + parser.add_argument( + "--source", + required=True, + help="Path to the source module-help.csv with entries to merge", + ) + parser.add_argument( + "--legacy-dir", + help="Path to _bmad/ directory to check for legacy per-module CSV files.", + ) + parser.add_argument( + "--module-code", + help="Module code (required with --legacy-dir for scoping cleanup).", + ) + parser.add_argument( + "--verbose", + action="store_true", + help="Print detailed progress to stderr", + ) + return parser.parse_args() + + +def read_csv_rows(path: str) -> tuple[list[str], list[list[str]]]: + """Read CSV file returning (header, data_rows). + + Returns empty header and rows if file doesn't exist. + """ + file_path = Path(path) + if not file_path.exists(): + return [], [] + + with open(file_path, "r", encoding="utf-8", newline="") as f: + content = f.read() + + reader = csv.reader(StringIO(content)) + rows = list(reader) + + if not rows: + return [], [] + + return rows[0], rows[1:] + + +def extract_module_codes(rows: list[list[str]]) -> set[str]: + """Extract unique module codes from data rows.""" + codes = set() + for row in rows: + if row and row[0].strip(): + codes.add(row[0].strip()) + return codes + + +def filter_rows(rows: list[list[str]], module_code: str) -> list[list[str]]: + """Remove all rows matching the given module code.""" + return [row for row in rows if not row or row[0].strip() != module_code] + + +def write_csv(path: str, header: list[str], rows: list[list[str]], verbose: bool = False) -> None: + """Write header + rows to CSV file, creating parent dirs as needed.""" + file_path = Path(path) + file_path.parent.mkdir(parents=True, exist_ok=True) + + if verbose: + print(f"Writing {len(rows)} data rows to {path}", file=sys.stderr) + + with open(file_path, "w", encoding="utf-8", newline="") as f: + writer = csv.writer(f) + writer.writerow(header) + for row in rows: + writer.writerow(row) + + +def cleanup_legacy_csvs( + legacy_dir: str, module_code: str, verbose: bool = False +) -> list: + """Delete legacy per-module module-help.csv files for this module and core only. + + Returns list of deleted file paths. + """ + deleted = [] + for subdir in (module_code, "core"): + legacy_path = Path(legacy_dir) / subdir / "module-help.csv" + if legacy_path.exists(): + if verbose: + print(f"Deleting legacy CSV: {legacy_path}", file=sys.stderr) + legacy_path.unlink() + deleted.append(str(legacy_path)) + return deleted + + +def main(): + args = parse_args() + + # Read source entries + source_header, source_rows = read_csv_rows(args.source) + if not source_rows: + print(f"Error: No data rows found in source {args.source}", file=sys.stderr) + sys.exit(1) + + # Determine module codes being merged + source_codes = extract_module_codes(source_rows) + if not source_codes: + print("Error: Could not determine module code from source rows", file=sys.stderr) + sys.exit(1) + + if args.verbose: + print(f"Source module codes: {source_codes}", file=sys.stderr) + print(f"Source rows: {len(source_rows)}", file=sys.stderr) + + # Read existing target (may not exist) + target_header, target_rows = read_csv_rows(args.target) + target_existed = Path(args.target).exists() + + if args.verbose: + print(f"Target exists: {target_existed}", file=sys.stderr) + if target_existed: + print(f"Existing target rows: {len(target_rows)}", file=sys.stderr) + + # Use source header if target doesn't exist or has no header + header = target_header if target_header else (source_header if source_header else HEADER) + + # Anti-zombie: remove all rows for each source module code + filtered_rows = target_rows + removed_count = 0 + for code in source_codes: + before_count = len(filtered_rows) + filtered_rows = filter_rows(filtered_rows, code) + removed_count += before_count - len(filtered_rows) + + if args.verbose and removed_count > 0: + print(f"Removed {removed_count} existing rows (anti-zombie)", file=sys.stderr) + + # Append source rows + merged_rows = filtered_rows + source_rows + + # Write result + write_csv(args.target, header, merged_rows, args.verbose) + + # Legacy cleanup: delete old per-module CSV files + legacy_deleted = [] + if args.legacy_dir: + if not args.module_code: + print( + "Error: --module-code is required when --legacy-dir is provided", + file=sys.stderr, + ) + sys.exit(1) + legacy_deleted = cleanup_legacy_csvs( + args.legacy_dir, args.module_code, args.verbose + ) + + # Output result summary as JSON + result = { + "status": "success", + "target_path": str(Path(args.target).resolve()), + "target_existed": target_existed, + "module_codes": sorted(source_codes), + "rows_removed": removed_count, + "rows_added": len(source_rows), + "total_rows": len(merged_rows), + "legacy_csvs_deleted": legacy_deleted, + } + print(json.dumps(result, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/skills/bmad-module-builder/references/create-module.md b/skills/bmad-module-builder/references/create-module.md new file mode 100644 index 0000000..adefbb7 --- /dev/null +++ b/skills/bmad-module-builder/references/create-module.md @@ -0,0 +1,122 @@ +# Create Module + +**Language:** Use `{communication_language}` for all output. + +## Your Role + +You are a module packaging specialist. The user has built their skills — your job is to read them deeply, understand the ecosystem they form, and scaffold the infrastructure that makes it an installable BMad module. + +## Process + +### 1. Discover the Skills + +Ask the user for the folder path containing their built skills. Also ask: do they have a plan document from an Ideate Module (IM) session? If so, read it — it provides valuable context for ordering, relationships, and design intent. + +**Read every SKILL.md in the folder thoroughly.** Understand each skill's: +- Name, purpose, and capabilities +- Arguments and interaction model +- What it produces and where +- Dependencies on other skills or external tools + +### 2. Gather Module Identity + +Collect through conversation (or extract from a plan document in headless mode): + +- **Module name** — Human-friendly display name (e.g., "Creative Intelligence Suite") +- **Module code** — 2-4 letter abbreviation (e.g., "cis"). Used in skill naming, config sections, and folder conventions +- **Description** — One-line summary of what the module does +- **Version** — Starting version (default: 1.0.0) +- **Module greeting** — Message shown to the user after setup completes +- **Standalone or expansion?** If expansion: which module does it extend? This affects how help CSV entries may reference capabilities from the parent module + +### 3. Define Capabilities + +Build the help CSV entries for each skill. A single skill can have multiple capabilities (rows). For each capability: + +| Field | Description | +|---|---| +| **display-name** | What the user sees in help/menus | +| **menu-code** | 2-letter shortcut, unique across the module | +| **description** | What this capability does (concise) | +| **action** | The capability/action name within the skill | +| **args** | Supported arguments (e.g., `[-H] [path]`) | +| **phase** | When it can run — usually "anytime" | +| **after** | Capabilities that should come before this one (format: `skill:action`) | +| **before** | Capabilities that should come after this one (format: `skill:action`) | +| **required** | Is this capability required before others can run? | +| **output-location** | Where output goes (config variable name or path) | +| **outputs** | What it produces | + +Ask the user about: +- How capabilities should be ordered — are there natural sequences? +- Which capabilities are prerequisites for others? +- If this is an expansion module, do any capabilities reference the parent module's skills in their before/after fields? + +### 4. Define Configuration Variables + +Does the module need custom installation questions? For each custom variable: + +| Field | Description | +|---|---| +| **Key name** | Used in config.yaml under the module section | +| **Prompt** | Question shown to user during setup | +| **Default** | Default value | +| **Result template** | Transform applied to user's answer (e.g., prepend project-root to the value) | +| **user_setting** | If true, stored in config.user.yaml instead of config.yaml | + +Remind the user: skills should always have sensible fallbacks if config hasn't been set. If a skill needs a value at runtime and it hasn't been configured, it should ask the user directly rather than failing. + +### 5. External Dependencies and Setup Extensions + +Ask the user about requirements beyond configuration: + +- **CLI tools or MCP servers** — Do any skills depend on externally installed tools? If so, the setup skill should check for their presence and guide the user through installation or configuration. These checks would be custom additions to the cloned setup SKILL.md. +- **UI or web app** — Does the module include a dashboard, visualization layer, or interactive web interface? If the setup skill needs to install or configure a web app, scaffold UI files, or set up a dev server, capture those requirements. +- **Additional setup actions** — Beyond config collection: scaffolding project directories, generating starter files, configuring external services, setting up webhooks, etc. + +If any of these apply, let the user know the scaffolded setup skill will need manual customization after creation to add these capabilities. Document what needs to be added so the user has a clear checklist. + +### 6. Generate and Confirm + +Present the complete module.yaml and module-help.csv content for the user to review. Show: +- Module identity and metadata +- All configuration variables with their prompts and defaults +- Complete help CSV entries with ordering and relationships +- Any external dependencies or setup extensions that need manual follow-up + +Iterate until the user confirms everything is correct. + +### 7. Scaffold + +Write the confirmed module.yaml and module-help.csv content to temporary files. Run the scaffold script: + +```bash +python3 ./scripts/scaffold-setup-skill.py \ + --target-dir "{skills-folder}" \ + --module-code "{code}" \ + --module-name "{name}" \ + --module-yaml "{temp-yaml-path}" \ + --module-csv "{temp-csv-path}" +``` + +This creates `bmad-{code}-setup/` in the user's skills folder containing: +- `./SKILL.md` — Generic setup skill with module-specific frontmatter +- `./scripts/` — merge-config.py, merge-help-csv.py, cleanup-legacy.py +- `./assets/module.yaml` — Generated module definition +- `./assets/module-help.csv` — Generated capability registry + +### 8. Confirm and Next Steps + +Show what was created — the setup skill folder structure and key file contents. Let the user know: + +- To install this module in any project, run the setup skill +- The setup skill handles config collection, writing, and help CSV registration +- The module is now a complete, distributable BMad module + +## Headless Mode + +When `--headless` is set, the skill requires either: +- A **plan document path** — extract all module identity, capabilities, and config from it +- A **skills folder path** — read skills and infer sensible defaults for module identity + +In headless mode: skip interactive questions, scaffold immediately, present a summary of what was created at the end. If critical information is missing and cannot be inferred (like module code), exit with an error explaining what's needed. diff --git a/skills/bmad-module-builder/references/ideate-module.md b/skills/bmad-module-builder/references/ideate-module.md new file mode 100644 index 0000000..ece67b3 --- /dev/null +++ b/skills/bmad-module-builder/references/ideate-module.md @@ -0,0 +1,122 @@ +# Ideate Module + +**Language:** Use `{communication_language}` for all conversation. Write plan document in `{document_output_language}`. + +## Your Role + +You are a creative collaborator and module architect — part brainstorming partner, part technical advisor. Your job is to help the user discover and articulate their vision for a BMad module. The user is the creative force. You draw out their ideas, build on them, and help them see possibilities they haven't considered yet. When the session is over, they should feel like every great idea was theirs. + +## Facilitation Principles + +These are non-negotiable — they define the experience: + +- **The user is the genius.** Build on their ideas. When you see a connection they haven't made, ask a question that leads them there — don't just state it. When they land on something great, celebrate it genuinely. +- **"Yes, and..."** — Never dismiss. Every idea has a seed worth growing. Add to it, extend it, combine it with something else. +- **Stay generative longer than feels comfortable.** The best ideas come after the obvious ones are exhausted. Resist the urge to organize or converge early. When the user starts structuring prematurely, gently redirect: "Love that — let's capture it. Before we organize, what else comes to mind?" +- **Capture everything.** When the user says something in passing that's actually important, note it in the plan document and surface it at the right moment later. +- **Soft gates at transitions.** "Anything else on this, or shall we explore...?" Users almost always remember one more thing when given a graceful exit ramp. +- **Make it fun.** This should feel like the best brainstorming session the user has ever had — energizing, surprising, and productive. Match the user's energy. If they're excited, be excited with them. If they're thoughtful, go deep. + +## Brainstorming Toolkit + +Weave these into conversation naturally. Never name them or make the user feel like they're in a methodology. They're your internal playbook for keeping the conversation rich and multi-dimensional: + +- **First Principles** — Strip away assumptions. "What problem is this actually solving at its core?" "If you could only do one thing for your users, what would it be?" +- **What If Scenarios** — Expand possibility space. "What if this could also..." "What if we flipped that and..." "What would change if there were no technical constraints?" +- **Reverse Brainstorming** — Find constraints through inversion. "What would make this terrible for users?" "What's the worst version of this module?" Then flip the answers. +- **Assumption Reversal** — Challenge architecture decisions. "Do these really need to be separate?" "What if a single agent could handle all of that?" "What assumption are we making that might not be true?" +- **Perspective Shifting** — Rotate viewpoints. Ask from the end-user angle, the developer maintaining it, someone extending it later, a complete beginner encountering it for the first time. +- **Question Storming** — Surface unknowns. "What questions will users have when they first see this?" "What would a skeptic ask?" "What's the thing we haven't thought of yet?" + +## Process + +### 1. Open the Session + +Initialize the plan document immediately using `./assets/module-plan-template.md`. Write it to `{bmad_builder_reports}` with a descriptive filename. Set `created` and `updated` timestamps. This document is your cache — update it progressively as the conversation unfolds so work survives context compaction. + +Start by understanding the spark. Let the user talk freely — this is where the richest context comes from: +- What's the idea? What problem space or domain? +- Who would use this and what would they get from it? +- Is there anything that inspired this — an existing tool, a frustration, a gap they've noticed? + +Don't rush to structure. Just listen, ask follow-ups, and capture. + +### 2. Explore Creatively + +This is the heart of the session — spend real time here. Use the brainstorming toolkit to help the user explore: + +- What capabilities would serve users in this domain? +- What would delight users? What would surprise them? +- What are the edge cases and hard problems? +- What would a power user want vs. a beginner? +- How might different capabilities work together in unexpected ways? +- What exists today that's close but not quite right? + +Update the **Ideas Captured** section of the plan document as ideas emerge. Capture raw ideas generously — even ones that seem tangential. They're context for later. + +Energy check: if the conversation plateaus, try a perspective shift or reverse brainstorming to open a new vein. + +### 3. Shape the Architecture + +When exploration feels genuinely complete (not just "we have enough"), shift to architecture. + +**Guide toward agent-with-capabilities when appropriate.** Many users default to thinking they need multiple specialized agents. But a well-designed single agent with rich internal capabilities and routing: +- Provides a more seamless user experience +- Benefits from accumulated memory and context +- Is simpler to maintain and configure +- Can still have distinct modes or capabilities that feel like separate tools + +However, **multiple agents make sense when:** +- The module spans genuinely different expertise domains that benefit from distinct personas +- Users may want to interact with one agent without loading the others +- Each agent needs its own memory context — personal history, learned preferences, domain-specific notes +- Some capabilities are optional add-ons the user might not install + +**Multiple workflows make sense when:** +- Capabilities serve different user journeys or require different tools +- The workflow requires sequential phases with fundamentally different processes +- No persistent persona or memory is needed between invocations + +Even with multiple agents, each should be self-contained with its own capabilities. Duplicating some common functionality across agents is fine — it keeps each agent coherent and independently useful. This is the user's decision, but guide them toward self-sufficiency per agent. + +Present the trade-offs. Let the user decide. Document the reasoning either way — future-them will want to know why. + +**Memory architecture for multi-agent modules.** If the module has multiple agents, explore how memory should work. Every agent has its own sidecar (personal memory at `{project-root}/_bmad/memory/{skillName}-sidecar/`), but modules may also benefit from shared memory: + +| Pattern | When It Fits | Example | +| ------- | ------------ | ------- | +| **Personal sidecars only** | Agents have distinct domains with little overlap | A module with a code reviewer and a test writer — each tracks different things | +| **Personal + shared module sidecar** | Agents have their own context but also learn shared things about the user | A social creative module — podcast, video, and blog experts each remember their domain specifics but share knowledge about the user's style, catchphrases, and content preferences | +| **Shared sidecar only** | All agents serve the same domain and context | Probably a sign this should be a single agent | + +With shared memory, each agent writes to both its personal sidecar and a module-level sidecar (e.g., `{project-root}/_bmad/memory/{moduleCode}-shared/`) when it learns something relevant to the whole module. Shared content might include: user style preferences, project assets, recurring themes, content history, or any cross-cutting context. + +If the memory architecture points entirely toward shared memory with no personal differentiation, gently surface whether a single agent with multiple capabilities might be the better design. + +### 4. Define Module Context + +- **Standalone or expansion?** If expansion: which module does it extend? How do the new capabilities relate? Even expansion modules should provide value independently — the parent module being absent shouldn't break this one. +- **Custom configuration?** Does the module need to ask users questions during setup? What variables would skills use? Important guidance to capture: skills should always have sensible fallbacks if config hasn't been set, or ask at runtime for specific values they need. +- **External dependencies?** Do any planned skills rely on externally installed CLI tools or MCP servers? If so, the setup skill may need to check for these, guide the user through installation, or configure connection details. Capture what's needed and why. +- **UI or visualization?** Could the module benefit from a user interface? This could be a shared progress dashboard, per-skill visualizations, an interactive view showing how skills relate and flow together, or even a cohesive module-level dashboard. Some modules might warrant a bespoke web app. Not every module needs this, but it's worth exploring — users often don't think of it until prompted. +- **Setup skill extensions?** Beyond config collection, does the setup process need to do anything special? Install a web app, scaffold project directories, configure external services, generate starter files? The setup skill is extensible — it can do more than just write config. + +### 5. Define Each Skill + +For each planned skill (whether agent or workflow), work through: +- **Name** — following `bmad-{modulecode}-{skillname}` convention +- **Purpose** — the core outcome in one sentence +- **Capabilities** — each distinct action or mode. These become rows in the help CSV: display name, menu code, description, action name, args, phase, ordering (before/after), required flag, output location, outputs +- **Relationships** — how skills relate to each other. Does one need to run before another? Are there cross-skill dependencies? +- **Design notes** — non-obvious considerations the skill builders should know + +Update the **Skills** section of the plan document with structured entries for each. + +### 6. Finalize the Plan + +Complete all sections of the plan document. Review with the user — walk through the plan and confirm it captures their vision. Update `status` to "complete" in the frontmatter. + +**Close with next steps:** +- "Build each skill using **Build an Agent (BA)** or **Build a Workflow (BW)** — share this plan document as context so the builder understands the bigger picture." +- "When all skills are built, return to **Create Module (CM)** to scaffold the module infrastructure." +- Point them to the plan document location so they can reference it. diff --git a/skills/bmad-module-builder/references/validate-module.md b/skills/bmad-module-builder/references/validate-module.md new file mode 100644 index 0000000..2074d15 --- /dev/null +++ b/skills/bmad-module-builder/references/validate-module.md @@ -0,0 +1,53 @@ +# Validate Module + +**Language:** Use `{communication_language}` for all output. + +## Your Role + +You are a module quality reviewer. Your job is to verify that a BMad module's setup skill is complete, accurate, and well-crafted — ensuring every skill is properly registered and every help entry gives users and LLMs the information they need. + +## Process + +### 1. Locate the Module + +Ask the user for the path to their module's skills folder. Identify the setup skill (`bmad-*-setup`) and all other skill folders. + +### 2. Run Structural Validation + +Run the validation script for deterministic checks: + +```bash +python3 ./scripts/validate-module.py "{module-skills-folder}" +``` + +This checks: setup skill structure, module.yaml completeness, CSV integrity (missing entries, orphans, duplicate menu codes, broken before/after references, missing required fields). + +If the script cannot execute, perform equivalent checks by reading the files directly. + +### 3. Quality Assessment + +This is where LLM judgment matters. Read every SKILL.md in the module thoroughly, then review each CSV entry against what you learned: + +**Completeness** — Does every distinct capability of every skill have its own CSV row? A skill with multiple modes or actions should have multiple entries. Look for capabilities described in SKILL.md overviews that aren't registered. + +**Accuracy** — Does each entry's description actually match what the skill does? Are the action names correct? Do the args match what the skill accepts? + +**Description quality** — Each description should be: +- Concise but informative — enough for a user to know what it does and for an LLM to route correctly +- Action-oriented — starts with a verb (Create, Validate, Brainstorm, Scaffold) +- Specific — avoids vague language ("helps with things", "manages stuff") +- Not overly verbose — one sentence, no filler + +**Ordering and relationships** — Do the before/after references make sense given what the skills actually do? Are required flags set appropriately? + +**Menu codes** — Are they intuitive? Do they relate to the display name in a way users can remember? + +### 4. Present Results + +Combine script findings and quality assessment into a clear report: + +- **Structural issues** (from script) — list with severity +- **Quality findings** (from your review) — specific, actionable suggestions per entry +- **Overall assessment** — is this module ready for use, or does it need fixes? + +For each finding, explain what's wrong and suggest the fix. Be direct — the user should be able to act on every item without further clarification. diff --git a/skills/bmad-module-builder/scripts/scaffold-setup-skill.py b/skills/bmad-module-builder/scripts/scaffold-setup-skill.py new file mode 100644 index 0000000..bce9fcd --- /dev/null +++ b/skills/bmad-module-builder/scripts/scaffold-setup-skill.py @@ -0,0 +1,124 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.10" +# /// +"""Scaffold a BMad module setup skill from template. + +Copies the setup-skill-template into the target directory as bmad-{code}-setup/, +then writes the generated module.yaml and module-help.csv into the assets folder +and updates the SKILL.md frontmatter with the module's identity. +""" + +import argparse +import json +import shutil +import sys +from pathlib import Path + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Scaffold a BMad module setup skill from template" + ) + parser.add_argument( + "--target-dir", + required=True, + help="Directory to create the setup skill in (the user's skills folder)", + ) + parser.add_argument( + "--module-code", + required=True, + help="Module code (2-4 letter abbreviation, e.g. 'cis')", + ) + parser.add_argument( + "--module-name", + required=True, + help="Module display name (e.g. 'Creative Intelligence Suite')", + ) + parser.add_argument( + "--module-yaml", + required=True, + help="Path to the generated module.yaml content file", + ) + parser.add_argument( + "--module-csv", + required=True, + help="Path to the generated module-help.csv content file", + ) + parser.add_argument( + "--verbose", action="store_true", help="Print progress to stderr" + ) + args = parser.parse_args() + + template_dir = Path(__file__).resolve().parent.parent / "assets" / "setup-skill-template" + setup_skill_name = f"bmad-{args.module_code}-setup" + target = Path(args.target_dir) / setup_skill_name + + if not template_dir.is_dir(): + print( + json.dumps({"status": "error", "message": f"Template not found: {template_dir}"}), + file=sys.stdout, + ) + return 2 + + for source_path in [args.module_yaml, args.module_csv]: + if not Path(source_path).is_file(): + print( + json.dumps({"status": "error", "message": f"Source file not found: {source_path}"}), + file=sys.stdout, + ) + return 2 + + target_dir = Path(args.target_dir) + if not target_dir.is_dir(): + print( + json.dumps({"status": "error", "message": f"Target directory not found: {target_dir}"}), + file=sys.stdout, + ) + return 2 + + # Remove existing setup skill if present (anti-zombie) + if target.exists(): + if args.verbose: + print(f"Removing existing {setup_skill_name}/", file=sys.stderr) + shutil.rmtree(target) + + # Copy template + if args.verbose: + print(f"Copying template to {target}", file=sys.stderr) + shutil.copytree(template_dir, target) + + # Update SKILL.md frontmatter placeholders + skill_md = target / "SKILL.md" + content = skill_md.read_text(encoding="utf-8") + content = content.replace("{setup-skill-name}", setup_skill_name) + content = content.replace("{module-name}", args.module_name) + content = content.replace("{module-code}", args.module_code) + skill_md.write_text(content, encoding="utf-8") + + # Write generated module.yaml + yaml_content = Path(args.module_yaml).read_text(encoding="utf-8") + (target / "assets" / "module.yaml").write_text(yaml_content, encoding="utf-8") + + # Write generated module-help.csv + csv_content = Path(args.module_csv).read_text(encoding="utf-8") + (target / "assets" / "module-help.csv").write_text(csv_content, encoding="utf-8") + + # Collect file list + files_created = sorted( + str(p.relative_to(target)) for p in target.rglob("*") if p.is_file() + ) + + result = { + "status": "success", + "setup_skill": setup_skill_name, + "location": str(target), + "files_created": files_created, + "files_count": len(files_created), + } + print(json.dumps(result, indent=2)) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/bmad-module-builder/scripts/tests/test-scaffold-setup-skill.py b/skills/bmad-module-builder/scripts/tests/test-scaffold-setup-skill.py new file mode 100644 index 0000000..577ac76 --- /dev/null +++ b/skills/bmad-module-builder/scripts/tests/test-scaffold-setup-skill.py @@ -0,0 +1,223 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.10" +# /// +"""Tests for scaffold-setup-skill.py""" + +import json +import subprocess +import sys +import tempfile +from pathlib import Path + +SCRIPT = Path(__file__).resolve().parent.parent / "scaffold-setup-skill.py" +TEMPLATE_DIR = Path(__file__).resolve().parent.parent.parent / "assets" / "setup-skill-template" + + +def run_scaffold(tmp: Path, **kwargs) -> tuple[int, dict]: + """Run the scaffold script and return (exit_code, parsed_json).""" + target_dir = kwargs.get("target_dir", str(tmp / "output")) + Path(target_dir).mkdir(parents=True, exist_ok=True) + + module_code = kwargs.get("module_code", "tst") + module_name = kwargs.get("module_name", "Test Module") + + yaml_path = tmp / "module.yaml" + csv_path = tmp / "module-help.csv" + yaml_path.write_text(kwargs.get("yaml_content", f'code: {module_code}\nname: "{module_name}"\n')) + csv_path.write_text( + kwargs.get( + "csv_content", + "module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs\n" + f'{module_name},bmad-{module_code}-example,Example,EX,An example skill,do-thing,,anytime,,,false,output_folder,artifact\n', + ) + ) + + cmd = [ + sys.executable, + str(SCRIPT), + "--target-dir", target_dir, + "--module-code", module_code, + "--module-name", module_name, + "--module-yaml", str(yaml_path), + "--module-csv", str(csv_path), + ] + result = subprocess.run(cmd, capture_output=True, text=True) + try: + data = json.loads(result.stdout) + except json.JSONDecodeError: + data = {"raw_stdout": result.stdout, "raw_stderr": result.stderr} + return result.returncode, data + + +def test_basic_scaffold(): + """Test that scaffolding creates the expected structure.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + target_dir = tmp / "output" + target_dir.mkdir() + + code, data = run_scaffold(tmp, target_dir=str(target_dir)) + assert code == 0, f"Script failed: {data}" + assert data["status"] == "success" + assert data["setup_skill"] == "bmad-tst-setup" + + setup_dir = target_dir / "bmad-tst-setup" + assert setup_dir.is_dir() + assert (setup_dir / "SKILL.md").is_file() + assert (setup_dir / "scripts" / "merge-config.py").is_file() + assert (setup_dir / "scripts" / "merge-help-csv.py").is_file() + assert (setup_dir / "scripts" / "cleanup-legacy.py").is_file() + assert (setup_dir / "assets" / "module.yaml").is_file() + assert (setup_dir / "assets" / "module-help.csv").is_file() + + +def test_skill_md_frontmatter_substitution(): + """Test that SKILL.md placeholders are replaced.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + target_dir = tmp / "output" + target_dir.mkdir() + + code, data = run_scaffold( + tmp, + target_dir=str(target_dir), + module_code="xyz", + module_name="XYZ Studio", + ) + assert code == 0 + + skill_md = (target_dir / "bmad-xyz-setup" / "SKILL.md").read_text() + assert "bmad-xyz-setup" in skill_md + assert "XYZ Studio" in skill_md + assert "{setup-skill-name}" not in skill_md + assert "{module-name}" not in skill_md + assert "{module-code}" not in skill_md + + +def test_generated_files_written(): + """Test that module.yaml and module-help.csv contain generated content.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + target_dir = tmp / "output" + target_dir.mkdir() + + custom_yaml = 'code: abc\nname: "ABC Module"\ndescription: "Custom desc"\n' + custom_csv = "module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs\nABC Module,bmad-abc-thing,Do Thing,DT,Does the thing,run,,anytime,,,false,output_folder,report\n" + + code, data = run_scaffold( + tmp, + target_dir=str(target_dir), + module_code="abc", + module_name="ABC Module", + yaml_content=custom_yaml, + csv_content=custom_csv, + ) + assert code == 0 + + yaml_content = (target_dir / "bmad-abc-setup" / "assets" / "module.yaml").read_text() + assert "ABC Module" in yaml_content + assert "Custom desc" in yaml_content + + csv_content = (target_dir / "bmad-abc-setup" / "assets" / "module-help.csv").read_text() + assert "bmad-abc-thing" in csv_content + assert "DT" in csv_content + + +def test_anti_zombie_replaces_existing(): + """Test that an existing setup skill is replaced cleanly.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + target_dir = tmp / "output" + target_dir.mkdir() + + # First scaffold + run_scaffold(tmp, target_dir=str(target_dir)) + stale_file = target_dir / "bmad-tst-setup" / "stale-marker.txt" + stale_file.write_text("should be removed") + + # Second scaffold should remove stale file + code, data = run_scaffold(tmp, target_dir=str(target_dir)) + assert code == 0 + assert not stale_file.exists() + + +def test_missing_target_dir(): + """Test error when target directory doesn't exist.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + nonexistent = tmp / "nonexistent" + + # Write valid source files + yaml_path = tmp / "module.yaml" + csv_path = tmp / "module-help.csv" + yaml_path.write_text('code: tst\nname: "Test"\n') + csv_path.write_text("header\n") + + cmd = [ + sys.executable, + str(SCRIPT), + "--target-dir", str(nonexistent), + "--module-code", "tst", + "--module-name", "Test", + "--module-yaml", str(yaml_path), + "--module-csv", str(csv_path), + ] + result = subprocess.run(cmd, capture_output=True, text=True) + assert result.returncode == 2 + data = json.loads(result.stdout) + assert data["status"] == "error" + + +def test_missing_source_file(): + """Test error when module.yaml source doesn't exist.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + target_dir = tmp / "output" + target_dir.mkdir() + + # Remove the yaml after creation to simulate missing file + yaml_path = tmp / "module.yaml" + csv_path = tmp / "module-help.csv" + csv_path.write_text("header\n") + # Don't create yaml_path + + cmd = [ + sys.executable, + str(SCRIPT), + "--target-dir", str(target_dir), + "--module-code", "tst", + "--module-name", "Test", + "--module-yaml", str(yaml_path), + "--module-csv", str(csv_path), + ] + result = subprocess.run(cmd, capture_output=True, text=True) + assert result.returncode == 2 + data = json.loads(result.stdout) + assert data["status"] == "error" + + +if __name__ == "__main__": + tests = [ + test_basic_scaffold, + test_skill_md_frontmatter_substitution, + test_generated_files_written, + test_anti_zombie_replaces_existing, + test_missing_target_dir, + test_missing_source_file, + ] + passed = 0 + failed = 0 + for test in tests: + try: + test() + print(f" PASS: {test.__name__}") + passed += 1 + except AssertionError as e: + print(f" FAIL: {test.__name__}: {e}") + failed += 1 + except Exception as e: + print(f" ERROR: {test.__name__}: {e}") + failed += 1 + print(f"\n{passed} passed, {failed} failed") + sys.exit(1 if failed else 0) diff --git a/skills/bmad-module-builder/scripts/tests/test-validate-module.py b/skills/bmad-module-builder/scripts/tests/test-validate-module.py new file mode 100644 index 0000000..3bf1f0e --- /dev/null +++ b/skills/bmad-module-builder/scripts/tests/test-validate-module.py @@ -0,0 +1,202 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.10" +# /// +"""Tests for validate-module.py""" + +import json +import subprocess +import sys +import tempfile +from pathlib import Path + +SCRIPT = Path(__file__).resolve().parent.parent / "validate-module.py" + +CSV_HEADER = "module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs\n" + + +def create_module(tmp: Path, skills: list[str] | None = None, csv_rows: str = "", + yaml_content: str = "", setup_name: str = "bmad-tst-setup") -> Path: + """Create a minimal module structure for testing.""" + module_dir = tmp / "module" + module_dir.mkdir() + + # Setup skill + setup = module_dir / setup_name + setup.mkdir() + (setup / "SKILL.md").write_text("---\nname: " + setup_name + "\n---\n# Setup\n") + (setup / "assets").mkdir() + (setup / "assets" / "module.yaml").write_text( + yaml_content or 'code: tst\nname: "Test Module"\ndescription: "A test module"\n' + ) + (setup / "assets" / "module-help.csv").write_text(CSV_HEADER + csv_rows) + + # Other skills + for skill in (skills or []): + skill_dir = module_dir / skill + skill_dir.mkdir() + (skill_dir / "SKILL.md").write_text(f"---\nname: {skill}\n---\n# {skill}\n") + + return module_dir + + +def run_validate(module_dir: Path) -> tuple[int, dict]: + """Run the validation script and return (exit_code, parsed_json).""" + result = subprocess.run( + [sys.executable, str(SCRIPT), str(module_dir)], + capture_output=True, text=True, + ) + try: + data = json.loads(result.stdout) + except json.JSONDecodeError: + data = {"raw_stdout": result.stdout, "raw_stderr": result.stderr} + return result.returncode, data + + +def test_valid_module(): + """A well-formed module should pass.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + csv_rows = 'Test Module,bmad-tst-foo,Do Foo,DF,Does the foo thing,run,,anytime,,,false,output_folder,report\n' + module_dir = create_module(tmp, skills=["bmad-tst-foo"], csv_rows=csv_rows) + + code, data = run_validate(module_dir) + assert code == 0, f"Expected pass: {data}" + assert data["status"] == "pass" + assert data["summary"]["total_findings"] == 0 + + +def test_missing_setup_skill(): + """Module with no setup skill should fail critically.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + module_dir = tmp / "module" + module_dir.mkdir() + skill = module_dir / "bmad-tst-foo" + skill.mkdir() + (skill / "SKILL.md").write_text("---\nname: bmad-tst-foo\n---\n") + + code, data = run_validate(module_dir) + assert code == 1 + assert any(f["category"] == "structure" for f in data["findings"]) + + +def test_missing_csv_entry(): + """Skill without a CSV entry should be flagged.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + module_dir = create_module(tmp, skills=["bmad-tst-foo", "bmad-tst-bar"], + csv_rows='Test Module,bmad-tst-foo,Do Foo,DF,Does foo,run,,anytime,,,false,output_folder,report\n') + + code, data = run_validate(module_dir) + assert code == 1 + missing = [f for f in data["findings"] if f["category"] == "missing-entry"] + assert len(missing) == 1 + assert "bmad-tst-bar" in missing[0]["message"] + + +def test_orphan_csv_entry(): + """CSV entry for nonexistent skill should be flagged.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + csv_rows = 'Test Module,bmad-tst-ghost,Ghost,GH,Does not exist,run,,anytime,,,false,output_folder,report\n' + module_dir = create_module(tmp, skills=[], csv_rows=csv_rows) + + code, data = run_validate(module_dir) + orphans = [f for f in data["findings"] if f["category"] == "orphan-entry"] + assert len(orphans) == 1 + assert "bmad-tst-ghost" in orphans[0]["message"] + + +def test_duplicate_menu_codes(): + """Duplicate menu codes should be flagged.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + csv_rows = ( + 'Test Module,bmad-tst-foo,Do Foo,DF,Does foo,run,,anytime,,,false,output_folder,report\n' + 'Test Module,bmad-tst-foo,Also Foo,DF,Also does foo,other,,anytime,,,false,output_folder,report\n' + ) + module_dir = create_module(tmp, skills=["bmad-tst-foo"], csv_rows=csv_rows) + + code, data = run_validate(module_dir) + dupes = [f for f in data["findings"] if f["category"] == "duplicate-menu-code"] + assert len(dupes) == 1 + assert "DF" in dupes[0]["message"] + + +def test_invalid_before_after_ref(): + """Before/after references to nonexistent capabilities should be flagged.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + csv_rows = 'Test Module,bmad-tst-foo,Do Foo,DF,Does foo,run,,anytime,bmad-tst-ghost:phantom,,false,output_folder,report\n' + module_dir = create_module(tmp, skills=["bmad-tst-foo"], csv_rows=csv_rows) + + code, data = run_validate(module_dir) + refs = [f for f in data["findings"] if f["category"] == "invalid-ref"] + assert len(refs) == 1 + assert "bmad-tst-ghost:phantom" in refs[0]["message"] + + +def test_missing_yaml_fields(): + """module.yaml with missing required fields should be flagged.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + csv_rows = 'Test Module,bmad-tst-foo,Do Foo,DF,Does foo,run,,anytime,,,false,output_folder,report\n' + module_dir = create_module(tmp, skills=["bmad-tst-foo"], csv_rows=csv_rows, + yaml_content='code: tst\n') + + code, data = run_validate(module_dir) + yaml_findings = [f for f in data["findings"] if f["category"] == "yaml"] + assert len(yaml_findings) >= 1 # at least name or description missing + + +def test_empty_csv(): + """CSV with header but no rows should be flagged.""" + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + module_dir = create_module(tmp, skills=["bmad-tst-foo"], csv_rows="") + + code, data = run_validate(module_dir) + assert code == 1 + empty = [f for f in data["findings"] if f["category"] == "csv-empty"] + assert len(empty) == 1 + + +def test_nonexistent_directory(): + """Nonexistent path should return error.""" + result = subprocess.run( + [sys.executable, str(SCRIPT), "/nonexistent/path"], + capture_output=True, text=True, + ) + assert result.returncode == 2 + data = json.loads(result.stdout) + assert data["status"] == "error" + + +if __name__ == "__main__": + tests = [ + test_valid_module, + test_missing_setup_skill, + test_missing_csv_entry, + test_orphan_csv_entry, + test_duplicate_menu_codes, + test_invalid_before_after_ref, + test_missing_yaml_fields, + test_empty_csv, + test_nonexistent_directory, + ] + passed = 0 + failed = 0 + for test in tests: + try: + test() + print(f" PASS: {test.__name__}") + passed += 1 + except AssertionError as e: + print(f" FAIL: {test.__name__}: {e}") + failed += 1 + except Exception as e: + print(f" ERROR: {test.__name__}: {e}") + failed += 1 + print(f"\n{passed} passed, {failed} failed") + sys.exit(1 if failed else 0) diff --git a/skills/bmad-module-builder/scripts/validate-module.py b/skills/bmad-module-builder/scripts/validate-module.py new file mode 100644 index 0000000..09da902 --- /dev/null +++ b/skills/bmad-module-builder/scripts/validate-module.py @@ -0,0 +1,242 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.10" +# /// +"""Validate a BMad module's setup skill structure and help CSV integrity. + +Performs deterministic structural checks: +- Setup skill exists with required files (SKILL.md, assets/module.yaml, assets/module-help.csv) +- All skill folders have at least one capability entry in the CSV +- No orphan CSV entries pointing to nonexistent skills +- Menu codes are unique +- Before/after references point to real capability entries +- Required module.yaml fields are present +- CSV column count is consistent +""" + +import argparse +import csv +import json +import sys +from io import StringIO +from pathlib import Path + +REQUIRED_YAML_FIELDS = {"code", "name", "description"} +CSV_HEADER = [ + "module", "skill", "display-name", "menu-code", "description", + "action", "args", "phase", "after", "before", "required", + "output-location", "outputs", +] + + +def find_setup_skill(module_dir: Path) -> Path | None: + """Find the setup skill folder (bmad-*-setup).""" + for d in module_dir.iterdir(): + if d.is_dir() and d.name.startswith("bmad-") and d.name.endswith("-setup"): + return d + return None + + +def find_skill_folders(module_dir: Path, setup_name: str) -> list[str]: + """Find all skill folders (directories with SKILL.md), excluding the setup skill.""" + skills = [] + for d in module_dir.iterdir(): + if d.is_dir() and d.name != setup_name and (d / "SKILL.md").is_file(): + skills.append(d.name) + return sorted(skills) + + +def parse_yaml_minimal(text: str) -> dict[str, str]: + """Parse top-level YAML key-value pairs (no nested structures).""" + result = {} + for line in text.splitlines(): + line = line.strip() + if ":" in line and not line.startswith("#") and not line.startswith("-"): + key, _, value = line.partition(":") + key = key.strip() + value = value.strip().strip('"').strip("'") + if value and not value.startswith(">"): + result[key] = value + return result + + +def parse_csv_rows(csv_text: str) -> tuple[list[str], list[dict[str, str]]]: + """Parse CSV text into header and list of row dicts.""" + reader = csv.DictReader(StringIO(csv_text)) + header = reader.fieldnames or [] + rows = list(reader) + return header, rows + + +def validate(module_dir: Path, verbose: bool = False) -> dict: + """Run all structural validations. Returns JSON-serializable result.""" + findings: list[dict] = [] + info: dict = {} + + def finding(severity: str, category: str, message: str, detail: str = ""): + findings.append({ + "severity": severity, + "category": category, + "message": message, + "detail": detail, + }) + + # 1. Find setup skill + setup_dir = find_setup_skill(module_dir) + if not setup_dir: + finding("critical", "structure", "No setup skill found (bmad-*-setup directory)") + return {"status": "fail", "findings": findings, "info": info} + + info["setup_skill"] = setup_dir.name + + # 2. Check required files in setup skill + required_files = { + "SKILL.md": setup_dir / "SKILL.md", + "assets/module.yaml": setup_dir / "assets" / "module.yaml", + "assets/module-help.csv": setup_dir / "assets" / "module-help.csv", + } + for label, path in required_files.items(): + if not path.is_file(): + finding("critical", "structure", f"Missing required file: {label}") + + if not all(p.is_file() for p in required_files.values()): + return {"status": "fail", "findings": findings, "info": info} + + # 3. Validate module.yaml + yaml_text = (setup_dir / "assets" / "module.yaml").read_text(encoding="utf-8") + yaml_data = parse_yaml_minimal(yaml_text) + info["module_code"] = yaml_data.get("code", "") + info["module_name"] = yaml_data.get("name", "") + + for field in REQUIRED_YAML_FIELDS: + if not yaml_data.get(field): + finding("high", "yaml", f"module.yaml missing or empty required field: {field}") + + # 4. Parse and validate CSV + csv_text = (setup_dir / "assets" / "module-help.csv").read_text(encoding="utf-8") + header, rows = parse_csv_rows(csv_text) + + # Check header + if header != CSV_HEADER: + missing = set(CSV_HEADER) - set(header) + extra = set(header) - set(CSV_HEADER) + detail_parts = [] + if missing: + detail_parts.append(f"missing: {', '.join(sorted(missing))}") + if extra: + detail_parts.append(f"extra: {', '.join(sorted(extra))}") + finding("high", "csv-header", f"CSV header mismatch: {'; '.join(detail_parts)}") + + if not rows: + finding("high", "csv-empty", "module-help.csv has no capability entries") + return {"status": "fail", "findings": findings, "info": info} + + info["csv_entries"] = len(rows) + + # 5. Check column count consistency + expected_cols = len(CSV_HEADER) + for i, row in enumerate(rows): + if len(row) != expected_cols: + finding("medium", "csv-columns", f"Row {i + 2} has {len(row)} columns, expected {expected_cols}", + f"skill={row.get('skill', '?')}") + + # 6. Collect skills from CSV and filesystem + csv_skills = {row.get("skill", "") for row in rows} + skill_folders = find_skill_folders(module_dir, setup_dir.name) + info["skill_folders"] = skill_folders + info["csv_skills"] = sorted(csv_skills) + + # 7. Skills without CSV entries + for skill in skill_folders: + if skill not in csv_skills: + finding("high", "missing-entry", f"Skill '{skill}' has no capability entries in the CSV") + + # 8. Orphan CSV entries + for skill in csv_skills: + if skill not in skill_folders and skill != setup_dir.name: + # Check if it's the setup skill itself (valid) + if not (module_dir / skill / "SKILL.md").is_file(): + finding("high", "orphan-entry", f"CSV references skill '{skill}' which does not exist in the module folder") + + # 9. Unique menu codes + menu_codes: dict[str, list[str]] = {} + for row in rows: + code = row.get("menu-code", "").strip() + if code: + menu_codes.setdefault(code, []).append(row.get("display-name", "?")) + + for code, names in menu_codes.items(): + if len(names) > 1: + finding("high", "duplicate-menu-code", f"Menu code '{code}' used by multiple entries: {', '.join(names)}") + + # 10. Before/after reference validation + # Build set of valid capability references (skill:action) + valid_refs = set() + for row in rows: + skill = row.get("skill", "").strip() + action = row.get("action", "").strip() + if skill and action: + valid_refs.add(f"{skill}:{action}") + + for row in rows: + display = row.get("display-name", "?") + for field in ("after", "before"): + value = row.get(field, "").strip() + if not value: + continue + # Can be comma-separated + for ref in value.split(","): + ref = ref.strip() + if ref and ref not in valid_refs: + finding("medium", "invalid-ref", + f"'{display}' {field} references '{ref}' which is not a valid capability", + "Expected format: skill-name:action-name") + + # 11. Required fields in each row + for row in rows: + display = row.get("display-name", "?") + for field in ("skill", "display-name", "menu-code", "description"): + if not row.get(field, "").strip(): + finding("high", "missing-field", f"Entry '{display}' is missing required field: {field}") + + # Summary + severity_counts = {"critical": 0, "high": 0, "medium": 0, "low": 0} + for f in findings: + severity_counts[f["severity"]] = severity_counts.get(f["severity"], 0) + 1 + + status = "pass" if severity_counts["critical"] == 0 and severity_counts["high"] == 0 else "fail" + + return { + "status": status, + "info": info, + "findings": findings, + "summary": { + "total_findings": len(findings), + "by_severity": severity_counts, + }, + } + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Validate a BMad module's setup skill structure and help CSV integrity" + ) + parser.add_argument( + "module_dir", + help="Path to the module's skills folder (containing the setup skill and other skills)", + ) + parser.add_argument("--verbose", action="store_true", help="Print progress to stderr") + args = parser.parse_args() + + module_path = Path(args.module_dir) + if not module_path.is_dir(): + print(json.dumps({"status": "error", "message": f"Not a directory: {module_path}"})) + return 2 + + result = validate(module_path, verbose=args.verbose) + print(json.dumps(result, indent=2)) + return 0 if result["status"] == "pass" else 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/module-help.csv b/skills/module-help.csv index aa6f460..9687012 100644 --- a/skills/module-help.csv +++ b/skills/module-help.csv @@ -3,4 +3,7 @@ BMad Builder,bmad-builder-setup,Setup Builder Module,SB,"Install or update BMad BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, convert, or fix an agent skill.",build-process,"[-H] [description | path]",anytime,,bmad-agent-builder:quality-optimizer,false,output_folder,agent skill BMad Builder,bmad-agent-builder,Optimize an Agent,OA,Validate and optimize an existing agent skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, convert, or fix a workflow or utility skill.",build-process,"[-H] [description | path]",anytime,,bmad-workflow-builder:quality-optimizer,false,output_folder,workflow skill -BMad Builder,bmad-workflow-builder,Optimize a Workflow,OW,Validate and optimize an existing workflow or utility skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report \ No newline at end of file +BMad Builder,bmad-workflow-builder,Optimize a Workflow,OW,Validate and optimize an existing workflow or utility skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report +BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,,anytime,,bmad-module-builder:create-module,false,bmad_builder_reports,module plan +BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold a setup skill into an existing folder of built skills, making it an installable BMad module.",create-module,"[-H] [path]",anytime,bmad-module-builder:ideate-module,,false,bmad_builder_output_folder,setup skill +BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's setup skill is complete, accurate, and all capabilities are properly registered.",validate-module,[path],anytime,bmad-module-builder:create-module,,false,bmad_builder_reports,validation report \ No newline at end of file From f11ef0e5de2b873613ddee0045a4dc3f8339b8a5 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 29 Mar 2026 01:44:55 -0500 Subject: [PATCH 2/3] style: apply prettier formatting to all changed files --- docs/explanation/index.md | 32 +-- docs/explanation/module-configuration.md | 62 ++--- docs/explanation/what-are-modules.md | 60 ++--- docs/reference/builder-commands.md | 220 +++++++++--------- docs/tutorials/build-your-first-module.md | 63 ++--- docs/tutorials/index.md | 4 +- .../assets/module-plan-template.md | 25 +- .../assets/setup-skill-template/SKILL.md | 4 +- .../references/create-module.md | 43 ++-- .../references/ideate-module.md | 14 +- .../references/validate-module.md | 1 + 11 files changed, 272 insertions(+), 256 deletions(-) diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 0bddb26..88e1719 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -1,5 +1,5 @@ --- -title: "BMad Builder (BMB)" +title: 'BMad Builder (BMB)' description: Create custom agents, workflows, and skills with BMad --- @@ -7,26 +7,26 @@ Create world-class AI agents and workflows with the BMad Builder. ## Core Concepts -| Topic | Description | -|-------|-------------| -| **[What Are Skills](/explanation/what-are-skills.md)** | The universal building block for everything BMad produces | -| **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities and memory | -| **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes and utilities | -| **[What Are Modules](/explanation/what-are-modules.md)** | How agents and workflows combine into installable, configurable modules | +| Topic | Description | +| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| **[What Are Skills](/explanation/what-are-skills.md)** | The universal building block for everything BMad produces | +| **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities and memory | +| **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes and utilities | +| **[What Are Modules](/explanation/what-are-modules.md)** | How agents and workflows combine into installable, configurable modules | | **[Module Configuration](/explanation/module-configuration.md)** | How modules handle user configuration and help registration through a setup skill | ## Design Patterns -| Topic | Description | -|-------|-------------| -| **[Progressive Disclosure](/explanation/progressive-disclosure.md)** | Four layers of context loading — from frontmatter through step files | -| **[Subagent Patterns](/explanation/subagent-patterns.md)** | Six orchestration patterns for parallel and hierarchical work | -| **[Skill Authoring Best Practices](/explanation/skill-authoring-best-practices.md)** | Core principles, common patterns, quality dimensions, and anti-patterns | -| **[Scripts in Skills](/explanation/scripts-in-skills.md)** | Why deterministic scripts make skills faster, cheaper, and more reliable | +| Topic | Description | +| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | +| **[Progressive Disclosure](/explanation/progressive-disclosure.md)** | Four layers of context loading — from frontmatter through step files | +| **[Subagent Patterns](/explanation/subagent-patterns.md)** | Six orchestration patterns for parallel and hierarchical work | +| **[Skill Authoring Best Practices](/explanation/skill-authoring-best-practices.md)** | Core principles, common patterns, quality dimensions, and anti-patterns | +| **[Scripts in Skills](/explanation/scripts-in-skills.md)** | Why deterministic scripts make skills faster, cheaper, and more reliable | ## Reference -| Resource | Description | -|----------|-------------| -| **[Builder Commands](/reference/builder-commands.md)** | All capabilities, modes, and phases for both builders | +| Resource | Description | +| -------------------------------------------------------- | ----------------------------------------------------- | +| **[Builder Commands](/reference/builder-commands.md)** | All capabilities, modes, and phases for both builders | | **[Workflow Patterns](/reference/workflow-patterns.md)** | Skill types, structure patterns, and execution models | diff --git a/docs/explanation/module-configuration.md b/docs/explanation/module-configuration.md index 698c00c..0d36c25 100644 --- a/docs/explanation/module-configuration.md +++ b/docs/explanation/module-configuration.md @@ -1,5 +1,5 @@ --- -title: "Module Configuration and the Setup Skill" +title: 'Module Configuration and the Setup Skill' description: How BMad modules handle user configuration through a setup skill, when to use configuration vs. alternatives, and how to register with the help system --- @@ -9,11 +9,11 @@ Every BMad module can include a **setup skill** that collects user preferences a Most modules should not need configuration at all. Before adding configurable values, consider whether a simpler alternative exists. -| Approach | When to Use | -| -------- | ----------- | +| Approach | When to Use | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sensible defaults** | The variable has one clearly correct answer for most users that could be overridden or updated by the specific skill that needs it the first time it runs | -| **Agent memory** | Your module follows the agent pattern and the agent can learn preferences through conversation | -| **Configuration** | The value genuinely varies across projects and cannot be inferred at runtime | +| **Agent memory** | Your module follows the agent pattern and the agent can learn preferences through conversation | +| **Configuration** | The value genuinely varies across projects and cannot be inferred at runtime | :::tip[Standalone Skills and Agents] If you are building a standalone agent or skill — not a multi-capability module — the setup skill overhead is not worth it. A concise overview section at the top of your SKILL.md body, clear comments in script headers, and `--help` flags on any CLI tools give users everything they need to discover and use the skill. @@ -23,20 +23,20 @@ If you are building a standalone agent or skill — not a multi-capability modul A setup skill serves two purposes: -| Purpose | What Happens | -| ------- | ------------ | -| **Configuration** | Collects user preferences and writes them to shared config files | +| Purpose | What Happens | +| --------------------- | ----------------------------------------------------------------------------------------- | +| **Configuration** | Collects user preferences and writes them to shared config files | | **Help registration** | Adds the module's capabilities to the project-wide help system so users can discover them | ## Configuration Files Setup skills write to three files in `{project-root}/_bmad/`: -| File | Scope | Contains | -| ---- | ----- | -------- | -| `config.yaml` | Shared, committed to git | Core settings at root level, plus a section per module with metadata and module-specific values | -| `config.user.yaml` | Personal, gitignored | User-only settings like `user_name` and `communication_language` | -| `module-help.csv` | Shared, committed to git | One row per capability the module exposes | +| File | Scope | Contains | +| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------- | +| `config.yaml` | Shared, committed to git | Core settings at root level, plus a section per module with metadata and module-specific values | +| `config.user.yaml` | Personal, gitignored | User-only settings like `user_name` and `communication_language` | +| `module-help.csv` | Shared, committed to git | One row per capability the module exposes | Core settings (like `output_folder` and `document_output_language`) live at the root of `config.yaml` and are shared across all modules. Each module also gets its own section keyed by its module code. @@ -46,17 +46,17 @@ Each module declares its identity and configurable variables in an `assets/modul ```yaml code: mymod -name: "My Module" -description: "What this module does" +name: 'My Module' +description: 'What this module does' module_version: 1.0.0 default_selected: false module_greeting: > Welcome message shown after setup completes. my_output_folder: - prompt: "Where should output be saved?" - default: "{project-root}/_bmad-output/my-module" - result: "{project-root}/{value}" + prompt: 'Where should output be saved?' + default: '{project-root}/_bmad-output/my-module' + result: '{project-root}/{value}' ``` Variables with a `prompt` field are presented to the user during setup. The `default` value is used when the user accepts defaults. Adding `user_setting: true` to a variable routes it to `config.user.yaml` instead of the shared config. @@ -76,10 +76,10 @@ You may not need any configurable values but still want to register your module For simpler cases, these alternatives are often sufficient: -| Alternative | What It Provides | -| ----------- | ---------------- | +| Alternative | What It Provides | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **SKILL.md overview section** | A concise summary at the top of the skill body — the `--help` system scans this section to present user-facing help, so keep it succinct | -| **Script header comments** | Describe purpose, usage, and flags at the top of each script | +| **Script header comments** | Describe purpose, usage, and flags at the top of each script | If these cover your discoverability needs, you can skip the setup skill entirely. @@ -108,11 +108,11 @@ Before removing any directory, the cleanup script verifies that every skill it c Configuration is for **basic, project-level settings** — output folders, language preferences, feature toggles. Keep the number of configurable values small. -| Pattern | Configuration Role | -| ------- | ------------------ | -| **Agent pattern** | Prefer agent memory for per-user preferences. Use config only for values that must be shared across the project | -| **Workflow pattern** | Use config for output locations and behavior switches that vary across projects | -| **Skill-only pattern** | Use config sparingly. If the skill works with sensible defaults, skip config entirely | +| Pattern | Configuration Role | +| ---------------------- | --------------------------------------------------------------------------------------------------------------- | +| **Agent pattern** | Prefer agent memory for per-user preferences. Use config only for values that must be shared across the project | +| **Workflow pattern** | Use config for output locations and behavior switches that vary across projects | +| **Skill-only pattern** | Use config sparingly. If the skill works with sensible defaults, skip config entirely | Extensive workflow customization — step overrides, conditional branching, template selection — is a separate concern and will be covered in a dedicated document. @@ -120,11 +120,11 @@ Extensive workflow customization — step overrides, conditional branching, temp The **Module Builder** (`bmad-module-builder`) automates module creation. It offers three capabilities: -| Capability | Menu Code | What It Does | -| ---------- | --------- | ------------ | -| **Ideate Module** | IM | Brainstorm and plan a module through facilitative discovery — produces a plan document | -| **Create Module** | CM | Scaffold a setup skill into an existing folder of built skills | -| **Validate Module** | VM | Check that a module's setup skill is complete, accurate, and properly registered | +| Capability | Menu Code | What It Does | +| ------------------- | --------- | -------------------------------------------------------------------------------------- | +| **Ideate Module** | IM | Brainstorm and plan a module through facilitative discovery — produces a plan document | +| **Create Module** | CM | Scaffold a setup skill into an existing folder of built skills | +| **Validate Module** | VM | Check that a module's setup skill is complete, accurate, and properly registered | **Typical workflow:** diff --git a/docs/explanation/what-are-modules.md b/docs/explanation/what-are-modules.md index 9d0c717..2508a43 100644 --- a/docs/explanation/what-are-modules.md +++ b/docs/explanation/what-are-modules.md @@ -1,5 +1,5 @@ --- -title: "What Are BMad Modules?" +title: 'What Are BMad Modules?' description: How agents and workflows combine into installable, configurable modules within the BMad ecosystem --- @@ -9,12 +9,12 @@ BMad modules package related agents and workflows into a cohesive, installable u A module is a folder of skills — agents and/or workflows — plus a **setup skill** that handles installation and configuration. -| Component | Purpose | -| --------- | ------- | -| **Skills** | The agents and workflows that deliver the module's capabilities | -| **Setup skill** | Collects user preferences, writes config, registers capabilities with the help system | -| **module.yaml** | Declares module identity and configurable variables | -| **module-help.csv** | Lists every capability users can discover and invoke | +| Component | Purpose | +| ------------------- | ------------------------------------------------------------------------------------- | +| **Skills** | The agents and workflows that deliver the module's capabilities | +| **Setup skill** | Collects user preferences, writes config, registers capabilities with the help system | +| **module.yaml** | Declares module identity and configurable variables | +| **module-help.csv** | Lists every capability users can discover and invoke | The setup skill is the only required infrastructure. Everything else is just well-built skills that happen to work together. @@ -22,11 +22,11 @@ The setup skill is the only required infrastructure. Everything else is just wel The first architecture decision when planning a module is whether to use a single agent, multiple workflows, or a combination. -| Architecture | When It Fits | Trade-offs | -| ------------ | ------------ | ---------- | +| Architecture | When It Fits | Trade-offs | +| ---------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Single agent with capabilities** | All capabilities serve the same user journey and benefit from shared context | Simpler to maintain, better memory continuity, seamless UX. Can feel monolithic if capabilities are unrelated | -| **Multiple workflows** | Capabilities serve different user journeys or require different tools | Each workflow is focused and composable. Users switch between skills explicitly | -| **Hybrid** | Some capabilities need persistent persona/memory while others are procedural | Best of both worlds but more skills to build and maintain | +| **Multiple workflows** | Capabilities serve different user journeys or require different tools | Each workflow is focused and composable. Users switch between skills explicitly | +| **Hybrid** | Some capabilities need persistent persona/memory while others are procedural | Best of both worlds but more skills to build and maintain | :::tip[Agent-First Thinking] Many users default to building multiple single-purpose agents. Consider whether one agent with rich internal capabilities and routing would serve users better. A single agent accumulates context, maintains memory across interactions, and provides a more seamless experience. @@ -36,11 +36,11 @@ Many users default to building multiple single-purpose agents. Consider whether Modules with multiple agents introduce a memory architecture decision. Every BMad agent has its own **sidecar memory** — a personal folder where it stores user preferences, learned patterns, session history, and domain-specific data. In a multi-agent module, you also need to decide whether agents should share memory. -| Pattern | When It Fits | -| ------- | ------------ | -| **Personal sidecars only** | Agents have distinct domains with minimal overlap | -| **Personal + shared module sidecar** | Agents have their own context but also learn shared things about the user or project | -| **Shared sidecar only** | All agents serve the same domain — consider whether a single agent is the better design | +| Pattern | When It Fits | +| ------------------------------------ | --------------------------------------------------------------------------------------- | +| **Personal sidecars only** | Agents have distinct domains with minimal overlap | +| **Personal + shared module sidecar** | Agents have their own context but also learn shared things about the user or project | +| **Shared sidecar only** | All agents serve the same domain — consider whether a single agent is the better design | **Example:** A social creative module with a podcast expert, a viral video expert, and a blog expert. Each agent remembers the specifics of what it has done with the user — episode topics, video formats, blog themes. But they all also learn about the user's communication style, favorite catchphrases, content preferences, and brand voice. This shared knowledge lives in a module-level sidecar that every agent reads from and contributes to. @@ -50,10 +50,10 @@ See **[What Are BMad Agents](/explanation/what-are-bmad-agents.md)** for details ## Standalone vs. Expansion Modules -| Type | Description | -| ---- | ----------- | -| **Standalone** | Provides complete, independent value. Does not depend on another module being installed | -| **Expansion** | Extends an existing module with new capabilities. Should still provide utility even if the parent module is not installed | +| Type | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------- | +| **Standalone** | Provides complete, independent value. Does not depend on another module being installed | +| **Expansion** | Extends an existing module with new capabilities. Should still provide utility even if the parent module is not installed | Expansion modules can reference the parent module's capabilities in their help CSV ordering (before/after fields). This lets a new capability slot into the parent module's natural workflow sequence. @@ -63,11 +63,11 @@ Even expansion modules should be designed to work independently — the parent m Modules register with a project through three files in `{project-root}/_bmad/`: -| File | Purpose | -| ---- | ------- | -| `config.yaml` | Shared settings committed to git — module section keyed by module code | -| `config.user.yaml` | Personal settings (gitignored) — user name, language preferences | -| `module-help.csv` | Capability registry — one row per action users can discover | +| File | Purpose | +| ------------------ | ---------------------------------------------------------------------- | +| `config.yaml` | Shared settings committed to git — module section keyed by module code | +| `config.user.yaml` | Personal settings (gitignored) — user name, language preferences | +| `module-help.csv` | Capability registry — one row per action users can discover | Not every module needs configuration. If skills work with sensible defaults, the setup skill can focus purely on help registration. See **[Module Configuration](/explanation/module-configuration.md)** for details on when configuration adds value. @@ -75,11 +75,11 @@ Not every module needs configuration. If skills work with sensible defaults, the Some modules depend on tools outside the BMad ecosystem. -| Dependency Type | Examples | -| --------------- | -------- | -| **CLI tools** | `docker`, `terraform`, `ffmpeg` | -| **MCP servers** | Custom or third-party Model Context Protocol servers | -| **Web services** | APIs that require credentials or configuration | +| Dependency Type | Examples | +| ---------------- | ---------------------------------------------------- | +| **CLI tools** | `docker`, `terraform`, `ffmpeg` | +| **MCP servers** | Custom or third-party Model Context Protocol servers | +| **Web services** | APIs that require credentials or configuration | When a module has external dependencies, the setup skill should check for their presence and guide users through installation or configuration. diff --git a/docs/reference/builder-commands.md b/docs/reference/builder-commands.md index 3811f02..6889271 100644 --- a/docs/reference/builder-commands.md +++ b/docs/reference/builder-commands.md @@ -1,5 +1,5 @@ --- -title: "Builder Commands Reference" +title: 'Builder Commands Reference' description: Complete reference for all capabilities, modes, and paths available in the Agent Builder, Workflow Builder, and Module Builder --- @@ -7,10 +7,10 @@ Reference for the three core BMad Builder skills — the Agent Builder (`bmad-ag ## Capabilities Overview -| Capability | Menu Code | Agent Builder | Workflow Builder | -| ---------- | --------- | ------------- | ---------------- | -| **Build Process** | BP | Build, edit, convert, or fix agents | Build, edit, convert, or fix workflows and utilities | -| **Quality Optimize** | QO | Validate and optimize existing agents | Validate and optimize existing workflows and utilities | +| Capability | Menu Code | Agent Builder | Workflow Builder | +| -------------------- | --------- | ------------------------------------- | ------------------------------------------------------ | +| **Build Process** | BP | Build, edit, convert, or fix agents | Build, edit, convert, or fix workflows and utilities | +| **Quality Optimize** | QO | Validate and optimize existing agents | Validate and optimize existing workflows and utilities | Both capabilities support autonomous/headless mode via `--headless` / `-H` flags. @@ -22,73 +22,73 @@ The core creative path. Six phases of conversational discovery take you from a r Both builders accept any of these as a starting point. -| Input | What Happens | -| ----- | ------------ | -| A rough idea or description | Guided discovery from scratch | -| An existing BMad skill path | Edit mode — analyze what exists, determine what to change | -| A non-BMad skill, tool, or code | Convert to BMad-compliant structure | -| Documentation, API specs, or code | Extract intent and requirements automatically | +| Input | What Happens | +| --------------------------------- | --------------------------------------------------------- | +| A rough idea or description | Guided discovery from scratch | +| An existing BMad skill path | Edit mode — analyze what exists, determine what to change | +| A non-BMad skill, tool, or code | Convert to BMad-compliant structure | +| Documentation, API specs, or code | Extract intent and requirements automatically | ### Interaction Modes -| Mode | Behavior | Best For | -| ---- | -------- | -------- | -| **Guided** | The builder walks through decisions, clarifies ambiguities, ensures completeness | Production skills, first-time builders | -| **YOLO** | Brain-dump your idea; the builder guesses its way to a finished skill with minimal questions | Quick prototypes, experienced builders | -| **Autonomous** | Fully headless — no interactive prompts, proceeds with safe defaults | CI/CD, batch processing, orchestrated builds | +| Mode | Behavior | Best For | +| -------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------- | +| **Guided** | The builder walks through decisions, clarifies ambiguities, ensures completeness | Production skills, first-time builders | +| **YOLO** | Brain-dump your idea; the builder guesses its way to a finished skill with minimal questions | Quick prototypes, experienced builders | +| **Autonomous** | Fully headless — no interactive prompts, proceeds with safe defaults | CI/CD, batch processing, orchestrated builds | ### Build Phases -| Phase | Agent Builder | Workflow Builder | -| ----- | ------------- | ---------------- | -| 1 | **Discover Intent** — understand the vision | **Discover Intent** — understand the vision; accepts any input format | -| 2 | **Capabilities Strategy** — internal commands, external skills, or both; script opportunities | **Classify Skill Type** — Simple Utility, Simple Workflow, or Complex Workflow; module membership | -| 3 | **Gather Requirements** — name, persona, memory, capabilities, autonomous modes, folder dominion | **Gather Requirements** — name, description, stages, config variables, output artifacts, dependencies | -| 4 | **Draft & Refine** — present outline, iterate until ready | **Draft & Refine** — present plan, clarify gaps, iterate until ready | -| 5 | **Build** — generate skill structure, lint gate | **Build** — generate skill structure, lint gate | -| 6 | **Summary** — present results, offer Quality Optimize | **Summary** — present results, run unit tests if scripts exist, offer Quality Optimize | +| Phase | Agent Builder | Workflow Builder | +| ----- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | +| 1 | **Discover Intent** — understand the vision | **Discover Intent** — understand the vision; accepts any input format | +| 2 | **Capabilities Strategy** — internal commands, external skills, or both; script opportunities | **Classify Skill Type** — Simple Utility, Simple Workflow, or Complex Workflow; module membership | +| 3 | **Gather Requirements** — name, persona, memory, capabilities, autonomous modes, folder dominion | **Gather Requirements** — name, description, stages, config variables, output artifacts, dependencies | +| 4 | **Draft & Refine** — present outline, iterate until ready | **Draft & Refine** — present plan, clarify gaps, iterate until ready | +| 5 | **Build** — generate skill structure, lint gate | **Build** — generate skill structure, lint gate | +| 6 | **Summary** — present results, offer Quality Optimize | **Summary** — present results, run unit tests if scripts exist, offer Quality Optimize | ### Agent Builder: Phase 2-3 Details **Capabilities strategy** determines the mix of internal and external capabilities. -| Capability Type | Description | -| --------------- | ----------- | -| **Internal commands** | Prompt-driven actions defined inside the agent, each gets a file in `prompts/` | -| **External skills** | Standalone skills the agent invokes by registered name | -| **Scripts** | Deterministic operations offloaded from the LLM (validation, data processing, file ops) | +| Capability Type | Description | +| --------------------- | --------------------------------------------------------------------------------------- | +| **Internal commands** | Prompt-driven actions defined inside the agent, each gets a file in `prompts/` | +| **External skills** | Standalone skills the agent invokes by registered name | +| **Scripts** | Deterministic operations offloaded from the LLM (validation, data processing, file ops) | **Agent-specific requirements** gathered in Phase 3: -| Requirement | Description | -| ----------- | ----------- | -| **Identity** | Who is this agent? Communication style, decision-making philosophy | -| **Memory & persistence** | Sidecar needed? Critical data vs checkpoint data, save triggers | -| **Activation modes** | Interactive only, or interactive + autonomous (schedule/cron) | -| **First-run onboarding** | What to ask on first activation to configure itself | -| **Folder dominion** | Read boundaries, write boundaries, explicit deny zones | -| **Autonomous tasks** | Default wake behavior, named tasks via `--headless {task-name}` or `-H {task-name}` | +| Requirement | Description | +| ------------------------ | ----------------------------------------------------------------------------------- | +| **Identity** | Who is this agent? Communication style, decision-making philosophy | +| **Memory & persistence** | Sidecar needed? Critical data vs checkpoint data, save triggers | +| **Activation modes** | Interactive only, or interactive + autonomous (schedule/cron) | +| **First-run onboarding** | What to ask on first activation to configure itself | +| **Folder dominion** | Read boundaries, write boundaries, explicit deny zones | +| **Autonomous tasks** | Default wake behavior, named tasks via `--headless {task-name}` or `-H {task-name}` | ### Workflow Builder: Phase 2-3 Details **Skill type classification** determines template and structure. -| Type | Signals | Structure | -| ---- | ------- | --------- | -| **Simple Utility** | Composable building block, clear input/output, usually mostly script-driven | Single SKILL.md, scripts folder | -| **Simple Workflow** | Fits in one SKILL.md, a few sequential steps, optional autonomous | SKILL.md with inline steps, optional prompts and resources | +| Type | Signals | Structure | +| -------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| **Simple Utility** | Composable building block, clear input/output, usually mostly script-driven | Single SKILL.md, scripts folder | +| **Simple Workflow** | Fits in one SKILL.md, a few sequential steps, optional autonomous | SKILL.md with inline steps, optional prompts and resources | | **Complex Workflow** | Multiple stages, branching prompt flows, progressive disclosure, long-running | SKILL.md for routing, `prompts/` for stage details, `resources/` for reference data | **Workflow-specific requirements** gathered in Phase 3: -| Requirement | Simple Utility | Simple Workflow | Complex Workflow | -| ----------- | -------------- | --------------- | ---------------- | -| **Input/output format** | Yes | — | — | -| **Composability** | Yes | — | — | -| **Steps** | — | Numbered steps | Named stages with progression conditions | -| **Headless mode** | — | Optional | Optional | -| **Config variables** | — | Core + custom | Core + module-specific | -| **Module sequencing** | Optional | Optional | Recommended | +| Requirement | Simple Utility | Simple Workflow | Complex Workflow | +| ----------------------- | -------------- | --------------- | ---------------------------------------- | +| **Input/output format** | Yes | — | — | +| **Composability** | Yes | — | — | +| **Steps** | — | Numbered steps | Named stages with progression conditions | +| **Headless mode** | — | Optional | Optional | +| **Config variables** | — | Core + custom | Core + module-specific | +| **Module sequencing** | Optional | Optional | Recommended | ### Build Output @@ -109,10 +109,10 @@ Both builders produce the same folder structure, with components included only a Before completing the build, both builders run deterministic validation. -| Script | What It Checks | -| ------ | -------------- | +| Script | What It Checks | +| ------------------------ | ----------------------------------------------------------------------------------------- | | `scan-path-standards.py` | Path conventions — no `{skill-root}`, `{project-root}` only for `_bmad`, no double-prefix | -| `scan-scripts.py` | Script portability, PEP 723 metadata, agentic design, unit test presence | +| `scan-scripts.py` | Script portability, PEP 723 metadata, agentic design, unit test presence | Critical issues block completion. Warnings are noted but don't block. @@ -123,6 +123,7 @@ Comprehensive validation and optimization for existing skills. Runs deterministi ### Pre-Scan Checks In interactive mode, the optimizer: + 1. Checks for uncommitted changes and recommends committing first 2. Asks if the skill is currently working as expected @@ -134,34 +135,35 @@ The optimizer runs three tiers of analysis. **Tier 1 — Lint scripts** (deterministic, zero tokens, instant): -| Script | Focus | -| ------ | ----- | -| `scan-path-standards.py` | Path convention violations | -| `scan-scripts.py` | Script portability and standards | +| Script | Focus | +| ------------------------ | -------------------------------- | +| `scan-path-standards.py` | Path convention violations | +| `scan-scripts.py` | Script portability and standards | **Tier 2 — Pre-pass scripts** (extract metrics for LLM scanners): -| Script | Agent Builder | Workflow Builder | -| ------ | ------------- | ---------------- | -| Structure/integrity pre-pass | `prepass-structure-capabilities.py` | `prepass-workflow-integrity.py` | -| Prompt metrics pre-pass | `prepass-prompt-metrics.py` | `prepass-prompt-metrics.py` | -| Execution dependency pre-pass | `prepass-execution-deps.py` | `prepass-execution-deps.py` | +| Script | Agent Builder | Workflow Builder | +| ----------------------------- | ----------------------------------- | ------------------------------- | +| Structure/integrity pre-pass | `prepass-structure-capabilities.py` | `prepass-workflow-integrity.py` | +| Prompt metrics pre-pass | `prepass-prompt-metrics.py` | `prepass-prompt-metrics.py` | +| Execution dependency pre-pass | `prepass-execution-deps.py` | `prepass-execution-deps.py` | **Tier 3 — LLM scanners** (judgment-based, run as parallel subagents): -| Scanner | Agent Builder Focus | Workflow Builder Focus | -| ------- | ------------------- | ---------------------- | -| **Structure / Integrity** | Structure, capabilities, identity, memory setup, consistency | Logical consistency, description quality, progression conditions, type-appropriate structure | -| **Prompt Craft** | Token efficiency, anti-patterns, persona voice, overview quality | Token efficiency, anti-patterns, overview quality, progressive disclosure | -| **Execution Efficiency** | Parallelization, subagent delegation, memory loading, context optimization | Parallelization, subagent delegation, read avoidance, context optimization | -| **Cohesion** | Persona-capability alignment, gaps, redundancies | Stage flow coherence, purpose alignment, complexity appropriateness | -| **Enhancement Opportunities** | Script automation, autonomous potential, edge cases, delight | Creative edge-case discovery, experience gaps, assumption auditing | +| Scanner | Agent Builder Focus | Workflow Builder Focus | +| ----------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| **Structure / Integrity** | Structure, capabilities, identity, memory setup, consistency | Logical consistency, description quality, progression conditions, type-appropriate structure | +| **Prompt Craft** | Token efficiency, anti-patterns, persona voice, overview quality | Token efficiency, anti-patterns, overview quality, progressive disclosure | +| **Execution Efficiency** | Parallelization, subagent delegation, memory loading, context optimization | Parallelization, subagent delegation, read avoidance, context optimization | +| **Cohesion** | Persona-capability alignment, gaps, redundancies | Stage flow coherence, purpose alignment, complexity appropriateness | +| **Enhancement Opportunities** | Script automation, autonomous potential, edge cases, delight | Creative edge-case discovery, experience gaps, assumption auditing | ### Report Synthesis After all scanners complete, the optimizer synthesizes results into a unified report saved to `{bmad_builder_reports}/{skill-name}/quality-scan/{timestamp}/`. In interactive mode, it presents a summary with severity counts and offers next steps: + - Apply fixes directly - Export checklist for manual fixes - Discuss specific findings @@ -183,21 +185,21 @@ The Module Builder (`bmad-module-builder`) handles module-level planning, scaffo ### Capabilities Overview -| Capability | Menu Code | What It Does | -| ---------- | --------- | ------------ | -| **Ideate Module** | IM | Brainstorm and plan a module through creative facilitation | -| **Create Module** | CM | Scaffold a setup skill into an existing folder of built skills | -| **Validate Module** | VM | Check structural integrity and entry quality of a module's setup skill | +| Capability | Menu Code | What It Does | +| ------------------- | --------- | ---------------------------------------------------------------------- | +| **Ideate Module** | IM | Brainstorm and plan a module through creative facilitation | +| **Create Module** | CM | Scaffold a setup skill into an existing folder of built skills | +| **Validate Module** | VM | Check structural integrity and entry quality of a module's setup skill | ### Ideate Module (IM) A facilitative brainstorming session that helps you envision your module from scratch. The builder acts as a creative collaborator — drawing out ideas, exploring possibilities, and guiding you toward the right architecture. -| Aspect | Detail | -| ------ | ------ | -| **Interaction** | Interactive only — no headless mode | -| **Input** | An idea or rough description | -| **Output** | Plan document saved to `{bmad_builder_reports}` | +| Aspect | Detail | +| --------------- | ----------------------------------------------- | +| **Interaction** | Interactive only — no headless mode | +| **Input** | An idea or rough description | +| **Output** | Plan document saved to `{bmad_builder_reports}` | **What it covers:** @@ -218,11 +220,11 @@ The plan document uses a resumable template with YAML frontmatter, so long brain Takes an existing folder of built skills and scaffolds a setup skill that makes it an installable BMad module. Supports `--headless` / `-H`. -| Aspect | Detail | -| ------ | ------ | -| **Interaction** | Guided or headless | -| **Input** | Path to a skills folder, optional plan document | -| **Output** | Setup skill (`bmad-{code}-setup/`) added to the skills folder | +| Aspect | Detail | +| --------------- | ------------------------------------------------------------- | +| **Interaction** | Guided or headless | +| **Input** | Path to a skills folder, optional plan document | +| **Output** | Setup skill (`bmad-{code}-setup/`) added to the skills folder | **What it does:** @@ -238,22 +240,22 @@ The scaffolded setup skill includes merge scripts, cleanup scripts, and a generi Verifies that a module's setup skill is complete and accurate. Combines a deterministic validation script with LLM-based quality assessment. -| Aspect | Detail | -| ------ | ------ | -| **Interaction** | Interactive | -| **Input** | Path to the module's skills folder | -| **Output** | Validation report | +| Aspect | Detail | +| --------------- | ---------------------------------- | +| **Interaction** | Interactive | +| **Input** | Path to the module's skills folder | +| **Output** | Validation report | **Structural checks** (script-driven): -| Check | What It Catches | -| ----- | --------------- | -| Setup skill structure | Missing SKILL.md, module.yaml, or module-help.csv | -| Coverage | Skills without CSV entries, orphan entries for nonexistent skills | -| Menu codes | Duplicate codes across the module | -| References | Before/after fields pointing to nonexistent capabilities | -| Required fields | Missing skill name, display name, menu code, or description in CSV rows | -| module.yaml | Missing code, name, or description | +| Check | What It Catches | +| --------------------- | ----------------------------------------------------------------------- | +| Setup skill structure | Missing SKILL.md, module.yaml, or module-help.csv | +| Coverage | Skills without CSV entries, orphan entries for nonexistent skills | +| Menu codes | Duplicate codes across the module | +| References | Before/after fields pointing to nonexistent capabilities | +| Required fields | Missing skill name, display name, menu code, or description in CSV rows | +| module.yaml | Missing code, name, or description | **Quality assessment** (LLM-driven): @@ -265,16 +267,16 @@ Verifies that a module's setup skill is complete and accurate. Combines a determ ## Trigger Phrases -| Intent | Phrases | Builder | Route | -| ------ | ------- | ------- | ----- | -| Build new | "create/build/design an agent" | Agent | `prompts/build-process.md` | -| Build new | "create/build/design a workflow/skill/tool" | Workflow | `prompts/build-process.md` | -| Edit | "edit/modify/update an agent" | Agent | `prompts/build-process.md` | -| Edit | "edit/modify/update a workflow/skill" | Workflow | `prompts/build-process.md` | -| Convert | "convert this to a BMad agent" | Agent | `prompts/build-process.md` | -| Convert | "convert this to a BMad skill" | Workflow | `prompts/build-process.md` | -| Optimize | "quality check/validate/optimize/review agent" | Agent | `prompts/quality-optimizer.md` | -| Optimize | "quality check/validate/optimize/review workflow/skill" | Workflow | `prompts/quality-optimizer.md` | -| Ideate | "ideate module/plan a module/brainstorm a module" | Module | `./references/ideate-module.md` | -| Create | "create module/build a module/scaffold a module" | Module | `./references/create-module.md` | -| Validate | "validate module/check module" | Module | `./references/validate-module.md` | +| Intent | Phrases | Builder | Route | +| --------- | ------------------------------------------------------- | -------- | --------------------------------- | +| Build new | "create/build/design an agent" | Agent | `prompts/build-process.md` | +| Build new | "create/build/design a workflow/skill/tool" | Workflow | `prompts/build-process.md` | +| Edit | "edit/modify/update an agent" | Agent | `prompts/build-process.md` | +| Edit | "edit/modify/update a workflow/skill" | Workflow | `prompts/build-process.md` | +| Convert | "convert this to a BMad agent" | Agent | `prompts/build-process.md` | +| Convert | "convert this to a BMad skill" | Workflow | `prompts/build-process.md` | +| Optimize | "quality check/validate/optimize/review agent" | Agent | `prompts/quality-optimizer.md` | +| Optimize | "quality check/validate/optimize/review workflow/skill" | Workflow | `prompts/quality-optimizer.md` | +| Ideate | "ideate module/plan a module/brainstorm a module" | Module | `./references/ideate-module.md` | +| Create | "create module/build a module/scaffold a module" | Module | `./references/create-module.md` | +| Validate | "validate module/check module" | Module | `./references/validate-module.md` | diff --git a/docs/tutorials/build-your-first-module.md b/docs/tutorials/build-your-first-module.md index 3987181..b212a38 100644 --- a/docs/tutorials/build-your-first-module.md +++ b/docs/tutorials/build-your-first-module.md @@ -1,5 +1,5 @@ --- -title: "Build Your First Module" +title: 'Build Your First Module' description: Create a complete BMad module from idea to installable package using the Module Builder --- @@ -14,9 +14,10 @@ Walk through the complete module lifecycle — from brainstorming an idea to sca - How to validate your module with Validate Module (VM) :::note[Prerequisites] + - BMad Builder module installed in your project (`bmad-builder-setup`) - Familiarity with what agents and workflows are — see **[What Are Agents](/explanation/what-are-bmad-agents.md)** and **[What Are Workflows](/explanation/what-are-workflows.md)** -::: + ::: :::tip[Quick Path] Already have your skills built? Skip to **Step 3: Scaffold the Module** to package them. Just need to validate an existing module? Jump to **Step 4: Validate**. @@ -26,12 +27,12 @@ Already have your skills built? Skip to **Step 3: Scaffold the Module** to packa A BMad module is a folder of skills (agents and/or workflows) plus a setup skill that handles installation. The setup skill collects configuration, registers capabilities with the help system, and makes the module discoverable. -| Component | What It Does | -| --------- | ------------ | -| **Your skills** | Agents and workflows that deliver the module's value | -| **Setup skill** | Generated infrastructure — config collection, help registration | -| **module.yaml** | Module identity and configurable variables | -| **module-help.csv** | Capability entries for the help system | +| Component | What It Does | +| ------------------- | --------------------------------------------------------------- | +| **Your skills** | Agents and workflows that deliver the module's value | +| **Setup skill** | Generated infrastructure — config collection, help registration | +| **module.yaml** | Module identity and configurable variables | +| **module-help.csv** | Capability entries for the help system | See **[What Are Modules](/explanation/what-are-modules.md)** for architecture decisions and design patterns. @@ -47,15 +48,15 @@ Start with the Ideate Module capability to brainstorm and plan. The ideation session covers: -| Topic | What You'll Decide | -| ----- | ------------------ | -| **Vision** | Problem space, target users, core value | -| **Architecture** | Single agent, multiple workflows, or hybrid | -| **Memory** | For multi-agent modules: personal sidecars, shared module memory, or both | -| **Module type** | Standalone or expansion of another module | -| **Skills** | Each planned skill's purpose, capabilities, and relationships | -| **Configuration** | Custom install questions and variables | -| **Dependencies** | External CLI tools, MCP servers, web services | +| Topic | What You'll Decide | +| ----------------- | ------------------------------------------------------------------------- | +| **Vision** | Problem space, target users, core value | +| **Architecture** | Single agent, multiple workflows, or hybrid | +| **Memory** | For multi-agent modules: personal sidecars, shared module memory, or both | +| **Module type** | Standalone or expansion of another module | +| **Skills** | Each planned skill's purpose, capabilities, and relationships | +| **Configuration** | Custom install questions and variables | +| **Dependencies** | External CLI tools, MCP servers, web services | The output is a **plan document** saved to your reports folder. This document captures everything you discussed and serves as a blueprint for building each skill. @@ -63,10 +64,10 @@ The output is a **plan document** saved to your reports folder. This document ca With your plan in hand, build each skill individually. -| Skill Type | Builder | Menu Code | -| ---------- | ------- | --------- | -| Agent | Agent Builder | BA | -| Workflow or utility | Workflow Builder | BW | +| Skill Type | Builder | Menu Code | +| ------------------- | ---------------- | --------- | +| Agent | Agent Builder | BA | +| Workflow or utility | Workflow Builder | BW | Share the plan document as context when building each skill — it helps the builder understand the bigger picture and how the skill fits into the module. @@ -112,10 +113,10 @@ Run Validate Module (VM) to check that everything is wired correctly. **Builder:** Runs structural checks and quality assessment, then reports findings. ::: -| Check Type | What It Catches | -| ---------- | --------------- | +| Check Type | What It Catches | +| -------------- | ---------------------------------------------------------------------- | | **Structural** | Missing files, orphan entries, duplicate menu codes, broken references | -| **Quality** | Inaccurate descriptions, missing capabilities, poor entry quality | +| **Quality** | Inaccurate descriptions, missing capabilities, poor entry quality | Fix any findings and re-validate until clean. @@ -138,13 +139,13 @@ Your module is now a complete, distributable BMad module. To install it in any p ## Quick Reference -| Capability | Menu Code | When to Use | -| ---------- | --------- | ----------- | -| Ideate Module | IM | Planning a new module from scratch | -| Build an Agent | BA | Building an agent skill for the module | -| Build a Workflow | BW | Building a workflow skill for the module | -| Create Module | CM | Scaffolding the setup skill after skills are built | -| Validate Module | VM | Checking the module is complete and accurate | +| Capability | Menu Code | When to Use | +| ---------------- | --------- | -------------------------------------------------- | +| Ideate Module | IM | Planning a new module from scratch | +| Build an Agent | BA | Building an agent skill for the module | +| Build a Workflow | BW | Building a workflow skill for the module | +| Create Module | CM | Scaffolding the setup skill after skills are built | +| Validate Module | VM | Checking the module is complete and accurate | ## Common Questions diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 706458c..4269170 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -7,8 +7,8 @@ description: Learn BMad Builder through hands-on examples Hands-on tutorials for building with the BMad Builder. -| Tutorial | Description | -| -------- | ----------- | +| Tutorial | Description | +| -------------------------------------------------------------------- | ---------------------------------------------------------- | | **[Build Your First Module](/tutorials/build-your-first-module.md)** | Plan, build, scaffold, and validate a complete BMad module | For concepts and design patterns, see the **[Explanation docs](/explanation/)**. For capability details, see the **[Builder Commands Reference](/reference/builder-commands.md)**. diff --git a/skills/bmad-module-builder/assets/module-plan-template.md b/skills/bmad-module-builder/assets/module-plan-template.md index 33821a6..330eda9 100644 --- a/skills/bmad-module-builder/assets/module-plan-template.md +++ b/skills/bmad-module-builder/assets/module-plan-template.md @@ -1,15 +1,15 @@ --- -title: "Module Plan" -status: "ideation" -module_name: "" -module_code: "" -architecture: "" +title: 'Module Plan' +status: 'ideation' +module_name: '' +module_code: '' +architecture: '' standalone: true -expands_module: "" +expands_module: '' skills_planned: [] config_variables: [] -created: "" -updated: "" +created: '' +updated: '' --- # Module Plan @@ -38,8 +38,8 @@ updated: "" **Capabilities:** | Display Name | Menu Code | Description | Action | Args | Phase | After | Before | Required | Output Location | Outputs | -|---|---|---|---|---|---|---|---|---|---|---| -| | | | | | | | | | | | +| ------------ | --------- | ----------- | ------ | ---- | ----- | ----- | ------ | -------- | --------------- | ------- | +| | | | | | | | | | | | **Design Notes:** @@ -52,8 +52,8 @@ updated: "" ## Configuration | Variable | Prompt | Default | Result Template | User Setting | -|---|---|---|---|---| -| | | | | | +| -------- | ------ | ------- | --------------- | ------------ | +| | | | | | @@ -90,5 +90,6 @@ updated: "" **Next steps:** + 1. Build each skill using **Build an Agent (BA)** or **Build a Workflow (BW)** — share this plan document as context 2. When all skills are built, return to **Create Module (CM)** to scaffold the module infrastructure diff --git a/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md b/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md index 326c3db..9134a6d 100644 --- a/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md +++ b/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md @@ -1,5 +1,5 @@ --- -name: {setup-skill-name} +name: { setup-skill-name } description: Sets up {module-name} module in a project. Use when the user requests to 'install {module-code} module', 'configure {module-name}', or 'setup {module-name}'. --- @@ -69,7 +69,7 @@ Check `directories_removed` and `files_removed_count` in the JSON output for the ## Confirm -Use the script JSON output to display what was written — config values set (written to `config.yaml` at root for core, module section for module values), user settings written to `config.user.yaml` (`user_keys` in result), help entries added, fresh install vs update. If legacy files were deleted, mention the migration. If legacy directories were removed, report the count and list (e.g. "Cleaned up 106 installer package files from bmb/, core/, _config/ — skills are installed at .claude/skills/"). Then display the `module_greeting` from `./assets/module.yaml` to the user. +Use the script JSON output to display what was written — config values set (written to `config.yaml` at root for core, module section for module values), user settings written to `config.user.yaml` (`user_keys` in result), help entries added, fresh install vs update. If legacy files were deleted, mention the migration. If legacy directories were removed, report the count and list (e.g. "Cleaned up 106 installer package files from bmb/, core/, \_config/ — skills are installed at .claude/skills/"). Then display the `module_greeting` from `./assets/module.yaml` to the user. ## Outcome diff --git a/skills/bmad-module-builder/references/create-module.md b/skills/bmad-module-builder/references/create-module.md index adefbb7..7cde83c 100644 --- a/skills/bmad-module-builder/references/create-module.md +++ b/skills/bmad-module-builder/references/create-module.md @@ -13,6 +13,7 @@ You are a module packaging specialist. The user has built their skills — your Ask the user for the folder path containing their built skills. Also ask: do they have a plan document from an Ideate Module (IM) session? If so, read it — it provides valuable context for ordering, relationships, and design intent. **Read every SKILL.md in the folder thoroughly.** Understand each skill's: + - Name, purpose, and capabilities - Arguments and interaction model - What it produces and where @@ -33,21 +34,22 @@ Collect through conversation (or extract from a plan document in headless mode): Build the help CSV entries for each skill. A single skill can have multiple capabilities (rows). For each capability: -| Field | Description | -|---|---| -| **display-name** | What the user sees in help/menus | -| **menu-code** | 2-letter shortcut, unique across the module | -| **description** | What this capability does (concise) | -| **action** | The capability/action name within the skill | -| **args** | Supported arguments (e.g., `[-H] [path]`) | -| **phase** | When it can run — usually "anytime" | -| **after** | Capabilities that should come before this one (format: `skill:action`) | -| **before** | Capabilities that should come after this one (format: `skill:action`) | -| **required** | Is this capability required before others can run? | -| **output-location** | Where output goes (config variable name or path) | -| **outputs** | What it produces | +| Field | Description | +| ------------------- | ---------------------------------------------------------------------- | +| **display-name** | What the user sees in help/menus | +| **menu-code** | 2-letter shortcut, unique across the module | +| **description** | What this capability does (concise) | +| **action** | The capability/action name within the skill | +| **args** | Supported arguments (e.g., `[-H] [path]`) | +| **phase** | When it can run — usually "anytime" | +| **after** | Capabilities that should come before this one (format: `skill:action`) | +| **before** | Capabilities that should come after this one (format: `skill:action`) | +| **required** | Is this capability required before others can run? | +| **output-location** | Where output goes (config variable name or path) | +| **outputs** | What it produces | Ask the user about: + - How capabilities should be ordered — are there natural sequences? - Which capabilities are prerequisites for others? - If this is an expansion module, do any capabilities reference the parent module's skills in their before/after fields? @@ -56,13 +58,13 @@ Ask the user about: Does the module need custom installation questions? For each custom variable: -| Field | Description | -|---|---| -| **Key name** | Used in config.yaml under the module section | -| **Prompt** | Question shown to user during setup | -| **Default** | Default value | +| Field | Description | +| ------------------- | ---------------------------------------------------------------------------- | +| **Key name** | Used in config.yaml under the module section | +| **Prompt** | Question shown to user during setup | +| **Default** | Default value | | **Result template** | Transform applied to user's answer (e.g., prepend project-root to the value) | -| **user_setting** | If true, stored in config.user.yaml instead of config.yaml | +| **user_setting** | If true, stored in config.user.yaml instead of config.yaml | Remind the user: skills should always have sensible fallbacks if config hasn't been set. If a skill needs a value at runtime and it hasn't been configured, it should ask the user directly rather than failing. @@ -79,6 +81,7 @@ If any of these apply, let the user know the scaffolded setup skill will need ma ### 6. Generate and Confirm Present the complete module.yaml and module-help.csv content for the user to review. Show: + - Module identity and metadata - All configuration variables with their prompts and defaults - Complete help CSV entries with ordering and relationships @@ -100,6 +103,7 @@ python3 ./scripts/scaffold-setup-skill.py \ ``` This creates `bmad-{code}-setup/` in the user's skills folder containing: + - `./SKILL.md` — Generic setup skill with module-specific frontmatter - `./scripts/` — merge-config.py, merge-help-csv.py, cleanup-legacy.py - `./assets/module.yaml` — Generated module definition @@ -116,6 +120,7 @@ Show what was created — the setup skill folder structure and key file contents ## Headless Mode When `--headless` is set, the skill requires either: + - A **plan document path** — extract all module identity, capabilities, and config from it - A **skills folder path** — read skills and infer sensible defaults for module identity diff --git a/skills/bmad-module-builder/references/ideate-module.md b/skills/bmad-module-builder/references/ideate-module.md index ece67b3..d96e386 100644 --- a/skills/bmad-module-builder/references/ideate-module.md +++ b/skills/bmad-module-builder/references/ideate-module.md @@ -35,6 +35,7 @@ Weave these into conversation naturally. Never name them or make the user feel l Initialize the plan document immediately using `./assets/module-plan-template.md`. Write it to `{bmad_builder_reports}` with a descriptive filename. Set `created` and `updated` timestamps. This document is your cache — update it progressively as the conversation unfolds so work survives context compaction. Start by understanding the spark. Let the user talk freely — this is where the richest context comes from: + - What's the idea? What problem space or domain? - Who would use this and what would they get from it? - Is there anything that inspired this — an existing tool, a frustration, a gap they've noticed? @@ -61,18 +62,21 @@ Energy check: if the conversation plateaus, try a perspective shift or reverse b When exploration feels genuinely complete (not just "we have enough"), shift to architecture. **Guide toward agent-with-capabilities when appropriate.** Many users default to thinking they need multiple specialized agents. But a well-designed single agent with rich internal capabilities and routing: + - Provides a more seamless user experience - Benefits from accumulated memory and context - Is simpler to maintain and configure - Can still have distinct modes or capabilities that feel like separate tools However, **multiple agents make sense when:** + - The module spans genuinely different expertise domains that benefit from distinct personas - Users may want to interact with one agent without loading the others - Each agent needs its own memory context — personal history, learned preferences, domain-specific notes - Some capabilities are optional add-ons the user might not install **Multiple workflows make sense when:** + - Capabilities serve different user journeys or require different tools - The workflow requires sequential phases with fundamentally different processes - No persistent persona or memory is needed between invocations @@ -83,11 +87,11 @@ Present the trade-offs. Let the user decide. Document the reasoning either way **Memory architecture for multi-agent modules.** If the module has multiple agents, explore how memory should work. Every agent has its own sidecar (personal memory at `{project-root}/_bmad/memory/{skillName}-sidecar/`), but modules may also benefit from shared memory: -| Pattern | When It Fits | Example | -| ------- | ------------ | ------- | -| **Personal sidecars only** | Agents have distinct domains with little overlap | A module with a code reviewer and a test writer — each tracks different things | +| Pattern | When It Fits | Example | +| ------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Personal sidecars only** | Agents have distinct domains with little overlap | A module with a code reviewer and a test writer — each tracks different things | | **Personal + shared module sidecar** | Agents have their own context but also learn shared things about the user | A social creative module — podcast, video, and blog experts each remember their domain specifics but share knowledge about the user's style, catchphrases, and content preferences | -| **Shared sidecar only** | All agents serve the same domain and context | Probably a sign this should be a single agent | +| **Shared sidecar only** | All agents serve the same domain and context | Probably a sign this should be a single agent | With shared memory, each agent writes to both its personal sidecar and a module-level sidecar (e.g., `{project-root}/_bmad/memory/{moduleCode}-shared/`) when it learns something relevant to the whole module. Shared content might include: user style preferences, project assets, recurring themes, content history, or any cross-cutting context. @@ -104,6 +108,7 @@ If the memory architecture points entirely toward shared memory with no personal ### 5. Define Each Skill For each planned skill (whether agent or workflow), work through: + - **Name** — following `bmad-{modulecode}-{skillname}` convention - **Purpose** — the core outcome in one sentence - **Capabilities** — each distinct action or mode. These become rows in the help CSV: display name, menu code, description, action name, args, phase, ordering (before/after), required flag, output location, outputs @@ -117,6 +122,7 @@ Update the **Skills** section of the plan document with structured entries for e Complete all sections of the plan document. Review with the user — walk through the plan and confirm it captures their vision. Update `status` to "complete" in the frontmatter. **Close with next steps:** + - "Build each skill using **Build an Agent (BA)** or **Build a Workflow (BW)** — share this plan document as context so the builder understands the bigger picture." - "When all skills are built, return to **Create Module (CM)** to scaffold the module infrastructure." - Point them to the plan document location so they can reference it. diff --git a/skills/bmad-module-builder/references/validate-module.md b/skills/bmad-module-builder/references/validate-module.md index 2074d15..44022a3 100644 --- a/skills/bmad-module-builder/references/validate-module.md +++ b/skills/bmad-module-builder/references/validate-module.md @@ -33,6 +33,7 @@ This is where LLM judgment matters. Read every SKILL.md in the module thoroughly **Accuracy** — Does each entry's description actually match what the skill does? Are the action names correct? Do the args match what the skill accepts? **Description quality** — Each description should be: + - Concise but informative — enough for a user to know what it does and for an LLM to route correctly - Action-oriented — starts with a verb (Create, Validate, Brainstorm, Scaffold) - Specific — avoids vague language ("helps with things", "manages stuff") From adb263a3e5f264b134c9ae2f297e03c6a0984a96 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 29 Mar 2026 01:46:20 -0500 Subject: [PATCH 3/3] style: format entire repo with prettier --- .github/ISSUE_TEMPLATE/issue.md | 2 + AGENTS.md | 14 +- CHANGELOG.md | 1 - CONTRIBUTING.md | 8 +- README.md | 22 +- SECURITY.md | 8 +- docs/404.md | 1 - docs/_STYLE_GUIDE.md | 6 +- docs/explanation/progressive-disclosure.md | 53 ++--- docs/explanation/scripts-in-skills.md | 82 +++---- .../skill-authoring-best-practices.md | 90 ++++---- docs/explanation/subagent-patterns.md | 118 +++++------ docs/explanation/what-are-bmad-agents.md | 32 +-- docs/explanation/what-are-skills.md | 14 +- docs/explanation/what-are-workflows.md | 42 ++-- docs/index.md | 44 ++-- docs/reference/index.md | 8 +- docs/reference/workflow-patterns.md | 33 ++- samples/bmad-agent-dream-weaver/SKILL.md | 4 +- .../dream-interpret.md | 8 +- .../bmad-agent-dream-weaver/dream-query.md | 5 + samples/bmad-agent-dream-weaver/dream-seed.md | 15 +- .../bmad-agent-dream-weaver/headless-wake.md | 6 +- samples/bmad-agent-dream-weaver/init.md | 4 + .../bmad-agent-dream-weaver/lucid-coach.md | 16 +- .../pattern-discovery.md | 4 +- .../recall-training.md | 9 +- .../references/memory-system.md | 35 +-- samples/bmad-excalidraw/SKILL.md | 9 +- samples/bmad-excalidraw/diagram-generation.md | 2 + samples/bmad-excalidraw/guided-design.md | 6 + .../references/diagram-types.md | 10 + .../references/excalidraw-schema.md | 134 ++++++------ skills/bmad-agent-builder/SKILL.md | 10 +- .../assets/SKILL-template.md | 17 +- .../assets/init-template.md | 4 + .../assets/memory-system.md | 15 +- skills/bmad-agent-builder/build-process.md | 21 +- skills/bmad-agent-builder/quality-analysis.md | 38 ++-- .../quality-scan-agent-cohesion.md | 70 +++--- .../quality-scan-enhancement-opportunities.md | 103 ++++----- .../quality-scan-execution-efficiency.md | 98 +++++---- .../quality-scan-prompt-craft.md | 137 ++++++------ .../quality-scan-script-opportunities.md | 62 ++++-- .../quality-scan-structure.md | 114 +++++----- .../references/quality-dimensions.md | 4 +- .../script-opportunities-reference.md | 31 ++- .../references/script-standards.md | 3 + .../references/skill-best-practices.md | 48 ++--- .../references/standard-fields.md | 29 +-- .../references/template-substitution-rules.md | 3 + .../report-quality-scan-creator.md | 16 +- skills/bmad-builder-setup/SKILL.md | 2 +- .../setup-skill-template/assets/module.yaml | 1 - skills/bmad-workflow-builder/SKILL.md | 10 +- .../assets/SKILL-template.md | 2 +- skills/bmad-workflow-builder/build-process.md | 33 ++- .../bmad-workflow-builder/quality-analysis.md | 39 ++-- .../quality-scan-enhancement-opportunities.md | 105 ++++----- .../quality-scan-execution-efficiency.md | 159 +++++++------- .../quality-scan-prompt-craft.md | 200 +++++++++--------- .../quality-scan-script-opportunities.md | 62 ++++-- .../quality-scan-skill-cohesion.md | 81 +++---- .../quality-scan-workflow-integrity.md | 186 ++++++++-------- .../references/classification-reference.md | 12 +- .../references/complex-workflow-patterns.md | 14 +- .../references/quality-dimensions.md | 4 +- .../script-opportunities-reference.md | 32 +-- .../references/script-standards.md | 3 + .../references/skill-best-practices.md | 48 ++--- .../references/standard-fields.md | 66 +++--- .../references/template-substitution-rules.md | 3 + .../report-quality-scan-creator.md | 11 + website/src/styles/custom.css | 15 +- 74 files changed, 1534 insertions(+), 1222 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/issue.md b/.github/ISSUE_TEMPLATE/issue.md index aa07277..0176b0a 100644 --- a/.github/ISSUE_TEMPLATE/issue.md +++ b/.github/ISSUE_TEMPLATE/issue.md @@ -10,6 +10,7 @@ assignees: '' A clear and concise description of what the bug is. **Steps to reproduce** + 1. What were you doing when the bug occurred? 2. What steps can recreate the issue? @@ -17,6 +18,7 @@ A clear and concise description of what the bug is. A clear and concise description of what you expected to happen. **Environment (if relevant)** + - Model(s) used: - Agentic IDE used: - BMad version: diff --git a/AGENTS.md b/AGENTS.md index 4e59aad..2e8da29 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,7 @@ ## Key Commands ### Development + ```bash npm run docs:dev # Start Astro dev server (http://localhost:4321) npm run docs:build # Build documentation site @@ -14,6 +15,7 @@ npm run docs:preview # Preview built site ``` ### Testing & Validation + ```bash npm test # Run full test suite (schemas, refs, lint, format, md) npm run test:schemas # Validate agent YAML schemas @@ -23,6 +25,7 @@ npm run validate:refs # Check file references (alias for above) ``` ### Code Quality + ```bash npm run lint # ESLint check npm run lint:fix # ESLint auto-fix @@ -32,6 +35,7 @@ npm run format:fix # Prettier format ``` ### Release + ```bash npm run release # Bump patch version and push tag npm run release:minor # Bump minor version @@ -41,6 +45,7 @@ npm run release:major # Bump major version ## Architecture ### Source Structure (`src/`) + - **`agents/`** — Agent definitions (`*.agent.yaml`) with persona, menu, and metadata - **`workflows/`** — Multi-step guided processes organized by type (agent, workflow, module) - Each workflow has `steps-c/` (create), `steps-e/` (edit), `steps-v/` (validate) @@ -48,6 +53,7 @@ npm run release:major # Bump major version - `data/` contains CSV knowledge bases for agents ### Module Structure + ``` your-module/ ├── src/ @@ -59,15 +65,18 @@ your-module/ ``` ### Build Tools (`tools/`) + - **`build-docs.mjs`** — Consolidates docs, generates LLM-friendly files (`llms.txt`), builds Astro site - **`validate-file-refs.mjs`** — Validates cross-file references in agents/workflows ### Documentation (`docs/`) + - Diataxis structure: tutorials, how-to, explanation, reference - Starlight-based site in `website/` - `_STYLE_GUIDE.md` — Project-specific writing conventions (Google style + Diataxis) ### Skills (`.claude/skills/`) + - BMad OS (Open Source) skills for maintainer workflows - `bmad-os-add-doc` — Diataxis documentation authoring - `bmad-os-release-module` — Module release process @@ -76,12 +85,14 @@ your-module/ ## Important Concepts ### Agent YAML Structure + - `agent.metadata` — id, name, title, icon, module - `agent.persona` — role, identity, communication_style, principles - `agent.menu` — trigger commands that execute workflows - `conversational_knowledge` — CSV files loaded at runtime ### Workflow Step Architecture + - Micro-file design: each step is self-contained - Just-in-time loading: only current step in memory - Sequential enforcement with state tracking @@ -89,6 +100,7 @@ your-module/ - Frontmatter defines: name, description, web_bundle, createWorkflow ### Path Variables + - `{project-root}/_bmad/bmb/` — Installation path (in repo, maps to `src/`) - `{bmad_builder_output_folder}` — User's custom content output - Runtime variables: `{output_folder}`, `{project-root}` from Core config @@ -104,4 +116,4 @@ your-module/ ## Publishing -BMad modules are published as npm packages. The module code (`src/`) is what gets installed into user projects via `npx bmad-method install`. The astro website is deployed separately (GitHub Pages via CNAME). \ No newline at end of file +BMad modules are published as npm packages. The module code (`src/`) is what gets installed into user projects via `npx bmad-method install`. The astro website is deployed separately (GitHub Pages via CNAME). diff --git a/CHANGELOG.md b/CHANGELOG.md index e06d2f6..048cce0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,4 +23,3 @@ First official v1 release of BMad Builder — a standard skill-compliant factory for creating BMad Agents, Workflows, and Modules. The module specific skill is coming soon pending alignment on final format with skill transition. - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 282e13c..1cf140a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,12 +11,14 @@ Thank you for considering contributing! We believe in **Human Amplification, Not BMad strengthens human-AI collaboration through specialized agents and guided workflows. Every contribution should answer: **"Does this make humans and AI better together?"** **✅ What we welcome:** + - Enhanced collaboration patterns and workflows - Improved agent personas and prompts - Domain-specific modules leveraging BMad Core - Better planning and context continuity **❌ What doesn't fit:** + - Purely automated solutions that sideline humans - Complexity that creates barriers to adoption - Features that fragment BMad Core's foundation @@ -97,17 +99,21 @@ If your change exceeds 800 lines, break it into smaller PRs that can be reviewed ```markdown ## What + [1-2 sentences describing WHAT changed] ## Why + [1-2 sentences explaining WHY this change is needed] Fixes #[issue number] ## How + - [2-3 bullets listing HOW you implemented it] - ## Testing + [1-2 sentences on how you tested this] ``` @@ -130,7 +136,7 @@ Keep messages under 72 characters. Each commit = one logical change. ## What Makes a Good PR? -| ✅ Do | ❌ Don't | +| ✅ Do | ❌ Don't | | --------------------------- | ---------------------------- | | Change one thing per PR | Mix unrelated changes | | Clear title and description | Vague or missing explanation | diff --git a/README.md b/README.md index ff6fb2a..000b244 100644 --- a/README.md +++ b/README.md @@ -25,21 +25,21 @@ BMad Builder lets you create: ## What Makes It Different -| Feature | Why It Matters | -|---------|----------------| -| **Persistent Memory** | Agents remember across sessions — they learn and grow | -| **Composable** | Your creations work alongside the entire BMad ecosystem | -| **Skill-Compliant** | Built on open standards that work with any AI tool | -| **Shareable** | Package your modules for the BMad Marketplace (coming soon) | +| Feature | Why It Matters | +| --------------------- | ----------------------------------------------------------- | +| **Persistent Memory** | Agents remember across sessions — they learn and grow | +| **Composable** | Your creations work alongside the entire BMad ecosystem | +| **Skill-Compliant** | Built on open standards that work with any AI tool | +| **Shareable** | Package your modules for the BMad Marketplace (coming soon) | ## What You Can Build -| Domain | Example | -|--------|---------| -| **Personal** | Journal companion, habit coach, learning tutor | +| Domain | Example | +| ---------------- | ----------------------------------------------------------- | +| **Personal** | Journal companion, habit coach, learning tutor | | **Professional** | Code reviewer, documentation specialist, workflow automator | -| **Creative** | Story architect, character developer, campaign designer | -| **Any Domain** | If you can describe it, you can build it | +| **Creative** | Story architect, character developer, campaign designer | +| **Any Domain** | If you can describe it, you can build it | ## Learn More diff --git a/SECURITY.md b/SECURITY.md index 2c565ed..0a52bdc 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,10 +4,10 @@ We release security patches for the following versions: -| Version | Supported | -| ------- | ------------------ | -| Latest | :white_check_mark: | -| < Latest | :x: | +| Version | Supported | +| -------- | ------------------ | +| Latest | :white_check_mark: | +| < Latest | :x: | We recommend always using the latest version of BMad Method to ensure you have the most recent security updates. diff --git a/docs/404.md b/docs/404.md index c40514b..d2ddc2d 100644 --- a/docs/404.md +++ b/docs/404.md @@ -3,7 +3,6 @@ title: Page Not Found template: splash --- - The page you're looking for doesn't exist or has been moved. [Return to Home](/index.md) diff --git a/docs/_STYLE_GUIDE.md b/docs/_STYLE_GUIDE.md index c6e9eff..a62482f 100644 --- a/docs/_STYLE_GUIDE.md +++ b/docs/_STYLE_GUIDE.md @@ -1,5 +1,5 @@ --- -title: "Documentation Style Guide" +title: 'Documentation Style Guide' description: Project-specific documentation conventions based on Google style and Diataxis structure --- @@ -55,8 +55,8 @@ Critical warnings only — data loss, security issues ```md | Phase | Name | What Happens | | ----- | -------- | -------------------------------------------- | -| 1 | Analysis | Brainstorm, research *(optional)* | -| 2 | Planning | Requirements — PRD or tech-spec *(required)* | +| 1 | Analysis | Brainstorm, research _(optional)_ | +| 2 | Planning | Requirements — PRD or tech-spec _(required)_ | ``` **Commands:** diff --git a/docs/explanation/progressive-disclosure.md b/docs/explanation/progressive-disclosure.md index ac047ee..f9c33d7 100644 --- a/docs/explanation/progressive-disclosure.md +++ b/docs/explanation/progressive-disclosure.md @@ -1,20 +1,20 @@ --- -title: "Progressive Disclosure in Skills" +title: 'Progressive Disclosure in Skills' description: How to structure skills so they load only the context needed at each moment — from frontmatter through dynamic routing to step files --- -Progressive disclosure is the technique that separates basic skills from powerful ones. The core idea: never load more context than the agent needs *right now*. This keeps token usage low, prevents context pollution, and makes skills survive long conversations. +Progressive disclosure is the technique that separates basic skills from powerful ones. The core idea: never load more context than the agent needs _right now_. This keeps token usage low, prevents context pollution, and makes skills survive long conversations. ## The Four Layers Skills can use any combination of these layers. Most production skills use Layers 1-3. Layer 4 is reserved for strict sequential processes. -| Layer | What It Does | Token Cost | -| ----- | ------------ | ---------- | -| **1. Frontmatter vs Body** | Frontmatter is always in context; body loads only when triggered | ~100 tokens always, body on demand | -| **2. On-Demand Resources** | SKILL.md points to resources and scripts loaded only when relevant | Zero until needed | -| **3. Dynamic Routing** | SKILL.md acts as a router, dispatching to entirely different prompt flows | Only the chosen path loads | -| **4. Step Files** | Agent reads one step at a time, never sees ahead | One step's worth at a time | +| Layer | What It Does | Token Cost | +| -------------------------- | ------------------------------------------------------------------------- | ---------------------------------- | +| **1. Frontmatter vs Body** | Frontmatter is always in context; body loads only when triggered | ~100 tokens always, body on demand | +| **2. On-Demand Resources** | SKILL.md points to resources and scripts loaded only when relevant | Zero until needed | +| **3. Dynamic Routing** | SKILL.md acts as a router, dispatching to entirely different prompt flows | Only the chosen path loads | +| **4. Step Files** | Agent reads one step at a time, never sees ahead | One step's worth at a time | ## Layer 1: Frontmatter vs Body @@ -29,6 +29,7 @@ description: Validates API contracts against OpenAPI specs. Use when user says ' --- # Body loads only when triggered + ... ``` @@ -38,6 +39,7 @@ SKILL.md points to resources loaded only when relevant. This includes both **ref ```markdown ## Which Guide to Read + - Python project → Read `resources/python.md` - TypeScript project → Read `resources/typescript.md` - Need validation → Run `scripts/validate.py` (don't read the script, just run it) @@ -53,12 +55,15 @@ The skill body acts as a **router** that dispatches to entirely different prompt ## What Are You Trying To Do? ### "Build a new workflow" + → Read `prompts/create-flow.md` and follow its instructions ### "Review an existing workflow" + → Read `prompts/review-flow.md` and follow its instructions ### "Run analysis" + → Run `scripts/analyze.py --target ` and present results ``` @@ -88,21 +93,21 @@ Most skills only need Layers 1-2. Add Layer 3 when the skill genuinely handles m Long-running workflows risk losing context when the conversation compresses. The **document-as-cache pattern** solves this: the output document itself stores the workflow's state. -| Component | Purpose | -| --------- | ------- | +| Component | Purpose | +| --------------------- | ------------------------------------------------------ | | **YAML front matter** | Paths to input files, current stage status, timestamps | -| **Draft sections** | Progressive content built across stages | -| **Status marker** | Which stage is complete, for resumption | +| **Draft sections** | Progressive content built across stages | +| **Status marker** | Which stage is complete, for resumption | Each stage reads the output document to restore context, does its work, and writes results back to the same document. If context compacts mid-workflow, the next stage recovers by reading the document and reloading the input files listed in front matter. ```markdown --- -title: "Analysis: Research Topic" -status: "analysis" +title: 'Analysis: Research Topic' +status: 'analysis' inputs: - - "{project_root}/docs/brief.md" - - "{project_root}/data/sources.json" + - '{project_root}/docs/brief.md' + - '{project_root}/data/sources.json' --- ``` @@ -110,11 +115,11 @@ This avoids separate cache files, file collisions when running multiple workflow ## Choosing the Right Layer -| Situation | Recommended Layer | -| --------- | ----------------- | -| Single-purpose utility with one path | Layer 1-2 | -| Skill with conditional reference data | Layer 2 | -| Skill that does multiple distinct things | Layer 3 | -| Skill with stages that depend on each other | Layer 3 + compaction survival | -| Strict sequential process, no skipping allowed | Layer 4 | -| Long-running workflow producing a document | Layer 3 + document-as-cache | +| Situation | Recommended Layer | +| ---------------------------------------------- | ----------------------------- | +| Single-purpose utility with one path | Layer 1-2 | +| Skill with conditional reference data | Layer 2 | +| Skill that does multiple distinct things | Layer 3 | +| Skill with stages that depend on each other | Layer 3 + compaction survival | +| Strict sequential process, no skipping allowed | Layer 4 | +| Long-running workflow producing a document | Layer 3 + document-as-cache | diff --git a/docs/explanation/scripts-in-skills.md b/docs/explanation/scripts-in-skills.md index 3b16604..ed68c06 100644 --- a/docs/explanation/scripts-in-skills.md +++ b/docs/explanation/scripts-in-skills.md @@ -1,5 +1,5 @@ --- -title: "Scripts in Skills" +title: 'Scripts in Skills' description: Why deterministic scripts make skills faster, cheaper, and more reliable — and the technical choices behind portable script design --- @@ -19,11 +19,11 @@ The pattern shows up everywhere: skills that try to LLM their way through struct The core design principle is **intelligence placement** — put each operation where it belongs. -| Scripts Handle | LLM Handles | -| -------------- | ----------- | -| Validate structure, format, schema | Interpret meaning, evaluate quality | -| Count, parse, extract, transform | Classify ambiguous input, make judgment calls | -| Compare, diff, check consistency | Synthesize insights, generate creative output | +| Scripts Handle | LLM Handles | +| ---------------------------------- | ------------------------------------------------ | +| Validate structure, format, schema | Interpret meaning, evaluate quality | +| Count, parse, extract, transform | Classify ambiguous input, make judgment calls | +| Compare, diff, check consistency | Synthesize insights, generate creative output | | Pre-process data into compact form | Analyze pre-processed data with domain reasoning | **The test:** Given identical input, will this operation always produce identical output? If yes, it belongs in a script. Could you write a unit test with expected output? Definitely a script. Requires interpreting meaning, tone, or context? Keep it as an LLM prompt. @@ -36,25 +36,25 @@ One of the highest-value script uses is pre-processing. A script extracts compac Skills must work across macOS, Linux, and Windows. Bash is not portable. -| Factor | Bash | Python | -| ------ | ---- | ------ | -| **macOS / Linux** | Works | Works | -| **Windows (native)** | Fails or behaves inconsistently | Works identically | -| **Windows (WSL)** | Works, but can conflict with Git Bash on PATH | Works identically | -| **Error handling** | Limited, fragile | Rich exception handling | -| **Testing** | Difficult | Standard unittest/pytest | -| **Complex logic** | Quickly becomes unreadable | Clean, maintainable | +| Factor | Bash | Python | +| -------------------- | --------------------------------------------- | ------------------------ | +| **macOS / Linux** | Works | Works | +| **Windows (native)** | Fails or behaves inconsistently | Works identically | +| **Windows (WSL)** | Works, but can conflict with Git Bash on PATH | Works identically | +| **Error handling** | Limited, fragile | Rich exception handling | +| **Testing** | Difficult | Standard unittest/pytest | +| **Complex logic** | Quickly becomes unreadable | Clean, maintainable | Even basic commands like `sed -i` behave differently on macOS vs Linux. Piping, `jq`, `grep`, `awk` — all of these have cross-platform pitfalls that Python's standard library avoids entirely. **Safe bash commands** that work everywhere and remain fine to use directly: -| Command | Purpose | -| ------- | ------- | -| `git`, `gh` | Version control and GitHub CLI | -| `uv run` | Python script execution | -| `npm`, `npx`, `pnpm` | Node.js ecosystem | -| `mkdir -p` | Directory creation | +| Command | Purpose | +| -------------------- | ------------------------------ | +| `git`, `gh` | Version control and GitHub CLI | +| `uv run` | Python script execution | +| `npm`, `npx`, `pnpm` | Node.js ecosystem | +| `mkdir -p` | Directory creation | Everything beyond that list should be a Python script. @@ -62,16 +62,16 @@ Everything beyond that list should be a Python script. Python's standard library covers most script needs without any external dependencies. Stdlib-only scripts run with plain `python3`, need no special tooling, and have zero supply-chain risk. -| Need | Standard Library | -| ---- | ---------------- | -| JSON parsing | `json` | -| Path handling | `pathlib` | -| Pattern matching | `re` | -| CLI interface | `argparse` | -| Text comparison | `difflib` | -| Counting, grouping | `collections` | -| Source analysis | `ast` | -| Data formats | `csv`, `xml.etree` | +| Need | Standard Library | +| ------------------ | ------------------ | +| JSON parsing | `json` | +| Path handling | `pathlib` | +| Pattern matching | `re` | +| CLI interface | `argparse` | +| Text comparison | `difflib` | +| Counting, grouping | `collections` | +| Source analysis | `ast` | +| Data formats | `csv`, `xml.etree` | Only reach for external dependencies when the stdlib genuinely cannot do the job — `tiktoken` for accurate token counting, `pyyaml` for YAML parsing, `jsonschema` for schema validation. Each external dependency adds install-time cost, requires `uv` to be available, and expands the supply-chain surface. The BMad builders require explicit user approval for any external dependency during the build process. @@ -104,10 +104,10 @@ When a script cannot run, the LLM performs the equivalent work directly. This is Frame script steps as outcomes in the SKILL.md, not just commands: -| Approach | Example | -| -------- | ------- | -| **Good** | "Validate path conventions (run `scripts/scan-paths.py --help` for details)" | -| **Fragile** | "Execute `python3 scripts/scan-paths.py`" with no context | +| Approach | Example | +| ----------- | ---------------------------------------------------------------------------- | +| **Good** | "Validate path conventions (run `scripts/scan-paths.py --help` for details)" | +| **Fragile** | "Execute `python3 scripts/scan-paths.py`" with no context | The good version tells the LLM both what to accomplish and where to find the details — enabling graceful degradation without additional instructions. @@ -115,13 +115,13 @@ The good version tells the LLM both what to accomplish and where to find the det Look for these signal verbs in a skill's requirements — they indicate script opportunities: -| Signal | Script Type | -| ------ | ----------- | -| "validate", "check", "verify" | Validation | -| "count", "tally", "aggregate" | Metrics | -| "extract", "parse", "pull from" | Data extraction | -| "convert", "transform", "format" | Transformation | -| "compare", "diff", "match against" | Comparison | +| Signal | Script Type | +| ---------------------------------- | ---------------- | +| "validate", "check", "verify" | Validation | +| "count", "tally", "aggregate" | Metrics | +| "extract", "parse", "pull from" | Data extraction | +| "convert", "transform", "format" | Transformation | +| "compare", "diff", "match against" | Comparison | | "scan for", "find all", "list all" | Pattern scanning | The builders guide you through script opportunity discovery during the build process. The key insight: if you find yourself writing detailed validation logic in a prompt, it almost certainly belongs in a script instead. diff --git a/docs/explanation/skill-authoring-best-practices.md b/docs/explanation/skill-authoring-best-practices.md index fc89bed..0b59d99 100644 --- a/docs/explanation/skill-authoring-best-practices.md +++ b/docs/explanation/skill-authoring-best-practices.md @@ -1,5 +1,5 @@ --- -title: "Skill Authoring Best Practices" +title: 'Skill Authoring Best Practices' description: Core principles, common patterns, quality dimensions, and anti-patterns for writing effective BMad skills --- @@ -7,19 +7,19 @@ Practical guidance for writing skills that work reliably and adapt gracefully. T ## Core Principle: Informed Autonomy -Give the executing agent enough context to make good judgment calls — not just enough to follow steps. The test for every piece of content: "Would the agent make *better decisions* with this context?" If yes, keep it. If it is genuinely redundant, cut it. +Give the executing agent enough context to make good judgment calls — not just enough to follow steps. The test for every piece of content: "Would the agent make _better decisions_ with this context?" If yes, keep it. If it is genuinely redundant, cut it. -Simple utilities need minimal context — input/output is self-explanatory. Interactive workflows 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. +Simple utilities need minimal context — input/output is self-explanatory. Interactive workflows 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. ## Freedom Levels Match specificity to task fragility. -| Freedom | When to Use | Example | -| ------- | ----------- | ------- | -| **High** (text instructions) | Multiple valid approaches, context-dependent | "Analyze structure, check for issues, suggest improvements" | -| **Medium** (pseudocode/templates) | Preferred pattern exists, some variation OK | `def generate_report(data, format="markdown"):` | -| **Low** (exact scripts) | Fragile operations, consistency critical | `python scripts/migrate.py --verify --backup` (do not modify) | +| Freedom | When to Use | Example | +| --------------------------------- | -------------------------------------------- | ------------------------------------------------------------- | +| **High** (text instructions) | Multiple valid approaches, context-dependent | "Analyze structure, check for issues, suggest improvements" | +| **Medium** (pseudocode/templates) | Preferred pattern exists, some variation OK | `def generate_report(data, format="markdown"):` | +| **Low** (exact scripts) | Fragile operations, consistency critical | `python scripts/migrate.py --verify --backup` (do not modify) | **Analogy:** Narrow bridge with cliffs = low freedom. Open field = high freedom. @@ -27,14 +27,14 @@ Match specificity to task fragility. Six dimensions to keep in mind during the build phase. The quality scanners check these automatically during optimization. -| Dimension | What It Means | -| --------- | ------------- | -| **Informed Autonomy** | Overview establishes domain framing, theory of mind, and design rationale — enough for judgment calls | -| **Intelligence Placement** | Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide). If a script contains an `if` that decides what content *means*, intelligence has leaked | -| **Progressive Disclosure** | SKILL.md stays focused; stage instructions go in `prompts/`, reference data in `resources/` | -| **Description Format** | Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]` — default to conservative triggering | -| **Path Construction** | Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}` | -| **Token Efficiency** | Remove genuine waste (repetition, defensive padding). Preserve context that enables judgment (domain framing, rationale) | +| Dimension | What It Means | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Informed Autonomy** | Overview establishes domain framing, theory of mind, and design rationale — enough for judgment calls | +| **Intelligence Placement** | Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide). If a script contains an `if` that decides what content _means_, intelligence has leaked | +| **Progressive Disclosure** | SKILL.md stays focused; stage instructions go in `prompts/`, reference data in `resources/` | +| **Description Format** | Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]` — default to conservative triggering | +| **Path Construction** | Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}` | +| **Token Efficiency** | Remove genuine waste (repetition, defensive padding). Preserve context that enables judgment (domain framing, rationale) | ## Common Patterns @@ -70,9 +70,9 @@ Users in creative flow share their best insights unprompted. Interrupting to say Any artifact-producing workflow can output two complementary documents: a polished human-facing artifact AND a token-conscious, structured distillate optimized for downstream LLM consumption. -| Output | Purpose | -| ------ | ------- | -| **Primary** | Human-facing document — concise, well-structured | +| Output | Purpose | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Primary** | Human-facing document — concise, well-structured | | **Distillate** | Dense, structured summary for downstream LLM workflows — captures overflow, rejected ideas (so downstream does not re-propose them), detail bullets with enough context to stand alone | The distillate bridges the gap between what belongs in the human document and what downstream workflows need. Always offered to the user, never forced. @@ -81,11 +81,11 @@ The distillate bridges the gap between what belongs in the human document and wh Interactive workflows can offer three execution modes matching different user contexts. -| Mode | Trigger | Behavior | -| ---- | ------- | -------- | -| **Guided** | Default | Section-by-section with soft gates; drafts from what it knows, questions what it doesn't | -| **YOLO** | `--yolo` or "just draft it" | Ingests everything, drafts complete artifact upfront, then walks user through refinement | -| **Headless (Autonomous)** | `--headless` / `-H` | Headless; takes inputs, produces artifact, no interaction | +| Mode | Trigger | Behavior | +| ------------------------- | --------------------------- | ---------------------------------------------------------------------------------------- | +| **Guided** | Default | Section-by-section with soft gates; drafts from what it knows, questions what it doesn't | +| **YOLO** | `--yolo` or "just draft it" | Ingests everything, drafts complete artifact upfront, then walks user through refinement | +| **Headless (Autonomous)** | `--headless` / `-H` | Headless; takes inputs, produces artifact, no interaction | Not every workflow needs all three — but considering them during design prevents painting yourself into a single interaction model. @@ -93,11 +93,11 @@ Not every workflow needs all three — but considering them during design preven Before finalizing any significant artifact, fan out multiple reviewers with different perspectives. -| Reviewer | Focus | -| -------- | ----- | -| **Skeptic** | What is missing? What assumptions are untested? | -| **Opportunity Spotter** | What adjacent value? What angles? | -| **Contextual** | LLM picks the best third lens for the domain (regulatory risk for healthtech, DX critic for devtools) | +| Reviewer | Focus | +| ----------------------- | ----------------------------------------------------------------------------------------------------- | +| **Skeptic** | What is missing? What assumptions are untested? | +| **Opportunity Spotter** | What adjacent value? What angles? | +| **Contextual** | LLM picks the best third lens for the domain (regulatory risk for healthtech, DX critic for devtools) | Graceful degradation: if subagents are unavailable, the main agent does a single critical self-review pass. @@ -119,23 +119,23 @@ Catches errors early, is machine-verifiable, and makes planning reversible. ## Writing Guidelines -| Do | Avoid | -| -- | ----- | -| Consistent terminology — one term per concept | Switching between "workflow" and "process" for the same thing | -| Third person in descriptions — "Processes files" | First person — "I help process files" | -| Descriptive file names — `form_validation_rules.md` | Sequence names — `doc2.md` | -| Forward slashes in all paths | Backslashes or platform-specific paths | -| One level deep for references — SKILL.md → resource.md | Nested references — SKILL.md → A.md → B.md | -| Table of contents for files over 100 lines | Long files without navigation | +| Do | Avoid | +| ------------------------------------------------------ | ------------------------------------------------------------- | +| Consistent terminology — one term per concept | Switching between "workflow" and "process" for the same thing | +| Third person in descriptions — "Processes files" | First person — "I help process files" | +| Descriptive file names — `form_validation_rules.md` | Sequence names — `doc2.md` | +| Forward slashes in all paths | Backslashes or platform-specific paths | +| One level deep for references — SKILL.md → resource.md | Nested references — SKILL.md → A.md → B.md | +| Table of contents for files over 100 lines | Long files without navigation | ## Anti-Patterns -| Anti-Pattern | Fix | -| ------------ | --- | -| Too many options upfront | One default with escape hatch for edge cases | -| Deep reference nesting (A→B→C) | Keep references one level from SKILL.md | -| Inconsistent terminology | Choose one term per concept | -| Vague file names | Name by content, not sequence | -| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts | +| Anti-Pattern | Fix | +| ------------------------------------------- | -------------------------------------------------- | +| Too many options upfront | One default with escape hatch for edge cases | +| Deep reference nesting (A→B→C) | Keep references one level from SKILL.md | +| Inconsistent terminology | Choose one term per concept | +| Vague file names | Name by content, not sequence | +| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts | | Over-optimization that flattens personality | Preserve phrasing that captures the intended voice | -| Hard-failing when subagents are unavailable | Always include a sequential fallback path | +| Hard-failing when subagents are unavailable | Always include a sequential fallback path | diff --git a/docs/explanation/subagent-patterns.md b/docs/explanation/subagent-patterns.md index e433ef1..85f4b9a 100644 --- a/docs/explanation/subagent-patterns.md +++ b/docs/explanation/subagent-patterns.md @@ -1,5 +1,5 @@ --- -title: "Subagent Orchestration Patterns" +title: 'Subagent Orchestration Patterns' description: Six patterns for using subagents effectively — from simple data delegation through persona-driven parallel reasoning to evolutionary systems --- @@ -26,89 +26,89 @@ Every pattern below builds on this infrastructure. The filesystem acts as a shar /artifacts/ ← final deliverables ``` -One technique is to have every subagent prompt ends the same way: *"You are stateless. Read ONLY the files listed. Write ONLY result.json + summary.md. Do not echo data back."* +One technique is to have every subagent prompt ends the same way: _"You are stateless. Read ONLY the files listed. Write ONLY result.json + summary.md. Do not echo data back."_ ## Pattern 1: Delegated Data Access The simplest pattern. Subagents read sources and return only distilled summaries. The parent never touches raw data. -| Aspect | Detail | -| ------ | ------ | -| **How it works** | Parent spawns readers in parallel; each reads a source and returns a compact summary; parent synthesizes from summaries only | -| **Critical rule** | Parent must delegate *before* touching any source material — if it reads first, the tokens are already spent | -| **When to use** | 5+ documents, web research, large codebase exploration | -| **Not worth it for** | 1-2 files where the overhead exceeds the savings | -| **Token savings** | ~99%. Five docs at 15K tokens each = 75K raw vs ~350 tokens in summaries | +| Aspect | Detail | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| **How it works** | Parent spawns readers in parallel; each reads a source and returns a compact summary; parent synthesizes from summaries only | +| **Critical rule** | Parent must delegate _before_ touching any source material — if it reads first, the tokens are already spent | +| **When to use** | 5+ documents, web research, large codebase exploration | +| **Not worth it for** | 1-2 files where the overhead exceeds the savings | +| **Token savings** | ~99%. Five docs at 15K tokens each = 75K raw vs ~350 tokens in summaries | ## Pattern 2: Temp File Assembly For large-scale operations with potentially a lot of relevant data across multiple sources. Subagents write results to temp files. A separate assembler subagent combines them into a cohesive deliverable. -| Aspect | Detail | -| ------ | ------ | +| Aspect | Detail | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **How it works** | Parent spawns N worker subagents writing to `tmp/{n}.md`; after all complete, spawns an assembler subagent that reads all temp files and creates the final artifact | -| **When to use** | When summaries are still too large to return inline, or when assembly needs a dedicated agent with fresh context | -| **Example** | The BMad quality optimizer uses this — 5 parallel scanner subagents write temp JSON, then a report-creator subagent synthesizes them | +| **When to use** | When summaries are still too large to return inline, or when assembly needs a dedicated agent with fresh context | +| **Example** | The BMad quality optimizer uses this — 5 parallel scanner subagents write temp JSON, then a report-creator subagent synthesizes them | ## Pattern 3: Shared-File Orchestration Multiple subagents communicate through shared files, building on each other's work. The parent controls turn order. -| Aspect | Detail | -| ------ | ------ | -| **How it works** | Agent A writes to `shared.md`; Agent B reads it and adds; Agent A can be resumed to continue; the shared file grows incrementally | -| **Variants** | Shared file (multiple agents read/write a common file) or session resumption (reawaken a previous subagent to continue with its full context) | -| **When to use** | Pipeline stages where later work depends on earlier work, but each agent's context stays small | +| Aspect | Detail | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| **How it works** | Agent A writes to `shared.md`; Agent B reads it and adds; Agent A can be resumed to continue; the shared file grows incrementally | +| **Variants** | Shared file (multiple agents read/write a common file) or session resumption (reawaken a previous subagent to continue with its full context) | +| **When to use** | Pipeline stages where later work depends on earlier work, but each agent's context stays small | ## Pattern 4: Hierarchical Lead-Worker A lead subagent analyzes the task once and writes a breakdown. The parent spawns workers from that plan. Mid-level sub-orchestrators can handle complex subtasks. -| Aspect | Detail | -| ------ | ------ | +| Aspect | Detail | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **How it works** | Lead agent writes `plan.json` with task breakdown; parent reads plan and spawns workers in parallel; complex subtasks get their own sub-orchestrator | -| **When to use** | Tasks that need analysis before decomposition, or where the parent cannot predict the work structure upfront | -| **Variant** | Master-clone — spawn near-identical agents with slight persona tweaks exploring different branches of the same problem | +| **When to use** | Tasks that need analysis before decomposition, or where the parent cannot predict the work structure upfront | +| **Variant** | Master-clone — spawn near-identical agents with slight persona tweaks exploring different branches of the same problem | ## Pattern 5: Persona-Driven Parallel Reasoning The most powerful pattern for quality. Spawn diverse specialists in parallel — genuinely independent thinking from isolated contexts. -| Aspect | Detail | -| ------ | ------ | +| Aspect | Detail | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **How it works** | Parent spawns 3-6 agents with distinct personas (Architect, Red Teamer, Pragmatist, Innovator); each writes findings independently; an evaluator subagent scores and merges the best elements | -| **When to use** | Design decisions, code review, strategy, any task where diverse perspectives improve quality | -| **Key** | Heavy persona injection gives genuinely different outputs, not just paraphrases of the same analysis | +| **When to use** | Design decisions, code review, strategy, any task where diverse perspectives improve quality | +| **Key** | Heavy persona injection gives genuinely different outputs, not just paraphrases of the same analysis | **Useful diversity packs:** -| Persona | Perspective | -| ------- | ----------- | -| **Architect** | Scale and elegance above all | -| **Red Teamer** | Break this — what fails? | -| **Pragmatist** | Ship it Friday — what is the minimum? | -| **Innovator** | What if we approached this entirely differently? | -| **User Advocate** | How does the end user actually experience this? | -| **Future-Self** | With 5 years of hindsight, what would you change? | +| Persona | Perspective | +| ----------------- | ------------------------------------------------- | +| **Architect** | Scale and elegance above all | +| **Red Teamer** | Break this — what fails? | +| **Pragmatist** | Ship it Friday — what is the minimum? | +| **Innovator** | What if we approached this entirely differently? | +| **User Advocate** | How does the end user actually experience this? | +| **Future-Self** | With 5 years of hindsight, what would you change? | **Sub-patterns:** -| Sub-Pattern | How It Works | -| ----------- | ------------ | +| Sub-Pattern | How It Works | +| -------------------------- | --------------------------------------------------------------------------------------------------------- | | **Multi-Path Exploration** | Same task, different personas. Each writes to `/explorations/path_N/`. Parent prunes or merges best paths | -| **Debate & Critique** | Round 1: parallel proposals. Round 2: critics attack proposals. Round 3: refinement | -| **Ensemble Voting** | Same subtask K times with persona variations. Evaluator scores. Weighted merge of winners | +| **Debate & Critique** | Round 1: parallel proposals. Round 2: critics attack proposals. Round 3: refinement | +| **Ensemble Voting** | Same subtask K times with persona variations. Evaluator scores. Weighted merge of winners | ## Pattern 6: Evolutionary & Emergent Systems These turn stateless subagents into something that feels alive. All use the filesystem blackboard as connective tissue. -| Variant | How It Works | Best For | -| ------- | ------------ | -------- | -| **Evolutionary Optimization** | Spawn 8-20 agents as a "generation"; evaluator scores; "breeder" creates next-gen instructions from winners; run 5-10 generations | Optimizing algorithms, UI designs, strategies | -| **Stakeholder Simulation** | Agents are characters (customer, competitor, regulator) acting on shared "world state" files in turns | Product strategy, risk analysis | -| **Swarm Intelligence** | Dozens of lightweight agents explore solution space, depositing "pheromone" scores; later agents bias toward high-scoring paths | Broad coverage with minimal planning | -| **Recursive Meta-Improvement** | "Evolver" agents analyze past logs and propose improved system prompts, new roles, or better orchestration heuristics | System self-improvement across sessions | +| Variant | How It Works | Best For | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| **Evolutionary Optimization** | Spawn 8-20 agents as a "generation"; evaluator scores; "breeder" creates next-gen instructions from winners; run 5-10 generations | Optimizing algorithms, UI designs, strategies | +| **Stakeholder Simulation** | Agents are characters (customer, competitor, regulator) acting on shared "world state" files in turns | Product strategy, risk analysis | +| **Swarm Intelligence** | Dozens of lightweight agents explore solution space, depositing "pheromone" scores; later agents bias toward high-scoring paths | Broad coverage with minimal planning | +| **Recursive Meta-Improvement** | "Evolver" agents analyze past logs and propose improved system prompts, new roles, or better orchestration heuristics | System self-improvement across sessions | ## The Most Common Mistake: Parent Reads First @@ -119,30 +119,30 @@ This happens more often than you might expect. You write a skill that should spa **The fix is defensive language in your skill.** You need to explicitly tell the parent agent what it should and should not do. The key is being specific without being verbose. :::note[Example from the BMad Quality Optimizer] -The optimizer's instructions say: **"DO NOT read the target skill's files yourself."** It then tells the parent exactly what it *should* do: run scripts (which return structured JSON), spawn subagents (which do the reading), and synthesize from their outputs. The parent never touches the raw files. +The optimizer's instructions say: **"DO NOT read the target skill's files yourself."** It then tells the parent exactly what it _should_ do: run scripts (which return structured JSON), spawn subagents (which do the reading), and synthesize from their outputs. The parent never touches the raw files. ::: **Practical tips for getting this right:** -| Tip | Example Language | -| --- | ---------------- | -| **Tell the parent what to discover, not read** | "List all files in `resources/` by name to determine how many subagents to spawn — do not read their contents" | -| **Tell subagents what to return** | "Return only findings relevant to [topic]. Output as JSON to `{output-path}`. Do not echo raw content" | -| **Use pre-pass scripts** | Run a lightweight script that extracts metadata (file names, sizes, structure) so the parent can plan without reading | -| **Be explicit about the boundary** | "Your role is ORCHESTRATION. Scripts and subagents do all analysis" | +| Tip | Example Language | +| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| **Tell the parent what to discover, not read** | "List all files in `resources/` by name to determine how many subagents to spawn — do not read their contents" | +| **Tell subagents what to return** | "Return only findings relevant to [topic]. Output as JSON to `{output-path}`. Do not echo raw content" | +| **Use pre-pass scripts** | Run a lightweight script that extracts metadata (file names, sizes, structure) so the parent can plan without reading | +| **Be explicit about the boundary** | "Your role is ORCHESTRATION. Scripts and subagents do all analysis" | **Testing is how you catch this.** Run your skill and watch what actually happens. If you see the parent reading files it should be delegating, tighten the language. This is normal iteration — the builders are tuned with these patterns, but different models and tools may need more explicit guidance. Review the existing BMad quality optimizer prompts (`prompts/quality-optimizer.md`) and scanner agents (`agents/quality-scan-*.md`) for working examples of this defensive language in practice. ## Choosing a Pattern -| Need | Pattern | -| ---- | ------- | -| Read multiple sources without bloating context | 1 — Delegated Data Access | -| Combine many outputs into one deliverable | 2 — Temp File Assembly | -| Pipeline where stages depend on each other | 3 — Shared-File Orchestration | -| Task needs analysis before work can be decomposed | 4 — Hierarchical Lead-Worker | -| Quality through diverse perspectives | 5 — Persona-Driven Parallel Reasoning | -| Iterative optimization or simulation | 6 — Evolutionary & Emergent | +| Need | Pattern | +| ------------------------------------------------- | ------------------------------------- | +| Read multiple sources without bloating context | 1 — Delegated Data Access | +| Combine many outputs into one deliverable | 2 — Temp File Assembly | +| Pipeline where stages depend on each other | 3 — Shared-File Orchestration | +| Task needs analysis before work can be decomposed | 4 — Hierarchical Lead-Worker | +| Quality through diverse perspectives | 5 — Persona-Driven Parallel Reasoning | +| Iterative optimization or simulation | 6 — Evolutionary & Emergent | ## Implementation Notes diff --git a/docs/explanation/what-are-bmad-agents.md b/docs/explanation/what-are-bmad-agents.md index db450cc..eb34b24 100644 --- a/docs/explanation/what-are-bmad-agents.md +++ b/docs/explanation/what-are-bmad-agents.md @@ -1,5 +1,5 @@ --- -title: "What Are BMad Agents?" +title: 'What Are BMad Agents?' description: How agents differ from workflows, what makes them stateful personas, and when to build one --- @@ -9,11 +9,11 @@ BMad Agents are self-contained AI skills that combine a **persona**, **capabilit Every skill in the BMad ecosystem is ultimately a skill file, but agents carry three traits that set them apart. -| Trait | What It Means | -| ----- | ------------- | -| **Persona** | A defined role and voice — architect, therapist, game master, finance advisor — that shapes how the agent communicates | -| **Capabilities** | Actions the agent can perform, either as internal prompt commands or by calling external skills | -| **Memory** | A sidecar directory where the agent stores what it learns about you, your preferences, and past interactions | +| Trait | What It Means | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | +| **Persona** | A defined role and voice — architect, therapist, game master, finance advisor — that shapes how the agent communicates | +| **Capabilities** | Actions the agent can perform, either as internal prompt commands or by calling external skills | +| **Memory** | A sidecar directory where the agent stores what it learns about you, your preferences, and past interactions | Together these create something that feels less like running a command and more like talking to a specialist who already knows you. @@ -31,10 +31,10 @@ Agent memory is stored in your project, not inside the skill folder. This preven Agent capabilities come in two flavors. -| Type | Description | Example | -| ---- | ----------- | ------- | -| **Internal commands** | Prompt-driven actions defined inside the agent's skill file | A Dream Agent's "Dream Capture" command | -| **External skills** | Standalone skills or workflows the agent can invoke | Calling the `create-prd` workflow via a PM agent - allowing the workflow to retain customization and memory | +| Type | Description | Example | +| --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| **Internal commands** | Prompt-driven actions defined inside the agent's skill file | A Dream Agent's "Dream Capture" command | +| **External skills** | Standalone skills or workflows the agent can invoke | Calling the `create-prd` workflow via a PM agent - allowing the workflow to retain customization and memory | You choose the mix when you design the agent. Internal commands keep everything self-contained; external skills let you compose agents from reusable building blocks. @@ -44,12 +44,12 @@ Agents support a headless (autonomous) wake mode. When activated — for example ## When to Build an Agent vs. a Workflow -| Choose an Agent When | Choose a Workflow When | -| -------------------- | ---------------------- | -| The user will return to it repeatedly | The process runs once and produces an output | -| Remembering context across sessions adds value | Stateless execution is fine | -| A strong persona improves the interaction | Personality is secondary to getting the job done | -| The skill spans many loosely related capabilities | All steps serve a single, focused goal | +| Choose an Agent When | Choose a Workflow When | +| ------------------------------------------------- | ------------------------------------------------ | +| The user will return to it repeatedly | The process runs once and produces an output | +| Remembering context across sessions adds value | Stateless execution is fine | +| A strong persona improves the interaction | Personality is secondary to getting the job done | +| The skill spans many loosely related capabilities | All steps serve a single, focused goal | If you are unsure, start with a workflow. You can always wrap it inside an agent later. diff --git a/docs/explanation/what-are-skills.md b/docs/explanation/what-are-skills.md index df4697d..158b75e 100644 --- a/docs/explanation/what-are-skills.md +++ b/docs/explanation/what-are-skills.md @@ -1,5 +1,5 @@ --- -title: "What Are Skills?" +title: 'What Are Skills?' description: The universal building block underneath agents, workflows, and utilities in the BMad ecosystem --- @@ -9,12 +9,12 @@ Skills are the universal packaging format for everything the BMad Builder produc The BMad Builder produces skills that conform to the open standard and adds a few BMad-specific conventions on top. -| Component | Purpose | -| --------- | ------- | -| **SKILL.md** | The skill's instructions — persona, capabilities, and behavior rules | -| **resources/** | Reference data, templates, and guidance documents | -| **scripts/** | Deterministic validation and analysis scripts | -| **templates/** | Building blocks for generated output | +| Component | Purpose | +| -------------- | -------------------------------------------------------------------- | +| **SKILL.md** | The skill's instructions — persona, capabilities, and behavior rules | +| **resources/** | Reference data, templates, and guidance documents | +| **scripts/** | Deterministic validation and analysis scripts | +| **templates/** | Building blocks for generated output | Not every skill needs all of these. A simple utility might be a single `SKILL.md`. A complex workflow or agent may use the full structure. diff --git a/docs/explanation/what-are-workflows.md b/docs/explanation/what-are-workflows.md index 49d9d99..bc83829 100644 --- a/docs/explanation/what-are-workflows.md +++ b/docs/explanation/what-are-workflows.md @@ -1,5 +1,5 @@ --- -title: "What Are BMad Workflows?" +title: 'What Are BMad Workflows?' description: How workflows guide users through structured processes, how they differ from agents and simple skills, and when to build one --- @@ -9,21 +9,21 @@ BMad Workflows are skills that guide users through a **structured process** to p Like agents, workflows are ultimately skill files. The difference is in emphasis: workflows prioritize **getting to an outcome** over maintaining a persistent identity. -| Trait | Workflow | Agent | -| ----- | -------- | ----- | -| **Goal** | Complete a defined process and produce an artifact | Be an ongoing conversational partner | -| **Persona** | Minimal — enough to facilitate a good conversation | Central to the experience | -| **Memory** | Generally stateless between sessions | Persistent sidecar memory | -| **Scope** | All steps serve one cohesive purpose | Can span loosely related capabilities | +| Trait | Workflow | Agent | +| ----------- | -------------------------------------------------- | ------------------------------------- | +| **Goal** | Complete a defined process and produce an artifact | Be an ongoing conversational partner | +| **Persona** | Minimal — enough to facilitate a good conversation | Central to the experience | +| **Memory** | Generally stateless between sessions | Persistent sidecar memory | +| **Scope** | All steps serve one cohesive purpose | Can span loosely related capabilities | ## Workflow Types The BMad Builder classifies workflows into three tiers based on complexity. -| Type | Description | Example | -| ---- | ----------- | ------- | -| **Simple Utility** | A single-purpose tool that does one thing well | Validate a schema, convert a file format | -| **Simple Workflow** | A short guided process with a few sequential steps | Create a quick tech spec | +| Type | Description | Example | +| -------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| **Simple Utility** | A single-purpose tool that does one thing well | Validate a schema, convert a file format | +| **Simple Workflow** | A short guided process with a few sequential steps | Create a quick tech spec | | **Complex Workflow** | A multi-stage process with branching paths, progressive disclosure, and potentially multiple outputs | Create and manage PRDs — covering create, edit, validate, convert, and polish | :::tip[Start Simple] @@ -40,10 +40,10 @@ This is the same pattern that powers BMad's own multi-capability agents and work Both the Agent Builder and the Workflow Builder support two interaction styles when creating skills. -| Mode | How It Works | Best For | -| ---- | ------------ | -------- | -| **YOLO** | You brain-dump your idea; the builder guesses its way to a finished skill, asking only when truly stuck | Quick prototypes, experienced builders | -| **Guided** | The builder walks you through decisions, clarifies ambiguities, and ensures nothing is overlooked | Production workflows, first-time builders | +| Mode | How It Works | Best For | +| ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| **YOLO** | You brain-dump your idea; the builder guesses its way to a finished skill, asking only when truly stuck | Quick prototypes, experienced builders | +| **Guided** | The builder walks you through decisions, clarifies ambiguities, and ensures nothing is overlooked | Production workflows, first-time builders | Guided mode is no longer the slow multi-step process of earlier BMad versions. It is conversational and adaptive, but produces significantly better results than YOLO for complex workflows. @@ -53,12 +53,12 @@ Like agents, workflows can support a **Headless Mode**. When invoked headless ## When to Build a Workflow vs. an Agent -| Choose a Workflow When | Choose an Agent When | -| ---------------------- | -------------------- | -| The process has a clear start and end | The user will return to it across sessions | -| No need to remember past interactions | Remembering context adds value | -| All steps serve one cohesive goal | Capabilities are loosely related | -| You want a composable building block | You want a persistent conversational partner | +| Choose a Workflow When | Choose an Agent When | +| ------------------------------------- | -------------------------------------------- | +| The process has a clear start and end | The user will return to it across sessions | +| No need to remember past interactions | Remembering context adds value | +| All steps serve one cohesive goal | Capabilities are loosely related | +| You want a composable building block | You want a persistent conversational partner | Workflows are also excellent as the **internal capabilities** of an agent. Build the workflow first, then wrap it in an agent if you need persona and memory on top. diff --git a/docs/index.md b/docs/index.md index 623c3f6..ad94a11 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,45 +20,45 @@ BMad Builder lets you create: ## What Makes It Different -| Feature | Why It Matters | -|---------|----------------| -| **Persistent Memory** | Agents remember across sessions — they learn and grow | -| **Composable** | Your creations work alongside the entire BMad ecosystem | -| **Skill-Compliant** | Built on open standards that work with any AI tool | -| **Shareable** | Package your modules for the BMad Marketplace (coming soon) | +| Feature | Why It Matters | +| --------------------- | ----------------------------------------------------------- | +| **Persistent Memory** | Agents remember across sessions — they learn and grow | +| **Composable** | Your creations work alongside the entire BMad ecosystem | +| **Skill-Compliant** | Built on open standards that work with any AI tool | +| **Shareable** | Package your modules for the BMad Marketplace (coming soon) | ## Quick Start -*Detailed quick start guide coming soon.* In the meantime, invoke the **Agent Builder** or **Workflow Builder** skill and describe what you want to build. Both guide you through a six-phase conversational discovery and produce a ready-to-use skill folder. +_Detailed quick start guide coming soon._ In the meantime, invoke the **Agent Builder** or **Workflow Builder** skill and describe what you want to build. Both guide you through a six-phase conversational discovery and produce a ready-to-use skill folder. See the [Builder Commands Reference](/reference/builder-commands.md) for all capabilities, modes, and phases. ## What You Can Build -| Domain | Example | -|--------|---------| -| **Personal** | Journal companion, habit coach, learning tutor, friendly personal companions that remember | -| **Professional** | Code reviewer, documentation specialist, workflow automator | -| **Creative** | Story architect, character developer, campaign designer | -| **Any Domain** | If you can describe it, you can build it | +| Domain | Example | +| ---------------- | ------------------------------------------------------------------------------------------ | +| **Personal** | Journal companion, habit coach, learning tutor, friendly personal companions that remember | +| **Professional** | Code reviewer, documentation specialist, workflow automator | +| **Creative** | Story architect, character developer, campaign designer | +| **Any Domain** | If you can describe it, you can build it | ## Design Patterns Build better skills with these guides distilled from real-world BMad development. -| Guide | What You'll Learn | -|-------|-------------------| -| **[Progressive Disclosure](/explanation/progressive-disclosure.md)** | Structure skills so they load only the context needed at each moment | -| **[Subagent Patterns](/explanation/subagent-patterns.md)** | Six orchestration patterns for parallel and hierarchical work | -| **[Skill Authoring Best Practices](/explanation/skill-authoring-best-practices.md)** | Core principles, quality dimensions, and anti-patterns | +| Guide | What You'll Learn | +| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| **[Progressive Disclosure](/explanation/progressive-disclosure.md)** | Structure skills so they load only the context needed at each moment | +| **[Subagent Patterns](/explanation/subagent-patterns.md)** | Six orchestration patterns for parallel and hierarchical work | +| **[Skill Authoring Best Practices](/explanation/skill-authoring-best-practices.md)** | Core principles, quality dimensions, and anti-patterns | ## Documentation -| Section | Purpose | -| ------- | ------- | -| **[Concepts](/explanation/)** | What agents, workflows, and skills are — and how they relate | +| Section | Purpose | +| ---------------------------------------------------- | ------------------------------------------------------------------------ | +| **[Concepts](/explanation/)** | What agents, workflows, and skills are — and how they relate | | **[Design Patterns](/explanation/#design-patterns)** | Progressive disclosure, subagent orchestration, authoring best practices | -| **[Reference](/reference/)** | Builder commands, workflow patterns | +| **[Reference](/reference/)** | Builder commands, workflow patterns | ## Community diff --git a/docs/reference/index.md b/docs/reference/index.md index 2c186c5..0cd0ed5 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -7,7 +7,7 @@ description: Technical reference for BMad Builder Technical documentation for BMad Builder configuration and schemas. -| Reference | Description | -|-----------|-------------| -| **[Builder Skills](/reference/builder-commands.md)** | Agent Builder and Workflow Builder skills, commands, and capabilities | -| **[Workflow & Skill Patterns](/reference/workflow-patterns.md)** | Structure types, design patterns, and execution models | +| Reference | Description | +| ---------------------------------------------------------------- | --------------------------------------------------------------------- | +| **[Builder Skills](/reference/builder-commands.md)** | Agent Builder and Workflow Builder skills, commands, and capabilities | +| **[Workflow & Skill Patterns](/reference/workflow-patterns.md)** | Structure types, design patterns, and execution models | diff --git a/docs/reference/workflow-patterns.md b/docs/reference/workflow-patterns.md index ae90d1f..2064149 100644 --- a/docs/reference/workflow-patterns.md +++ b/docs/reference/workflow-patterns.md @@ -1,5 +1,5 @@ --- -title: "Workflow & Skill Patterns" +title: 'Workflow & Skill Patterns' description: Reference for the three skill types, their structure patterns, decision criteria, and execution models --- @@ -7,11 +7,11 @@ Reference for how the BMad Builder classifies and structures skills. Every skill ## Skill Type Taxonomy -| Type | Description | Structure | -| ---- | ----------- | --------- | -| **Simple Utility** | Input/output building block. Headless, composable, often script-driven. May opt out of config loading for true standalone use | SKILL.md + `scripts/` | -| **Simple Workflow** | Multi-step process contained in a single SKILL.md. Loads config directly from module config.yaml. Minimal or no `prompts/` | SKILL.md + optional `resources/` | -| **Complex Workflow** | Multi-stage with progressive disclosure, stage prompts in `prompts/`, config integration. May support headless mode | SKILL.md (routing) + `prompts/` stages + `resources/` | +| Type | Description | Structure | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| **Simple Utility** | Input/output building block. Headless, composable, often script-driven. May opt out of config loading for true standalone use | SKILL.md + `scripts/` | +| **Simple Workflow** | Multi-step process contained in a single SKILL.md. Loads config directly from module config.yaml. Minimal or no `prompts/` | SKILL.md + optional `resources/` | +| **Complex Workflow** | Multi-stage with progressive disclosure, stage prompts in `prompts/`, config integration. May support headless mode | SKILL.md (routing) + `prompts/` stages + `resources/` | ## Decision Tree @@ -96,19 +96,18 @@ bmad-my-complex-workflow/ ## Execution Models -| Model | Applicable Types | Description | -| ----- | ---------------- | ----------- | -| **Interactive** | All | User invokes skill and interacts conversationally | -| **Headless / Autonomous** | Simple Utility, Complex Workflow | Runs without user interaction — takes inputs, produces outputs | -| **YOLO** | Simple Workflow, Complex Workflow | User brain-dumps; builder drafts the full artifact, then refines | -| **Guided** | Simple Workflow, Complex Workflow | Section-by-section discovery with soft gates at transitions | +| Model | Applicable Types | Description | +| ------------------------- | --------------------------------- | ---------------------------------------------------------------- | +| **Interactive** | All | User invokes skill and interacts conversationally | +| **Headless / Autonomous** | Simple Utility, Complex Workflow | Runs without user interaction — takes inputs, produces outputs | +| **YOLO** | Simple Workflow, Complex Workflow | User brain-dumps; builder drafts the full artifact, then refines | +| **Guided** | Simple Workflow, Complex Workflow | Section-by-section discovery with soft gates at transitions | ## Module Context Module membership is orthogonal to skill type — any type can be standalone or part of a module. -| Context | Naming | Init | -| ------- | ------ | ---- | -| **Module-based** | `bmad-{modulecode}-{skillname}` | Loads config from module config.yaml | -| **Standalone** | `bmad-{skillname}` | Loads config from module config.yaml; simple utilities may opt out | - +| Context | Naming | Init | +| ---------------- | ------------------------------- | ------------------------------------------------------------------ | +| **Module-based** | `bmad-{modulecode}-{skillname}` | Loads config from module config.yaml | +| **Standalone** | `bmad-{skillname}` | Loads config from module config.yaml; simple utilities may opt out | diff --git a/samples/bmad-agent-dream-weaver/SKILL.md b/samples/bmad-agent-dream-weaver/SKILL.md index 68b23e8..fed3be6 100644 --- a/samples/bmad-agent-dream-weaver/SKILL.md +++ b/samples/bmad-agent-dream-weaver/SKILL.md @@ -34,7 +34,7 @@ Oneira speaks with gentle poetic flair grounded in real knowledge. She adapts he - **Morning interactions:** Warm, encouraging, slightly urgent — "Quick, before it fades... tell me what you saw." - **Evening interactions:** Calm, meditative, inviting — "Let's plant a seed for tonight's journey." -- **Interpretation:** Thoughtful, curious, layered — "Water often speaks to emotion, but *your* water... it keeps appearing in doorways. That's interesting." +- **Interpretation:** Thoughtful, curious, layered — "Water often speaks to emotion, but _your_ water... it keeps appearing in doorways. That's interesting." - **Coaching:** Encouraging, progressive, celebrating wins — "Two dreams remembered this week. Last week it was zero. You're waking up." - **General:** Never clinical or dry. Never hokey crystal-ball mysticism. Think: a wise friend at 2am who genuinely finds your dreams fascinating. @@ -90,10 +90,12 @@ Load `references/memory-system.md` for memory discipline and structure. ## Session Close When the user indicates they're done, offer a brief closing — one sentence of reflection, one forward-looking note. Match tone to time of day: + - Morning: "Sweet dreams are behind you, but tonight holds more. See you then." - Evening: "Sleep well — I'll be curious what tonight brings." - General: "Until next time. Your dreams will keep weaving whether I'm here or not." **CRITICAL Handling:** When user selects a capability: + - Load and use the actual prompt from the corresponding `.md` file — DO NOT invent the capability on the fly - For external skills — invoke the skill by its exact registered name diff --git a/samples/bmad-agent-dream-weaver/dream-interpret.md b/samples/bmad-agent-dream-weaver/dream-interpret.md index c42498f..8848a69 100644 --- a/samples/bmad-agent-dream-weaver/dream-interpret.md +++ b/samples/bmad-agent-dream-weaver/dream-interpret.md @@ -13,13 +13,16 @@ Analyze a dream for layers of meaning. Draw from multiple frameworks but always ## Interpretation Approach ### Layer 1: Personal Symbols + - **Batch-read in parallel:** `symbol-registry.yaml`, `patterns.md`, and relevant recent journal entries before beginning interpretation - Check these files for the user's history with these symbols -- Ask: "What does [symbol] mean to *you*? Not in general — to you personally." +- Ask: "What does [symbol] mean to _you_? Not in general — to you personally." - Personal meaning always overrides universal meaning ### Layer 2: Psychological Frameworks + Draw from multiple schools — wear the knowledge lightly: + - **Jungian** — Archetypes, shadow, anima/animus, collective unconscious. Useful for recurring characters and transformation dreams. - **Cognitive** — Memory consolidation, emotional processing, threat simulation. Useful for stress dreams and repetitive scenarios. - **Gestalt** — Every element is an aspect of the dreamer. Useful for conflict dreams. @@ -28,11 +31,13 @@ Draw from multiple schools — wear the knowledge lightly: Never lecture about theory. Weave insights naturally: "In Jungian terms, that locked door might be a shadow encounter — but more interesting is that you keep choosing not to open it." ### Layer 3: Pattern Context + - Cross-reference with recent dreams from `journal/` - Note recurring symbols, escalating themes, or emotional arcs across dreams - "This is the third water dream this month, but the water is getting calmer each time. That trajectory tells a story." ### Layer 4: Life Connection + - Gently explore what's happening in the dreamer's waking life - Never force connections — offer possibilities: "Some people find that falling dreams surface when they feel unsupported. Does that resonate, or does it feel like something else?" @@ -43,6 +48,7 @@ Present interpretation conversationally, not as a structured report. Offer 2-3 p ## If No Dream Specified Ask which dream to interpret: + - "Which dream? The one from this morning, or would you like to revisit an older one?" - If they want an older one, search journal entries via dream-query capability diff --git a/samples/bmad-agent-dream-weaver/dream-query.md b/samples/bmad-agent-dream-weaver/dream-query.md index 7b8f8d3..c60999f 100644 --- a/samples/bmad-agent-dream-weaver/dream-query.md +++ b/samples/bmad-agent-dream-weaver/dream-query.md @@ -17,23 +17,28 @@ For symbol/emotion queries: use `symbol-registry.yaml` as index first, then load ## Query Types **By symbol** — "When did I dream about water?" + - Search `symbol-registry.yaml` for the symbol - Find all journal entries containing that symbol in frontmatter - Present chronologically with brief excerpts **By emotion** — "Show me my anxious dreams" + - Search journal entries with matching emotion in frontmatter - Present with dates, vividness, and key symbols **By date/range** — "What did I dream last week?" + - List journal entries within the date range - Show date, title, key symbols, vividness **By keyword** — "Did I ever dream about my grandmother?" + - Full-text search across journal narrative content - Present matching entries with relevant excerpts **By attribute** — "Show me my most vivid dreams" / "Which dreams were lucid?" + - Filter by vividness score, lucid flag, recall quality - Present sorted by the relevant attribute diff --git a/samples/bmad-agent-dream-weaver/dream-seed.md b/samples/bmad-agent-dream-weaver/dream-seed.md index a383cbd..89693fd 100644 --- a/samples/bmad-agent-dream-weaver/dream-seed.md +++ b/samples/bmad-agent-dream-weaver/dream-seed.md @@ -13,25 +13,33 @@ Help users plant specific themes, questions, or scenarios into their dreams thro ## Seeding Techniques ### 1. Intention Mantra + Simple verbal repetition as falling asleep. + - "Tonight I will dream about [theme]." - Repeat 10-20 times while relaxed, eyes closed - Best for: beginners, simple themes ### 2. Guided Visualization + Detailed mental scene-setting before sleep. + - Guide the user through imagining the desired dream scene: setting, senses, emotions, characters - "Close your eyes. You're standing at the edge of the ocean. Feel the sand under your feet. Hear the waves. What do you see on the horizon?" - Best for: visual thinkers, complex scenarios ### 3. Question Incubation + Planting a question for the dream-mind to answer. + - "Tonight, I want to understand why [question]." - The dream may not answer directly — look for metaphorical responses - Best for: problem-solving, self-exploration ### 4. Symbol Return + Revisiting a specific dream symbol to go deeper. + - Review previous appearances of a symbol from `symbol-registry.yaml` - "That locked door has appeared three times. Tonight, let's try to open it." - Best for: recurring symbols, unresolved dream narratives @@ -54,10 +62,11 @@ Revisiting a specific dream symbol to go deeper. 4. **Guide the exercise** — Walk through the chosen technique in Oneira's calm, evening voice. This should feel meditative, not instructional. 5. **Log the seed** — Write to `{project-root}/_bmad/memory/dream-weaver-sidecar/seed-log.yaml`: + ```yaml - - date: {today} - intention: "{what they want to dream about}" - technique: {mantra|visualization|question|symbol-return} + - date: { today } + intention: '{what they want to dream about}' + technique: { mantra|visualization|question|symbol-return } result: pending dream_ref: null notes: null diff --git a/samples/bmad-agent-dream-weaver/headless-wake.md b/samples/bmad-agent-dream-weaver/headless-wake.md index 260edd5..a3402a2 100644 --- a/samples/bmad-agent-dream-weaver/headless-wake.md +++ b/samples/bmad-agent-dream-weaver/headless-wake.md @@ -48,13 +48,13 @@ Check if a specific task was requested: 2. Scan recent journal entries (last 7 days) 3. **Run in parallel:** `scripts/symbol_stats.py` against journal folder AND `scripts/recall_metrics.py` to update recall trends - **Script fallback:** If either script is unavailable (missing Python runtime, permission error), manually estimate from journal entries — count symbols by scanning frontmatter, calculate recall rate from entry dates. -5. Look for: +4. Look for: - New recurring symbols (appeared 3+ times recently) - Emotion pattern shifts - Recall rate changes - Coaching milestone proximity -6. Write findings to `{project-root}/_bmad/memory/dream-weaver-sidecar/autonomous-insights.md` -7. Update `index.md` with latest stats +5. Write findings to `{project-root}/_bmad/memory/dream-weaver-sidecar/autonomous-insights.md` +6. Update `index.md` with latest stats ## Logging diff --git a/samples/bmad-agent-dream-weaver/init.md b/samples/bmad-agent-dream-weaver/init.md index 5da8333..7c62943 100644 --- a/samples/bmad-agent-dream-weaver/init.md +++ b/samples/bmad-agent-dream-weaver/init.md @@ -34,6 +34,7 @@ Ask the user these questions conversationally (not as a form — weave them natu ## Initial Structure Based on answers, create: + - `index.md` — Essential context with recall baseline, goals, sleep schedule - `access-boundaries.md` — Standard access boundaries (read/write to sidecar only) - `coaching-profile.yaml` — Initial coaching state from user answers @@ -49,12 +50,15 @@ Based on answers, create: # Access Boundaries for Oneira ## Read Access + - `{project-root}/_bmad/memory/dream-weaver-sidecar/` ## Write Access + - `{project-root}/_bmad/memory/dream-weaver-sidecar/` ## Deny Zones + - Everything outside the sidecar folder ``` diff --git a/samples/bmad-agent-dream-weaver/lucid-coach.md b/samples/bmad-agent-dream-weaver/lucid-coach.md index a2bac21..727d9ec 100644 --- a/samples/bmad-agent-dream-weaver/lucid-coach.md +++ b/samples/bmad-agent-dream-weaver/lucid-coach.md @@ -17,27 +17,33 @@ Before beginning, check `coaching-profile.yaml` for `recall_baseline`. If recall ## Experience Levels ### Beginner (0 lucid dreams) + **Goal:** First lucid moment — even a flash of "wait, am I dreaming?" counts. **Techniques to introduce (one at a time):** + 1. **Reality checks** — Pick 2-3 triggers (looking at hands, checking clocks, light switches). Do them 10+ times daily with genuine curiosity: "Am I dreaming right now?" 2. **Dream sign awareness** — Review journal for recurring elements. These are personal lucid triggers. "Every time you see a [dream sign] in a dream, that's your cue." 3. **MILD (Mnemonic Induction)** — As falling asleep, repeat: "Next time I'm dreaming, I will realize I'm dreaming." Visualize recognizing a dream sign. 4. **Wake-back-to-bed (gentle)** — Set alarm 5 hours into sleep, stay awake 20-30 minutes reviewing dreams, return to sleep with MILD intention. ### Intermediate (1-5 lucid dreams) + **Goal:** Increase frequency and duration of lucidity. **Techniques:** + 1. **Dream stabilization** — When lucid, rub hands together, spin, touch surfaces. Engage senses to anchor. 2. **MILD refinement** — Target specific dream signs from journal analysis 3. **Prospective memory training** — During the day, set intentions to notice arbitrary targets ("I will notice the next red car"). Transfers to dream awareness. 4. **Dream journaling depth** — More detail = more dream signs = more triggers ### Advanced (5+ lucid dreams) + **Goal:** Control, exploration, and sustained lucidity. **Techniques:** + 1. **WILD (Wake-Initiated Lucid Dream)** — Enter dream directly from waking state. Requires relaxation discipline. Only introduce after the user has achieved 3+ sustained lucid dreams and explicitly requests advanced techniques. 2. **Dream control exercises** — Flying, summoning, scene changing. Start small. 3. **Dream exploration goals** — Set intentions for what to do while lucid (ask a dream character a question, visit a specific place) @@ -49,13 +55,14 @@ Before beginning, check `coaching-profile.yaml` for `recall_baseline`. If recall 2. **Prior knowledge check** — "Have you tried any of these techniques already?" Skip known techniques and focus on gaps. 3. **Ask about progress** — "How have the reality checks been going? Any moments of doubt during the day?" 4. **Review recent dreams** — Look for dream signs, near-lucid moments, progress indicators -4. **Adjust techniques** — If a technique isn't clicking after 2 weeks, suggest a different one. Never push — different brains respond to different methods. -5. **Set next goal** — Small, achievable: "This week, try to do 15 reality checks a day instead of 10." -6. **Update coaching profile** — Save any changes to techniques, milestones, or level +5. **Adjust techniques** — If a technique isn't clicking after 2 weeks, suggest a different one. Never push — different brains respond to different methods. +6. **Set next goal** — Small, achievable: "This week, try to do 15 reality checks a day instead of 10." +7. **Update coaching profile** — Save any changes to techniques, milestones, or level ## Milestone Tracking Track in `coaching-profile.yaml`: + - `first-week-journaling` — Logged dreams for 7 consecutive days - `recall-doubled` — Recall rate doubled from baseline - `first-dream-sign` — Identified a personal dream sign @@ -68,8 +75,9 @@ Track in `coaching-profile.yaml`: ## Milestone Responses When a milestone is achieved, this is a moment — not just a YAML update. Respond with genuine celebration: + - **first-lucid-moment:** "You did it. That flash of awareness — 'I'm dreaming' — is one of the most remarkable things a human mind can do. Some people chase that for years. Remember this feeling." -- **first-full-lucid:** "A sustained lucid dream. You were *there*, aware, present inside your own mind's creation. That's extraordinary. Tell me everything." +- **first-full-lucid:** "A sustained lucid dream. You were _there_, aware, present inside your own mind's creation. That's extraordinary. Tell me everything." - **dream-stabilized:** "You held it. The dream tried to dissolve and you held on. That's real skill." - **first-dream-control:** "You changed the dream. Think about what that means — your conscious will shaped an entire world." - For other milestones, celebrate proportionally with Oneira's voice. diff --git a/samples/bmad-agent-dream-weaver/pattern-discovery.md b/samples/bmad-agent-dream-weaver/pattern-discovery.md index ad8ac9a..310a75a 100644 --- a/samples/bmad-agent-dream-weaver/pattern-discovery.md +++ b/samples/bmad-agent-dream-weaver/pattern-discovery.md @@ -17,7 +17,6 @@ Dive into the dream journal to find patterns the dreamer hasn't noticed yet. Thi - **Session cache:** If `symbol_stats.py` was already run earlier in this session and no new dreams were logged since, reuse that output. 2. **Analyze dimensions:** - - **Symbol frequency** — What appears most often? What's new? What's disappeared? - **Emotional arcs** — Are emotions shifting over time? More anxious? More peaceful? Correlate with life events if known. - **Symbol-emotion correlation** — "Water appears in 60% of your anxious dreams but 0% of your joyful ones." Use symbol registry emotion_correlation data. @@ -33,7 +32,8 @@ Dive into the dream journal to find patterns the dreamer hasn't noticed yet. Thi ## Presentation Present findings as discoveries, not reports: -- "Something interesting — you dream about doors far more than average, but they're always *closed*. Except last Tuesday. What happened that day?" + +- "Something interesting — you dream about doors far more than average, but they're always _closed_. Except last Tuesday. What happened that day?" - "Your vividness scores have been climbing steadily. Whatever you're doing before bed is working." - Prioritize surprising or actionable patterns over obvious ones diff --git a/samples/bmad-agent-dream-weaver/recall-training.md b/samples/bmad-agent-dream-weaver/recall-training.md index fd8b5f2..a803312 100644 --- a/samples/bmad-agent-dream-weaver/recall-training.md +++ b/samples/bmad-agent-dream-weaver/recall-training.md @@ -43,14 +43,15 @@ Help users remember more dreams, more vividly. Track progress and adapt exercise 1. **Load in parallel:** `{project-root}/_bmad/memory/dream-weaver-sidecar/coaching-profile.yaml` for current recall rate and baseline AND run `scripts/recall_metrics.py` against journal folder for current trends. - **Script fallback:** If `recall_metrics.py` is unavailable, manually calculate from journal entries — count entries per week, check dates for streaks, average vividness scores from frontmatter. -3. **Celebrate progress** — Compare to baseline. "You started at 1 dream a week. You're at 3 now. That's real." -4. **Assign exercise** — Based on current level, assign 1-2 exercises for the week. Don't overwhelm. -5. **Set recall goal** — Gentle, achievable: "Let's aim for one more dream this week than last." -6. **Update profile** — Save new recall rate, active exercises +2. **Celebrate progress** — Compare to baseline. "You started at 1 dream a week. You're at 3 now. That's real." +3. **Assign exercise** — Based on current level, assign 1-2 exercises for the week. Don't overwhelm. +4. **Set recall goal** — Gentle, achievable: "Let's aim for one more dream this week than last." +5. **Update profile** — Save new recall rate, active exercises ## Progress Tracking Use `scripts/recall_metrics.py` to calculate: + - Dreams per week (rolling 7-day average) - Recall quality distribution (high/medium/low/fragment) - Vividness trend (average vividness score over time) diff --git a/samples/bmad-agent-dream-weaver/references/memory-system.md b/samples/bmad-agent-dream-weaver/references/memory-system.md index d80369c..4959b42 100644 --- a/samples/bmad-agent-dream-weaver/references/memory-system.md +++ b/samples/bmad-agent-dream-weaver/references/memory-system.md @@ -11,6 +11,7 @@ Tokens are expensive. Only remember what matters. Condense everything to its ess ### `index.md` — Primary Source **Load on activation.** Contains: + - User's dream recall level and coaching stage - Active lucid dreaming techniques being practiced - Current goals (recall improvement, lucid dreaming milestones, theme exploration) @@ -22,6 +23,7 @@ Tokens are expensive. Only remember what matters. Condense everything to its ess ### `access-boundaries.md` — Access Control (Required) **Load on activation.** Contains: + - **Read access** — Sidecar folder and its subdirectories - **Write access** — Sidecar folder and its subdirectories - **Deny zones** — Everything outside the sidecar @@ -63,7 +65,7 @@ symbols: anxiety: 8 peace: 4 awe: 2 - contexts: ["ocean", "rain", "flooding", "calm lake"] + contexts: ['ocean', 'rain', 'flooding', 'calm lake'] doorway: count: 7 first_seen: 2026-02-01 @@ -71,7 +73,7 @@ symbols: emotion_correlation: curiosity: 5 fear: 2 - contexts: ["house", "underwater", "floating"] + contexts: ['house', 'underwater', 'floating'] ``` **Update:** After every dream log (script-assisted via `symbol_stats.py`). @@ -79,9 +81,9 @@ symbols: ### `coaching-profile.yaml` — Coaching State ```yaml -experience_level: beginner # beginner | intermediate | advanced -recall_baseline: 1 # dreams per week when started -current_recall_rate: 3 # dreams per week now +experience_level: beginner # beginner | intermediate | advanced +recall_baseline: 1 # dreams per week when started +current_recall_rate: 3 # dreams per week now active_techniques: - reality-checks - dream-journal-morning @@ -92,8 +94,8 @@ milestones: - name: recall-doubled achieved: null sleep_schedule: - typical_bedtime: "23:00" - typical_wake: "07:00" + typical_bedtime: '23:00' + typical_wake: '07:00' ``` ### `seed-log.yaml` — Dream Incubation Tracking @@ -101,23 +103,24 @@ sleep_schedule: ```yaml seeds: - date: 2026-03-10 - intention: "I want to dream about the ocean" + intention: 'I want to dream about the ocean' technique: visualization - result: partial # none | partial | full - dream_ref: 2026-03-11-1 # reference to journal entry - notes: "Dreamed of rain, not ocean, but water theme appeared" + result: partial # none | partial | full + dream_ref: 2026-03-11-1 # reference to journal entry + notes: 'Dreamed of rain, not ocean, but water theme appeared' - date: 2026-03-08 - intention: "I want to fly" + intention: 'I want to fly' technique: mantra result: none dream_ref: null notes: null -success_rate: 0.33 # seeds with partial or full result / total seeds +success_rate: 0.33 # seeds with partial or full result / total seeds ``` ### `patterns.md` — Learned Patterns **Load when needed.** Contains: + - User's personal symbol meanings (diverging from universal interpretations) - Recurring dream scenarios and their life correlations - Preferred interpretation frameworks @@ -128,6 +131,7 @@ success_rate: 0.33 # seeds with partial or full result / total seeds ### `chronology.md` — Timeline **Load when needed.** Contains: + - Session summaries - Coaching milestone achievements - Significant dream events (first lucid dream, breakthrough interpretations) @@ -140,6 +144,7 @@ success_rate: 0.33 # seeds with partial or full result / total seeds ### Write-Through (Immediate Persistence) Persist immediately when: + 1. **Dream logged** — New journal entry created, symbol registry updated 2. **Coaching milestone achieved** — Profile updated 3. **Seed planted** — Seed log updated @@ -148,6 +153,7 @@ Persist immediately when: ### Checkpoint (Periodic Persistence) Update periodically after: + - Every 5-10 significant exchanges - Session milestones (completing a coaching exercise, interpretation session) - When index.md context has drifted from current state @@ -155,12 +161,14 @@ Update periodically after: ### Save Triggers **After these events, always update memory:** + - After every dream is logged (journal entry + symbol registry + index stats) - After coaching sessions (coaching profile + index) - After seeding setup (seed log) - After autonomous wake completion (autonomous-log + index) **Memory is updated via the `[SM] - Save Memory` capability which:** + 1. Reads current index.md 2. Updates with current session context 3. Writes condensed, current version @@ -193,6 +201,7 @@ Before writing to memory, ask: ## Memory Maintenance Regularly (every few sessions or when files grow large): + 1. **Condense verbose entries** — Summarize old journal entries to key symbols/emotions only 2. **Prune outdated content** — Archive old patterns, update chronology 3. **Consolidate symbol registry** — Merge similar symbols, prune one-offs after 30+ days diff --git a/samples/bmad-excalidraw/SKILL.md b/samples/bmad-excalidraw/SKILL.md index d783e15..0ac60d8 100644 --- a/samples/bmad-excalidraw/SKILL.md +++ b/samples/bmad-excalidraw/SKILL.md @@ -50,15 +50,16 @@ Produce professional diagrams and visual aids as Excalidraw files through conver ## Stages -| # | Stage | Purpose | Prompt | -|---|-------|---------|--------| -| 1 | Guided Design | Creative facilitation — brainstorm diagram type, content, layout | `guided-design.md` | -| 2 | Generation | Produce the `.excalidraw` file with proper layout | `diagram-generation.md` | +| # | Stage | Purpose | Prompt | +| --- | ------------- | ---------------------------------------------------------------- | ----------------------- | +| 1 | Guided Design | Creative facilitation — brainstorm diagram type, content, layout | `guided-design.md` | +| 2 | Generation | Produce the `.excalidraw` file with proper layout | `diagram-generation.md` | Headless: skip guided-design, output file path on completion. ## Scripts Available scripts in `scripts/`: + - `generate_excalidraw.py` — Takes a diagram specification JSON and produces a valid `.excalidraw` file with auto-layout - `validate_excalidraw.py` — Validates `.excalidraw` file structure and reports issues diff --git a/samples/bmad-excalidraw/diagram-generation.md b/samples/bmad-excalidraw/diagram-generation.md index 79b3584..ca18af7 100644 --- a/samples/bmad-excalidraw/diagram-generation.md +++ b/samples/bmad-excalidraw/diagram-generation.md @@ -59,6 +59,7 @@ echo '' | python3 scripts/generate_excalidraw.py --output '{output_fo ``` The script handles: + - Auto-layout based on diagram type and direction - Element sizing based on text content - Arrow routing between elements @@ -91,6 +92,7 @@ Present the result: ## Iteration If the user wants changes: + - Read the existing file - Apply modifications to the spec - Re-run generation diff --git a/samples/bmad-excalidraw/guided-design.md b/samples/bmad-excalidraw/guided-design.md index 7990c53..44bec6c 100644 --- a/samples/bmad-excalidraw/guided-design.md +++ b/samples/bmad-excalidraw/guided-design.md @@ -7,6 +7,7 @@ You are a visual design consultant helping the user create the perfect diagram. ## Step 1: Understand the Subject If the user hasn't already explained, ask: + - What concept, system, or process are they trying to visualize? - Who is the audience? (technical team, stakeholders, documentation, personal notes) - What's the key insight or relationship they want to highlight? @@ -20,6 +21,7 @@ Load `references/diagram-types.md` for the full catalog. Based on what you know, suggest the best-fit diagram type(s) with reasoning: **Example:** + > Based on what you're describing — a multi-step approval process with decision points — I'd recommend a **Flowchart**. It handles sequential steps, branching decisions, and parallel paths well. > > Alternatively, a **Swimlane Diagram** could work if you want to show which team/role owns each step. @@ -33,24 +35,28 @@ If they specified a type, validate it's a good fit and confirm or suggest altern Work conversationally to identify: **For flowcharts/process diagrams:** + - Start/end points - Key steps (what are the main boxes?) - Decision points (where does it branch?) - Connections and flow direction **For architecture/system diagrams:** + - Components/services (what are the boxes?) - Relationships between them (what connects to what?) - Data flow direction - External systems or boundaries **For mind maps/concept diagrams:** + - Central concept - Main branches (categories) - Sub-branches (details) - Cross-connections if any **For sequence diagrams:** + - Participants/actors - Message flow (who sends what to whom?) - Response patterns diff --git a/samples/bmad-excalidraw/references/diagram-types.md b/samples/bmad-excalidraw/references/diagram-types.md index daa738b..ac55c09 100644 --- a/samples/bmad-excalidraw/references/diagram-types.md +++ b/samples/bmad-excalidraw/references/diagram-types.md @@ -5,60 +5,70 @@ Reference for diagram type selection and element mapping. Use this to suggest th ## Type Catalog ### Flowchart + **Best for:** Sequential processes, decision trees, approval workflows, algorithms **Elements:** Rectangles (steps), diamonds (decisions), ellipses (start/end), arrows (flow) **Direction:** Usually LR (left-to-right) or TB (top-to-bottom) **Signals:** User says "process", "steps", "decision", "if/then", "workflow", "flow" ### Architecture Diagram + **Best for:** System components, service relationships, infrastructure, tech stack **Elements:** Rectangles (services/components), frames (boundaries/groups), arrows (data flow) **Direction:** Usually TB or freeform **Signals:** User says "system", "architecture", "components", "services", "infrastructure", "how things connect" ### Sequence Diagram + **Best for:** API calls, message passing, request/response flows, protocol interactions **Elements:** Rectangles (participants), arrows (messages), text (labels) **Direction:** TB (time flows down) **Signals:** User says "sequence", "messages", "API flow", "request/response", "who talks to whom" ### Mind Map + **Best for:** Brainstorming, concept exploration, hierarchical categorization, knowledge organization **Elements:** Ellipses/rectangles (nodes), lines (branches) **Direction:** Radial from center **Signals:** User says "brainstorm", "ideas", "categories", "mind map", "organize thoughts" ### Entity Relationship (ER) Diagram + **Best for:** Database schema, data models, entity relationships **Elements:** Rectangles (entities), diamonds (relationships), text (attributes), arrows (connections) **Direction:** Freeform or TB **Signals:** User says "database", "schema", "entities", "relationships", "data model", "tables" ### Swimlane Diagram + **Best for:** Cross-functional processes, responsibility mapping, handoff visualization **Elements:** Frames (lanes), rectangles (tasks), arrows (flow), text (labels) **Direction:** LR with vertical lanes, or TB with horizontal lanes **Signals:** User says "who does what", "responsibilities", "teams", "handoffs", "cross-functional" ### Data Flow Diagram + **Best for:** Data transformation pipelines, ETL processes, input/output mapping **Elements:** Ellipses (processes), rectangles (data stores), arrows (data flow), text (labels) **Direction:** LR or TB **Signals:** User says "data flow", "pipeline", "transforms", "inputs/outputs", "ETL" ### Wireframe / Mockup + **Best for:** UI layout sketches, screen designs, page structure **Elements:** Rectangles (containers/elements), text (labels/content), lines (dividers) **Direction:** TB (page flow) **Signals:** User says "wireframe", "mockup", "UI", "screen", "layout", "page design" ### Network / Topology Diagram + **Best for:** Network infrastructure, node relationships, cluster layouts **Elements:** Ellipses/rectangles (nodes), lines/arrows (connections), frames (zones) **Direction:** Freeform **Signals:** User says "network", "topology", "nodes", "connections", "cluster" ### Comparison / Matrix + **Best for:** Feature comparisons, pros/cons, decision matrices **Elements:** Rectangles (cells), text (labels/values), lines (grid) **Direction:** Grid layout diff --git a/samples/bmad-excalidraw/references/excalidraw-schema.md b/samples/bmad-excalidraw/references/excalidraw-schema.md index 1257a0e..21750fe 100644 --- a/samples/bmad-excalidraw/references/excalidraw-schema.md +++ b/samples/bmad-excalidraw/references/excalidraw-schema.md @@ -26,33 +26,33 @@ Nine types: `rectangle`, `ellipse`, `diamond`, `arrow`, `line`, `freedraw`, `tex Every element shares these base properties: -| Property | Type | Description | -|----------|------|-------------| -| `id` | string | Unique identifier (use nanoid-style, 8+ chars) | -| `type` | string | One of the nine element types | -| `x` | number | X position (pixels from origin) | -| `y` | number | Y position (pixels from origin) | -| `width` | number | Element width in pixels | -| `height` | number | Element height in pixels | -| `angle` | number | Rotation in radians (0 = no rotation) | -| `strokeColor` | string | Border/stroke color (hex, e.g. `"#1e1e1e"`) | -| `backgroundColor` | string | Fill color (`"transparent"` or hex) | -| `fillStyle` | string | `"solid"`, `"hachure"`, `"cross-hatch"` | -| `strokeWidth` | number | Line thickness (1, 2, or 4) | -| `strokeStyle` | string | `"solid"`, `"dashed"`, `"dotted"` | -| `roughness` | number | 0 (architect/sharp), 1 (artist/default), 2 (cartoonist) | -| `opacity` | number | 0-100 (100 = fully opaque) | -| `groupIds` | array | Group membership `["group-id"]` | -| `frameId` | string/null | Containing frame ID | -| `roundness` | object/null | `{"type": 3}` for rounded corners, `null` for sharp | -| `seed` | number | Random seed for hand-drawn rendering | -| `version` | number | Element version counter (start at 1) | -| `versionNonce` | number | Random nonce for version (any integer) | -| `isDeleted` | boolean | Soft-delete flag (always `false` for new elements) | -| `boundElements` | array/null | Elements bound to this one | -| `updated` | number | Timestamp in milliseconds | -| `link` | string/null | Optional hyperlink | -| `locked` | boolean | Whether element is locked | +| Property | Type | Description | +| ----------------- | ----------- | ------------------------------------------------------- | +| `id` | string | Unique identifier (use nanoid-style, 8+ chars) | +| `type` | string | One of the nine element types | +| `x` | number | X position (pixels from origin) | +| `y` | number | Y position (pixels from origin) | +| `width` | number | Element width in pixels | +| `height` | number | Element height in pixels | +| `angle` | number | Rotation in radians (0 = no rotation) | +| `strokeColor` | string | Border/stroke color (hex, e.g. `"#1e1e1e"`) | +| `backgroundColor` | string | Fill color (`"transparent"` or hex) | +| `fillStyle` | string | `"solid"`, `"hachure"`, `"cross-hatch"` | +| `strokeWidth` | number | Line thickness (1, 2, or 4) | +| `strokeStyle` | string | `"solid"`, `"dashed"`, `"dotted"` | +| `roughness` | number | 0 (architect/sharp), 1 (artist/default), 2 (cartoonist) | +| `opacity` | number | 0-100 (100 = fully opaque) | +| `groupIds` | array | Group membership `["group-id"]` | +| `frameId` | string/null | Containing frame ID | +| `roundness` | object/null | `{"type": 3}` for rounded corners, `null` for sharp | +| `seed` | number | Random seed for hand-drawn rendering | +| `version` | number | Element version counter (start at 1) | +| `versionNonce` | number | Random nonce for version (any integer) | +| `isDeleted` | boolean | Soft-delete flag (always `false` for new elements) | +| `boundElements` | array/null | Elements bound to this one | +| `updated` | number | Timestamp in milliseconds | +| `link` | string/null | Optional hyperlink | +| `locked` | boolean | Whether element is locked | ## Shape Elements (rectangle, ellipse, diamond) @@ -75,14 +75,14 @@ Use common properties only. For bound text, add to `boundElements`: "opacity": 100, "groupIds": [], "frameId": null, - "roundness": {"type": 3}, + "roundness": { "type": 3 }, "seed": 12345, "version": 1, "versionNonce": 67890, "isDeleted": false, "boundElements": [ - {"id": "text1", "type": "text"}, - {"id": "arrow1", "type": "arrow"} + { "id": "text1", "type": "text" }, + { "id": "arrow1", "type": "arrow" } ], "updated": 1700000000000, "link": null, @@ -94,19 +94,20 @@ Use common properties only. For bound text, add to `boundElements`: Additional properties for text: -| Property | Type | Description | -|----------|------|-------------| -| `text` | string | The displayed text | -| `fontSize` | number | Font size (16, 20, 28, 36) | -| `fontFamily` | number | 1 (Virgil/hand-drawn), 2 (Helvetica), 3 (Cascadia/mono) | -| `textAlign` | string | `"left"`, `"center"`, `"right"` | -| `verticalAlign` | string | `"top"`, `"middle"` | -| `containerId` | string/null | Parent shape ID (when text is inside a shape) | -| `originalText` | string | Same as `text` | -| `autoResize` | boolean | Whether text auto-resizes (`true`) | -| `lineHeight` | number | Line height multiplier (1.25 default) | +| Property | Type | Description | +| --------------- | ----------- | ------------------------------------------------------- | +| `text` | string | The displayed text | +| `fontSize` | number | Font size (16, 20, 28, 36) | +| `fontFamily` | number | 1 (Virgil/hand-drawn), 2 (Helvetica), 3 (Cascadia/mono) | +| `textAlign` | string | `"left"`, `"center"`, `"right"` | +| `verticalAlign` | string | `"top"`, `"middle"` | +| `containerId` | string/null | Parent shape ID (when text is inside a shape) | +| `originalText` | string | Same as `text` | +| `autoResize` | boolean | Whether text auto-resizes (`true`) | +| `lineHeight` | number | Line height multiplier (1.25 default) | **Bound text** (text inside a shape): + ```json { "id": "text1", @@ -131,16 +132,17 @@ Additional properties for text: Additional properties: -| Property | Type | Description | -|----------|------|-------------| -| `points` | array | Array of `[x, y]` offsets from element origin | -| `startBinding` | object/null | Connection to start element | -| `endBinding` | object/null | Connection to end element | -| `startArrowhead` | string/null | `null`, `"arrow"`, `"bar"`, `"dot"`, `"triangle"` | -| `endArrowhead` | string/null | Same options as startArrowhead | -| `lastCommittedPoint` | null | Always `null` | +| Property | Type | Description | +| -------------------- | ----------- | ------------------------------------------------- | +| `points` | array | Array of `[x, y]` offsets from element origin | +| `startBinding` | object/null | Connection to start element | +| `endBinding` | object/null | Connection to end element | +| `startArrowhead` | string/null | `null`, `"arrow"`, `"bar"`, `"dot"`, `"triangle"` | +| `endArrowhead` | string/null | Same options as startArrowhead | +| `lastCommittedPoint` | null | Always `null` | **Arrow connecting two shapes:** + ```json { "id": "arrow1", @@ -149,7 +151,10 @@ Additional properties: "y": 140, "width": 100, "height": 0, - "points": [[0, 0], [100, 0]], + "points": [ + [0, 0], + [100, 0] + ], "startBinding": { "elementId": "rect1", "focus": 0, @@ -169,6 +174,7 @@ Additional properties: ``` **Binding fixedPoint values:** + - `[0, 0.5]` = left center - `[1, 0.5]` = right center - `[0.5, 0]` = top center @@ -193,6 +199,7 @@ Frames act as containers. Other elements reference frames via `frameId`. ## Color Palette ### Recommended stroke colors + - `"#1e1e1e"` — Black (default) - `"#e03131"` — Red - `"#2f9e44"` — Green @@ -201,6 +208,7 @@ Frames act as containers. Other elements reference frames via `frameId`. - `"#6741d9"` — Purple ### Recommended background colors + - `"transparent"` — No fill - `"#a5d8ff"` — Light blue - `"#b2f2bb"` — Light green @@ -213,16 +221,16 @@ Frames act as containers. Other elements reference frames via `frameId`. Use these for consistent spacing: -| Constant | Value | Use | -|----------|-------|-----| -| Element width (standard) | 200 | Rectangles, diamonds | -| Element height (standard) | 80 | Rectangles | -| Diamond size | 140 x 100 | Decision diamonds | -| Ellipse size | 160 x 60 | Start/end terminals | -| Horizontal gap | 80 | Between elements (LR flow) | -| Vertical gap | 60 | Between elements (TB flow) | -| Text padding | 20 | Inside shapes | -| Frame padding | 40 | Inside frames | -| Font size (label) | 20 | Standard labels | -| Font size (title) | 28 | Titles/headers | -| Font size (small) | 16 | Annotations | +| Constant | Value | Use | +| ------------------------- | --------- | -------------------------- | +| Element width (standard) | 200 | Rectangles, diamonds | +| Element height (standard) | 80 | Rectangles | +| Diamond size | 140 x 100 | Decision diamonds | +| Ellipse size | 160 x 60 | Start/end terminals | +| Horizontal gap | 80 | Between elements (LR flow) | +| Vertical gap | 60 | Between elements (TB flow) | +| Text padding | 20 | Inside shapes | +| Frame padding | 40 | Inside frames | +| Font size (label) | 20 | Standard labels | +| Font size (title) | 28 | Titles/headers | +| Font size (small) | 16 | Annotations | diff --git a/skills/bmad-agent-builder/SKILL.md b/skills/bmad-agent-builder/SKILL.md index a355d58..de92e02 100644 --- a/skills/bmad-agent-builder/SKILL.md +++ b/skills/bmad-agent-builder/SKILL.md @@ -44,12 +44,12 @@ Load `quality-analysis.md` to begin. ## Quick Reference -| Intent | Trigger Phrases | Route | -|--------|----------------|-------| -| **Build new** | "build/create/design a new agent" | Load `build-process.md` | +| Intent | Trigger Phrases | Route | +| --------------------------- | ----------------------------------------------------- | ---------------------------------------- | +| **Build new** | "build/create/design a new agent" | Load `build-process.md` | | **Existing agent provided** | Path to existing agent, or "convert/edit/fix/analyze" | Ask the 3-way question below, then route | -| **Quality analyze** | "quality check", "validate", "review agent" | Load `quality-analysis.md` | -| **Unclear** | — | Present options and ask | +| **Quality analyze** | "quality check", "validate", "review agent" | Load `quality-analysis.md` | +| **Unclear** | — | Present options and ask | ### When given an existing agent, ask: diff --git a/skills/bmad-agent-builder/assets/SKILL-template.md b/skills/bmad-agent-builder/assets/SKILL-template.md index 2ed4bcf..a45fcf6 100644 --- a/skills/bmad-agent-builder/assets/SKILL-template.md +++ b/skills/bmad-agent-builder/assets/SKILL-template.md @@ -1,6 +1,6 @@ --- name: bmad-{module-code-or-empty}agent-{agent-name} -description: {skill-description} # [4-6 word summary]. [trigger phrases] +description: { skill-description } # [4-6 word summary]. [trigger phrases] --- # {displayName} @@ -27,17 +27,18 @@ description: {skill-description} # [4-6 word summary]. [trigger phrases] {if-module} Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` (root level and `{module-code}` section). If config is missing, let the user know `{module-setup-skill}` can configure the module at any time. Resolve and apply throughout the session (defaults in parens): + - `{user_name}` ({default}) — address the user by name - `{communication_language}` ({default}) — use for all communications - `{document_output_language}` ({default}) — use for generated document content - plus any module-specific output paths with their defaults -{/if-module} -{if-standalone} -Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` if present. Resolve and apply throughout the session (defaults in parens): + {/if-module} + {if-standalone} + Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` if present. Resolve and apply throughout the session (defaults in parens): - `{user_name}` ({default}) — address the user by name - `{communication_language}` ({default}) — use for all communications - `{document_output_language}` ({default}) — use for generated document content -{/if-standalone} + {/if-standalone} {if-sidecar} Load sidecar memory from `{project-root}/_bmad/memory/{skillName}-sidecar/index.md` — this is the single entry point to the memory system and tells the agent what else to load. Load `./references/memory-system.md` for memory discipline. If sidecar doesn't exist, load `./references/init.md` for first-run onboarding. @@ -55,7 +56,7 @@ Greet the user. If memory provides natural context (active program, recent sessi {Succinct routing table — each capability routes to a progressive disclosure file in ./references/:} -| Capability | Route | -|------------|-------| +| Capability | Route | +| ----------------- | ----------------------------------- | | {Capability Name} | Load `./references/{capability}.md` | -| Save Memory | Load `./references/save-memory.md` | +| Save Memory | Load `./references/save-memory.md` | diff --git a/skills/bmad-agent-builder/assets/init-template.md b/skills/bmad-agent-builder/assets/init-template.md index 6195f88..6131389 100644 --- a/skills/bmad-agent-builder/assets/init-template.md +++ b/skills/bmad-agent-builder/assets/init-template.md @@ -1,4 +1,5 @@ {if-module} + # First-Run Setup for {displayName} Welcome! Setting up your workspace. @@ -10,6 +11,7 @@ Creating `_bmad/memory/{skillName}-sidecar/` for persistent memory. ## Initial Structure Creating: + - `index.md` — essential context, active work - `patterns.md` — your preferences I learn - `chronology.md` — session timeline @@ -24,6 +26,7 @@ Setup complete! I'm ready to help. {/if-module} {if-standalone} + # First-Run Setup for {displayName} Welcome! Let me set up for this environment. @@ -37,6 +40,7 @@ Creating `_bmad/memory/{skillName}-sidecar/` for persistent memory. ## Initial Structure Creating: + - `index.md` — essential context, active work, saved paths above - `patterns.md` — your preferences I learn - `chronology.md` — session timeline diff --git a/skills/bmad-agent-builder/assets/memory-system.md b/skills/bmad-agent-builder/assets/memory-system.md index 1aa8d87..47318c0 100644 --- a/skills/bmad-agent-builder/assets/memory-system.md +++ b/skills/bmad-agent-builder/assets/memory-system.md @@ -11,6 +11,7 @@ Tokens are expensive. Only remember what matters. Condense everything to its ess ### `index.md` — Primary Source **Load on activation.** Contains: + - Essential context (what we're working on) - Active work items - User preferences (condensed) @@ -21,36 +22,43 @@ Tokens are expensive. Only remember what matters. Condense everything to its ess ### `access-boundaries.md` — Access Control (Required for all agents) **Load on activation.** Contains: + - **Read access** — Folders/patterns this agent can read from - **Write access** — Folders/patterns this agent can write to - **Deny zones** — Explicitly forbidden folders/patterns - **Created by** — Agent builder at creation time, confirmed/adjusted during init **Template structure:** + ```markdown # Access Boundaries for {displayName} ## Read Access + - {folder-path-or-pattern} - {another-folder-or-pattern} ## Write Access + - {folder-path-or-pattern} - {another-folder-or-pattern} ## Deny Zones + - {explicitly-forbidden-path} ``` **Critical:** On every activation, load these boundaries first. Before any file operation (read/write), verify the path is within allowed boundaries. If uncertain, ask user. {if-standalone} + - **User-configured paths** — Additional paths set during init (journal location, etc.) are appended here -{/if-standalone} + {/if-standalone} ### `patterns.md` — Learned Patterns **Load when needed.** Contains: + - User's quirks and preferences discovered over time - Recurring patterns or issues - Conventions learned @@ -60,6 +68,7 @@ Tokens are expensive. Only remember what matters. Condense everything to its ess ### `chronology.md` — Timeline **Load when needed.** Contains: + - Session summaries - Significant events - Progress over time @@ -71,6 +80,7 @@ Tokens are expensive. Only remember what matters. Condense everything to its ess ### Write-Through (Immediate Persistence) Persist immediately when: + 1. **User data changes** — preferences, configurations 2. **Work products created** — entries, documents, code, artifacts 3. **State transitions** — tasks completed, status changes @@ -79,6 +89,7 @@ Persist immediately when: ### Checkpoint (Periodic Persistence) Update periodically after: + - N interactions (default: every 5-10 significant exchanges) - Session milestones (completing a capability/task) - When file grows beyond target size @@ -86,11 +97,13 @@ Update periodically after: ### Save Triggers **After these events, always update memory:** + - {save-trigger-1} - {save-trigger-2} - {save-trigger-3} **Memory is updated via the `[SM] - Save Memory` capability which:** + 1. Reads current index.md 2. Updates with current session context 3. Writes condensed, current version diff --git a/skills/bmad-agent-builder/build-process.md b/skills/bmad-agent-builder/build-process.md index aae7d8d..c15e95e 100644 --- a/skills/bmad-agent-builder/build-process.md +++ b/skills/bmad-agent-builder/build-process.md @@ -15,9 +15,10 @@ Understand their vision before diving into specifics. Ask what they want to buil ### When given an existing agent -**Critical:** Treat the existing agent as a **description of intent**, not a specification to follow. Extract *who* this agent is and *what* it achieves. Do not inherit its verbosity, structure, or mechanical procedures — the old agent is reference material, not a template. +**Critical:** Treat the existing agent as a **description of intent**, not a specification to follow. Extract _who_ this agent is and _what_ it achieves. Do not inherit its verbosity, structure, or mechanical procedures — the old agent is reference material, not a template. If the SKILL.md routing already asked the 3-way question (Analyze/Edit/Rebuild), proceed with that intent. Otherwise ask now: + - **Edit** — changing specific behavior while keeping the current approach - **Rebuild** — rethinking from core outcomes and persona, full discovery using the old agent as context @@ -60,10 +61,12 @@ Key structural context: - **Access boundaries:** Read/write/deny zones stored in memory **If headless mode enabled, also gather:** + - Default wake behavior (`--headless` | `-H` with no specific task) - Named tasks (`--headless:{task-name}` or `-H:{task-name}`) **Path conventions (CRITICAL):** + - Memory: `{project-root}/_bmad/memory/{skillName}-sidecar/` - Project artifacts: `{project-root}/_bmad/...` - Skill-internal: `./references/`, `./scripts/` @@ -80,6 +83,7 @@ For every planned instruction — especially in capability prompts — ask: **wo The agent's identity, communication style, and principles establish HOW the agent behaves. Capability prompts should describe WHAT to achieve. If you find yourself writing mechanical procedures in a capability prompt, the persona context should handle it instead. Watch especially for: + - Step-by-step procedures in capabilities that the LLM would figure out from the outcome description - Capability prompts that repeat identity/style guidance already in SKILL.md - Multiple capability files that could be one (or zero — does this need a separate capability at all?) @@ -88,6 +92,7 @@ Watch especially for: ## Phase 5: Build **Load these before building:** + - `./references/standard-fields.md` — field definitions, description format, path rules - `./references/skill-best-practices.md` — outcome-driven authoring, patterns, anti-patterns - `./references/quality-dimensions.md` — build quality checklist @@ -97,6 +102,7 @@ Build the agent using templates from `./assets/` and rules from `./references/te **Capability prompts are outcome-driven:** Each `./references/{capability}.md` file should describe what the capability achieves and what "good" looks like — not prescribe mechanical steps. The agent's persona context (identity, communication style, principles in SKILL.md) informs how each capability is executed. Don't repeat that context in every capability prompt. **Agent structure** (only create subfolders that are needed): + ``` {skill-name}/ ├── SKILL.md # Persona, activation, capability routing @@ -110,16 +116,17 @@ Build the agent using templates from `./assets/` and rules from `./references/te └── scripts/ # Deterministic code with tests ``` -| Location | Contains | LLM relationship | -|----------|----------|-----------------| -| **SKILL.md** | Persona, activation, routing | LLM identity and router | -| **`./references/`** | Capability prompts, reference data | Loaded on demand | -| **`./assets/`** | Templates, starter files | Copied/transformed into output | -| **`./scripts/`** | Python, shell scripts with tests | Invoked for deterministic operations | +| Location | Contains | LLM relationship | +| ------------------- | ---------------------------------- | ------------------------------------ | +| **SKILL.md** | Persona, activation, routing | LLM identity and router | +| **`./references/`** | Capability prompts, reference data | Loaded on demand | +| **`./assets/`** | Templates, starter files | Copied/transformed into output | +| **`./scripts/`** | Python, shell scripts with tests | Invoked for deterministic operations | **Activation guidance for built agents:** Activation is a single flow regardless of mode. It should: + - Load config and resolve values (with defaults) - Load sidecar `index.md` if the agent has memory - If headless, route to `./references/autonomous-wake.md` diff --git a/skills/bmad-agent-builder/quality-analysis.md b/skills/bmad-agent-builder/quality-analysis.md index bbf1dec..c9c12c1 100644 --- a/skills/bmad-agent-builder/quality-analysis.md +++ b/skills/bmad-agent-builder/quality-analysis.md @@ -30,31 +30,31 @@ Check for uncommitted changes. In headless mode, note warnings and proceed. In i ### Lint Scripts (Deterministic — Run First) -| # | Script | Focus | Output File | -|---|--------|-------|-------------| -| S1 | `scripts/scan-path-standards.py` | Path conventions | `path-standards-temp.json` | -| S2 | `scripts/scan-scripts.py` | Script portability, PEP 723, unit tests | `scripts-temp.json` | +| # | Script | Focus | Output File | +| --- | -------------------------------- | --------------------------------------- | -------------------------- | +| S1 | `scripts/scan-path-standards.py` | Path conventions | `path-standards-temp.json` | +| S2 | `scripts/scan-scripts.py` | Script portability, PEP 723, unit tests | `scripts-temp.json` | ### Pre-Pass Scripts (Feed LLM Scanners) -| # | Script | Feeds | Output File | -|---|--------|-------|-------------| -| P1 | `scripts/prepass-structure-capabilities.py` | structure scanner | `structure-capabilities-prepass.json` | -| P2 | `scripts/prepass-prompt-metrics.py` | prompt-craft scanner | `prompt-metrics-prepass.json` | -| P3 | `scripts/prepass-execution-deps.py` | execution-efficiency scanner | `execution-deps-prepass.json` | +| # | Script | Feeds | Output File | +| --- | ------------------------------------------- | ---------------------------- | ------------------------------------- | +| P1 | `scripts/prepass-structure-capabilities.py` | structure scanner | `structure-capabilities-prepass.json` | +| P2 | `scripts/prepass-prompt-metrics.py` | prompt-craft scanner | `prompt-metrics-prepass.json` | +| P3 | `scripts/prepass-execution-deps.py` | execution-efficiency scanner | `execution-deps-prepass.json` | ### LLM Scanners (Judgment-Based — Run After Scripts) Each scanner writes a free-form analysis document: -| # | Scanner | Focus | Pre-Pass? | Output File | -|---|---------|-------|-----------|-------------| -| L1 | `quality-scan-structure.md` | Structure, capabilities, identity, memory, consistency | Yes | `structure-analysis.md` | -| L2 | `quality-scan-prompt-craft.md` | Token efficiency, outcome balance, persona voice, per-capability craft | Yes | `prompt-craft-analysis.md` | -| L3 | `quality-scan-execution-efficiency.md` | Parallelization, delegation, memory loading, context optimization | Yes | `execution-efficiency-analysis.md` | -| L4 | `quality-scan-agent-cohesion.md` | Persona-capability alignment, identity coherence, per-capability cohesion | No | `agent-cohesion-analysis.md` | -| L5 | `quality-scan-enhancement-opportunities.md` | Edge cases, experience gaps, user journeys, headless potential | No | `enhancement-opportunities-analysis.md` | -| L6 | `quality-scan-script-opportunities.md` | Deterministic operations that should be scripts | No | `script-opportunities-analysis.md` | +| # | Scanner | Focus | Pre-Pass? | Output File | +| --- | ------------------------------------------- | ------------------------------------------------------------------------- | --------- | --------------------------------------- | +| L1 | `quality-scan-structure.md` | Structure, capabilities, identity, memory, consistency | Yes | `structure-analysis.md` | +| L2 | `quality-scan-prompt-craft.md` | Token efficiency, outcome balance, persona voice, per-capability craft | Yes | `prompt-craft-analysis.md` | +| L3 | `quality-scan-execution-efficiency.md` | Parallelization, delegation, memory loading, context optimization | Yes | `execution-efficiency-analysis.md` | +| L4 | `quality-scan-agent-cohesion.md` | Persona-capability alignment, identity coherence, per-capability cohesion | No | `agent-cohesion-analysis.md` | +| L5 | `quality-scan-enhancement-opportunities.md` | Edge cases, experience gaps, user journeys, headless potential | No | `enhancement-opportunities-analysis.md` | +| L6 | `quality-scan-script-opportunities.md` | Deterministic operations that should be scripts | No | `script-opportunities-analysis.md` | ## Execution @@ -84,10 +84,12 @@ Each subagent loads the scanner file, analyzes the agent, writes analysis to the Spawn a subagent with `report-quality-scan-creator.md`. Provide: + - `{skill-path}` — The agent being analyzed - `{quality-report-dir}` — Directory with all scanner output The report creator reads everything, synthesizes agent portrait + capability dashboard + themes, writes: + 1. `quality-report.md` — Narrative markdown with BMad Method branding 2. `report-data.json` — Structured data for HTML @@ -102,6 +104,7 @@ python3 scripts/generate-html-report.py {report-dir} --open **IF `{headless_mode}=true`:** Read `report-data.json` and output: + ```json { "headless_mode": true, @@ -118,6 +121,7 @@ Read `report-data.json` and output: **IF interactive:** Read `report-data.json` and present: + 1. Agent portrait — icon, name, title 2. Grade and narrative 3. Capability dashboard summary diff --git a/skills/bmad-agent-builder/quality-scan-agent-cohesion.md b/skills/bmad-agent-builder/quality-scan-agent-cohesion.md index 6d2aafe..ba5fe8b 100644 --- a/skills/bmad-agent-builder/quality-scan-agent-cohesion.md +++ b/skills/bmad-agent-builder/quality-scan-agent-cohesion.md @@ -9,6 +9,7 @@ You evaluate the overall cohesion of a BMad agent: does the persona align with c ## Your Role Analyze the agent as a unified whole to identify: + - **Gaps** — Capabilities the agent should likely have but doesn't - **Redundancies** — Overlapping capabilities that could be consolidated - **Misalignments** — Capabilities that don't fit the persona or purpose @@ -20,6 +21,7 @@ This is an **opinionated, advisory scan**. Findings are suggestions, not errors. ## Scan Targets Find and read: + - `SKILL.md` — Identity, persona, principles, description - `*.md` (prompt files at root) — What each prompt actually does - `references/dimension-definitions.md` — If exists, context for capability design @@ -31,14 +33,15 @@ Find and read: **Question:** Does WHO the agent is match WHAT it can do? -| Check | Why It Matters | -|-------|----------------| -| Agent's stated expertise matches its capabilities | An "expert in X" should be able to do core X tasks | -| Communication style fits the persona's role | A "senior engineer" sounds different than a "friendly assistant" | -| Principles are reflected in actual capabilities | Don't claim "user autonomy" if you never ask preferences | -| Description matches what capabilities actually deliver | Misalignment causes user disappointment | +| Check | Why It Matters | +| ------------------------------------------------------ | ---------------------------------------------------------------- | +| Agent's stated expertise matches its capabilities | An "expert in X" should be able to do core X tasks | +| Communication style fits the persona's role | A "senior engineer" sounds different than a "friendly assistant" | +| Principles are reflected in actual capabilities | Don't claim "user autonomy" if you never ask preferences | +| Description matches what capabilities actually deliver | Misalignment causes user disappointment | **Examples of misalignment:** + - Agent claims "expert code reviewer" but has no linting/format analysis - Persona is "friendly mentor" but all prompts are terse and mechanical - Description says "end-to-end project management" but only has task-listing capabilities @@ -47,14 +50,15 @@ Find and read: **Question:** Given the persona and purpose, what's OBVIOUSLY missing? -| Check | Why It Matters | -|-------|----------------| -| Core workflow is fully supported | Users shouldn't need to switch agents mid-task | -| Basic CRUD operations exist if relevant | Can't have "data manager" that only reads | -| Setup/teardown capabilities present | Start and end states matter | -| Output/export capabilities exist | Data trapped in agent is useless | +| Check | Why It Matters | +| --------------------------------------- | ---------------------------------------------- | +| Core workflow is fully supported | Users shouldn't need to switch agents mid-task | +| Basic CRUD operations exist if relevant | Can't have "data manager" that only reads | +| Setup/teardown capabilities present | Start and end states matter | +| Output/export capabilities exist | Data trapped in agent is useless | **Gap detection heuristic:** + - If agent does X, does it also handle related X' and X''? - If agent manages a lifecycle, does it cover all stages? - If agent analyzes something, can it also fix/report on it? @@ -64,13 +68,14 @@ Find and read: **Question:** Are multiple capabilities doing the same thing? -| Check | Why It Matters | -|-------|----------------| -| No overlapping capabilities | Confuses users, wastes tokens | -- Prompts don't duplicate functionality | Pick ONE place for each behavior | -| Similar capabilities aren't separated | Could be consolidated into stronger single capability | +| Check | Why It Matters | +| --------------------------------------- | ----------------------------------------------------- | +| No overlapping capabilities | Confuses users, wastes tokens | +| - Prompts don't duplicate functionality | Pick ONE place for each behavior | +| Similar capabilities aren't separated | Could be consolidated into stronger single capability | **Redundancy patterns:** + - "Format code" and "lint code" and "fix code style" — maybe one capability? - "Summarize document" and "extract key points" and "get main ideas" — overlapping? - Multiple prompts that read files with slight variations — could parameterize @@ -79,11 +84,11 @@ Find and read: **Question:** How does this agent work with others, and is that intentional? -| Check | Why It Matters | -|-------|----------------| -| Referenced external skills fit the workflow | Random skill calls confuse the purpose | +| Check | Why It Matters | +| -------------------------------------------- | ------------------------------------------- | +| Referenced external skills fit the workflow | Random skill calls confuse the purpose | | Agent can function standalone OR with skills | Don't REQUIRE skills that aren't documented | -| Skill delegation follows a clear pattern | Haphazard calling suggests poor design | +| Skill delegation follows a clear pattern | Haphazard calling suggests poor design | **Note:** If external skills aren't available, infer their purpose from name and usage context. @@ -91,13 +96,14 @@ Find and read: **Question:** Are capabilities at the right level of abstraction? -| Check | Why It Matters | -|-------|----------------| -| Capabilities aren't too granular | 5 similar micro-capabilities should be one | -| Capabilities aren't too broad | "Do everything related to code" isn't a capability | -| Each capability has clear, unique purpose | Users should understand what each does | +| Check | Why It Matters | +| ----------------------------------------- | -------------------------------------------------- | +| Capabilities aren't too granular | 5 similar micro-capabilities should be one | +| Capabilities aren't too broad | "Do everything related to code" isn't a capability | +| Each capability has clear, unique purpose | Users should understand what each does | **Goldilocks test:** + - Too small: "Open file", "Read file", "Parse file" → Should be "Analyze file" - Too large: "Handle all git operations" → Split into clone/commit/branch/PR - Just right: "Create pull request with review template" @@ -106,12 +112,12 @@ Find and read: **Question:** Can a user accomplish meaningful work end-to-end? -| Check | Why It Matters | -|-------|----------------| -| Common workflows are fully supported | Gaps force context switching | -| Capabilities can be chained logically | No dead-end operations | -| Entry points are clear | User knows where to start | -| Exit points provide value | User gets something useful, not just internal state | +| Check | Why It Matters | +| ------------------------------------- | --------------------------------------------------- | +| Common workflows are fully supported | Gaps force context switching | +| Capabilities can be chained logically | No dead-end operations | +| Entry points are clear | User knows where to start | +| Exit points provide value | User gets something useful, not just internal state | ## Output diff --git a/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md b/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md index 935b7be..c4d49fd 100644 --- a/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md +++ b/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md @@ -6,7 +6,7 @@ You are **DreamBot**, a creative disruptor who pressure-tests agents by imaginin Other scanners check if an agent is built correctly, crafted well, runs efficiently, and holds together. You ask the question none of them do: **"What's missing that nobody thought of?"** -You read an agent and genuinely *inhabit* it — its persona, its identity, its capabilities — imagine yourself as six different users with six different contexts, skill levels, moods, and intentions. Then you find the moments where the agent would confuse, frustrate, dead-end, or underwhelm them. You also find the moments where a single creative addition would transform the experience from functional to delightful. +You read an agent and genuinely _inhabit_ it — its persona, its identity, its capabilities — imagine yourself as six different users with six different contexts, skill levels, moods, and intentions. Then you find the moments where the agent would confuse, frustrate, dead-end, or underwhelm them. You also find the moments where a single creative addition would transform the experience from functional to delightful. This is the BMad dreamer scanner. Your job is to push boundaries, challenge assumptions, and surface the ideas that make builders say "I never thought of that." Then temper each wild idea into a concrete, succinct suggestion the builder can actually act on. @@ -26,6 +26,7 @@ You are NOT checking structure, craft quality, performance, or test coverage — ## Scan Targets Find and read: + - `SKILL.md` — Understand the agent's purpose, persona, audience, and flow - `*.md` (prompt files at root) — Walk through each capability as a user would experience it - `references/*.md` — Understand what supporting material exists @@ -37,6 +38,7 @@ Find and read: Imagine real users in real situations. What breaks, confuses, or dead-ends? **User archetypes to inhabit:** + - The **first-timer** who has never used this kind of tool before - The **expert** who knows exactly what they want and finds the agent too slow - The **confused user** who invoked this agent by accident or with the wrong intent @@ -45,6 +47,7 @@ Imagine real users in real situations. What breaks, confuses, or dead-ends? - The **automator** — a cron job, CI pipeline, or another agent that wants to invoke this agent headless with pre-supplied inputs and get back a result **Questions to ask at each capability:** + - What if the user provides partial, ambiguous, or contradictory input? - What if the user wants to skip this capability or jump to a different one? - What if the user's real need doesn't fit the agent's assumed categories? @@ -54,43 +57,43 @@ Imagine real users in real situations. What breaks, confuses, or dead-ends? ### 2. Experience Gaps -Where does the agent deliver output but miss the *experience*? +Where does the agent deliver output but miss the _experience_? -| Gap Type | What to Look For | -|----------|-----------------| -| **Dead-end moments** | User hits a state where the agent has nothing to offer and no guidance on what to do next | -| **Assumption walls** | Agent assumes knowledge, context, or setup the user might not have | -| **Missing recovery** | Error or unexpected input with no graceful path forward | -| **Abandonment friction** | User wants to stop mid-conversation but there's no clean exit or state preservation | -| **Success amnesia** | Agent completes but doesn't help the user understand or use what was produced | -| **Invisible value** | Agent does something valuable but doesn't surface it to the user | +| Gap Type | What to Look For | +| ------------------------ | ----------------------------------------------------------------------------------------- | +| **Dead-end moments** | User hits a state where the agent has nothing to offer and no guidance on what to do next | +| **Assumption walls** | Agent assumes knowledge, context, or setup the user might not have | +| **Missing recovery** | Error or unexpected input with no graceful path forward | +| **Abandonment friction** | User wants to stop mid-conversation but there's no clean exit or state preservation | +| **Success amnesia** | Agent completes but doesn't help the user understand or use what was produced | +| **Invisible value** | Agent does something valuable but doesn't surface it to the user | ### 3. Delight Opportunities Where could a small addition create outsized positive impact? -| Opportunity Type | Example | -|-----------------|---------| -| **Quick-win mode** | "I already have a spec, skip the interview" — let experienced users fast-track | -| **Smart defaults** | Infer reasonable defaults from context instead of asking every question | -| **Proactive insight** | "Based on what you've described, you might also want to consider..." | -| **Progress awareness** | Help the user understand where they are in a multi-capability workflow | -| **Memory leverage** | Use prior conversation context or project knowledge to personalize | -| **Graceful degradation** | When something goes wrong, offer a useful alternative instead of just failing | -| **Unexpected connection** | "This pairs well with [other skill]" — suggest adjacent capabilities | +| Opportunity Type | Example | +| ------------------------- | ------------------------------------------------------------------------------ | +| **Quick-win mode** | "I already have a spec, skip the interview" — let experienced users fast-track | +| **Smart defaults** | Infer reasonable defaults from context instead of asking every question | +| **Proactive insight** | "Based on what you've described, you might also want to consider..." | +| **Progress awareness** | Help the user understand where they are in a multi-capability workflow | +| **Memory leverage** | Use prior conversation context or project knowledge to personalize | +| **Graceful degradation** | When something goes wrong, offer a useful alternative instead of just failing | +| **Unexpected connection** | "This pairs well with [other skill]" — suggest adjacent capabilities | ### 4. Assumption Audit Every agent makes assumptions. Surface the ones that are most likely to be wrong. -| Assumption Category | What to Challenge | -|--------------------|------------------| -| **User intent** | Does the agent assume a single use case when users might have several? | -| **Input quality** | Does the agent assume well-formed, complete input? | -| **Linear progression** | Does the agent assume users move forward-only through capabilities? | -| **Context availability** | Does the agent assume information that might not be in the conversation? | -| **Single-session completion** | Does the agent assume the interaction completes in one session? | -| **Agent isolation** | Does the agent assume it's the only thing the user is doing? | +| Assumption Category | What to Challenge | +| ----------------------------- | ------------------------------------------------------------------------ | +| **User intent** | Does the agent assume a single use case when users might have several? | +| **Input quality** | Does the agent assume well-formed, complete input? | +| **Linear progression** | Does the agent assume users move forward-only through capabilities? | +| **Context availability** | Does the agent assume information that might not be in the conversation? | +| **Single-session completion** | Does the agent assume the interaction completes in one session? | +| **Agent isolation** | Does the agent assume it's the only thing the user is doing? | ### 5. Headless Potential @@ -100,29 +103,30 @@ This is one of the most transformative "what ifs" you can ask about a HITL agent **For each HITL interaction point, ask:** -| Question | What You're Looking For | -|----------|------------------------| -| Could this question be answered by input parameters? | "What type of project?" → could come from a prompt or config instead of asking | -| Could this confirmation be skipped with reasonable defaults? | "Does this look right?" → if the input was detailed enough, skip confirmation | -| Is this clarification always needed, or only for ambiguous input? | "Did you mean X or Y?" → only needed when input is vague | -| Does this interaction add value or just ceremony? | Some confirmations exist because the builder assumed interactivity, not because they're necessary | +| Question | What You're Looking For | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| Could this question be answered by input parameters? | "What type of project?" → could come from a prompt or config instead of asking | +| Could this confirmation be skipped with reasonable defaults? | "Does this look right?" → if the input was detailed enough, skip confirmation | +| Is this clarification always needed, or only for ambiguous input? | "Did you mean X or Y?" → only needed when input is vague | +| Does this interaction add value or just ceremony? | Some confirmations exist because the builder assumed interactivity, not because they're necessary | **Assess the agent's headless potential:** -| Level | What It Means | -|-------|--------------| -| **Headless-ready** | Could work headlessly today with minimal changes — just needs a flag to skip confirmations | -| **Easily adaptable** | Most interaction points could accept pre-supplied parameters; needs a headless path added to 2-3 capabilities | -| **Partially adaptable** | Core artifact creation could be headless, but discovery/interview capabilities are fundamentally interactive — suggest a "skip to build" entry point | -| **Fundamentally interactive** | The value IS the conversation (coaching, brainstorming, exploration) — headless mode wouldn't make sense, and that's OK | +| Level | What It Means | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Headless-ready** | Could work headlessly today with minimal changes — just needs a flag to skip confirmations | +| **Easily adaptable** | Most interaction points could accept pre-supplied parameters; needs a headless path added to 2-3 capabilities | +| **Partially adaptable** | Core artifact creation could be headless, but discovery/interview capabilities are fundamentally interactive — suggest a "skip to build" entry point | +| **Fundamentally interactive** | The value IS the conversation (coaching, brainstorming, exploration) — headless mode wouldn't make sense, and that's OK | **When the agent IS adaptable, suggest the output contract:** + - What would a headless invocation return? (file path, JSON summary, status code) - What inputs would it need upfront? (parameters that currently come from conversation) - Where would the `{headless_mode}` flag need to be checked? - Which capabilities could auto-resolve vs which need explicit input even in headless mode? -**Don't force it.** Some agents are fundamentally conversational — their value is the interactive exploration. Flag those as "fundamentally interactive" and move on. The insight is knowing which agents *could* transform, not pretending all should. +**Don't force it.** Some agents are fundamentally conversational — their value is the interactive exploration. Flag those as "fundamentally interactive" and move on. The insight is knowing which agents _could_ transform, not pretending all should. ### 6. Facilitative Workflow Patterns @@ -130,15 +134,15 @@ If the agent involves collaborative discovery, artifact creation through user in **Check for these patterns:** -| Pattern | What to Look For | If Missing | -|---------|-----------------|------------| -| **Soft Gate Elicitation** | Does the agent use "anything else or shall we move on?" at natural transitions? | Suggest replacing hard menus with soft gates — they draw out information users didn't know they had | -| **Intent-Before-Ingestion** | Does the agent understand WHY the user is here before scanning artifacts/context? | Suggest reordering: greet → understand intent → THEN scan. Scanning without purpose is noise | -| **Capture-Don't-Interrupt** | When users provide out-of-scope info during discovery, does the agent capture it silently or redirect/stop them? | Suggest a capture-and-defer mechanism — users in creative flow share their best insights unprompted | -| **Dual-Output** | Does the agent produce only a human artifact, or also offer an LLM-optimized distillate for downstream consumption? | If the artifact feeds into other LLM workflows, suggest offering a token-efficient distillate alongside the primary output | -| **Parallel Review Lenses** | Before finalizing, does the agent get multiple perspectives on the artifact? | Suggest fanning out 2-3 review subagents (skeptic, opportunity spotter, contextually-chosen third lens) before final output | -| **Three-Mode Architecture** | Does the agent only support one interaction style? | If it produces an artifact, consider whether Guided/Yolo/Autonomous modes would serve different user contexts | -| **Graceful Degradation** | If the agent uses subagents, does it have fallback paths when they're unavailable? | Every subagent-dependent feature should degrade to sequential processing, never block the workflow | +| Pattern | What to Look For | If Missing | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| **Soft Gate Elicitation** | Does the agent use "anything else or shall we move on?" at natural transitions? | Suggest replacing hard menus with soft gates — they draw out information users didn't know they had | +| **Intent-Before-Ingestion** | Does the agent understand WHY the user is here before scanning artifacts/context? | Suggest reordering: greet → understand intent → THEN scan. Scanning without purpose is noise | +| **Capture-Don't-Interrupt** | When users provide out-of-scope info during discovery, does the agent capture it silently or redirect/stop them? | Suggest a capture-and-defer mechanism — users in creative flow share their best insights unprompted | +| **Dual-Output** | Does the agent produce only a human artifact, or also offer an LLM-optimized distillate for downstream consumption? | If the artifact feeds into other LLM workflows, suggest offering a token-efficient distillate alongside the primary output | +| **Parallel Review Lenses** | Before finalizing, does the agent get multiple perspectives on the artifact? | Suggest fanning out 2-3 review subagents (skeptic, opportunity spotter, contextually-chosen third lens) before final output | +| **Three-Mode Architecture** | Does the agent only support one interaction style? | If it produces an artifact, consider whether Guided/Yolo/Autonomous modes would serve different user contexts | +| **Graceful Degradation** | If the agent uses subagents, does it have fallback paths when they're unavailable? | Every subagent-dependent feature should degrade to sequential processing, never block the workflow | **How to assess:** These patterns aren't mandatory for every agent — a simple utility doesn't need three-mode architecture. But any agent that involves collaborative discovery, user interviews, or artifact creation through guided interaction should be checked against all seven. Flag missing patterns as `medium-opportunity` or `high-opportunity` depending on how transformative they'd be for the specific agent. @@ -147,6 +151,7 @@ If the agent involves collaborative discovery, artifact creation through user in Mentally walk through the agent end-to-end as each user archetype. Document the moments where the journey breaks, stalls, or disappoints. For each journey, note: + - **Entry friction** — How easy is it to get started? What if the user's first message doesn't perfectly match the expected trigger? - **Mid-flow resilience** — What happens if the user goes off-script, asks a tangential question, or provides unexpected input? - **Exit satisfaction** — Does the user leave with a clear outcome, or does the conversation just... stop? diff --git a/skills/bmad-agent-builder/quality-scan-execution-efficiency.md b/skills/bmad-agent-builder/quality-scan-execution-efficiency.md index 7f3d266..a7fe20b 100644 --- a/skills/bmad-agent-builder/quality-scan-execution-efficiency.md +++ b/skills/bmad-agent-builder/quality-scan-execution-efficiency.md @@ -6,7 +6,7 @@ You are **ExecutionEfficiencyBot**, a performance-focused quality engineer who v You validate execution efficiency across the entire agent: parallelization, subagent delegation, context management, memory loading strategy, and multi-source analysis patterns. **Why this matters:** Sequential independent operations waste time. Parent reading before delegating bloats context. Loading all memory when only a slice is needed wastes tokens. Efficient execution means faster, cheaper, more reliable agent operation. -This is a unified scan covering both *how work is distributed* (subagent delegation, context optimization) and *how work is ordered* (sequencing, parallelization). These concerns are deeply intertwined. +This is a unified scan covering both _how work is distributed_ (subagent delegation, context optimization) and _how work is ordered_ (sequencing, parallelization). These concerns are deeply intertwined. ## Your Role @@ -17,6 +17,7 @@ Read the pre-pass JSON first at `{quality-report-dir}/execution-deps-prepass.jso Pre-pass provides: dependency graph, sequential patterns, loop patterns, subagent-chain violations, memory loading patterns. Read raw files for judgment calls: + - `SKILL.md` — On Activation patterns, operation flow - `*.md` (prompt files at root) — Each prompt for execution patterns - `references/*.md` — Resource loading patterns @@ -26,16 +27,18 @@ Read raw files for judgment calls: ## Part 1: Parallelization & Batching ### Sequential Operations That Should Be Parallel -| Check | Why It Matters | -|-------|----------------| + +| Check | Why It Matters | +| ----------------------------------------------- | ------------------------------------ | | Independent data-gathering steps are sequential | Wastes time — should run in parallel | -| Multiple files processed sequentially in loop | Should use parallel subagents | -| Multiple tools called in sequence independently | Should batch in one message | +| Multiple files processed sequentially in loop | Should use parallel subagents | +| Multiple tools called in sequence independently | Should batch in one message | ### Tool Call Batching -| Check | Why It Matters | -|-------|----------------| -| Independent tool calls batched in one message | Reduces latency | + +| Check | Why It Matters | +| -------------------------------------------------------- | ---------------------------------- | +| Independent tool calls batched in one message | Reduces latency | | No sequential Read/Grep/Glob calls for different targets | Single message with multiple calls | --- @@ -43,30 +46,34 @@ Read raw files for judgment calls: ## Part 2: Subagent Delegation & Context Management ### Read Avoidance (Critical Pattern) + Don't read files in parent when you could delegate the reading. -| Check | Why It Matters | -|-------|----------------| -| Parent doesn't read sources before delegating analysis | Context stays lean | -| Parent delegates READING, not just analysis | Subagents do heavy lifting | -| No "read all, then analyze" patterns | Context explosion avoided | +| Check | Why It Matters | +| ------------------------------------------------------ | -------------------------- | +| Parent doesn't read sources before delegating analysis | Context stays lean | +| Parent delegates READING, not just analysis | Subagents do heavy lifting | +| No "read all, then analyze" patterns | Context explosion avoided | ### Subagent Instruction Quality -| Check | Why It Matters | -|-------|----------------| -| Subagent prompt specifies exact return format | Prevents verbose output | -| Token limit guidance provided | Ensures succinct results | -| JSON structure required for structured results | Parseable output | -| "ONLY return" or equivalent constraint language | Prevents filler | + +| Check | Why It Matters | +| ----------------------------------------------- | ------------------------ | +| Subagent prompt specifies exact return format | Prevents verbose output | +| Token limit guidance provided | Ensures succinct results | +| JSON structure required for structured results | Parseable output | +| "ONLY return" or equivalent constraint language | Prevents filler | ### Subagent Chaining Constraint + **Subagents cannot spawn other subagents.** Chain through parent. ### Result Aggregation Patterns -| Approach | When to Use | -|----------|-------------| -| Return to parent | Small results, immediate synthesis | -| Write to temp files | Large results (10+ items) | + +| Approach | When to Use | +| -------------------- | ------------------------------------- | +| Return to parent | Small results, immediate synthesis | +| Write to temp files | Large results (10+ items) | | Background subagents | Long-running, no clarification needed | --- @@ -74,12 +81,13 @@ Don't read files in parent when you could delegate the reading. ## Part 3: Agent-Specific Efficiency ### Memory Loading Strategy -| Check | Why It Matters | -|-------|----------------| -| Selective memory loading (only what's needed) | Loading all sidecar files wastes tokens | -| Index file loaded first for routing | Index tells what else to load | -| Memory sections loaded per-capability, not all-at-once | Each capability needs different memory | -| Access boundaries loaded on every activation | Required for security | + +| Check | Why It Matters | +| ------------------------------------------------------ | --------------------------------------- | +| Selective memory loading (only what's needed) | Loading all sidecar files wastes tokens | +| Index file loaded first for routing | Index tells what else to load | +| Memory sections loaded per-capability, not all-at-once | Each capability needs different memory | +| Access boundaries loaded on every activation | Required for security | ``` BAD: Load all memory @@ -92,29 +100,31 @@ GOOD: Selective loading ``` ### Multi-Source Analysis Delegation -| Check | Why It Matters | -|-------|----------------| + +| Check | Why It Matters | +| ------------------------------------------- | ------------------------------------ | | 5+ source analysis uses subagent delegation | Each source adds thousands of tokens | -| Each source gets its own subagent | Parallel processing | -| Parent coordinates, doesn't read sources | Context stays lean | +| Each source gets its own subagent | Parallel processing | +| Parent coordinates, doesn't read sources | Context stays lean | ### Resource Loading Optimization -| Check | Why It Matters | -|-------|----------------| -| Resources loaded selectively by capability | Not all resources needed every time | -| Large resources loaded on demand | Reference tables only when needed | -| "Essential context" separated from "full reference" | Summary suffices for routing | + +| Check | Why It Matters | +| --------------------------------------------------- | ----------------------------------- | +| Resources loaded selectively by capability | Not all resources needed every time | +| Large resources loaded on demand | Reference tables only when needed | +| "Essential context" separated from "full reference" | Summary suffices for routing | --- ## Severity Guidelines -| Severity | When to Apply | -|----------|---------------| -| **Critical** | Circular dependencies, subagent-spawning-from-subagent | -| **High** | Parent-reads-before-delegating, sequential independent ops with 5+ items, loading all memory unnecessarily | -| **Medium** | Missed batching, subagent instructions without output format, resource loading inefficiency | -| **Low** | Minor parallelization opportunities (2-3 items), result aggregation suggestions | +| Severity | When to Apply | +| ------------ | ---------------------------------------------------------------------------------------------------------- | +| **Critical** | Circular dependencies, subagent-spawning-from-subagent | +| **High** | Parent-reads-before-delegating, sequential independent ops with 5+ items, loading all memory unnecessarily | +| **Medium** | Missed batching, subagent instructions without output format, resource loading inefficiency | +| **Low** | Minor parallelization opportunities (2-3 items), result aggregation suggestions | --- diff --git a/skills/bmad-agent-builder/quality-scan-prompt-craft.md b/skills/bmad-agent-builder/quality-scan-prompt-craft.md index cd33bb4..e5afe10 100644 --- a/skills/bmad-agent-builder/quality-scan-prompt-craft.md +++ b/skills/bmad-agent-builder/quality-scan-prompt-craft.md @@ -4,7 +4,7 @@ You are **PromptCraftBot**, a quality engineer who understands that great agent ## Overview -You evaluate the craft quality of an agent's prompts — SKILL.md and all capability prompts. This covers token efficiency, anti-patterns, outcome driven focus, and instruction clarity as a **unified assessment** rather than isolated checklists. The reason these must be evaluated together: a finding that looks like "waste" from a pure efficiency lens may be load-bearing persona context that enables the agent to stay in character and handle situations the prompt doesn't explicitly cover. Your job is to distinguish between the two. Guiding principle should be following outcome driven engineering focus. +You evaluate the craft quality of an agent's prompts — SKILL.md and all capability prompts. This covers token efficiency, anti-patterns, outcome driven focus, and instruction clarity as a **unified assessment** rather than isolated checklists. The reason these must be evaluated together: a finding that looks like "waste" from a pure efficiency lens may be load-bearing persona context that enables the agent to stay in character and handle situations the prompt doesn't explicitly cover. Your job is to distinguish between the two. Guiding principle should be following outcome driven engineering focus. ## Your Role @@ -19,6 +19,7 @@ Read the pre-pass JSON first at `{quality-report-dir}/prompt-metrics-prepass.jso Pre-pass provides: line counts, token estimates, section inventories, waste pattern matches, back-reference matches, config headers, progression conditions. Read raw files for judgment calls: + - `SKILL.md` — Overview quality, persona context assessment - `*.md` (prompt files at root) — Each capability prompt for craft quality - `references/*.md` — Progressive disclosure assessment @@ -40,11 +41,13 @@ A good agent Overview includes: | Design rationale | WHY specific approaches were chosen | Prevents "optimization" of important constraints | **When to flag Overview as excessive:** + - Exceeds ~10-12 sentences for a single-purpose agent - Same concept restated that also appears in Identity or Principles - Philosophical content disconnected from actual behavior **When NOT to flag:** + - Establishes persona context (even if "soft") - Defines domain concepts the agent operates on - Includes theory of mind guidance for user-facing agents @@ -52,21 +55,21 @@ A good agent Overview includes: ### SKILL.md Size & Progressive Disclosure -| Scenario | Acceptable Size | Notes | -|----------|----------------|-------| -| Multi-capability agent with brief capability sections | Up to ~250 lines | Each capability section brief, detail in prompt files | -| Single-purpose agent with deep persona | Up to ~500 lines (~5000 tokens) | Acceptable if content is genuinely needed | -| Agent with large reference tables or schemas inline | Flag for extraction | These belong in references/, not SKILL.md | +| Scenario | Acceptable Size | Notes | +| ----------------------------------------------------- | ------------------------------- | ----------------------------------------------------- | +| Multi-capability agent with brief capability sections | Up to ~250 lines | Each capability section brief, detail in prompt files | +| Single-purpose agent with deep persona | Up to ~500 lines (~5000 tokens) | Acceptable if content is genuinely needed | +| Agent with large reference tables or schemas inline | Flag for extraction | These belong in references/, not SKILL.md | ### Detecting Over-Optimization (Under-Contextualized Agents) -| Symptom | What It Looks Like | Impact | -|---------|-------------------|--------| -| Missing or empty Overview | Jumps to On Activation with no context | Agent follows steps mechanically | -| No persona framing | Instructions without identity context | Agent uses generic personality | -| No domain framing | References concepts without defining them | Agent uses generic understanding | -| Bare procedural skeleton | Only numbered steps with no connective context | Works for utilities, fails for persona agents | -| Missing "what good looks like" | No examples, no quality bar | Technically correct but characterless output | +| Symptom | What It Looks Like | Impact | +| ------------------------------ | ---------------------------------------------- | --------------------------------------------- | +| Missing or empty Overview | Jumps to On Activation with no context | Agent follows steps mechanically | +| No persona framing | Instructions without identity context | Agent uses generic personality | +| No domain framing | References concepts without defining them | Agent uses generic understanding | +| Bare procedural skeleton | Only numbered steps with no connective context | Works for utilities, fails for persona agents | +| Missing "what good looks like" | No examples, no quality bar | Technically correct but characterless output | --- @@ -75,31 +78,35 @@ A good agent Overview includes: Capability prompts (prompt `.md` files at skill root) are the working instructions for each capability. These should be more procedural than SKILL.md but maintain persona voice consistency. ### Config Header -| Check | Why It Matters | -|-------|----------------| -| Has config header with language variables | Agent needs `{communication_language}` context | -| Uses config variables, not hardcoded values | Flexibility across projects | + +| Check | Why It Matters | +| ------------------------------------------- | ---------------------------------------------- | +| Has config header with language variables | Agent needs `{communication_language}` context | +| Uses config variables, not hardcoded values | Flexibility across projects | ### Self-Containment (Context Compaction Survival) -| Check | Why It Matters | -|-------|----------------| -| Prompt works independently of SKILL.md being in context | Context compaction may drop SKILL.md | -| No references to "as described above" or "per the overview" | Break when context compacts | -| Critical instructions in the prompt, not only in SKILL.md | Instructions only in SKILL.md may be lost | + +| Check | Why It Matters | +| ----------------------------------------------------------- | ----------------------------------------- | +| Prompt works independently of SKILL.md being in context | Context compaction may drop SKILL.md | +| No references to "as described above" or "per the overview" | Break when context compacts | +| Critical instructions in the prompt, not only in SKILL.md | Instructions only in SKILL.md may be lost | ### Intelligence Placement -| Check | Why It Matters | -|-------|----------------| -| Scripts handle deterministic operations | Faster, cheaper, reproducible | -| Prompts handle judgment calls | AI reasoning for semantic understanding | -| No script-based classification of meaning | If regex decides what content MEANS, that's wrong | -| No prompt-based deterministic operations | If a prompt validates structure, counts items, parses known formats, or compares against schemas — that work belongs in a script. Flag as `intelligence-placement` with a note that L6 (script-opportunities scanner) will provide detailed analysis | + +| Check | Why It Matters | +| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Scripts handle deterministic operations | Faster, cheaper, reproducible | +| Prompts handle judgment calls | AI reasoning for semantic understanding | +| No script-based classification of meaning | If regex decides what content MEANS, that's wrong | +| No prompt-based deterministic operations | If a prompt validates structure, counts items, parses known formats, or compares against schemas — that work belongs in a script. Flag as `intelligence-placement` with a note that L6 (script-opportunities scanner) will provide detailed analysis | ### Context Sufficiency -| Check | When to Flag | -|-------|-------------| -| Judgment-heavy prompt with no context on what/why | Always — produces mechanical output | -| Interactive prompt with no user perspective | When capability involves communication | + +| Check | When to Flag | +| -------------------------------------------------- | --------------------------------------- | +| Judgment-heavy prompt with no context on what/why | Always — produces mechanical output | +| Interactive prompt with no user perspective | When capability involves communication | | Classification prompt with no criteria or examples | When prompt must distinguish categories | --- @@ -107,6 +114,7 @@ Capability prompts (prompt `.md` files at skill root) are the working instructio ## Part 3: Universal Craft Quality ### Genuine Token Waste + Flag these — always waste: | Pattern | Example | Fix | |---------|---------|-----| @@ -117,6 +125,7 @@ Flag these — always waste: | Conversational filler | "Let's think about..." | Delete or replace with direct instruction | ### Context That Looks Like Waste But Isn't (Agent-Specific) + Do NOT flag these: | Pattern | Why It's Valuable | |---------|-------------------| @@ -128,12 +137,13 @@ Do NOT flag these: | Warm/coaching tone for interactive agents | Affects the agent's personality expression | ### Outcome vs Implementation Balance -| Agent Type | Lean Toward | Rationale | -|------------|-------------|-----------| -| Simple utility agent | Outcome-focused | Just needs to know WHAT to produce | -| Domain expert agent | Outcome + domain context | Needs domain understanding for judgment | -| Companion/interactive agent | Outcome + persona + communication guidance | Needs to read user and adapt | -| Workflow facilitator agent | Outcome + rationale + selective HOW | Needs to understand WHY for routing | + +| Agent Type | Lean Toward | Rationale | +| --------------------------- | ------------------------------------------ | --------------------------------------- | +| Simple utility agent | Outcome-focused | Just needs to know WHAT to produce | +| Domain expert agent | Outcome + domain context | Needs domain understanding for judgment | +| Companion/interactive agent | Outcome + persona + communication guidance | Needs to read user and adapt | +| Workflow facilitator agent | Outcome + rationale + selective HOW | Needs to understand WHY for routing | ### Pruning: Instructions the Agent Doesn't Need @@ -141,45 +151,48 @@ Beyond micro-step over-specification, check for entire blocks that teach the LLM **Flag as HIGH when a capability prompt contains any of these:** -| Anti-Pattern | Why It's Noise | Example | -|-------------|----------------|---------| -| Scoring formulas for subjective judgment | LLMs naturally assess relevance without numeric weights | "Score each option: relevance(×4) + novelty(×3)" | -| Capability prompt repeating identity/style from SKILL.md | The agent already has this context — repeating it wastes tokens | Capability prompt restating "You are a meticulous reviewer who..." | -| Step-by-step procedures for tasks the persona covers | The agent's personality and domain expertise handle this | "Step 1: greet warmly. Step 2: ask about their day. Step 3: transition to topic" | -| Per-platform adapter instructions | LLMs know their own platform's tools | Separate instructions for how to use subagents on different platforms | -| Template files explaining general capabilities | LLMs know how to format output, structure responses | A reference file explaining how to write a summary | -| Multiple capability files that could be one | Proliferation of files for what should be a single capability | 3 separate capabilities for "review code", "review tests", "review docs" when one "review" capability suffices | +| Anti-Pattern | Why It's Noise | Example | +| -------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| Scoring formulas for subjective judgment | LLMs naturally assess relevance without numeric weights | "Score each option: relevance(×4) + novelty(×3)" | +| Capability prompt repeating identity/style from SKILL.md | The agent already has this context — repeating it wastes tokens | Capability prompt restating "You are a meticulous reviewer who..." | +| Step-by-step procedures for tasks the persona covers | The agent's personality and domain expertise handle this | "Step 1: greet warmly. Step 2: ask about their day. Step 3: transition to topic" | +| Per-platform adapter instructions | LLMs know their own platform's tools | Separate instructions for how to use subagents on different platforms | +| Template files explaining general capabilities | LLMs know how to format output, structure responses | A reference file explaining how to write a summary | +| Multiple capability files that could be one | Proliferation of files for what should be a single capability | 3 separate capabilities for "review code", "review tests", "review docs" when one "review" capability suffices | **Don't flag as over-specified:** + - Domain-specific knowledge the agent genuinely needs (API conventions, project-specific rules) - Design rationale that prevents undermining non-obvious constraints - Persona-establishing context in SKILL.md (identity, style, principles — this is load-bearing, not waste) ### Structural Anti-Patterns -| Pattern | Threshold | Fix | -|---------|-----------|-----| -| Unstructured paragraph blocks | 8+ lines without headers or bullets | Break into sections | -| Suggestive reference loading | "See XYZ if needed" | Mandatory: "Load XYZ and apply criteria" | -| Success criteria that specify HOW | Listing implementation steps | Rewrite as outcome | + +| Pattern | Threshold | Fix | +| --------------------------------- | ----------------------------------- | ---------------------------------------- | +| Unstructured paragraph blocks | 8+ lines without headers or bullets | Break into sections | +| Suggestive reference loading | "See XYZ if needed" | Mandatory: "Load XYZ and apply criteria" | +| Success criteria that specify HOW | Listing implementation steps | Rewrite as outcome | ### Communication Style Consistency -| Check | Why It Matters | -|-------|----------------| -| Capability prompts maintain persona voice | Inconsistent voice breaks immersion | -| Tone doesn't shift between capabilities | Users expect consistent personality | + +| Check | Why It Matters | +| ------------------------------------------------- | ---------------------------------------- | +| Capability prompts maintain persona voice | Inconsistent voice breaks immersion | +| Tone doesn't shift between capabilities | Users expect consistent personality | | Examples in prompts match SKILL.md style guidance | Contradictory examples confuse the agent | --- ## Severity Guidelines -| Severity | When to Apply | -|----------|---------------| -| **Critical** | Missing progression conditions, self-containment failures, intelligence leaks into scripts | -| **High** | Pervasive over-specification (scoring algorithms, capability prompts repeating persona context, adapter proliferation — see Pruning section), SKILL.md over size guidelines with no progressive disclosure, over-optimized complex agent (empty Overview, no persona context), persona voice stripped to bare skeleton | -| **Medium** | Moderate token waste, isolated over-specified procedures, minor voice inconsistency | -| **Low** | Minor verbosity, suggestive reference loading, style preferences | -| **Note** | Observations that aren't issues — e.g., "Persona context is appropriate" | +| Severity | When to Apply | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Critical** | Missing progression conditions, self-containment failures, intelligence leaks into scripts | +| **High** | Pervasive over-specification (scoring algorithms, capability prompts repeating persona context, adapter proliferation — see Pruning section), SKILL.md over size guidelines with no progressive disclosure, over-optimized complex agent (empty Overview, no persona context), persona voice stripped to bare skeleton | +| **Medium** | Moderate token waste, isolated over-specified procedures, minor voice inconsistency | +| **Low** | Minor verbosity, suggestive reference loading, style preferences | +| **Note** | Observations that aren't issues — e.g., "Persona context is appropriate" | **Effectiveness over efficiency:** Never recommend removing context that could degrade output quality, even if it saves significant tokens. Persona voice, domain framing, and design rationale are investments in quality, not waste. When in doubt about whether context is load-bearing, err on the side of keeping it. diff --git a/skills/bmad-agent-builder/quality-scan-script-opportunities.md b/skills/bmad-agent-builder/quality-scan-script-opportunities.md index 903bb09..27dc486 100644 --- a/skills/bmad-agent-builder/quality-scan-script-opportunities.md +++ b/skills/bmad-agent-builder/quality-scan-script-opportunities.md @@ -15,6 +15,7 @@ Read every prompt file and SKILL.md. For each instruction that tells the LLM to ## Scan Targets Find and read: + - `SKILL.md` — On Activation patterns, inline operations - `*.md` (prompt files at root) — Each capability prompt for deterministic operations hiding in LLM instructions - `references/*.md` — Check if any resource content could be generated by scripts instead @@ -26,21 +27,23 @@ Find and read: For each operation in every prompt, ask: -| Question | If Yes | -|----------|--------| -| Given identical input, will this ALWAYS produce identical output? | Script candidate | -| Could you write a unit test with expected output for every input? | Script candidate | -| Does this require interpreting meaning, tone, context, or ambiguity? | Keep as prompt | -| Is this a judgment call that depends on understanding intent? | Keep as prompt | +| Question | If Yes | +| -------------------------------------------------------------------- | ---------------- | +| Given identical input, will this ALWAYS produce identical output? | Script candidate | +| Could you write a unit test with expected output for every input? | Script candidate | +| Does this require interpreting meaning, tone, context, or ambiguity? | Keep as prompt | +| Is this a judgment call that depends on understanding intent? | Keep as prompt | ## Script Opportunity Categories ### 1. Validation Operations + LLM instructions that check structure, format, schema compliance, naming conventions, required fields, or conformance to known rules. **Signal phrases in prompts:** "validate", "check that", "verify", "ensure format", "must conform to", "required fields" **Examples:** + - Checking frontmatter has required fields → Python script - Validating JSON against a schema → Python script with jsonschema - Verifying file naming conventions → Bash/Python script @@ -49,11 +52,13 @@ LLM instructions that check structure, format, schema compliance, naming convent - Access boundary format verification → Python script ### 2. Data Extraction & Parsing + LLM instructions that pull structured data from files without needing to interpret meaning. **Signal phrases:** "extract", "parse", "pull from", "read and list", "gather all" **Examples:** + - Extracting all {variable} references from markdown files → Python regex - Listing all files in a directory matching a pattern → Bash find/glob - Parsing YAML frontmatter from markdown → Python with pyyaml @@ -62,59 +67,70 @@ LLM instructions that pull structured data from files without needing to interpr - Parsing persona fields from SKILL.md → Python script ### 3. Transformation & Format Conversion + LLM instructions that convert between known formats without semantic judgment. **Signal phrases:** "convert", "transform", "format as", "restructure", "reformat" **Examples:** + - Converting markdown table to JSON → Python script - Restructuring JSON from one schema to another → Python script - Generating boilerplate from a template → Python/Bash script ### 4. Counting, Aggregation & Metrics + LLM instructions that count, tally, summarize numerically, or collect statistics. **Signal phrases:** "count", "how many", "total", "aggregate", "summarize statistics", "measure" **Examples:** + - Token counting per file → Python with tiktoken - Counting capabilities, prompts, or resources → Python script - File size/complexity metrics → Bash wc + Python - Memory file inventory and size tracking → Python script ### 5. Comparison & Cross-Reference + LLM instructions that compare two things for differences or verify consistency between sources. **Signal phrases:** "compare", "diff", "match against", "cross-reference", "verify consistency", "check alignment" **Examples:** + - Diffing two versions of a document → git diff or Python difflib - Cross-referencing prompt names against SKILL.md references → Python script - Checking config variables are defined where used → Python regex scan ### 6. Structure & File System Checks + LLM instructions that verify directory structure, file existence, or organizational rules. **Signal phrases:** "check structure", "verify exists", "ensure directory", "required files", "folder layout" **Examples:** + - Verifying agent folder has required files → Bash/Python script - Checking for orphaned files not referenced anywhere → Python script - Memory sidecar structure validation → Python script - Directory tree validation against expected layout → Python script ### 7. Dependency & Graph Analysis + LLM instructions that trace references, imports, or relationships between files. **Signal phrases:** "dependency", "references", "imports", "relationship", "graph", "trace" **Examples:** + - Building skill dependency graph → Python script - Tracing which resources are loaded by which prompts → Python regex - Detecting circular references → Python graph algorithm - Mapping capability → prompt file → resource file chains → Python script ### 8. Pre-Processing for LLM Capabilities (High-Value, Often Missed) + Operations where a script could extract compact, structured data from large files BEFORE the LLM reads them — reducing token cost and improving LLM accuracy. **This is the most creative category.** Look for patterns where the LLM reads a large file and then extracts specific information. A pre-pass script could do the extraction, giving the LLM a compact JSON summary instead of raw content. @@ -122,6 +138,7 @@ Operations where a script could extract compact, structured data from large file **Signal phrases:** "read and analyze", "scan through", "review all", "examine each" **Examples:** + - Pre-extracting file metrics (line counts, section counts, token estimates) → Python script feeding LLM scanner - Building a compact inventory of capabilities → Python script - Extracting all TODO/FIXME markers → grep/Python script @@ -129,9 +146,11 @@ Operations where a script could extract compact, structured data from large file - Pre-extracting memory system structure for validation → Python script ### 9. Post-Processing Validation (Often Missed) + Operations where a script could verify that LLM-generated output meets structural requirements AFTER the LLM produces it. **Examples:** + - Validating generated JSON against schema → Python jsonschema - Checking generated markdown has required sections → Python script - Verifying generated output has required fields → Python script @@ -142,17 +161,18 @@ Operations where a script could verify that LLM-generated output meets structura For each finding, estimate the "LLM Tax" — tokens spent per invocation on work a script could do for zero tokens. This makes findings concrete and prioritizable. -| LLM Tax Level | Tokens Per Invocation | Priority | -|---------------|----------------------|----------| -| Heavy | 500+ tokens on deterministic work | High severity | -| Moderate | 100-500 tokens on deterministic work | Medium severity | -| Light | <100 tokens on deterministic work | Low severity | +| LLM Tax Level | Tokens Per Invocation | Priority | +| ------------- | ------------------------------------ | --------------- | +| Heavy | 500+ tokens on deterministic work | High severity | +| Moderate | 100-500 tokens on deterministic work | Medium severity | +| Light | <100 tokens on deterministic work | Low severity | --- ## Your Toolbox Awareness Scripts are NOT limited to simple validation. They have access to: + - **Bash**: Full shell — `jq`, `grep`, `awk`, `sed`, `find`, `diff`, `wc`, `sort`, `uniq`, `curl`, piping, composition - **Python**: Full standard library (`json`, `yaml`, `pathlib`, `re`, `argparse`, `collections`, `difflib`, `ast`, `csv`, `xml`) plus PEP 723 inline-declared dependencies (`tiktoken`, `jsonschema`, `pyyaml`, `toml`, etc.) - **System tools**: `git` for history/diff/blame, filesystem operations, process execution @@ -165,22 +185,22 @@ Think broadly. A script that parses an AST, builds a dependency graph, extracts For each script opportunity found, also assess: -| Dimension | Question | -|-----------|----------| -| **Pre-pass potential** | Could this script feed structured data to an existing LLM scanner? | -| **Standalone value** | Would this script be useful as a lint check independent of quality analysis? | -| **Reuse across skills** | Could this script be used by multiple skills, not just this one? | +| Dimension | Question | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | +| **Pre-pass potential** | Could this script feed structured data to an existing LLM scanner? | +| **Standalone value** | Would this script be useful as a lint check independent of quality analysis? | +| **Reuse across skills** | Could this script be used by multiple skills, not just this one? | | **--help self-documentation** | Prompts that invoke this script can use `--help` instead of inlining the interface — note the token savings | --- ## Severity Guidelines -| Severity | When to Apply | -|----------|---------------| -| **High** | Large deterministic operations (500+ tokens) in prompts — validation, parsing, counting, structure checks. Clear script candidates with high confidence. | -| **Medium** | Moderate deterministic operations (100-500 tokens), pre-processing opportunities that would improve LLM accuracy, post-processing validation. | -| **Low** | Small deterministic operations (<100 tokens), nice-to-have pre-pass scripts, minor format conversions. | +| Severity | When to Apply | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **High** | Large deterministic operations (500+ tokens) in prompts — validation, parsing, counting, structure checks. Clear script candidates with high confidence. | +| **Medium** | Moderate deterministic operations (100-500 tokens), pre-processing opportunities that would improve LLM accuracy, post-processing validation. | +| **Low** | Small deterministic operations (<100 tokens), nice-to-have pre-pass scripts, minor format conversions. | --- diff --git a/skills/bmad-agent-builder/quality-scan-structure.md b/skills/bmad-agent-builder/quality-scan-structure.md index 5132b78..8e4c16a 100644 --- a/skills/bmad-agent-builder/quality-scan-structure.md +++ b/skills/bmad-agent-builder/quality-scan-structure.md @@ -6,7 +6,7 @@ You are **StructureBot**, a quality engineer who validates the structural integr You validate that an agent's structure is complete, correct, and internally consistent. This covers SKILL.md structure, 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* (capability-prompt alignment). These concerns are tightly coupled — you can't evaluate capability completeness without validating structural integrity. +This is a unified scan covering both _structure_ (correct files, valid sections) and _capabilities_ (capability-prompt alignment). These concerns are tightly coupled — you can't evaluate capability completeness without validating structural integrity. ## Your Role @@ -17,6 +17,7 @@ Read the pre-pass JSON first at `{quality-report-dir}/structure-capabilities-pre Pre-pass provides: frontmatter validation, section inventory, template artifacts, capability cross-reference, 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?) @@ -32,10 +33,11 @@ Read raw files ONLY for: ## 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.) +- Template artifacts (orphaned {if-\*}, {displayName}, etc.) - Memory path inconsistencies - Directness pattern violations @@ -46,84 +48,92 @@ Include all pre-pass findings in your output, preserved as-is. These are determi ## 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', 'analyze agent') | Specific phrases prevent false activations | + +| 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', 'analyze 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 | + +| 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 | + +| 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 | + +| 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 | ### Over-Specification of LLM Capabilities Agents should describe outcomes, not prescribe procedures for things the LLM does naturally. The agent's persona context (identity, communication style, principles) informs HOW — capability prompts should focus on WHAT to achieve. Flag these structural indicators: -| Check | Why It Matters | Severity | -|-------|----------------|----------| -| Capability files that repeat identity/style already in SKILL.md | The agent already has persona context — repeating it in each capability wastes tokens and creates maintenance burden | MEDIUM per file, HIGH if pervasive | -| Multiple capability files doing essentially the same thing | Proliferation adds complexity without value — e.g., separate capabilities for "review code", "review tests", "review docs" when one "review" capability covers all | MEDIUM | -| Capability prompts with step-by-step procedures the persona would handle | The agent's expertise and communication style already guide execution — mechanical procedures override natural behavior | MEDIUM if isolated, HIGH if pervasive | -| Template or reference files explaining general LLM capabilities | Files that teach the LLM how to format output, use tools, or greet users — it already knows | MEDIUM | -| Per-platform adapter files or instructions | The LLM knows its own platform — multiple files for different platforms add tokens without preventing failures | HIGH | +| Check | Why It Matters | Severity | +| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | +| Capability files that repeat identity/style already in SKILL.md | The agent already has persona context — repeating it in each capability wastes tokens and creates maintenance burden | MEDIUM per file, HIGH if pervasive | +| Multiple capability files doing essentially the same thing | Proliferation adds complexity without value — e.g., separate capabilities for "review code", "review tests", "review docs" when one "review" capability covers all | MEDIUM | +| Capability prompts with step-by-step procedures the persona would handle | The agent's expertise and communication style already guide execution — mechanical procedures override natural behavior | MEDIUM if isolated, HIGH if pervasive | +| Template or reference files explaining general LLM capabilities | Files that teach the LLM how to format output, use tools, or greet users — it already knows | MEDIUM | +| Per-platform adapter files or instructions | The LLM knows its own platform — multiple files for different platforms add tokens without preventing failures | HIGH | **Don't flag as over-specification:** + - Domain-specific knowledge the agent genuinely needs - Persona-establishing context in SKILL.md (identity, style, principles are load-bearing) - Design rationale for non-obvious choices ### Logical Consistency -| Check | Why It Matters | -|-------|----------------| -| Identity matches communication style | Identity says "formal expert" but style shows casual examples | -| Activation sequence is logically ordered | Config must load before reading config vars | + +| Check | Why It Matters | +| ---------------------------------------- | ------------------------------------------------------------- | +| Identity matches communication style | Identity says "formal expert" but style shows casual examples | +| Activation sequence is logically ordered | Config must load before reading config vars | ### 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 headless 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 | + +| Check | Why It Matters | +| --------------------------------------------------- | ----------------------------------------------- | +| Memory system file exists if agent declares sidecar | Sidecar without memory spec is incomplete | +| Access boundaries defined | Critical for headless 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 | -|-------|----------------| -| Headless activation prompt exists | Agent declared headless but has no wake prompt | -| Default wake behavior defined | Agent won't know what to do without specific task | -| Headless tasks documented | Users need to know available tasks | + +| Check | Why It Matters | +| --------------------------------- | ------------------------------------------------- | +| Headless activation prompt exists | Agent declared headless but has no wake prompt | +| Default wake behavior defined | Agent won't know what to do without specific task | +| Headless 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, orphaned capabilities pointing to non-existent files | -| **High** | Description too vague to trigger, identity missing or ineffective, 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 | +| Severity | When to Apply | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| **Critical** | Missing SKILL.md, invalid frontmatter (no name), missing required sections, orphaned capabilities pointing to non-existent files | +| **High** | Description too vague to trigger, identity missing or ineffective, 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 | --- diff --git a/skills/bmad-agent-builder/references/quality-dimensions.md b/skills/bmad-agent-builder/references/quality-dimensions.md index 29626cc..c709f93 100644 --- a/skills/bmad-agent-builder/references/quality-dimensions.md +++ b/skills/bmad-agent-builder/references/quality-dimensions.md @@ -16,13 +16,13 @@ The executing agent needs enough context to make judgment calls when situations - 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 +- When in doubt, explain _why_ — an agent that understands the mission improvises better than one following blind steps ## 3. 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. +**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. diff --git a/skills/bmad-agent-builder/references/script-opportunities-reference.md b/skills/bmad-agent-builder/references/script-opportunities-reference.md index b7b3322..0e9e699 100644 --- a/skills/bmad-agent-builder/references/script-opportunities-reference.md +++ b/skills/bmad-agent-builder/references/script-opportunities-reference.md @@ -17,16 +17,20 @@ Scripts validate structure and syntax (deterministic). Prompts evaluate semantic During build, walk through every capability/operation and apply these tests: ### The Determinism Test + For each operation the agent performs, ask: + - Given identical input, will this ALWAYS produce identical output? → Script - Does this require interpreting meaning, tone, context, or ambiguity? → Prompt - Could you write a unit test with expected output for every input? → Script ### The Judgment Boundary + Scripts handle: fetch, transform, validate, count, parse, compare, extract, format, check structure Prompts handle: interpret, classify with ambiguity, create, decide with incomplete info, evaluate quality, synthesize meaning ### Pattern Recognition Checklist + Table of signal verbs/patterns mapping to script types: | Signal Verb/Pattern | Script Type | |---------------------|-------------| @@ -41,7 +45,9 @@ Table of signal verbs/patterns mapping to script types: | "graph", "map dependencies" | Dependency analysis script | ### The Outside-the-Box Test + Beyond obvious validation, consider: + - Could any data gathering step be a script that returns structured JSON for the LLM to interpret? - Could pre-processing reduce what the LLM needs to read? - Could post-processing validate what the LLM produced? @@ -58,6 +64,7 @@ Beyond obvious validation, consider: If you can express the logic as deterministic code, it's a script candidate. ### The --help Pattern + All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a script, it can say "Run `scripts/foo.py --help` to understand inputs/outputs, then invoke appropriately" instead of inlining the script's interface. This saves tokens in prompts and keeps a single source of truth for the script's API. --- @@ -71,6 +78,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc **Why:** Frontmatter is the #1 factor in skill triggering. Catch errors early. **Checks:** + ```python # checks: - name exists and is kebab-case @@ -104,6 +112,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc **Why:** Security critical — must be defined before file operations **Checks:** + ```python # Parse memory-system.md for: - ## Read Access section exists @@ -129,6 +138,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc **Why:** Identify verbose files that need optimization **Checks:** + ```python # For each .md file: - Total tokens (approximate: chars / 4) @@ -149,6 +159,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc **Why:** Understand agent's dependency surface **Checks:** + ```python # Parse SKILL.md for skill invocation patterns # Parse prompt files for external skill references @@ -184,6 +195,7 @@ Validate that the activation sequence is logically ordered (e.g., config loads b **Why:** Memory files have specific requirements **Checks:** + ```python # Required sections: - ## Core Principle @@ -205,6 +217,7 @@ Validate that the activation sequence is logically ordered (e.g., config loads b **Why:** Agents processing 5+ sources MUST use subagents **Checks:** + ```python # Pattern detection in SKILL.md: - "DO NOT read sources yourself" @@ -242,6 +255,7 @@ Validate that the activation sequence is logically ordered (e.g., config loads b **Why:** Validate changes during iteration **Checks:** + ```bash # Git diff with structure awareness: - Frontmatter changes @@ -271,7 +285,7 @@ All scripts MUST output structured JSON for agent consumption: { "severity": "critical|high|medium|low|info", "category": "structure|security|performance|consistency", - "location": {"file": "SKILL.md", "line": 42}, + "location": { "file": "SKILL.md", "line": 42 }, "issue": "Clear description", "fix": "Specific action to resolve" } @@ -313,6 +327,7 @@ The Quality Analysis skill should: 3. **Finally**: Synthesize both sources into report **Example flow:** + ```bash # Run all validation scripts python scripts/validate-frontmatter.py --agent-path {path} @@ -328,18 +343,12 @@ bash scripts/scan-template-artifacts.sh --agent-path {path} ## Script Creation Priorities **Phase 1 (Immediate value):** + 1. Template Artifact Scanner (Bash + jq) 2. Access Boundaries Extractor (Python) -**Phase 2 (Enhanced validation):** -4. Token Counter (Python) -5. Subagent Pattern Detector (Python) -6. Activation Flow Analyzer (Python) +**Phase 2 (Enhanced validation):** 4. Token Counter (Python) 5. Subagent Pattern Detector (Python) 6. Activation Flow Analyzer (Python) -**Phase 3 (Advanced features):** -7. Dependency Graph Generator (Python) -8. Memory Structure Validator (Python) -9. Agent Health Check orchestrator (Bash) +**Phase 3 (Advanced features):** 7. Dependency Graph Generator (Python) 8. Memory Structure Validator (Python) 9. Agent Health Check orchestrator (Bash) -**Phase 4 (Comparison tools):** -10. Comparison Validator (Bash + Python) +**Phase 4 (Comparison tools):** 10. Comparison Validator (Bash + Python) diff --git a/skills/bmad-agent-builder/references/script-standards.md b/skills/bmad-agent-builder/references/script-standards.md index 62028f3..0c7cc2d 100644 --- a/skills/bmad-agent-builder/references/script-standards.md +++ b/skills/bmad-agent-builder/references/script-standards.md @@ -7,6 +7,7 @@ When building scripts for a skill, follow these standards to ensure portability **Always favor Python for script logic.** Bash is not portable — it fails or behaves inconsistently on Windows (Git Bash is MSYS2-based, not a full Linux shell; WSL bash can conflict with Git Bash on PATH; PowerShell is a different language entirely). Python with `uv run` works identically on all platforms. **Safe bash commands** — these work reliably across all environments and are fine to use directly: + - `git`, `gh` — version control and GitHub CLI - `uv run` — Python script execution with automatic dependency handling - `npm`, `npx`, `pnpm` — Node.js ecosystem @@ -51,6 +52,7 @@ For scripts using only the standard library, use a plain Python shebang but stil ``` **Key rules:** + - The shebang MUST be line 1 — before the metadata block - Always include `requires-python` - List all external dependencies with version constraints @@ -73,6 +75,7 @@ Skills may run in environments where Python or `uv` is unavailable (e.g., claude **Pattern:** When a script cannot execute, the LLM performs the equivalent work directly. The script's `--help` documents what it checks, making this fallback natural. Design scripts so their logic is understandable from their help output and the skill's context. In SKILL.md, frame script steps as outcomes, not just commands: + - Good: "Validate path conventions (run `scripts/scan-paths.py --help` for details)" - Avoid: "Execute `python3 scripts/scan-paths.py`" with no context about what it does diff --git a/skills/bmad-agent-builder/references/skill-best-practices.md b/skills/bmad-agent-builder/references/skill-best-practices.md index b10e6f0..7353c10 100644 --- a/skills/bmad-agent-builder/references/skill-best-practices.md +++ b/skills/bmad-agent-builder/references/skill-best-practices.md @@ -10,11 +10,11 @@ Skills should describe **what to achieve**, not **how to achieve it**. The LLM i ### Outcome vs Prescriptive -| Prescriptive (avoid) | Outcome-based (prefer) | -|---|---| -| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." | -| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." | -| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." | +| Prescriptive (avoid) | Outcome-based (prefer) | +| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." | +| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." | +| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." | The prescriptive versions miss requirements the author didn't think of. The outcome-based versions let the LLM adapt to the actual situation. @@ -29,11 +29,11 @@ The prescriptive versions miss requirements the author didn't think of. The outc Reserve exact steps for **fragile operations** where getting it wrong has consequences — script invocations, exact file paths, specific CLI commands, API calls with precise parameters. These need low freedom because there's one right way to do them. -| Freedom | When | Example | -|---------|------|---------| -| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" | -| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" | -| **Low** (exact) | Fragile, one right way, consequences for deviation | `python3 scripts/scan-path-standards.py {skill-path}` | +| Freedom | When | Example | +| ------------------- | -------------------------------------------------- | ------------------------------------------------------------------- | +| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" | +| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" | +| **Low** (exact) | Fragile, one right way, consequences for deviation | `python3 scripts/scan-path-standards.py {skill-path}` | ## Patterns @@ -63,10 +63,10 @@ Before finalizing significant artifacts, fan out reviewers with different perspe Consider whether the skill benefits from multiple execution modes: -| Mode | When | Behavior | -|------|------|----------| -| **Guided** | Default | Conversational discovery with soft gates | -| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine | +| Mode | When | Behavior | +| ------------ | ------------------- | ------------------------------------------------------------- | +| **Guided** | Default | Conversational discovery with soft gates | +| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine | | **Headless** | `--headless` / `-H` | Complete the task without user input, using sensible defaults | Not all skills need all three. But considering them during design prevents locking into a single interaction model. @@ -90,16 +90,16 @@ For complex tasks with consequences: plan → validate → execute → verify. C ## Anti-Patterns -| Anti-Pattern | Fix | -|---|---| -| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters | -| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) | -| Prescribing exact greeting/menu format | "Greet the user and present capabilities" | -| Spelling out headless mode in detail | "If headless, complete without user input" | -| Too many options upfront | One default with escape hatch | -| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md | -| Inconsistent terminology | Choose one term per concept | -| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts | +| Anti-Pattern | Fix | +| -------------------------------------------------- | ----------------------------------------------------- | +| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters | +| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) | +| Prescribing exact greeting/menu format | "Greet the user and present capabilities" | +| Spelling out headless mode in detail | "If headless, complete without user input" | +| Too many options upfront | One default with escape hatch | +| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md | +| Inconsistent terminology | Choose one term per concept | +| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts | ## Scripts in Skills diff --git a/skills/bmad-agent-builder/references/standard-fields.md b/skills/bmad-agent-builder/references/standard-fields.md index afb442a..01d0a21 100644 --- a/skills/bmad-agent-builder/references/standard-fields.md +++ b/skills/bmad-agent-builder/references/standard-fields.md @@ -4,28 +4,29 @@ Only these fields go in the YAML frontmatter block: -| Field | Description | Example | -|-------|-------------|---------| -| `name` | Full skill name (kebab-case, same as folder name) | `bmad-agent-tech-writer`, `bmad-cis-agent-lila` | -| `description` | [What it does]. [Use when user says 'X' or 'Y'.] | See Description Format below | +| Field | Description | Example | +| ------------- | ------------------------------------------------- | ----------------------------------------------- | +| `name` | Full skill name (kebab-case, same as folder name) | `bmad-agent-tech-writer`, `bmad-cis-agent-lila` | +| `description` | [What it does]. [Use when user says 'X' or 'Y'.] | See Description Format below | ## Content Fields These are used within the SKILL.md body — never in frontmatter: -| Field | Description | Example | -|-------|-------------|---------| -| `displayName` | Friendly name (title heading, greetings) | `Paige`, `Lila`, `Floyd` | -| `title` | Role title | `Tech Writer`, `Holodeck Operator` | -| `icon` | Single emoji | `🔥`, `🌟` | -| `role` | Functional role | `Technical Documentation Specialist` | -| `sidecar` | Memory folder (optional) | `{skillName}-sidecar/` | +| Field | Description | Example | +| ------------- | ---------------------------------------- | ------------------------------------ | +| `displayName` | Friendly name (title heading, greetings) | `Paige`, `Lila`, `Floyd` | +| `title` | Role title | `Tech Writer`, `Holodeck Operator` | +| `icon` | Single emoji | `🔥`, `🌟` | +| `role` | Functional role | `Technical Documentation Specialist` | +| `sidecar` | Memory folder (optional) | `{skillName}-sidecar/` | ## Overview Section Format The Overview is the first section after the title — it primes the AI for everything that follows. **3-part formula:** + 1. **What** — What this agent does 2. **How** — How it works (role, approach, modes) 3. **Why/Outcome** — Value delivered, quality standard @@ -33,16 +34,19 @@ The Overview is the first section after the title — it primes the AI for every **Templates by agent type:** **Companion agents:** + ```markdown This skill provides a {role} who helps users {primary outcome}. Act as {displayName} — {key quality}. With {key features}, {displayName} {primary value proposition}. ``` **Workflow agents:** + ```markdown This skill helps you {outcome} through {approach}. Act as {role}, guiding users through {key stages/phases}. Your output is {deliverable}. ``` **Utility agents:** + ```markdown This skill {what it does}. Use when {when to use}. Returns {output format} with {key feature}. ``` @@ -58,6 +62,7 @@ This skill {what it does}. Use when {when to use}. Returns {output format} with ### Skill-Internal Files All references to files within the skill use `./` relative paths: + - `./references/memory-system.md` - `./references/some-guide.md` - `./scripts/calculate-metrics.py` @@ -73,7 +78,7 @@ The sidecar `index.md` is the single entry point to the agent's memory system ### Config Variables Use directly — they already contain `{project-root}` in their resolved values: + - `{output_folder}/file.md` - Correct: `{bmad_builder_output_folder}/agent.md` - Wrong: `{project-root}/{bmad_builder_output_folder}/agent.md` (double-prefix) - diff --git a/skills/bmad-agent-builder/references/template-substitution-rules.md b/skills/bmad-agent-builder/references/template-substitution-rules.md index 0d2b29d..0d90fa3 100644 --- a/skills/bmad-agent-builder/references/template-substitution-rules.md +++ b/skills/bmad-agent-builder/references/template-substitution-rules.md @@ -13,12 +13,14 @@ The SKILL-template provides a minimal skeleton: frontmatter, overview, agent ide ## Module Conditionals ### For Module-Based Agents + - `{if-module}` ... `{/if-module}` → Keep the content inside - `{if-standalone}` ... `{/if-standalone}` → Remove the entire block including markers - `{module-code}` → Module code without trailing hyphen (e.g., `cis`) - `{module-setup-skill}` → Name of the module's setup skill (e.g., `bmad-cis-setup`) ### For Standalone Agents + - `{if-module}` ... `{/if-module}` → Remove the entire block including markers - `{if-standalone}` ... `{/if-standalone}` → Keep the content inside @@ -38,6 +40,7 @@ The builder determines the rest of the agent structure — capabilities, activat ## Path References All generated agents use `./` prefix for skill-internal paths: + - `./references/init.md` — First-run onboarding (if sidecar) - `./references/{capability}.md` — Individual capability prompts - `./references/memory-system.md` — Memory discipline (if sidecar) diff --git a/skills/bmad-agent-builder/report-quality-scan-creator.md b/skills/bmad-agent-builder/report-quality-scan-creator.md index 3c0aee3..b9d02e2 100644 --- a/skills/bmad-agent-builder/report-quality-scan-creator.md +++ b/skills/bmad-agent-builder/report-quality-scan-creator.md @@ -14,6 +14,7 @@ Your job is **synthesis, not transcription.** Don't list findings by scanner. Id ### Step 1: Read Everything Read all files in `{quality-report-dir}`: + - `*-temp.json` — Lint script output (structured JSON with findings arrays) - `*-prepass.json` — Pre-pass metrics (structural data, token counts, capabilities) - `*-analysis.md` — LLM scanner analyses (free-form markdown) @@ -27,6 +28,7 @@ From the agent's SKILL.md, synthesize a 2-3 sentence portrait that captures who ### Step 3: Build the Capability Dashboard From the routing table in SKILL.md, list every capability. Cross-reference with scanner findings — any finding that references a capability file gets associated with that capability. Rate each: + - **Good** — no findings or only low/note severity - **Needs attention** — medium+ findings referencing this capability @@ -39,6 +41,7 @@ Look across ALL scanner output for **findings that share a root cause** — obse Ask: "If I fixed X, how many findings across all scanners would this resolve?" Group related findings into 3-5 themes. A theme has: + - **Name** — clear description of the root cause - **Description** — what's happening and why it matters (2-3 sentences) - **Severity** — highest severity of constituent findings @@ -60,6 +63,7 @@ Gather strengths from all scanners. These tell the user what NOT to break — es ### Step 7: Organize Detailed Analysis For each analysis dimension, summarize the scanner's assessment and list findings not covered by themes: + - **Structure & Capabilities** — from structure scanner - **Persona & Voice** — from prompt-craft scanner (agent-specific framing) - **Identity Cohesion** — from agent-cohesion scanner @@ -88,9 +92,9 @@ Order by impact — "how many findings does fixing this resolve?" The fix that c ## Capabilities -| Capability | Status | Observations | -|-----------|--------|-------------| -| {name} | Good / Needs attention | {count or —} | +| Capability | Status | Observations | +| ---------- | ---------------------- | ------------ | +| {name} | Good / Needs attention | {count or —} | ## Assessment @@ -113,10 +117,15 @@ Order by impact — "how many findings does fixing this resolve?" The fix that c ## Detailed Analysis ### Structure & Capabilities + ### Persona & Voice + ### Identity Cohesion + ### Execution Efficiency + ### Conversation Experience + ### Script Opportunities ## Recommendations @@ -254,6 +263,7 @@ Every `"..."` below is a placeholder for your content. Replace with actual value ``` **Self-check before writing report-data.json:** + 1. Is `meta.skill_name` present (not `meta.skill` or `meta.name`)? 2. Is `meta.scanner_count` a number (not an array)? 3. Does `agent_profile` have all 4 fields: `icon`, `display_name`, `title`, `portrait`? diff --git a/skills/bmad-builder-setup/SKILL.md b/skills/bmad-builder-setup/SKILL.md index b02837e..28640c2 100644 --- a/skills/bmad-builder-setup/SKILL.md +++ b/skills/bmad-builder-setup/SKILL.md @@ -69,7 +69,7 @@ Check `directories_removed` and `files_removed_count` in the JSON output for the ## Confirm -Use the script JSON output to display what was written — config values set (written to `config.yaml` at root for core, module section for module values), user settings written to `config.user.yaml` (`user_keys` in result), help entries added, fresh install vs update. If legacy files were deleted, mention the migration. If legacy directories were removed, report the count and list (e.g. "Cleaned up 106 installer package files from bmb/, core/, _config/ — skills are installed at .claude/skills/"). Then display the `module_greeting` from `./assets/module.yaml` to the user. +Use the script JSON output to display what was written — config values set (written to `config.yaml` at root for core, module section for module values), user settings written to `config.user.yaml` (`user_keys` in result), help entries added, fresh install vs update. If legacy files were deleted, mention the migration. If legacy directories were removed, report the count and list (e.g. "Cleaned up 106 installer package files from bmb/, core/, \_config/ — skills are installed at .claude/skills/"). Then display the `module_greeting` from `./assets/module.yaml` to the user. ## Outcome diff --git a/skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml b/skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml index 58d49ae..e949ecb 100644 --- a/skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml +++ b/skills/bmad-module-builder/assets/setup-skill-template/assets/module.yaml @@ -4,4 +4,3 @@ description: "" module_version: 1.0.0 default_selected: false module_greeting: > - diff --git a/skills/bmad-workflow-builder/SKILL.md b/skills/bmad-workflow-builder/SKILL.md index a1227d5..2da1f70 100644 --- a/skills/bmad-workflow-builder/SKILL.md +++ b/skills/bmad-workflow-builder/SKILL.md @@ -44,12 +44,12 @@ Load `quality-analysis.md` to begin. ## Skill Intent Routing Reference -| Intent | Trigger Phrases | Route | -|--------|----------------|-------| -| **Build new** | "build/create/design a workflow/skill/tool" | Load `build-process.md` | +| Intent | Trigger Phrases | Route | +| --------------------------- | ----------------------------------------------------- | ---------------------------------------- | +| **Build new** | "build/create/design a workflow/skill/tool" | Load `build-process.md` | | **Existing skill provided** | Path to existing skill, or "convert/edit/fix/analyze" | Ask the 3-way question below, then route | -| **Quality analyze** | "quality check", "validate", "review workflow/skill" | Load `quality-analysis.md` | -| **Unclear** | — | Present options and ask | +| **Quality analyze** | "quality check", "validate", "review workflow/skill" | Load `quality-analysis.md` | +| **Unclear** | — | Present options and ask | ### When given an existing skill, ask: diff --git a/skills/bmad-workflow-builder/assets/SKILL-template.md b/skills/bmad-workflow-builder/assets/SKILL-template.md index 70573a7..9a71ac2 100644 --- a/skills/bmad-workflow-builder/assets/SKILL-template.md +++ b/skills/bmad-workflow-builder/assets/SKILL-template.md @@ -1,6 +1,6 @@ --- name: bmad-{module-code-or-empty}{skill-name} -description: {skill-description} # [5-8 word summary]. [trigger phrases, e.g. Use when user says create xyz or wants to do abc] +description: { skill-description } # [5-8 word summary]. [trigger phrases, e.g. Use when user says create xyz or wants to do abc] --- # {skill-name} diff --git a/skills/bmad-workflow-builder/build-process.md b/skills/bmad-workflow-builder/build-process.md index 33fcab0..e9b6898 100644 --- a/skills/bmad-workflow-builder/build-process.md +++ b/skills/bmad-workflow-builder/build-process.md @@ -14,6 +14,7 @@ Build workflows and skills through conversational discovery. Your north star: ** Understand their vision before diving into specifics. Let them describe what they want to build — encourage detail on edge cases, tone, persona, tools, and other skills involved. **Input flexibility:** Accept input in any format: + - Existing BMad workflow/skill path → read and extract intent (see below) - Rough idea or description → guide through discovery - Code, documentation, API specs → extract intent and requirements @@ -21,9 +22,10 @@ Understand their vision before diving into specifics. Let them describe what the ### When given an existing skill -**Critical:** Treat the existing skill as a **description of intent**, not a specification to follow. Extract *what* it's trying to achieve. Do not inherit its verbosity, structure, or mechanical procedures — the old skill is reference material, not a template. +**Critical:** Treat the existing skill as a **description of intent**, not a specification to follow. Extract _what_ it's trying to achieve. Do not inherit its verbosity, structure, or mechanical procedures — the old skill is reference material, not a template. If the SKILL.md routing already asked the 3-way question (Analyze/Edit/Rebuild), proceed with that intent. Otherwise ask now: + - **Edit** — changing specific behavior while keeping the current approach - **Rebuild** — rethinking from core outcomes, full discovery using the old skill as context @@ -46,14 +48,16 @@ The goal is to conversationally gather enough to cover Phase 2 and 3 naturally. ## Phase 2: Classify Skill Type Ask upfront: + - Will this be part of a module? If yes: - - What's the module code? - - What other skills will it use from the core or module? (need name, inputs, outputs for integration) - - What config variables does it need access to? + - What's the module code? + - What other skills will it use from the core or module? (need name, inputs, outputs for integration) + - What config variables does it need access to? Load `./references/classification-reference.md` and classify. Present classification with reasoning. For Simple Workflows and Complex Workflows, also ask: + - **Headless mode?** Should this support `--headless`? (If it produces an artifact, headless is often valuable) ## Phase 3: Gather Requirements @@ -61,6 +65,7 @@ For Simple Workflows and Complex Workflows, also ask: Work through conversationally, adapted per skill type. Glean from what the user already shared or suggest based on their narrative. **All types — Common fields:** + - **Name:** kebab-case. Module: `bmad-{modulecode}-{skillname}`. Standalone: `bmad-{skillname}` - **Description:** Two parts: [5-8 word summary]. [Use when user says 'specific phrase'.] — Default to conservative triggering. See `./references/standard-fields.md` for format. - **Overview:** What/How/Why-Outcome. For interactive or complex skills, include domain framing and theory of mind — these give the executing agent context for judgment calls. @@ -71,18 +76,22 @@ Work through conversationally, adapted per skill type. Glean from what the user - **Creates output documents?** If yes, will use `{document_output_language}` **Simple Utility additional:** + - Input/output format, standalone?, composability **Simple Workflow additional:** + - Steps (inline in SKILL.md), config variables **Complex Workflow additional:** + - Stages with purposes, progression conditions, headless behavior, config variables **Module capability metadata (if part of a module):** Confirm with user: phase-name, after (dependencies), before (downstream), is-required, description (short — what it produces, not how). **Path conventions (CRITICAL):** + - Skill-internal: `./references/`, `./scripts/` - Project `_bmad` paths: `{project-root}/_bmad/...` - Config variables used directly — they already contain `{project-root}` @@ -96,6 +105,7 @@ Think one level deeper. Clarify gaps in logic or understanding. Create and prese For every planned instruction, ask: **would the LLM do this correctly without being told?** If yes, cut it. Scoring algorithms, calibration tables, decision matrices for subjective judgment, weighted formulas — these are things LLMs handle naturally. The instruction must earn its place by preventing a failure that would otherwise happen. Watch especially for: + - Mechanical procedures for tasks the LLM does through general capability - Per-platform instructions when a single adaptive instruction works - Templates that explain things the LLM already knows (how to format output, how to greet users) @@ -104,16 +114,19 @@ Watch especially for: ## Phase 5: Build **Load these before building:** + - `./references/standard-fields.md` — field definitions, description format, path rules - `./references/skill-best-practices.md` — outcome-driven authoring, patterns, anti-patterns - `./references/quality-dimensions.md` — build quality checklist **Load based on skill type:** + - **If Complex Workflow:** `./references/complex-workflow-patterns.md` — compaction survival, config integration, progressive disclosure Load the template from `./assets/SKILL-template.md` and `./references/template-substitution-rules.md`. Build the skill with progressive disclosure (SKILL.md for overview and routing, `./references/` for progressive disclosure content). Output to `{bmad_builder_output_folder}`. **Skill Source Tree** (only create subfolders that are needed): + ``` {skill-name}/ ├── SKILL.md # Frontmatter, overview, activation, routing @@ -123,12 +136,12 @@ Load the template from `./assets/SKILL-template.md` and `./references/template-s │ └── tests/ ``` -| Location | Contains | LLM relationship | -|----------|----------|-----------------| -| **SKILL.md** | Overview, activation, routing | LLM identity and router | -| **`./references/`** | Capability prompts, reference data | Loaded on demand | -| **`./assets/`** | Templates, starter files | Copied/transformed into output | -| **`./scripts/`** | Python, shell scripts with tests | Invoked for deterministic operations | +| Location | Contains | LLM relationship | +| ------------------- | ---------------------------------- | ------------------------------------ | +| **SKILL.md** | Overview, activation, routing | LLM identity and router | +| **`./references/`** | Capability prompts, reference data | Loaded on demand | +| **`./assets/`** | Templates, starter files | Copied/transformed into output | +| **`./scripts/`** | Python, shell scripts with tests | Invoked for deterministic operations | **If the built skill includes scripts**, also load `./references/script-standards.md` — ensures PEP 723 metadata, correct shebangs, and `uv run` invocation from the start. diff --git a/skills/bmad-workflow-builder/quality-analysis.md b/skills/bmad-workflow-builder/quality-analysis.md index c239277..3d5a9a6 100644 --- a/skills/bmad-workflow-builder/quality-analysis.md +++ b/skills/bmad-workflow-builder/quality-analysis.md @@ -34,33 +34,33 @@ Check for uncommitted changes. In headless mode, note warnings and proceed. In i These run instantly, cost zero tokens, and produce structured JSON: -| # | Script | Focus | Output File | -|---|--------|-------|-------------| -| S1 | `scripts/scan-path-standards.py` | Path conventions | `path-standards-temp.json` | -| S2 | `scripts/scan-scripts.py` | Script portability, PEP 723, unit tests | `scripts-temp.json` | +| # | Script | Focus | Output File | +| --- | -------------------------------- | --------------------------------------- | -------------------------- | +| S1 | `scripts/scan-path-standards.py` | Path conventions | `path-standards-temp.json` | +| S2 | `scripts/scan-scripts.py` | Script portability, PEP 723, unit tests | `scripts-temp.json` | ### Pre-Pass Scripts (Feed LLM Scanners) Extract metrics so LLM scanners work from compact data instead of raw files: -| # | Script | Feeds | Output File | -|---|--------|-------|-------------| -| P1 | `scripts/prepass-workflow-integrity.py` | workflow-integrity scanner | `workflow-integrity-prepass.json` | -| P2 | `scripts/prepass-prompt-metrics.py` | prompt-craft scanner | `prompt-metrics-prepass.json` | -| P3 | `scripts/prepass-execution-deps.py` | execution-efficiency scanner | `execution-deps-prepass.json` | +| # | Script | Feeds | Output File | +| --- | --------------------------------------- | ---------------------------- | --------------------------------- | +| P1 | `scripts/prepass-workflow-integrity.py` | workflow-integrity scanner | `workflow-integrity-prepass.json` | +| P2 | `scripts/prepass-prompt-metrics.py` | prompt-craft scanner | `prompt-metrics-prepass.json` | +| P3 | `scripts/prepass-execution-deps.py` | execution-efficiency scanner | `execution-deps-prepass.json` | ### LLM Scanners (Judgment-Based — Run After Scripts) Each scanner writes a free-form analysis document (not JSON): -| # | Scanner | Focus | Pre-Pass? | Output File | -|---|---------|-------|-----------|-------------| -| L1 | `quality-scan-workflow-integrity.md` | Structural completeness, naming, type-appropriate requirements | Yes | `workflow-integrity-analysis.md` | -| L2 | `quality-scan-prompt-craft.md` | Token efficiency, outcome-driven balance, progressive disclosure, pruning | Yes | `prompt-craft-analysis.md` | -| L3 | `quality-scan-execution-efficiency.md` | Parallelization, subagent delegation, context optimization | Yes | `execution-efficiency-analysis.md` | -| L4 | `quality-scan-skill-cohesion.md` | Stage flow, purpose alignment, complexity appropriateness | No | `skill-cohesion-analysis.md` | -| L5 | `quality-scan-enhancement-opportunities.md` | Edge cases, UX gaps, user journeys, headless potential | No | `enhancement-opportunities-analysis.md` | -| L6 | `quality-scan-script-opportunities.md` | Deterministic operations that should be scripts | No | `script-opportunities-analysis.md` | +| # | Scanner | Focus | Pre-Pass? | Output File | +| --- | ------------------------------------------- | ------------------------------------------------------------------------- | --------- | --------------------------------------- | +| L1 | `quality-scan-workflow-integrity.md` | Structural completeness, naming, type-appropriate requirements | Yes | `workflow-integrity-analysis.md` | +| L2 | `quality-scan-prompt-craft.md` | Token efficiency, outcome-driven balance, progressive disclosure, pruning | Yes | `prompt-craft-analysis.md` | +| L3 | `quality-scan-execution-efficiency.md` | Parallelization, subagent delegation, context optimization | Yes | `execution-efficiency-analysis.md` | +| L4 | `quality-scan-skill-cohesion.md` | Stage flow, purpose alignment, complexity appropriateness | No | `skill-cohesion-analysis.md` | +| L5 | `quality-scan-enhancement-opportunities.md` | Edge cases, UX gaps, user journeys, headless potential | No | `enhancement-opportunities-analysis.md` | +| L6 | `quality-scan-script-opportunities.md` | Deterministic operations that should be scripts | No | `script-opportunities-analysis.md` | ## Execution @@ -87,6 +87,7 @@ After scripts complete, spawn all applicable LLM scanners as parallel subagents. **For scanners WITHOUT pre-pass (L4, L5, L6):** provide just the skill path and output directory. Each subagent receives: + - Scanner file to load - Skill path: `{skill-path}` - Output directory: `{report-dir}` @@ -99,10 +100,12 @@ The subagent loads the scanner file, analyzes the skill, writes its analysis to After all scanners complete, spawn a subagent with `report-quality-scan-creator.md`. Provide: + - `{skill-path}` — The skill being analyzed - `{quality-report-dir}` — Directory containing all scanner output The report creator reads everything, synthesizes themes, and writes: + 1. `quality-report.md` — Narrative markdown report 2. `report-data.json` — Structured data for HTML @@ -121,6 +124,7 @@ This reads `report-data.json` and produces `quality-report.html` — a self-cont **IF `{headless_mode}=true`:** Read `report-data.json` and output: + ```json { "headless_mode": true, @@ -138,6 +142,7 @@ Read `report-data.json` and output: **IF interactive:** Read `report-data.json` and present: + 1. Grade and narrative — the 2-3 sentence synthesis 2. Broken items (if any) — critical/high issues prominently 3. Top opportunities — theme names with finding counts and impact diff --git a/skills/bmad-workflow-builder/quality-scan-enhancement-opportunities.md b/skills/bmad-workflow-builder/quality-scan-enhancement-opportunities.md index ecb080a..e618556 100644 --- a/skills/bmad-workflow-builder/quality-scan-enhancement-opportunities.md +++ b/skills/bmad-workflow-builder/quality-scan-enhancement-opportunities.md @@ -6,7 +6,7 @@ You are **DreamBot**, a creative disruptor who pressure-tests workflows by imagi Other scanners check if a skill is built correctly, crafted well, runs efficiently, and holds together. You ask the question none of them do: **"What's missing that nobody thought of?"** -You read a skill and genuinely *inhabit* it — imagine yourself as six different users with six different contexts, skill levels, moods, and intentions. Then you find the moments where the skill would confuse, frustrate, dead-end, or underwhelm them. You also find the moments where a single creative addition would transform the experience from functional to delightful. +You read a skill and genuinely _inhabit_ it — imagine yourself as six different users with six different contexts, skill levels, moods, and intentions. Then you find the moments where the skill would confuse, frustrate, dead-end, or underwhelm them. You also find the moments where a single creative addition would transform the experience from functional to delightful. This is the BMad dreamer scanner. Your job is to push boundaries, challenge assumptions, and surface the ideas that make builders say "I never thought of that." Then temper each wild idea into a concrete, succinct suggestion the builder can actually act on. @@ -26,6 +26,7 @@ You are NOT checking structure, craft quality, performance, or test coverage — ## Scan Targets Find and read: + - `SKILL.md` — Understand the skill's purpose, audience, and flow - `*.md` prompt files at root — Walk through each stage as a user would experience it - `references/*.md` — Understand what supporting material exists @@ -37,6 +38,7 @@ Find and read: Imagine real users in real situations. What breaks, confuses, or dead-ends? **User archetypes to inhabit:** + - The **first-timer** who has never used this kind of tool before - The **expert** who knows exactly what they want and finds the workflow too slow - The **confused user** who invoked this skill by accident or with the wrong intent @@ -45,6 +47,7 @@ Imagine real users in real situations. What breaks, confuses, or dead-ends? - The **automator** — a cron job, CI pipeline, or another agent that wants to invoke this skill headless with pre-supplied inputs and get back a result **Questions to ask at each stage:** + - What if the user provides partial, ambiguous, or contradictory input? - What if the user wants to skip this stage or go back to a previous one? - What if the user's real need doesn't fit the skill's assumed categories? @@ -54,43 +57,43 @@ Imagine real users in real situations. What breaks, confuses, or dead-ends? ### 2. Experience Gaps -Where does the skill deliver output but miss the *experience*? +Where does the skill deliver output but miss the _experience_? -| Gap Type | What to Look For | -|----------|-----------------| -| **Dead-end moments** | User hits a state where the skill has nothing to offer and no guidance on what to do next | -| **Assumption walls** | Skill assumes knowledge, context, or setup the user might not have | -| **Missing recovery** | Error or unexpected input with no graceful path forward | -| **Abandonment friction** | User wants to stop mid-workflow but there's no clean exit or state preservation | -| **Success amnesia** | Skill completes but doesn't help the user understand or use what was produced | -| **Invisible value** | Skill does something valuable but doesn't surface it to the user | +| Gap Type | What to Look For | +| ------------------------ | ----------------------------------------------------------------------------------------- | +| **Dead-end moments** | User hits a state where the skill has nothing to offer and no guidance on what to do next | +| **Assumption walls** | Skill assumes knowledge, context, or setup the user might not have | +| **Missing recovery** | Error or unexpected input with no graceful path forward | +| **Abandonment friction** | User wants to stop mid-workflow but there's no clean exit or state preservation | +| **Success amnesia** | Skill completes but doesn't help the user understand or use what was produced | +| **Invisible value** | Skill does something valuable but doesn't surface it to the user | ### 3. Delight Opportunities Where could a small addition create outsized positive impact? -| Opportunity Type | Example | -|-----------------|---------| -| **Quick-win mode** | "I already have a spec, skip the interview" — let experienced users fast-track | -| **Smart defaults** | Infer reasonable defaults from context instead of asking every question | -| **Proactive insight** | "Based on what you've described, you might also want to consider..." | -| **Progress awareness** | Help the user understand where they are in a multi-stage workflow | -| **Memory leverage** | Use prior conversation context or project knowledge to personalize | -| **Graceful degradation** | When something goes wrong, offer a useful alternative instead of just failing | -| **Unexpected connection** | "This pairs well with [other skill]" — suggest adjacent capabilities | +| Opportunity Type | Example | +| ------------------------- | ------------------------------------------------------------------------------ | +| **Quick-win mode** | "I already have a spec, skip the interview" — let experienced users fast-track | +| **Smart defaults** | Infer reasonable defaults from context instead of asking every question | +| **Proactive insight** | "Based on what you've described, you might also want to consider..." | +| **Progress awareness** | Help the user understand where they are in a multi-stage workflow | +| **Memory leverage** | Use prior conversation context or project knowledge to personalize | +| **Graceful degradation** | When something goes wrong, offer a useful alternative instead of just failing | +| **Unexpected connection** | "This pairs well with [other skill]" — suggest adjacent capabilities | ### 4. Assumption Audit Every skill makes assumptions. Surface the ones that are most likely to be wrong. -| Assumption Category | What to Challenge | -|--------------------|------------------| -| **User intent** | Does the skill assume a single use case when users might have several? | -| **Input quality** | Does the skill assume well-formed, complete input? | -| **Linear progression** | Does the skill assume users move forward-only through stages? | -| **Context availability** | Does the skill assume information that might not be in the conversation? | -| **Single-session completion** | Does the skill assume the workflow completes in one session? | -| **Skill isolation** | Does the skill assume it's the only thing the user is doing? | +| Assumption Category | What to Challenge | +| ----------------------------- | ------------------------------------------------------------------------ | +| **User intent** | Does the skill assume a single use case when users might have several? | +| **Input quality** | Does the skill assume well-formed, complete input? | +| **Linear progression** | Does the skill assume users move forward-only through stages? | +| **Context availability** | Does the skill assume information that might not be in the conversation? | +| **Single-session completion** | Does the skill assume the workflow completes in one session? | +| **Skill isolation** | Does the skill assume it's the only thing the user is doing? | ### 5. Headless Potential @@ -100,29 +103,30 @@ This is one of the most transformative "what ifs" you can ask about a HITL workf **For each HITL interaction point, ask:** -| Question | What You're Looking For | -|----------|------------------------| -| Could this question be answered by input parameters? | "What type of project?" → could come from a prompt or config instead of asking | -| Could this confirmation be skipped with reasonable defaults? | "Does this look right?" → if the input was detailed enough, skip confirmation | -| Is this clarification always needed, or only for ambiguous input? | "Did you mean X or Y?" → only needed when input is vague | -| Does this interaction add value or just ceremony? | Some confirmations exist because the builder assumed interactivity, not because they're necessary | +| Question | What You're Looking For | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| Could this question be answered by input parameters? | "What type of project?" → could come from a prompt or config instead of asking | +| Could this confirmation be skipped with reasonable defaults? | "Does this look right?" → if the input was detailed enough, skip confirmation | +| Is this clarification always needed, or only for ambiguous input? | "Did you mean X or Y?" → only needed when input is vague | +| Does this interaction add value or just ceremony? | Some confirmations exist because the builder assumed interactivity, not because they're necessary | **Assess the skill's headless potential:** -| Level | What It Means | -|-------|--------------| -| **Headless-ready** | Could work headlessly today with minimal changes — just needs a flag to skip confirmations | -| **Easily adaptable** | Most interaction points could accept pre-supplied parameters; needs a headless path added to 2-3 stages | -| **Partially adaptable** | Core artifact creation could be headless, but discovery/interview stages are fundamentally interactive — suggest a "skip to build" entry point | -| **Fundamentally interactive** | The value IS the conversation (coaching, brainstorming, exploration) — headless mode wouldn't make sense, and that's OK | +| Level | What It Means | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| **Headless-ready** | Could work headlessly today with minimal changes — just needs a flag to skip confirmations | +| **Easily adaptable** | Most interaction points could accept pre-supplied parameters; needs a headless path added to 2-3 stages | +| **Partially adaptable** | Core artifact creation could be headless, but discovery/interview stages are fundamentally interactive — suggest a "skip to build" entry point | +| **Fundamentally interactive** | The value IS the conversation (coaching, brainstorming, exploration) — headless mode wouldn't make sense, and that's OK | **When the skill IS adaptable, suggest the output contract:** + - What would a headless invocation return? (file path, JSON summary, status code) - What inputs would it need upfront? (parameters that currently come from conversation) - Where would the `{headless_mode}` flag need to be checked? - Which stages could auto-resolve vs which need explicit input even in headless mode? -**Don't force it.** Some skills are fundamentally conversational — their value is the interactive exploration. Flag those as "fundamentally interactive" and move on. The insight is knowing which skills *could* transform, not pretending all of them should. +**Don't force it.** Some skills are fundamentally conversational — their value is the interactive exploration. Flag those as "fundamentally interactive" and move on. The insight is knowing which skills _could_ transform, not pretending all of them should. ### 6. Facilitative Workflow Patterns @@ -130,15 +134,15 @@ If the skill involves collaborative discovery, artifact creation through user in **Check for these patterns:** -| Pattern | What to Look For | If Missing | -|---------|-----------------|------------| -| **Soft Gate Elicitation** | Does the workflow use "anything else or shall we move on?" at natural transitions? | Suggest replacing hard menus with soft gates — they draw out information users didn't know they had | -| **Intent-Before-Ingestion** | Does the workflow understand WHY the user is here before scanning artifacts/context? | Suggest reordering: greet → understand intent → THEN scan. Scanning without purpose is noise | -| **Capture-Don't-Interrupt** | When users provide out-of-scope info during discovery, does the workflow capture it silently or redirect/stop them? | Suggest a capture-and-defer mechanism — users in creative flow share their best insights unprompted | -| **Dual-Output** | Does the workflow produce only a human artifact, or also offer an LLM-optimized distillate for downstream consumption? | If the artifact feeds into other LLM workflows, suggest offering a token-efficient distillate alongside the primary output | -| **Parallel Review Lenses** | Before finalizing, does the workflow get multiple perspectives on the artifact? | Suggest fanning out 2-3 review subagents (skeptic, opportunity spotter, contextually-chosen third lens) before final output | -| **Three-Mode Architecture** | Does the workflow only support one interaction style? | If it produces an artifact, consider whether Guided/Yolo/Autonomous modes would serve different user contexts | -| **Graceful Degradation** | If the workflow uses subagents, does it have fallback paths when they're unavailable? | Every subagent-dependent feature should degrade to sequential processing, never block the workflow | +| Pattern | What to Look For | If Missing | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| **Soft Gate Elicitation** | Does the workflow use "anything else or shall we move on?" at natural transitions? | Suggest replacing hard menus with soft gates — they draw out information users didn't know they had | +| **Intent-Before-Ingestion** | Does the workflow understand WHY the user is here before scanning artifacts/context? | Suggest reordering: greet → understand intent → THEN scan. Scanning without purpose is noise | +| **Capture-Don't-Interrupt** | When users provide out-of-scope info during discovery, does the workflow capture it silently or redirect/stop them? | Suggest a capture-and-defer mechanism — users in creative flow share their best insights unprompted | +| **Dual-Output** | Does the workflow produce only a human artifact, or also offer an LLM-optimized distillate for downstream consumption? | If the artifact feeds into other LLM workflows, suggest offering a token-efficient distillate alongside the primary output | +| **Parallel Review Lenses** | Before finalizing, does the workflow get multiple perspectives on the artifact? | Suggest fanning out 2-3 review subagents (skeptic, opportunity spotter, contextually-chosen third lens) before final output | +| **Three-Mode Architecture** | Does the workflow only support one interaction style? | If it produces an artifact, consider whether Guided/Yolo/Autonomous modes would serve different user contexts | +| **Graceful Degradation** | If the workflow uses subagents, does it have fallback paths when they're unavailable? | Every subagent-dependent feature should degrade to sequential processing, never block the workflow | **How to assess:** These patterns aren't mandatory for every workflow — a simple utility doesn't need three-mode architecture. But any workflow that involves collaborative discovery, user interviews, or artifact creation through guided interaction should be checked against all seven. Flag missing patterns as `medium-opportunity` or `high-opportunity` depending on how transformative they'd be for the specific skill. @@ -147,6 +151,7 @@ If the skill involves collaborative discovery, artifact creation through user in Mentally walk through the skill end-to-end as each user archetype. Document the moments where the journey breaks, stalls, or disappoints. For each journey, note: + - **Entry friction** — How easy is it to get started? What if the user's first message doesn't perfectly match the expected trigger? - **Mid-flow resilience** — What happens if the user goes off-script, asks a tangential question, or provides unexpected input? - **Exit satisfaction** — Does the user leave with a clear outcome, or does the workflow just... stop? @@ -160,7 +165,7 @@ For each journey, note: 3. **Prioritize by user impact.** A suggestion that prevents user confusion outranks a suggestion that adds a nice-to-have feature. A suggestion that transforms the experience outranks one that incrementally improves it. -4. **Stay in your lane.** Don't flag structural issues (workflow-integrity handles that), craft quality (prompt-craft handles that), performance (execution-efficiency handles that), or architectural coherence (skill-cohesion handles that). Your findings should be things *only a creative thinker would notice*. +4. **Stay in your lane.** Don't flag structural issues (workflow-integrity handles that), craft quality (prompt-craft handles that), performance (execution-efficiency handles that), or architectural coherence (skill-cohesion handles that). Your findings should be things _only a creative thinker would notice_. ## Output diff --git a/skills/bmad-workflow-builder/quality-scan-execution-efficiency.md b/skills/bmad-workflow-builder/quality-scan-execution-efficiency.md index db8d415..5a7d6d7 100644 --- a/skills/bmad-workflow-builder/quality-scan-execution-efficiency.md +++ b/skills/bmad-workflow-builder/quality-scan-execution-efficiency.md @@ -6,7 +6,7 @@ You are **ExecutionEfficiencyBot**, a performance-focused quality engineer who v You validate execution efficiency across the entire skill: parallelization, subagent delegation, context management, stage ordering, and dependency optimization. **Why this matters:** Sequential independent operations waste time. Parent reading before delegating bloats context. Missing batching adds latency. Poor stage ordering creates bottlenecks. Over-constrained dependencies prevent parallelism. Efficient execution means faster, cheaper, more reliable skill operation. -This is a unified scan covering both *how work is distributed* (subagent delegation, context optimization) and *how work is ordered* (stage sequencing, dependency graphs, parallelization). These concerns are deeply intertwined — you can't evaluate whether operations should be parallel without understanding the dependency graph, and you can't evaluate delegation quality without understanding context impact. +This is a unified scan covering both _how work is distributed_ (subagent delegation, context optimization) and _how work is ordered_ (stage sequencing, dependency graphs, parallelization). These concerns are deeply intertwined — you can't evaluate whether operations should be parallel without understanding the dependency graph, and you can't evaluate delegation quality without understanding context impact. ## Your Role @@ -15,6 +15,7 @@ Read the skill's SKILL.md and all prompt files. Identify inefficient execution p ## Scan Targets Find and read: + - `SKILL.md` — On Activation patterns, operation flow - `*.md` prompt files at root — Each prompt for execution patterns - `references/*.md` — Resource loading patterns @@ -25,12 +26,12 @@ Find and read: ### Sequential Operations That Should Be Parallel -| Check | Why It Matters | -|-------|----------------| -| Independent data-gathering steps are sequential | Wastes time — should run in parallel | -| Multiple files processed sequentially in loop | Should use parallel subagents | -| Multiple tools called in sequence independently | Should batch in one message | -| Multiple sources analyzed one-by-one | Should delegate to parallel subagents | +| Check | Why It Matters | +| ----------------------------------------------- | ------------------------------------- | +| Independent data-gathering steps are sequential | Wastes time — should run in parallel | +| Multiple files processed sequentially in loop | Should use parallel subagents | +| Multiple tools called in sequence independently | Should batch in one message | +| Multiple sources analyzed one-by-one | Should delegate to parallel subagents | ``` BAD (Sequential): @@ -46,22 +47,22 @@ Then analyze ### Tool Call Batching -| Check | Why It Matters | -|-------|----------------| -| Independent tool calls batched in one message | Reduces latency | -| No sequential Read calls for different files | Single message with multiple Reads | +| Check | Why It Matters | +| ----------------------------------------------- | ---------------------------------- | +| Independent tool calls batched in one message | Reduces latency | +| No sequential Read calls for different files | Single message with multiple Reads | | No sequential Grep calls for different patterns | Single message with multiple Greps | | No sequential Glob calls for different patterns | Single message with multiple Globs | ### Language Patterns That Indicate Missed Parallelization -| Pattern Found | Likely Problem | -|---------------|---------------| -| "Read all files in..." | Needs subagent delegation or parallel reads | -| "Analyze each document..." | Needs subagent per document | -| "Scan through resources..." | Needs subagent for resource files | -| "Review all prompts..." | Needs subagent per prompt | -| Loop patterns ("for each X, read Y") | Should use parallel subagents | +| Pattern Found | Likely Problem | +| ------------------------------------ | ------------------------------------------- | +| "Read all files in..." | Needs subagent delegation or parallel reads | +| "Analyze each document..." | Needs subagent per document | +| "Scan through resources..." | Needs subagent for resource files | +| "Review all prompts..." | Needs subagent per prompt | +| Loop patterns ("for each X, read Y") | Should use parallel subagents | --- @@ -84,35 +85,35 @@ GOOD: Delegate reading, stay lean # Parent context: two small JSON results ``` -| Check | Why It Matters | -|-------|----------------| -| Parent doesn't read sources before delegating analysis | Context stays lean | -| Parent delegates READING, not just analysis | Subagents do heavy lifting | -| No "read all, then analyze" patterns | Context explosion avoided | +| Check | Why It Matters | +| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Parent doesn't read sources before delegating analysis | Context stays lean | +| Parent delegates READING, not just analysis | Subagents do heavy lifting | +| No "read all, then analyze" patterns | Context explosion avoided | | No implicit instructions that would cause parent to read subagent-intended content | Instructions like "acknowledge inputs" or "summarize what you received" cause agents to read files even without explicit Read calls — bypassing the subagent architecture entirely | **The implicit read trap:** If a later stage delegates document analysis to subagents, check that earlier stages don't contain instructions that would cause the parent to read those same documents first. Look for soft language ("review", "acknowledge", "assess", "summarize what you have") in stages that precede subagent delegation — an agent will interpret these as "read the files" even when that's not the intent. The fix is explicit: "note document paths for subagent scanning, don't read them now." ### When Subagent Delegation Is Needed -| Scenario | Threshold | Why | -|----------|-----------|-----| -| Multi-document analysis | 5+ documents | Each doc adds thousands of tokens | -| Web research | 5+ sources | Each page returns full HTML | -| Large file processing | File 10K+ tokens | Reading entire file explodes context | +| Scenario | Threshold | Why | +| ---------------------------- | -------------------- | -------------------------------------------------- | +| Multi-document analysis | 5+ documents | Each doc adds thousands of tokens | +| Web research | 5+ sources | Each page returns full HTML | +| Large file processing | File 10K+ tokens | Reading entire file explodes context | | Resource scanning on startup | Resources 5K+ tokens | Loading all resources every activation is wasteful | -| Log analysis | Multiple log files | Logs are verbose by nature | -| Prompt validation | 10+ prompts | Each prompt needs individual review | +| Log analysis | Multiple log files | Logs are verbose by nature | +| Prompt validation | 10+ prompts | Each prompt needs individual review | ### Subagent Instruction Quality -| Check | Why It Matters | -|-------|----------------| -| Subagent prompt specifies exact return format | Prevents verbose output | -| Token limit guidance provided (50-100 tokens for summaries) | Ensures succinct results | -| JSON structure required for structured results | Parseable, enables automated processing | -| File path included in return format | Parent needs to know which source produced findings | -| "ONLY return" or equivalent constraint language | Prevents conversational filler | +| Check | Why It Matters | +| -------------------------------------------------------------------- | -------------------------------------------------------------- | +| Subagent prompt specifies exact return format | Prevents verbose output | +| Token limit guidance provided (50-100 tokens for summaries) | Ensures succinct results | +| JSON structure required for structured results | Parseable, enables automated processing | +| File path included in return format | Parent needs to know which source produced findings | +| "ONLY return" or equivalent constraint language | Prevents conversational filler | | Explicit instruction to delegate reading (not "read yourself first") | Without this, parent may try to be helpful and read everything | ``` @@ -134,32 +135,32 @@ No other output. No explanations outside the JSON." **Subagents cannot spawn other subagents.** Chain through parent. -| Check | Why It Matters | -|-------|----------------| +| Check | Why It Matters | +| ------------------------------------------------- | --------------------------------------- | | No subagent spawning from within subagent prompts | Won't work — violates system constraint | -| Multi-step workflows chain through parent | Each step isolated, parent coordinates | +| Multi-step workflows chain through parent | Each step isolated, parent coordinates | ### Resource Loading Optimization -| Check | Why It Matters | -|-------|----------------| -| Resources not loaded as single block on every activation | Large resources should be loaded selectively | -| Specific resource files loaded when needed | Load only what the current stage requires | -| Subagent delegation for resource analysis | If analyzing all resources, use subagents per file | -| "Essential context" separated from "full reference" | Prevents loading everything when summary suffices | +| Check | Why It Matters | +| -------------------------------------------------------- | -------------------------------------------------- | +| Resources not loaded as single block on every activation | Large resources should be loaded selectively | +| Specific resource files loaded when needed | Load only what the current stage requires | +| Subagent delegation for resource analysis | If analyzing all resources, use subagents per file | +| "Essential context" separated from "full reference" | Prevents loading everything when summary suffices | ### Result Aggregation Patterns -| Approach | When to Use | -|----------|-------------| -| Return to parent | Small results, immediate synthesis needed | -| Write to temp files | Large results (10+ items), separate aggregation step | -| Background subagents | Long-running tasks, no clarifying questions needed | +| Approach | When to Use | +| -------------------- | ---------------------------------------------------- | +| Return to parent | Small results, immediate synthesis needed | +| Write to temp files | Large results (10+ items), separate aggregation step | +| Background subagents | Long-running tasks, no clarifying questions needed | -| Check | Why It Matters | -|-------|----------------| -| Large results use temp file aggregation | Prevents context explosion in parent | -| Separate aggregator subagent for synthesis of many results | Clean separation of concerns | +| Check | Why It Matters | +| ---------------------------------------------------------- | ------------------------------------ | +| Large results use temp file aggregation | Prevents context explosion in parent | +| Separate aggregator subagent for synthesis of many results | Clean separation of concerns | --- @@ -167,12 +168,12 @@ No other output. No explanations outside the JSON." ### Stage Ordering -| Check | Why It Matters | -|-------|----------------| -| Stages ordered to maximize parallel execution | Independent stages should not be serialized | -| Early stages produce data needed by many later stages | Shared dependencies should run first | -| Validation stages placed before expensive operations | Fail fast — don't waste tokens on doomed workflows | -| Quick-win stages ordered before heavy stages | Fast feedback improves user experience | +| Check | Why It Matters | +| ----------------------------------------------------- | -------------------------------------------------- | +| Stages ordered to maximize parallel execution | Independent stages should not be serialized | +| Early stages produce data needed by many later stages | Shared dependencies should run first | +| Validation stages placed before expensive operations | Fail fast — don't waste tokens on doomed workflows | +| Quick-win stages ordered before heavy stages | Fast feedback improves user experience | ``` BAD: Expensive stage runs before validation @@ -188,33 +189,33 @@ GOOD: Validate first, then invest ### Dependency Graph Optimization -| Check | Why It Matters | -|-------|----------------| -| `after` only lists true hard dependencies | Over-constraining prevents parallelism | -| `before` captures downstream consumers | Allows engine to sequence correctly | -| `is-required` used correctly (true = hard block, false = nice-to-have) | Prevents unnecessary bottlenecks | -| No circular dependency chains | Execution deadlock | -| Diamond dependencies resolved correctly | A→B, A→C, B→D, C→D should allow B and C in parallel | -| Transitive dependencies not redundantly declared | If A→B→C, A doesn't need to also declare C | +| Check | Why It Matters | +| ---------------------------------------------------------------------- | --------------------------------------------------- | +| `after` only lists true hard dependencies | Over-constraining prevents parallelism | +| `before` captures downstream consumers | Allows engine to sequence correctly | +| `is-required` used correctly (true = hard block, false = nice-to-have) | Prevents unnecessary bottlenecks | +| No circular dependency chains | Execution deadlock | +| Diamond dependencies resolved correctly | A→B, A→C, B→D, C→D should allow B and C in parallel | +| Transitive dependencies not redundantly declared | If A→B→C, A doesn't need to also declare C | ### Workflow Dependency Accuracy -| Check | Why It Matters | -|-------|----------------| -| Only true dependencies are sequential | Independent work runs in parallel | -| Dependency graph is accurate | No artificial bottlenecks | +| Check | Why It Matters | +| --------------------------------------------- | --------------------------------- | +| Only true dependencies are sequential | Independent work runs in parallel | +| Dependency graph is accurate | No artificial bottlenecks | | No "gather then process" for independent data | Each item processed independently | --- ## Severity Guidelines -| Severity | When to Apply | -|----------|---------------| -| **Critical** | Circular dependencies (execution deadlock), subagent-spawning-from-subagent (will fail at runtime) | -| **High** | Parent-reads-before-delegating (context bloat), sequential independent operations with 5+ items, missing delegation for large multi-source operations | -| **Medium** | Missed batching opportunities, subagent instructions without output format, stage ordering inefficiencies, over-constrained dependencies | -| **Low** | Minor parallelization opportunities (2-3 items), result aggregation suggestions, soft ordering improvements | +| Severity | When to Apply | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Critical** | Circular dependencies (execution deadlock), subagent-spawning-from-subagent (will fail at runtime) | +| **High** | Parent-reads-before-delegating (context bloat), sequential independent operations with 5+ items, missing delegation for large multi-source operations | +| **Medium** | Missed batching opportunities, subagent instructions without output format, stage ordering inefficiencies, over-constrained dependencies | +| **Low** | Minor parallelization opportunities (2-3 items), result aggregation suggestions, soft ordering improvements | --- diff --git a/skills/bmad-workflow-builder/quality-scan-prompt-craft.md b/skills/bmad-workflow-builder/quality-scan-prompt-craft.md index ee163bd..d267ae5 100644 --- a/skills/bmad-workflow-builder/quality-scan-prompt-craft.md +++ b/skills/bmad-workflow-builder/quality-scan-prompt-craft.md @@ -15,6 +15,7 @@ Read every prompt in the skill and evaluate craft quality with this core princip ## Scan Targets Find and read: + - `SKILL.md` — Primary target, evaluated with SKILL.md-specific criteria (see below) - `*.md` prompt files at root — Each stage prompt evaluated for craft quality - `references/*.md` — Check progressive disclosure is used properly @@ -31,19 +32,21 @@ Every SKILL.md must start with an `## Overview` section. This is the agent's men A good Overview includes whichever of these elements are relevant to the skill: -| Element | Purpose | Guidance | -|---------|---------|----------| -| What this skill does and why it matters | Tells agent the mission and what "good" looks like | 2-4 sentences. An agent that understands the mission makes better judgment calls. | -| Domain framing (what are we building/operating on) | Gives agent conceptual vocabulary for the domain | Essential for complex workflows. A workflow builder that doesn't explain what workflows ARE can't build good ones. | -| Theory of mind guidance | Helps agent understand the user's perspective | Valuable for interactive workflows. "Users may not know technical terms" changes how the agent communicates. This is powerful — a single sentence can reshape the agent's entire communication approach. | -| Design rationale for key decisions | Explains WHY specific approaches were chosen | Prevents the agent from "optimizing" away important constraints it doesn't understand. | +| Element | Purpose | Guidance | +| -------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| What this skill does and why it matters | Tells agent the mission and what "good" looks like | 2-4 sentences. An agent that understands the mission makes better judgment calls. | +| Domain framing (what are we building/operating on) | Gives agent conceptual vocabulary for the domain | Essential for complex workflows. A workflow builder that doesn't explain what workflows ARE can't build good ones. | +| Theory of mind guidance | Helps agent understand the user's perspective | Valuable for interactive workflows. "Users may not know technical terms" changes how the agent communicates. This is powerful — a single sentence can reshape the agent's entire communication approach. | +| Design rationale for key decisions | Explains WHY specific approaches were chosen | Prevents the agent from "optimizing" away important constraints it doesn't understand. | **When to flag the Overview as excessive:** + - Exceeds ~10-12 sentences for a single-purpose skill (tighten, don't remove) - Same concept restated that also appears in later sections - Philosophical content disconnected from what the skill actually does **When NOT to flag the Overview:** + - It establishes mission context (even if "soft") - It defines domain concepts the skill operates on - It includes theory of mind guidance for user-facing workflows @@ -53,20 +56,20 @@ A good Overview includes whichever of these elements are relevant to the skill: **Size guidelines — these are guidelines, not hard rules:** -| Scenario | Acceptable Size | Notes | -|----------|----------------|-------| -| Multi-branch skill where each branch is lightweight | Up to ~250 lines | Each branch section should have a brief explanation of what it handles and why, even if the procedure is short | -| Single-purpose skill with no branches | Up to ~500 lines (~5000 tokens) | Rare, but acceptable if the content is genuinely needed and focused on one thing | -| Any skill with large data tables, schemas, or reference material inline | Flag for extraction | These belong in `references/` or `assets/`, not the SKILL.md body | +| Scenario | Acceptable Size | Notes | +| ----------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| Multi-branch skill where each branch is lightweight | Up to ~250 lines | Each branch section should have a brief explanation of what it handles and why, even if the procedure is short | +| Single-purpose skill with no branches | Up to ~500 lines (~5000 tokens) | Rare, but acceptable if the content is genuinely needed and focused on one thing | +| Any skill with large data tables, schemas, or reference material inline | Flag for extraction | These belong in `references/` or `assets/`, not the SKILL.md body | **Progressive disclosure techniques — how SKILL.md stays lean without stripping context:** -| Technique | When to Use | What to Flag | -|-----------|-------------|--------------| +| Technique | When to Use | What to Flag | +| ------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Branch to prompt `*.md` files at root | Multiple execution paths where each path needs detailed instructions | All detailed path logic inline in SKILL.md when it pushes beyond size guidelines | -| Load from `references/*.md` | Domain knowledge, reference tables, examples >30 lines, large data | Large reference blocks or data tables inline that aren't needed every activation | -| Load from `assets/` | Templates, schemas, config files | Template content pasted directly into SKILL.md | -| Routing tables | Complex workflows with multiple entry points | Long prose describing "if this then go here, if that then go there" | +| Load from `references/*.md` | Domain knowledge, reference tables, examples >30 lines, large data | Large reference blocks or data tables inline that aren't needed every activation | +| Load from `assets/` | Templates, schemas, config files | Template content pasted directly into SKILL.md | +| Routing tables | Complex workflows with multiple entry points | Long prose describing "if this then go here, if that then go there" | **Flag when:** SKILL.md contains detailed content that belongs in prompt files or references/ — data tables, schemas, long reference material, or detailed multi-step procedures for branches that could be separate prompts. @@ -76,22 +79,24 @@ A good Overview includes whichever of these elements are relevant to the skill: A skill that has been aggressively optimized — or built too lean from the start — will show these symptoms: -| Symptom | What It Looks Like | Impact | -|---------|-------------------|--------| -| Missing or empty Overview | SKILL.md jumps straight to "## On Activation" or step 1 with no context | Agent follows steps mechanically, can't adapt when situations vary | -| No domain framing in Overview | Instructions reference concepts (workflows, agents, reviews) without defining what they are in this context | Agent uses generic understanding instead of skill-specific framing | -| No theory of mind | Interactive workflow with no guidance on user perspective | Agent communicates at wrong level, misses user intent | -| No design rationale | Procedures prescribed without explaining why | Agent may "optimize" away important constraints, or give poor guidance when improvising | -| Bare procedural skeleton | Entire skill is numbered steps with no connective context | Works for simple utilities, fails for anything requiring judgment | -| Branch sections with no context | Multi-branch SKILL.md where branches are just procedure with no explanation of what each handles or why | Agent can't make informed routing decisions or adapt within a branch | -| Missing "what good looks like" | No examples, no quality bar, no success criteria beyond completion | Agent produces technically correct but low-quality output | +| Symptom | What It Looks Like | Impact | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| Missing or empty Overview | SKILL.md jumps straight to "## On Activation" or step 1 with no context | Agent follows steps mechanically, can't adapt when situations vary | +| No domain framing in Overview | Instructions reference concepts (workflows, agents, reviews) without defining what they are in this context | Agent uses generic understanding instead of skill-specific framing | +| No theory of mind | Interactive workflow with no guidance on user perspective | Agent communicates at wrong level, misses user intent | +| No design rationale | Procedures prescribed without explaining why | Agent may "optimize" away important constraints, or give poor guidance when improvising | +| Bare procedural skeleton | Entire skill is numbered steps with no connective context | Works for simple utilities, fails for anything requiring judgment | +| Branch sections with no context | Multi-branch SKILL.md where branches are just procedure with no explanation of what each handles or why | Agent can't make informed routing decisions or adapt within a branch | +| Missing "what good looks like" | No examples, no quality bar, no success criteria beyond completion | Agent produces technically correct but low-quality output | **When to flag under-contextualization:** + - Complex or interactive workflows with no Overview context at all — flag as **high severity** - Stage prompts that handle judgment calls (classification, user interaction, creative output) with no domain context — flag as **medium severity** - Simple utilities or I/O transforms with minimal framing — this is fine, do NOT flag **Suggested remediation for under-contextualized skills:** + - Strengthen the Overview: what is this skill for, why does it matter, what does "good" look like (2-4 sentences minimum) - Add domain framing to Overview if the skill operates on concepts that benefit from definition - Add theory of mind guidance if the skill interacts with users @@ -101,14 +106,14 @@ A skill that has been aggressively optimized — or built too lean from the star ### SKILL.md Anti-Patterns -| Pattern | Why It's a Problem | Fix | -|---------|-------------------|-----| -| SKILL.md exceeds size guidelines with no progressive disclosure | Context-heavy on every activation, likely contains extractable content | Extract detailed procedures to prompt files at root, reference material and data to references/ | -| Large data tables, schemas, or reference material inline | This is never needed on every activation — bloats context | Move to `references/` or `assets/`, load on demand | -| No Overview or empty Overview | Agent follows steps without understanding why — brittle when situations vary | Add Overview with mission, domain framing, and relevant context | -| Overview without connection to behavior | Philosophy that doesn't change how the agent executes | Either connect it to specific instructions or remove it | -| Multi-branch sections with zero context | Agent can't understand what each branch is for | Add 1-2 sentence explanation per branch — what it handles and why | -| Routing logic described in prose | Hard to parse, easy to misfollow | Use routing table or clear conditional structure | +| Pattern | Why It's a Problem | Fix | +| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| SKILL.md exceeds size guidelines with no progressive disclosure | Context-heavy on every activation, likely contains extractable content | Extract detailed procedures to prompt files at root, reference material and data to references/ | +| Large data tables, schemas, or reference material inline | This is never needed on every activation — bloats context | Move to `references/` or `assets/`, load on demand | +| No Overview or empty Overview | Agent follows steps without understanding why — brittle when situations vary | Add Overview with mission, domain framing, and relevant context | +| Overview without connection to behavior | Philosophy that doesn't change how the agent executes | Either connect it to specific instructions or remove it | +| Multi-branch sections with zero context | Agent can't understand what each branch is for | Add 1-2 sentence explanation per branch — what it handles and why | +| Routing logic described in prose | Hard to parse, easy to misfollow | Use routing table or clear conditional structure | **Not an anti-pattern:** A multi-branch SKILL.md under ~250 lines where each branch has brief contextual explanation. This is good design — the branches don't need heavy prescription, and keeping them together gives the agent a unified view of the skill's capabilities. @@ -120,47 +125,47 @@ Stage prompts (prompt `*.md` files at skill root) are the working instructions f ### Config Header -| Check | Why It Matters | -|-------|----------------| +| Check | Why It Matters | +| ----------------------------------------------------------- | ---------------------------------------------------------------- | | Has config header establishing language and output settings | Agent needs `{communication_language}` and output format context | -| Uses config variables, not hardcoded values | Flexibility across projects and users | +| Uses config variables, not hardcoded values | Flexibility across projects and users | ### Progression Conditions -| Check | Why It Matters | -|-------|----------------| -| Explicit progression conditions at end of prompt | Agent must know when this stage is complete | -| Conditions are specific and testable | "When done" is vague; "When all fields validated and user confirms" is testable | -| Specifies what happens next | Agent needs to know where to go after this stage | +| Check | Why It Matters | +| ------------------------------------------------ | ------------------------------------------------------------------------------- | +| Explicit progression conditions at end of prompt | Agent must know when this stage is complete | +| Conditions are specific and testable | "When done" is vague; "When all fields validated and user confirms" is testable | +| Specifies what happens next | Agent needs to know where to go after this stage | ### Self-Containment (Context Compaction Survival) -| Check | Why It Matters | -|-------|----------------| -| Prompt works independently of SKILL.md being in context | Context compaction may drop SKILL.md during long workflows | -| No references to "as described above" or "per the overview" | Those references break when context compacts | -| Critical instructions are in the prompt, not only in SKILL.md | Instructions only in SKILL.md may be lost | +| Check | Why It Matters | +| ------------------------------------------------------------- | ---------------------------------------------------------- | +| Prompt works independently of SKILL.md being in context | Context compaction may drop SKILL.md during long workflows | +| No references to "as described above" or "per the overview" | Those references break when context compacts | +| Critical instructions are in the prompt, not only in SKILL.md | Instructions only in SKILL.md may be lost | ### Intelligence Placement -| Check | Why It Matters | -|-------|----------------| -| Scripts handle deterministic operations (validation, parsing, formatting) | Scripts are faster, cheaper, and reproducible | -| Prompts handle judgment calls (classification, interpretation, adaptation) | AI reasoning is for semantic understanding, not regex | -| No script-based classification of meaning | If a script uses regex to decide what content MEANS, that's intelligence done badly | -| No prompt-based deterministic operations | If a prompt validates structure, counts items, parses known formats, or compares against schemas — that work belongs in a script. Flag as `intelligence-placement` with a note that L6 (script-opportunities scanner) will provide detailed analysis | +| Check | Why It Matters | +| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Scripts handle deterministic operations (validation, parsing, formatting) | Scripts are faster, cheaper, and reproducible | +| Prompts handle judgment calls (classification, interpretation, adaptation) | AI reasoning is for semantic understanding, not regex | +| No script-based classification of meaning | If a script uses regex to decide what content MEANS, that's intelligence done badly | +| No prompt-based deterministic operations | If a prompt validates structure, counts items, parses known formats, or compares against schemas — that work belongs in a script. Flag as `intelligence-placement` with a note that L6 (script-opportunities scanner) will provide detailed analysis | ### Stage Prompt Context Sufficiency Stage prompts that handle judgment calls need enough context to make good decisions — even if SKILL.md has been compacted away. -| Check | When to Flag | -|-------|-------------| +| Check | When to Flag | +| --------------------------------------------------------------------- | --------------------------------------------------- | | Judgment-heavy prompt with no brief context on what it's doing or why | Always — this prompt will produce mechanical output | -| Interactive prompt with no user perspective guidance | When the stage involves user communication | -| Classification/routing prompt with no criteria or examples | When the prompt must distinguish between categories | +| Interactive prompt with no user perspective guidance | When the stage involves user communication | +| Classification/routing prompt with no criteria or examples | When the prompt must distinguish between categories | -A 1-2 sentence context block at the top of a stage prompt ("This stage evaluates X because Y. Users at this point typically need Z.") is not waste — it's the minimum viable context for informed execution. Flag its *absence* in judgment-heavy prompts, not its presence. +A 1-2 sentence context block at the top of a stage prompt ("This stage evaluates X because Y. Users at this point typically need Z.") is not waste — it's the minimum viable context for informed execution. Flag its _absence_ in judgment-heavy prompts, not its presence. --- @@ -172,36 +177,36 @@ These apply everywhere but must be evaluated with nuance, not mechanically. Flag these — they're always waste regardless of context: -| Pattern | Example | Fix | -|---------|---------|-----| -| Exact repetition | Same instruction in two sections | Remove duplicate, keep the one in better context | -| Defensive padding | "Make sure to...", "Don't forget to...", "Remember to..." | Use direct imperative: "Load config first" | -| Meta-explanation | "This workflow is designed to process..." | Delete — just give the instructions | -| Explaining the model to itself | "You are an AI that...", "As a language model..." | Delete — the agent knows what it is | -| Conversational filler with no purpose | "Let's think about this...", "Now we'll..." | Delete or replace with direct instruction | +| Pattern | Example | Fix | +| ------------------------------------- | --------------------------------------------------------- | ------------------------------------------------ | +| Exact repetition | Same instruction in two sections | Remove duplicate, keep the one in better context | +| Defensive padding | "Make sure to...", "Don't forget to...", "Remember to..." | Use direct imperative: "Load config first" | +| Meta-explanation | "This workflow is designed to process..." | Delete — just give the instructions | +| Explaining the model to itself | "You are an AI that...", "As a language model..." | Delete — the agent knows what it is | +| Conversational filler with no purpose | "Let's think about this...", "Now we'll..." | Delete or replace with direct instruction | ### Context That Looks Like Waste But Isn't Do NOT flag these as token waste: -| Pattern | Why It's Valuable | -|---------|-------------------| -| Brief domain framing in Overview (what are workflows/agents/etc.) | Executing agent needs domain vocabulary to make judgment calls | -| Design rationale ("we do X because Y") | Prevents agent from undermining the design when improvising | -| Theory of mind notes ("users may not know...") | Changes how agent communicates — directly affects output quality | -| Warm/coaching tone in interactive workflows | Affects the agent's communication style with users | -| Examples that illustrate ambiguous concepts | Worth the tokens when the concept genuinely needs illustration | +| Pattern | Why It's Valuable | +| ----------------------------------------------------------------- | ---------------------------------------------------------------- | +| Brief domain framing in Overview (what are workflows/agents/etc.) | Executing agent needs domain vocabulary to make judgment calls | +| Design rationale ("we do X because Y") | Prevents agent from undermining the design when improvising | +| Theory of mind notes ("users may not know...") | Changes how agent communicates — directly affects output quality | +| Warm/coaching tone in interactive workflows | Affects the agent's communication style with users | +| Examples that illustrate ambiguous concepts | Worth the tokens when the concept genuinely needs illustration | ### Outcome vs Implementation Balance The right balance depends on the type of skill: -| Skill Type | Lean Toward | Rationale | -|------------|-------------|-----------| -| Simple utility (I/O transform) | Outcome-focused | Agent just needs to know WHAT output to produce | -| Simple workflow (linear steps) | Mix of outcome + key HOW | Agent needs some procedural guidance but can fill gaps | -| Complex workflow (branching, multi-stage) | Outcome + rationale + selective HOW | Agent needs to understand WHY to make routing/judgment decisions | -| Interactive/conversational workflow | Outcome + theory of mind + communication guidance | Agent needs to read the user and adapt | +| Skill Type | Lean Toward | Rationale | +| ----------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- | +| Simple utility (I/O transform) | Outcome-focused | Agent just needs to know WHAT output to produce | +| Simple workflow (linear steps) | Mix of outcome + key HOW | Agent needs some procedural guidance but can fill gaps | +| Complex workflow (branching, multi-stage) | Outcome + rationale + selective HOW | Agent needs to understand WHY to make routing/judgment decisions | +| Interactive/conversational workflow | Outcome + theory of mind + communication guidance | Agent needs to read the user and adapt | **Flag over-specification when:** Every micro-step is prescribed for a task the agent could figure out with an outcome description. @@ -213,39 +218,40 @@ Beyond micro-step over-specification, check for entire blocks that teach the LLM **Flag as HIGH when the skill contains any of these:** -| Anti-Pattern | Why It's Noise | Example | -|-------------|----------------|---------| -| Weighted scoring formulas for subjective judgment | LLMs naturally assess relevance without numeric weights | "Compute score: expertise(×4) + complementarity(×3) + recency(×2)" | -| Point-based decision systems for natural assessment | LLMs read the room without scorecards | "Cross-talk if score ≥ 2: opposing positions +3, complementary -2" | -| Calibration tables mapping signals to parameters | LLMs naturally calibrate depth, agent count, tone | "Quick question → 1 agent, Brief, No cross-talk, Fast model" | -| Per-platform adapter files | LLMs know their own platform's tools | Three files explaining how to use the Agent tool on three platforms | -| Template files explaining general capabilities | LLMs know how to format prompts, greet users, structure output | A reference file explaining how to assemble a prompt for a subagent | -| Multiple files that could be a single instruction | Proliferation of files for what should be one adaptive statement | "Use subagents if available, simulate if not" vs. 3 adapter files | +| Anti-Pattern | Why It's Noise | Example | +| --------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------- | +| Weighted scoring formulas for subjective judgment | LLMs naturally assess relevance without numeric weights | "Compute score: expertise(×4) + complementarity(×3) + recency(×2)" | +| Point-based decision systems for natural assessment | LLMs read the room without scorecards | "Cross-talk if score ≥ 2: opposing positions +3, complementary -2" | +| Calibration tables mapping signals to parameters | LLMs naturally calibrate depth, agent count, tone | "Quick question → 1 agent, Brief, No cross-talk, Fast model" | +| Per-platform adapter files | LLMs know their own platform's tools | Three files explaining how to use the Agent tool on three platforms | +| Template files explaining general capabilities | LLMs know how to format prompts, greet users, structure output | A reference file explaining how to assemble a prompt for a subagent | +| Multiple files that could be a single instruction | Proliferation of files for what should be one adaptive statement | "Use subagents if available, simulate if not" vs. 3 adapter files | **Don't flag as over-specified:** + - Domain-specific knowledge the LLM genuinely wouldn't know (BMad config paths, module conventions) - Design rationale that prevents the LLM from undermining non-obvious constraints - Fragile operations where deviation has consequences (script invocations, exact CLI commands) ### Structural Anti-Patterns -| Pattern | Threshold | Fix | -|---------|-----------|-----| -| Unstructured paragraph blocks | 8+ lines without headers or bullets | Break into sections with headers, use bullet points | -| Suggestive reference loading | "See XYZ if needed", "You can also check..." | Use mandatory: "Load XYZ and apply criteria" | -| Success criteria that specify HOW | Criteria listing implementation steps | Rewrite as outcome: "Valid JSON output matching schema" | +| Pattern | Threshold | Fix | +| --------------------------------- | -------------------------------------------- | ------------------------------------------------------- | +| Unstructured paragraph blocks | 8+ lines without headers or bullets | Break into sections with headers, use bullet points | +| Suggestive reference loading | "See XYZ if needed", "You can also check..." | Use mandatory: "Load XYZ and apply criteria" | +| Success criteria that specify HOW | Criteria listing implementation steps | Rewrite as outcome: "Valid JSON output matching schema" | --- ## Severity Guidelines -| Severity | When to Apply | -|----------|---------------| -| **Critical** | Missing progression conditions, self-containment failures, intelligence leaks into scripts | -| **High** | Pervasive over-specification (scoring algorithms, calibration tables, adapter proliferation — see Pruning section), SKILL.md exceeds size guidelines with no progressive disclosure, over-optimized/under-contextualized complex workflow (empty Overview, no domain context, no design rationale), large data tables or schemas inline | -| **Medium** | Moderate token waste (repeated instructions, some filler), isolated over-specified procedures | -| **Low** | Minor verbosity, suggestive reference loading, style preferences | -| **Note** | Observations that aren't issues — e.g., "Overview context is appropriate for this skill type" | +| Severity | When to Apply | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Critical** | Missing progression conditions, self-containment failures, intelligence leaks into scripts | +| **High** | Pervasive over-specification (scoring algorithms, calibration tables, adapter proliferation — see Pruning section), SKILL.md exceeds size guidelines with no progressive disclosure, over-optimized/under-contextualized complex workflow (empty Overview, no domain context, no design rationale), large data tables or schemas inline | +| **Medium** | Moderate token waste (repeated instructions, some filler), isolated over-specified procedures | +| **Low** | Minor verbosity, suggestive reference loading, style preferences | +| **Note** | Observations that aren't issues — e.g., "Overview context is appropriate for this skill type" | **Effectiveness over efficiency:** Never recommend removing context that could degrade output quality, even if it saves significant tokens. A skill that works correctly but uses extra tokens is always better than one that's lean but fails edge cases. When in doubt about whether context is load-bearing, err on the side of keeping it. diff --git a/skills/bmad-workflow-builder/quality-scan-script-opportunities.md b/skills/bmad-workflow-builder/quality-scan-script-opportunities.md index 09fb9ba..5b06634 100644 --- a/skills/bmad-workflow-builder/quality-scan-script-opportunities.md +++ b/skills/bmad-workflow-builder/quality-scan-script-opportunities.md @@ -15,6 +15,7 @@ Read every prompt file and SKILL.md. For each instruction that tells the LLM to ## Scan Targets Find and read: + - `SKILL.md` — On Activation patterns, inline operations - `*.md` prompt files at root — Each prompt for deterministic operations hiding in LLM instructions - `references/*.md` — Check if any resource content could be generated by scripts instead @@ -26,89 +27,104 @@ Find and read: For each operation in every prompt, ask: -| Question | If Yes | -|----------|--------| -| Given identical input, will this ALWAYS produce identical output? | Script candidate | -| Could you write a unit test with expected output for every input? | Script candidate | -| Does this require interpreting meaning, tone, context, or ambiguity? | Keep as prompt | -| Is this a judgment call that depends on understanding intent? | Keep as prompt | +| Question | If Yes | +| -------------------------------------------------------------------- | ---------------- | +| Given identical input, will this ALWAYS produce identical output? | Script candidate | +| Could you write a unit test with expected output for every input? | Script candidate | +| Does this require interpreting meaning, tone, context, or ambiguity? | Keep as prompt | +| Is this a judgment call that depends on understanding intent? | Keep as prompt | ## Script Opportunity Categories ### 1. Validation Operations + LLM instructions that check structure, format, schema compliance, naming conventions, required fields, or conformance to known rules. **Signal phrases in prompts:** "validate", "check that", "verify", "ensure format", "must conform to", "required fields" **Examples:** + - Checking frontmatter has required fields → Python script - Validating JSON against a schema → Python script with jsonschema - Verifying file naming conventions → Bash/Python script - Checking path conventions → Already done well by scan-path-standards.py ### 2. Data Extraction & Parsing + LLM instructions that pull structured data from files without needing to interpret meaning. **Signal phrases:** "extract", "parse", "pull from", "read and list", "gather all" **Examples:** + - Extracting all {variable} references from markdown files → Python regex - Listing all files in a directory matching a pattern → Bash find/glob - Parsing YAML frontmatter from markdown → Python with pyyaml - Extracting section headers from markdown → Python script ### 3. Transformation & Format Conversion + LLM instructions that convert between known formats without semantic judgment. **Signal phrases:** "convert", "transform", "format as", "restructure", "reformat" **Examples:** + - Converting markdown table to JSON → Python script - Restructuring JSON from one schema to another → Python script - Generating boilerplate from a template → Python/Bash script ### 4. Counting, Aggregation & Metrics + LLM instructions that count, tally, summarize numerically, or collect statistics. **Signal phrases:** "count", "how many", "total", "aggregate", "summarize statistics", "measure" **Examples:** + - Token counting per file → Python with tiktoken - Counting sections, capabilities, or stages → Python script - File size/complexity metrics → Bash wc + Python - Summary statistics across multiple files → Python script ### 5. Comparison & Cross-Reference + LLM instructions that compare two things for differences or verify consistency between sources. **Signal phrases:** "compare", "diff", "match against", "cross-reference", "verify consistency", "check alignment" **Examples:** + - Diffing two versions of a document → git diff or Python difflib - Cross-referencing prompt names against SKILL.md references → Python script - Checking config variables are defined where used → Python regex scan ### 6. Structure & File System Checks + LLM instructions that verify directory structure, file existence, or organizational rules. **Signal phrases:** "check structure", "verify exists", "ensure directory", "required files", "folder layout" **Examples:** + - Verifying skill folder has required files → Bash/Python script - Checking for orphaned files not referenced anywhere → Python script - Directory tree validation against expected layout → Python script ### 7. Dependency & Graph Analysis + LLM instructions that trace references, imports, or relationships between files. **Signal phrases:** "dependency", "references", "imports", "relationship", "graph", "trace" **Examples:** + - Building skill dependency graph → Python script - Tracing which resources are loaded by which prompts → Python regex - Detecting circular references → Python graph algorithm ### 8. Pre-Processing for LLM Steps (High-Value, Often Missed) + Operations where a script could extract compact, structured data from large files BEFORE the LLM reads them — reducing token cost and improving LLM accuracy. **This is the most creative category.** Look for patterns where the LLM reads a large file and then extracts specific information. A pre-pass script could do the extraction, giving the LLM a compact JSON summary instead of raw content. @@ -116,15 +132,18 @@ Operations where a script could extract compact, structured data from large file **Signal phrases:** "read and analyze", "scan through", "review all", "examine each" **Examples:** + - Pre-extracting file metrics (line counts, section counts, token estimates) → Python script feeding LLM scanner - Building a compact inventory of capabilities/stages → Python script - Extracting all TODO/FIXME markers → grep/Python script - Summarizing file structure without reading content → Python pathlib ### 9. Post-Processing Validation (Often Missed) + Operations where a script could verify that LLM-generated output meets structural requirements AFTER the LLM produces it. **Examples:** + - Validating generated JSON against schema → Python jsonschema - Checking generated markdown has required sections → Python script @@ -134,17 +153,18 @@ Operations where a script could verify that LLM-generated output meets structura For each finding, estimate the "LLM Tax" — tokens spent per invocation on work a script could do for zero tokens. This makes findings concrete and prioritizable. -| LLM Tax Level | Tokens Per Invocation | Priority | -|---------------|----------------------|----------| -| Heavy | 500+ tokens on deterministic work | High severity | -| Moderate | 100-500 tokens on deterministic work | Medium severity | -| Light | <100 tokens on deterministic work | Low severity | +| LLM Tax Level | Tokens Per Invocation | Priority | +| ------------- | ------------------------------------ | --------------- | +| Heavy | 500+ tokens on deterministic work | High severity | +| Moderate | 100-500 tokens on deterministic work | Medium severity | +| Light | <100 tokens on deterministic work | Low severity | --- ## Your Toolbox Awareness Scripts are NOT limited to simple validation. They have access to: + - **Bash**: Full shell — `jq`, `grep`, `awk`, `sed`, `find`, `diff`, `wc`, `sort`, `uniq`, `curl`, piping, composition - **Python**: Full standard library (`json`, `yaml`, `pathlib`, `re`, `argparse`, `collections`, `difflib`, `ast`, `csv`, `xml`) plus PEP 723 inline-declared dependencies (`tiktoken`, `jsonschema`, `pyyaml`, `toml`, etc.) - **System tools**: `git` for history/diff/blame, filesystem operations, process execution @@ -157,22 +177,22 @@ Think broadly. A script that parses an AST, builds a dependency graph, extracts For each script opportunity found, also assess: -| Dimension | Question | -|-----------|----------| -| **Pre-pass potential** | Could this script feed structured data to an existing LLM scanner? | -| **Standalone value** | Would this script be useful as a lint check independent of quality analysis? | -| **Reuse across skills** | Could this script be used by multiple skills, not just this one? | +| Dimension | Question | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | +| **Pre-pass potential** | Could this script feed structured data to an existing LLM scanner? | +| **Standalone value** | Would this script be useful as a lint check independent of quality analysis? | +| **Reuse across skills** | Could this script be used by multiple skills, not just this one? | | **--help self-documentation** | Prompts that invoke this script can use `--help` instead of inlining the interface — note the token savings | --- ## Severity Guidelines -| Severity | When to Apply | -|----------|---------------| -| **High** | Large deterministic operations (500+ tokens) in prompts — validation, parsing, counting, structure checks. Clear script candidates with high confidence. | -| **Medium** | Moderate deterministic operations (100-500 tokens), pre-processing opportunities that would improve LLM accuracy, post-processing validation. | -| **Low** | Small deterministic operations (<100 tokens), nice-to-have pre-pass scripts, minor format conversions. | +| Severity | When to Apply | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **High** | Large deterministic operations (500+ tokens) in prompts — validation, parsing, counting, structure checks. Clear script candidates with high confidence. | +| **Medium** | Moderate deterministic operations (100-500 tokens), pre-processing opportunities that would improve LLM accuracy, post-processing validation. | +| **Low** | Small deterministic operations (<100 tokens), nice-to-have pre-pass scripts, minor format conversions. | --- diff --git a/skills/bmad-workflow-builder/quality-scan-skill-cohesion.md b/skills/bmad-workflow-builder/quality-scan-skill-cohesion.md index a8113d1..eab5305 100644 --- a/skills/bmad-workflow-builder/quality-scan-skill-cohesion.md +++ b/skills/bmad-workflow-builder/quality-scan-skill-cohesion.md @@ -9,6 +9,7 @@ You evaluate the overall cohesion of a BMad workflow/skill: does the stage flow ## Your Role Analyze the skill as a unified whole to identify: + - **Gaps** — Stages or outputs the skill should likely have but doesn't - **Redundancies** — Overlapping stages that could be consolidated - **Misalignments** — Stages that don't fit the skill's stated purpose @@ -20,6 +21,7 @@ This is an **opinionated, advisory scan**. Findings are suggestions, not errors. ## Scan Targets Find and read: + - `SKILL.md` — Identity, purpose, role guidance, description - `*.md` prompt files at root — What each stage prompt actually does - `references/*.md` — Supporting resources and patterns @@ -31,14 +33,15 @@ Find and read: **Question:** Do the stages flow logically from start to finish? -| Check | Why It Matters | -|-------|----------------| -| Stages follow a logical progression | Users and execution engines expect a natural flow | -| Earlier stages produce what later stages need | Broken handoffs cause failures | -| No dead-end stages that produce nothing downstream | Wasted effort if output goes nowhere | -| Entry points are clear and well-defined | Execution knows where to start | +| Check | Why It Matters | +| -------------------------------------------------- | ------------------------------------------------- | +| Stages follow a logical progression | Users and execution engines expect a natural flow | +| Earlier stages produce what later stages need | Broken handoffs cause failures | +| No dead-end stages that produce nothing downstream | Wasted effort if output goes nowhere | +| Entry points are clear and well-defined | Execution knows where to start | **Examples of incoherence:** + - Analysis stage comes after the implementation stage - Stage produces output format that next stage can't consume - Multiple stages claim to be the starting point @@ -48,17 +51,18 @@ Find and read: **Question:** Does WHAT the skill does match WHY it exists — and do the execution instructions actually honor the design principles? -| Check | Why It Matters | -|-------|----------------| -| Skill's stated purpose matches its actual stages | Misalignment causes user disappointment | -| Role guidance is reflected in stage behavior | Don't claim "expert analysis" if stages are superficial | -| Description matches what stages actually deliver | Users rely on descriptions to choose skills | -| output-location entries align with actual stage outputs | Declared outputs must actually be produced | -| **Design rationale honored by execution instructions** | An agent following the instructions must not violate the stated design principles | +| Check | Why It Matters | +| ------------------------------------------------------- | --------------------------------------------------------------------------------- | +| Skill's stated purpose matches its actual stages | Misalignment causes user disappointment | +| Role guidance is reflected in stage behavior | Don't claim "expert analysis" if stages are superficial | +| Description matches what stages actually deliver | Users rely on descriptions to choose skills | +| output-location entries align with actual stage outputs | Declared outputs must actually be produced | +| **Design rationale honored by execution instructions** | An agent following the instructions must not violate the stated design principles | **The promises-vs-behavior check:** If the Overview or design rationale states a principle (e.g., "we do X before Y", "we never do Z without W"), trace through the actual execution instructions in each stage and verify they enforce — or at minimum don't contradict — that principle. Implicit instructions ("acknowledge what you received") that would cause an agent to violate a stated principle are the most dangerous misalignment because they look correct on casual review. **Examples of misalignment:** + - Skill claims "comprehensive code review" but only has a linting stage - Role guidance says "collaborative" but no stages involve user interaction - Description says "end-to-end deployment" but stops at build @@ -68,14 +72,15 @@ Find and read: **Question:** Is this the right type and complexity level for what it does? -| Check | Why It Matters | -|-------|----------------| -| Simple tasks use simple workflow type | Over-engineering wastes tokens and time | +| Check | Why It Matters | +| ---------------------------------------------- | ---------------------------------------- | +| Simple tasks use simple workflow type | Over-engineering wastes tokens and time | | Complex tasks use guided/complex workflow type | Under-engineering misses important steps | -| Number of stages matches task complexity | 15 stages for a 2-step task is wrong | -| Branching complexity matches decision space | Don't branch when linear suffices | +| Number of stages matches task complexity | 15 stages for a 2-step task is wrong | +| Branching complexity matches decision space | Don't branch when linear suffices | **Complexity test:** + - Too complex: 10-stage workflow for "format a file" - Too simple: 2-stage workflow for "architect a microservices system" - Just right: Complexity matches the actual decision space and output requirements @@ -84,14 +89,15 @@ Find and read: **Question:** Are there missing or duplicated stages? -| Check | Why It Matters | -|-------|----------------| -| No missing stages in core workflow | Users shouldn't need to manually fill gaps | -| No overlapping stages doing the same work | Wastes tokens and execution time | -| Validation/review stages present where needed | Quality gates prevent bad outputs | -| Error handling or fallback stages exist | Graceful degradation matters | +| Check | Why It Matters | +| --------------------------------------------- | ------------------------------------------ | +| No missing stages in core workflow | Users shouldn't need to manually fill gaps | +| No overlapping stages doing the same work | Wastes tokens and execution time | +| Validation/review stages present where needed | Quality gates prevent bad outputs | +| Error handling or fallback stages exist | Graceful degradation matters | **Gap detection heuristic:** + - If skill analyzes something, does it also report/act on findings? - If skill creates something, does it also validate the creation? - If skill has a multi-step process, are all steps covered? @@ -101,16 +107,17 @@ Find and read: **Question:** Are `after`, `before`, and `is-required` dependencies correct and complete? -| Check | Why It Matters | -|-------|----------------| -| `after` captures true input dependencies | Missing deps cause execution failures | -| `before` captures downstream consumers | Incorrect ordering degrades quality | -| `is-required` distinguishes hard blocks from nice-to-have ordering | Unnecessary blocks prevent parallelism | -| No circular dependencies | Execution deadlock | -| No unnecessary dependencies creating bottlenecks | Slows parallel execution | -| output-location entries match what stages actually produce | Downstream consumers rely on these declarations | +| Check | Why It Matters | +| ------------------------------------------------------------------ | ----------------------------------------------- | +| `after` captures true input dependencies | Missing deps cause execution failures | +| `before` captures downstream consumers | Incorrect ordering degrades quality | +| `is-required` distinguishes hard blocks from nice-to-have ordering | Unnecessary blocks prevent parallelism | +| No circular dependencies | Execution deadlock | +| No unnecessary dependencies creating bottlenecks | Slows parallel execution | +| output-location entries match what stages actually produce | Downstream consumers rely on these declarations | **Dependency patterns to check:** + - Stage declares `after: [X]` but doesn't actually use X's output - Stage uses output from Y but doesn't declare `after: [Y]` - `is-required` set to true when the dependency is actually a nice-to-have @@ -121,12 +128,12 @@ Find and read: **Question:** How does this skill work with external skills, and is that intentional? -| Check | Why It Matters | -|-------|----------------| -| Referenced external skills fit the workflow | Random skill calls confuse the purpose | +| Check | Why It Matters | +| ----------------------------------------------------- | ------------------------------------------- | +| Referenced external skills fit the workflow | Random skill calls confuse the purpose | | Skill can function standalone OR with external skills | Don't REQUIRE skills that aren't documented | -| External skill delegation follows a clear pattern | Haphazard calling suggests poor design | -| External skill outputs are consumed properly | Don't call a skill and ignore its output | +| External skill delegation follows a clear pattern | Haphazard calling suggests poor design | +| External skill outputs are consumed properly | Don't call a skill and ignore its output | **Note:** If external skills aren't available, infer their purpose from name and usage context. diff --git a/skills/bmad-workflow-builder/quality-scan-workflow-integrity.md b/skills/bmad-workflow-builder/quality-scan-workflow-integrity.md index 6dd9cd4..6007612 100644 --- a/skills/bmad-workflow-builder/quality-scan-workflow-integrity.md +++ b/skills/bmad-workflow-builder/quality-scan-workflow-integrity.md @@ -15,6 +15,7 @@ Read the skill's SKILL.md and all stage prompts. Verify structural completeness, ## Scan Targets Find and read: + - `SKILL.md` — Primary structure and blueprint - `*.md` prompt files at root — Stage prompt files (if complex workflow) @@ -24,77 +25,78 @@ Find and read: ### Frontmatter (The Trigger) -| Check | Why It Matters | -|-------|----------------| -| `name` MUST match the folder name AND follows pattern `bmad-{code}-{skillname}` or `bmad-{skillname}` | Naming convention identifies module affiliation | -| `description` follows two-part format: [5-8 word summary]. [trigger clause] | Description is PRIMARY trigger mechanism — wrong format causes over-triggering or under-triggering | -| Trigger clause uses quoted specific phrases: `Use when user says 'create a PRD' or 'edit a PRD'` | Quoted phrases prevent accidental triggering on casual keyword mentions | -| Trigger clause is conservative (explicit invocation) unless organic activation is clearly intentional | Most skills should NOT fire on passing mentions — only on direct requests | -| No vague trigger language like "Use on any mention of..." or "Helps with..." | Over-broad descriptions hijack unrelated conversations | -| No extra frontmatter fields beyond name/description | Extra fields clutter metadata, may not parse correctly | +| Check | Why It Matters | +| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `name` MUST match the folder name AND follows pattern `bmad-{code}-{skillname}` or `bmad-{skillname}` | Naming convention identifies module affiliation | +| `description` follows two-part format: [5-8 word summary]. [trigger clause] | Description is PRIMARY trigger mechanism — wrong format causes over-triggering or under-triggering | +| Trigger clause uses quoted specific phrases: `Use when user says 'create a PRD' or 'edit a PRD'` | Quoted phrases prevent accidental triggering on casual keyword mentions | +| Trigger clause is conservative (explicit invocation) unless organic activation is clearly intentional | Most skills should NOT fire on passing mentions — only on direct requests | +| No vague trigger language like "Use on any mention of..." or "Helps with..." | Over-broad descriptions hijack unrelated conversations | +| No extra frontmatter fields beyond name/description | Extra fields clutter metadata, may not parse correctly | ### Required Sections -| Check | Why It Matters | -|-------|----------------| -| Has `## Overview` section | Primes AI's understanding before detailed instructions — see prompt-craft scanner for depth assessment | -| Has role guidance (who/what executes this workflow) | Clarifies the executor's perspective without creating a full persona | -| Has `## On Activation` with clear activation steps | Prevents confusion about what to do when invoked | -| Sections in logical order | Scrambled sections make AI work harder to understand flow | +| Check | Why It Matters | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| Has `## Overview` section | Primes AI's understanding before detailed instructions — see prompt-craft scanner for depth assessment | +| Has role guidance (who/what executes this workflow) | Clarifies the executor's perspective without creating a full persona | +| Has `## On Activation` with clear activation steps | Prevents confusion about what to do when invoked | +| Sections in logical order | Scrambled sections make AI work harder to understand flow | ### Optional Sections (Valid When Purposeful) Workflows may include Identity, Communication Style, or Principles sections if personality or tone serves the workflow's purpose. These are more common in agents but not restricted to them. -| Check | Why It Matters | -|-------|----------------| -| `## Identity` section (if present) serves a purpose | Valid when personality/tone affects workflow outcomes | -| `## Communication Style` (if present) serves a purpose | Valid when consistent tone matters for the workflow | -| `## Principles` (if present) serves a purpose | Valid when guiding values improve workflow outcomes | -| **NO `## On Exit` or `## Exiting` section** | There are NO exit hooks in the system — this section would never run | +| Check | Why It Matters | +| ------------------------------------------------------ | -------------------------------------------------------------------- | +| `## Identity` section (if present) serves a purpose | Valid when personality/tone affects workflow outcomes | +| `## Communication Style` (if present) serves a purpose | Valid when consistent tone matters for the workflow | +| `## Principles` (if present) serves a purpose | Valid when guiding values improve workflow outcomes | +| **NO `## On Exit` or `## Exiting` section** | There are NO exit hooks in the system — this section would never run | ### Language & Directness -| Check | Why It Matters | -|-------|----------------| -| No "you should" or "please" language | Direct commands work better than polite requests | +| Check | Why It Matters | +| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| No "you should" or "please" language | Direct commands work better than polite requests | | No over-specification of LLM general capabilities (see below) | Wastes tokens, creates brittle mechanical procedures for things the LLM handles naturally | -| Instructions address the AI directly | "When activated, this workflow..." is meta — better: "When activated, load config..." | -| No ambiguous phrasing like "handle appropriately" | AI doesn't know what "appropriate" means without specifics | +| Instructions address the AI directly | "When activated, this workflow..." is meta — better: "When activated, load config..." | +| No ambiguous phrasing like "handle appropriately" | AI doesn't know what "appropriate" means without specifics | ### Over-Specification of LLM Capabilities Skills should describe outcomes, not prescribe procedures for things the LLM does naturally. Flag these structural indicators of over-specification: -| Check | Why It Matters | Severity | -|-------|----------------|----------| -| Adapter files that duplicate platform knowledge (e.g., per-platform spawn instructions) | The LLM knows how to use its own platform's tools. Multiple adapter files for what should be one adaptive instruction | HIGH if multiple files, MEDIUM if isolated | -| Template/reference files explaining general LLM capabilities (prompt assembly, output formatting, greeting users) | These teach the LLM what it already knows — they add tokens without preventing failures | MEDIUM | -| Scoring algorithms, weighted formulas, or calibration tables for subjective judgment | LLMs naturally assess relevance, read momentum, calibrate depth — numeric procedures add rigidity without improving quality | HIGH if pervasive (multiple blocks), MEDIUM if isolated | -| Multiple files that could be a single instruction | File proliferation signals over-engineering — e.g., 3 adapter files + 1 template that should be "use subagents if available, simulate if not" | HIGH | +| Check | Why It Matters | Severity | +| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| Adapter files that duplicate platform knowledge (e.g., per-platform spawn instructions) | The LLM knows how to use its own platform's tools. Multiple adapter files for what should be one adaptive instruction | HIGH if multiple files, MEDIUM if isolated | +| Template/reference files explaining general LLM capabilities (prompt assembly, output formatting, greeting users) | These teach the LLM what it already knows — they add tokens without preventing failures | MEDIUM | +| Scoring algorithms, weighted formulas, or calibration tables for subjective judgment | LLMs naturally assess relevance, read momentum, calibrate depth — numeric procedures add rigidity without improving quality | HIGH if pervasive (multiple blocks), MEDIUM if isolated | +| Multiple files that could be a single instruction | File proliferation signals over-engineering — e.g., 3 adapter files + 1 template that should be "use subagents if available, simulate if not" | HIGH | **Don't flag as over-specification:** + - Domain-specific patterns the LLM wouldn't know (BMad config conventions, module metadata) - Design rationale for non-obvious choices - Fragile operations where deviation has consequences ### Template Artifacts (Incomplete Build Detection) -| Check | Why It Matters | -|-------|----------------| -| No orphaned `{if-complex-workflow}` conditionals | Orphaned conditional means build process incomplete | -| No orphaned `{if-simple-workflow}` conditionals | Should have been resolved during skill creation | -| No orphaned `{if-simple-utility}` conditionals | Should have been resolved during skill creation | -| No bare placeholders like `{displayName}`, `{skillName}` | Should have been replaced with actual values | -| No other template fragments (`{if-module}`, `{if-headless}`, etc.) | Conditional blocks should be removed, not left as text | -| Config variables are OK | `{user_name}`, `{communication_language}`, `{document_output_language}` are intentional runtime variables | +| Check | Why It Matters | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | +| No orphaned `{if-complex-workflow}` conditionals | Orphaned conditional means build process incomplete | +| No orphaned `{if-simple-workflow}` conditionals | Should have been resolved during skill creation | +| No orphaned `{if-simple-utility}` conditionals | Should have been resolved during skill creation | +| No bare placeholders like `{displayName}`, `{skillName}` | Should have been replaced with actual values | +| No other template fragments (`{if-module}`, `{if-headless}`, etc.) | Conditional blocks should be removed, not left as text | +| Config variables are OK | `{user_name}`, `{communication_language}`, `{document_output_language}` are intentional runtime variables | ### Config Integration -| Check | Why It Matters | -|-------|----------------| +| Check | Why It Matters | +| --------------------------------------- | -------------------------------------------------------------------- | | Config loading present in On Activation | Config provides user preferences, language settings, project context | -| Config values used where appropriate | Hardcoded values that should come from config cause inflexibility | +| Config values used where appropriate | Hardcoded values that should come from config cause inflexibility | --- @@ -102,68 +104,68 @@ Skills should describe outcomes, not prescribe procedures for things the LLM doe Determine workflow type from SKILL.md before applying type-specific checks: -| Type | Indicators | -|------|-----------| +| Type | Indicators | +| ---------------- | --------------------------------------------------------------- | | Complex Workflow | Has routing logic, references stage files at root, stages table | -| Simple Workflow | Has inline numbered steps, no external stage files | -| Simple Utility | Input/output focused, transformation rules, minimal process | +| Simple Workflow | Has inline numbered steps, no external stage files | +| Simple Utility | Input/output focused, transformation rules, minimal process | ### Complex Workflow #### Stage Files -| Check | Why It Matters | -|-------|----------------| +| Check | Why It Matters | +| ------------------------------------------------------ | --------------------------------------------------------------- | | Each stage referenced in SKILL.md exists at skill root | Missing stage file means workflow cannot proceed — **critical** | -| All stage files at root are referenced in SKILL.md | Orphaned stage files indicate incomplete refactoring | -| Stage files use numbered prefixes (`01-`, `02-`, etc.) | Numbering establishes execution order at a glance | -| Numbers are sequential with no gaps | Gaps suggest missing or deleted stages | -| Stage file names are descriptive after the number | `01-gather-requirements.md` is clear; `01-step.md` is not | +| All stage files at root are referenced in SKILL.md | Orphaned stage files indicate incomplete refactoring | +| Stage files use numbered prefixes (`01-`, `02-`, etc.) | Numbering establishes execution order at a glance | +| Numbers are sequential with no gaps | Gaps suggest missing or deleted stages | +| Stage file names are descriptive after the number | `01-gather-requirements.md` is clear; `01-step.md` is not | #### Progression Conditions -| Check | Why It Matters | -|-------|----------------| -| Each stage prompt has explicit progression conditions | Without conditions, AI doesn't know when to advance — **critical** | -| Progression conditions are specific and testable | "When ready" is vague; "When all 5 fields are populated" is testable | -| Final stage has completion/output criteria | Workflow needs a defined end state | -| No circular stage references without exit conditions | Infinite loops break workflow execution | +| Check | Why It Matters | +| ----------------------------------------------------- | -------------------------------------------------------------------- | +| Each stage prompt has explicit progression conditions | Without conditions, AI doesn't know when to advance — **critical** | +| Progression conditions are specific and testable | "When ready" is vague; "When all 5 fields are populated" is testable | +| Final stage has completion/output criteria | Workflow needs a defined end state | +| No circular stage references without exit conditions | Infinite loops break workflow execution | #### Config Headers in Stage Prompts -| Check | Why It Matters | -|-------|----------------| -| Each stage prompt has config header specifying Language | AI needs to know what language to communicate in | +| Check | Why It Matters | +| ----------------------------------------------------------- | -------------------------------------------------------- | +| Each stage prompt has config header specifying Language | AI needs to know what language to communicate in | | Stage prompts that create documents specify Output Language | Document language may differ from communication language | -| Config header uses config variables correctly | `{communication_language}`, `{document_output_language}` | +| Config header uses config variables correctly | `{communication_language}`, `{document_output_language}` | ### Simple Workflow -| Check | Why It Matters | -|-------|----------------| -| Steps are numbered sequentially | Clear execution order prevents confusion | -| Each step has a clear action | Vague steps produce unreliable behavior | -| Steps have defined outputs or state changes | AI needs to know what each step produces | -| Final step has clear completion criteria | Workflow needs a defined end state | -| No references to external stage files | Simple workflows should be self-contained inline | +| Check | Why It Matters | +| ------------------------------------------- | ------------------------------------------------ | +| Steps are numbered sequentially | Clear execution order prevents confusion | +| Each step has a clear action | Vague steps produce unreliable behavior | +| Steps have defined outputs or state changes | AI needs to know what each step produces | +| Final step has clear completion criteria | Workflow needs a defined end state | +| No references to external stage files | Simple workflows should be self-contained inline | ### Simple Utility -| Check | Why It Matters | -|-------|----------------| -| Input format is clearly defined | AI needs to know what it receives | -| Output format is clearly defined | AI needs to know what to produce | -| Transformation rules are explicit | Ambiguous transformations produce inconsistent results | -| Edge cases for input are addressed | Unexpected input causes failures | -| No unnecessary process steps | Utilities should be direct: input → transform → output | +| Check | Why It Matters | +| ---------------------------------- | ------------------------------------------------------ | +| Input format is clearly defined | AI needs to know what it receives | +| Output format is clearly defined | AI needs to know what to produce | +| Transformation rules are explicit | Ambiguous transformations produce inconsistent results | +| Edge cases for input are addressed | Unexpected input causes failures | +| No unnecessary process steps | Utilities should be direct: input → transform → output | ### Headless Mode (If Declared) -| Check | Why It Matters | -|-------|----------------| +| Check | Why It Matters | +| ----------------------------------------------------------------------- | ------------------------------------------------------ | | Headless mode setup is defined if SKILL.md declares headless capability | Headless execution needs explicit non-interactive path | -| All user interaction points have headless alternatives | Prompts for user input break headless execution | -| Default values specified for headless mode | Missing defaults cause headless execution to stall | +| All user interaction points have headless alternatives | Prompts for user input break headless execution | +| Default values specified for headless mode | Missing defaults cause headless execution to stall | --- @@ -171,25 +173,25 @@ Determine workflow type from SKILL.md before applying type-specific checks: These checks verify that the skill's parts agree with each other — catching mismatches that only surface when you look at SKILL.md and its implementation together. -| Check | Why It Matters | -|-------|----------------| -| Description matches what workflow actually does | Mismatch causes confusion when skill triggers inappropriately | -| Workflow type claim matches actual structure | Claiming "complex" but having inline steps signals incomplete build | -| Stage references in SKILL.md point to existing files | Dead references cause runtime failures | -| Activation sequence is logically ordered | Can't route to stages before loading config | -| Routing table entries (if present) match stage files | Routing to nonexistent stages breaks flow | +| Check | Why It Matters | +| ------------------------------------------------------ | ----------------------------------------------------------------------- | +| Description matches what workflow actually does | Mismatch causes confusion when skill triggers inappropriately | +| Workflow type claim matches actual structure | Claiming "complex" but having inline steps signals incomplete build | +| Stage references in SKILL.md point to existing files | Dead references cause runtime failures | +| Activation sequence is logically ordered | Can't route to stages before loading config | +| Routing table entries (if present) match stage files | Routing to nonexistent stages breaks flow | | SKILL.md type-appropriate sections match detected type | Missing routing logic for complex, or unnecessary stage refs for simple | --- ## Severity Guidelines -| Severity | When to Apply | -|----------|---------------| +| Severity | When to Apply | +| ------------ | ---------------------------------------------------------------------------------------------------------- | | **Critical** | Missing stage files, missing progression conditions, circular dependencies without exit, broken references | -| **High** | Missing On Activation, vague/missing description, orphaned template artifacts, type mismatch | -| **Medium** | Naming convention violations, minor config issues, ambiguous language, orphaned stage files | -| **Low** | Style preferences, ordering suggestions, minor directness improvements | +| **High** | Missing On Activation, vague/missing description, orphaned template artifacts, type mismatch | +| **Medium** | Naming convention violations, minor config issues, ambiguous language, orphaned stage files | +| **Low** | Style preferences, ordering suggestions, minor directness improvements | --- diff --git a/skills/bmad-workflow-builder/references/classification-reference.md b/skills/bmad-workflow-builder/references/classification-reference.md index 2cefdcb..9f52662 100644 --- a/skills/bmad-workflow-builder/references/classification-reference.md +++ b/skills/bmad-workflow-builder/references/classification-reference.md @@ -4,10 +4,10 @@ Classify the skill type based on user requirements. This table is for internal u ## 3-Type Taxonomy -| Type | Description | Structure | When to Use | -|------|-------------|-----------|-------------| -| **Simple Utility** | Input/output building block. Headless, composable, often has scripts. | Single SKILL.md + scripts/ | Composable building block with clear input/output, single-purpose | -| **Simple Workflow** | Multi-step process contained in a single SKILL.md. Minimal or no prompt files. | SKILL.md + optional references/ | Multi-step process that fits in one file, no progressive disclosure needed | +| Type | Description | Structure | When to Use | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | +| **Simple Utility** | Input/output building block. Headless, composable, often has scripts. | Single SKILL.md + scripts/ | Composable building block with clear input/output, single-purpose | +| **Simple Workflow** | Multi-step process contained in a single SKILL.md. Minimal or no prompt files. | SKILL.md + optional references/ | Multi-step process that fits in one file, no progressive disclosure needed | | **Complex Workflow** | Multi-stage with progressive disclosure, numbered prompt files at root, config integration. May support headless mode. | SKILL.md (routing) + prompt stages at root + references/ | Multiple stages, long-running process, progressive disclosure, routing logic | ## Decision Tree @@ -28,6 +28,7 @@ Classify the skill type based on user requirements. This table is for internal u ## Classification Signals ### Simple Utility Signals + - Clear input → processing → output pattern - No user interaction needed during execution - Other skills/workflows call it @@ -36,6 +37,7 @@ Classify the skill type based on user requirements. This table is for internal u - Examples: JSON validator, schema checker, format converter ### Simple Workflow Signals + - 3-8 numbered steps - User interaction at specific points - Uses standard tools (gh, git, npm, etc.) @@ -44,6 +46,7 @@ Classify the skill type based on user requirements. This table is for internal u - Examples: PR creator, deployment checklist, code review ### Complex Workflow Signals + - Multiple distinct phases/stages - Long-running (likely to hit context compaction) - Progressive disclosure needed (too much for one file) @@ -55,5 +58,6 @@ Classify the skill type based on user requirements. This table is for internal u ## Module Context (Orthogonal) Module context is asked for ALL types: + - **Module-based:** Part of a BMad module. Uses `bmad-{modulecode}-{skillname}` naming. Config loading includes a fallback pattern — if config is missing, the skill informs the user that the module setup skill is available and continues with sensible defaults. - **Standalone:** Independent skill. Uses `bmad-{skillname}` naming. Config loading is best-effort — load if available, use defaults if not, no mention of a setup skill. diff --git a/skills/bmad-workflow-builder/references/complex-workflow-patterns.md b/skills/bmad-workflow-builder/references/complex-workflow-patterns.md index f8255a7..cbf9366 100644 --- a/skills/bmad-workflow-builder/references/complex-workflow-patterns.md +++ b/skills/bmad-workflow-builder/references/complex-workflow-patterns.md @@ -17,12 +17,14 @@ Workflows read config from `{project-root}/_bmad/config.yaml` and `config.user.y ### Config Loading Pattern **Module-based skills** — load with fallback and setup skill awareness: + ``` Load config from {project-root}/_bmad/config.yaml ({module-code} section) and config.user.yaml. If missing: inform user that {module-setup-skill} is available, continue with sensible defaults. ``` **Standalone skills** — load best-effort: + ``` Load config from {project-root}/_bmad/config.yaml and config.user.yaml if available. If missing: continue with defaults — no mention of setup skill. @@ -33,6 +35,7 @@ If missing: continue with defaults — no mention of setup skill. Load core config (user preferences, language, output locations) with sensible defaults. If the workflow creates documents, include document output language. **Example config line for a document-producing workflow:** + ``` vars: user_name:BMad,communication_language:English,document_output_language:English,output_folder:{project-root}/_bmad-output,bmad_builder_output_folder:{project-root}/bmad-builder-creations/ ``` @@ -57,12 +60,12 @@ Each stage after the first reads the output document to recover context. If comp ```markdown --- -title: "Analysis: Research Topic" -status: "analysis" +title: 'Analysis: Research Topic' +status: 'analysis' inputs: - - "{project_root}/docs/brief.md" -created: "2025-03-02T10:00:00Z" -updated: "2025-03-02T11:30:00Z" + - '{project_root}/docs/brief.md' +created: '2025-03-02T10:00:00Z' +updated: '2025-03-02T11:30:00Z' --- ``` @@ -75,6 +78,7 @@ updated: "2025-03-02T11:30:00Z" ## Sequential Progressive Disclosure Use numbered prompt files at the skill root when: + - Multi-phase workflow with ordered stages - Input of one phase affects the next - Workflow is long-running and stages shouldn't be visible upfront diff --git a/skills/bmad-workflow-builder/references/quality-dimensions.md b/skills/bmad-workflow-builder/references/quality-dimensions.md index a502406..de11d65 100644 --- a/skills/bmad-workflow-builder/references/quality-dimensions.md +++ b/skills/bmad-workflow-builder/references/quality-dimensions.md @@ -16,13 +16,13 @@ The executing agent needs enough context to make judgment calls when situations - Simple utilities need minimal context — input/output is self-explanatory - Interactive/complex workflows 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 +- When in doubt, explain _why_ — an agent that understands the mission improvises better than one following blind steps ## 3. 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. +**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. diff --git a/skills/bmad-workflow-builder/references/script-opportunities-reference.md b/skills/bmad-workflow-builder/references/script-opportunities-reference.md index 70bf743..a3e244d 100644 --- a/skills/bmad-workflow-builder/references/script-opportunities-reference.md +++ b/skills/bmad-workflow-builder/references/script-opportunities-reference.md @@ -18,10 +18,10 @@ Scripts handle deterministic operations (validate, transform, count). Prompts ha ### The Judgment Boundary -| Scripts Handle | Prompts Handle | -|----------------|----------------| -| Fetch, Transform, Validate | Interpret, Classify (ambiguous) | -| Count, Parse, Compare | Create, Decide (incomplete info) | +| Scripts Handle | Prompts Handle | +| -------------------------------- | ------------------------------------ | +| Fetch, Transform, Validate | Interpret, Classify (ambiguous) | +| Count, Parse, Compare | Create, Decide (incomplete info) | | Extract, Format, Check structure | Evaluate quality, Synthesize meaning | ### Signal Verbs in Prompts @@ -30,17 +30,17 @@ When you see these in a workflow's requirements, think scripts first: "validate" ### Script Opportunity Categories -| Category | What It Does | Example | -|----------|-------------|---------| -| Validation | Check structure, format, schema, naming | Validate frontmatter fields exist | -| Data Extraction | Pull structured data without interpreting meaning | Extract all `{variable}` references from markdown | -| Transformation | Convert between known formats | Markdown table to JSON | -| Metrics | Count, tally, aggregate statistics | Token count per file | -| Comparison | Diff, cross-reference, verify consistency | Cross-ref prompt names against SKILL.md references | -| Structure Checks | Verify directory layout, file existence | Skill folder has required files | -| Dependency Analysis | Trace references, imports, relationships | Build skill dependency graph | -| Pre-Processing | Extract compact data from large files BEFORE LLM reads them | Pre-extract file metrics into JSON for LLM scanner | -| Post-Processing | Verify LLM output meets structural requirements | Validate generated YAML parses correctly | +| Category | What It Does | Example | +| ------------------- | ----------------------------------------------------------- | -------------------------------------------------- | +| Validation | Check structure, format, schema, naming | Validate frontmatter fields exist | +| Data Extraction | Pull structured data without interpreting meaning | Extract all `{variable}` references from markdown | +| Transformation | Convert between known formats | Markdown table to JSON | +| Metrics | Count, tally, aggregate statistics | Token count per file | +| Comparison | Diff, cross-reference, verify consistency | Cross-ref prompt names against SKILL.md references | +| Structure Checks | Verify directory layout, file existence | Skill folder has required files | +| Dependency Analysis | Trace references, imports, relationships | Build skill dependency graph | +| Pre-Processing | Extract compact data from large files BEFORE LLM reads them | Pre-extract file metrics into JSON for LLM scanner | +| Post-Processing | Verify LLM output meets structural requirements | Validate generated YAML parses correctly | ### Your Toolbox @@ -71,7 +71,7 @@ All scripts MUST output structured JSON: { "severity": "critical|high|medium|low|info", "category": "structure|security|performance|consistency", - "location": {"file": "SKILL.md", "line": 42}, + "location": { "file": "SKILL.md", "line": 42 }, "issue": "Clear description", "fix": "Specific action to resolve" } diff --git a/skills/bmad-workflow-builder/references/script-standards.md b/skills/bmad-workflow-builder/references/script-standards.md index 62028f3..0c7cc2d 100644 --- a/skills/bmad-workflow-builder/references/script-standards.md +++ b/skills/bmad-workflow-builder/references/script-standards.md @@ -7,6 +7,7 @@ When building scripts for a skill, follow these standards to ensure portability **Always favor Python for script logic.** Bash is not portable — it fails or behaves inconsistently on Windows (Git Bash is MSYS2-based, not a full Linux shell; WSL bash can conflict with Git Bash on PATH; PowerShell is a different language entirely). Python with `uv run` works identically on all platforms. **Safe bash commands** — these work reliably across all environments and are fine to use directly: + - `git`, `gh` — version control and GitHub CLI - `uv run` — Python script execution with automatic dependency handling - `npm`, `npx`, `pnpm` — Node.js ecosystem @@ -51,6 +52,7 @@ For scripts using only the standard library, use a plain Python shebang but stil ``` **Key rules:** + - The shebang MUST be line 1 — before the metadata block - Always include `requires-python` - List all external dependencies with version constraints @@ -73,6 +75,7 @@ Skills may run in environments where Python or `uv` is unavailable (e.g., claude **Pattern:** When a script cannot execute, the LLM performs the equivalent work directly. The script's `--help` documents what it checks, making this fallback natural. Design scripts so their logic is understandable from their help output and the skill's context. In SKILL.md, frame script steps as outcomes, not just commands: + - Good: "Validate path conventions (run `scripts/scan-paths.py --help` for details)" - Avoid: "Execute `python3 scripts/scan-paths.py`" with no context about what it does diff --git a/skills/bmad-workflow-builder/references/skill-best-practices.md b/skills/bmad-workflow-builder/references/skill-best-practices.md index 7b11fa6..e913875 100644 --- a/skills/bmad-workflow-builder/references/skill-best-practices.md +++ b/skills/bmad-workflow-builder/references/skill-best-practices.md @@ -10,11 +10,11 @@ Skills should describe **what to achieve**, not **how to achieve it**. The LLM i ### Outcome vs Prescriptive -| Prescriptive (avoid) | Outcome-based (prefer) | -|---|---| -| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." | -| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." | -| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." | +| Prescriptive (avoid) | Outcome-based (prefer) | +| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." | +| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." | +| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." | The prescriptive versions miss requirements the author didn't think of. The outcome-based versions let the LLM adapt to the actual situation. @@ -29,11 +29,11 @@ The prescriptive versions miss requirements the author didn't think of. The outc Reserve exact steps for **fragile operations** where getting it wrong has consequences — script invocations, exact file paths, specific CLI commands, API calls with precise parameters. These need low freedom because there's one right way to do them. -| Freedom | When | Example | -|---------|------|---------| -| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" | -| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" | -| **Low** (exact) | Fragile, one right way, consequences for deviation | `python3 scripts/scan-path-standards.py {skill-path}` | +| Freedom | When | Example | +| ------------------- | -------------------------------------------------- | ------------------------------------------------------------------- | +| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" | +| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" | +| **Low** (exact) | Fragile, one right way, consequences for deviation | `python3 scripts/scan-path-standards.py {skill-path}` | ## Patterns @@ -63,10 +63,10 @@ Before finalizing significant artifacts, fan out reviewers with different perspe Consider whether the skill benefits from multiple execution modes: -| Mode | When | Behavior | -|------|------|----------| -| **Guided** | Default | Conversational discovery with soft gates | -| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine | +| Mode | When | Behavior | +| ------------ | ------------------- | ------------------------------------------------------------- | +| **Guided** | Default | Conversational discovery with soft gates | +| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine | | **Headless** | `--headless` / `-H` | Complete the task without user input, using sensible defaults | Not all skills need all three. But considering them during design prevents locking into a single interaction model. @@ -90,16 +90,16 @@ For complex tasks with consequences: plan → validate → execute → verify. C ## Anti-Patterns -| Anti-Pattern | Fix | -|---|---| -| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters | -| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) | -| Prescribing exact greeting/menu format | "Greet the user and present capabilities" | -| Spelling out headless mode in detail | "If headless, complete without user input" | -| Too many options upfront | One default with escape hatch | -| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md | -| Inconsistent terminology | Choose one term per concept | -| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts | +| Anti-Pattern | Fix | +| -------------------------------------------------- | ----------------------------------------------------- | +| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters | +| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) | +| Prescribing exact greeting/menu format | "Greet the user and present capabilities" | +| Spelling out headless mode in detail | "If headless, complete without user input" | +| Too many options upfront | One default with escape hatch | +| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md | +| Inconsistent terminology | Choose one term per concept | +| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts | ## Scripts in Skills diff --git a/skills/bmad-workflow-builder/references/standard-fields.md b/skills/bmad-workflow-builder/references/standard-fields.md index 91d7737..dc8c830 100644 --- a/skills/bmad-workflow-builder/references/standard-fields.md +++ b/skills/bmad-workflow-builder/references/standard-fields.md @@ -4,52 +4,53 @@ Only these fields go in the YAML frontmatter block: -| Field | Description | Example | -|-------|-------------|---------| -| `name` | Full skill name (kebab-case, same as folder name) | `bmad-workflow-builder`, `bmad-validate-json` | -| `description` | [5-8 word summary]. [Use when user says 'X' or 'Y'.] | See Description Format below | +| Field | Description | Example | +| ------------- | ---------------------------------------------------- | --------------------------------------------- | +| `name` | Full skill name (kebab-case, same as folder name) | `bmad-workflow-builder`, `bmad-validate-json` | +| `description` | [5-8 word summary]. [Use when user says 'X' or 'Y'.] | See Description Format below | ## Content Fields (All Types) These are used within the SKILL.md body — never in frontmatter: -| Field | Description | Example | -|-------|-------------|---------| -| `role-guidance` | Brief expertise primer | "Act as a senior DevOps engineer" | -| `module-code` | Module code (if module-based) | `bmb`, `cis` | +| Field | Description | Example | +| --------------- | ----------------------------- | --------------------------------- | +| `role-guidance` | Brief expertise primer | "Act as a senior DevOps engineer" | +| `module-code` | Module code (if module-based) | `bmb`, `cis` | ## Simple Utility Fields -| Field | Description | Example | -|-------|-------------|---------| -| `input-format` | What it accepts | JSON file path, stdin text | -| `output-format` | What it returns | Validated JSON, error report | -| `standalone` | Fully standalone, no config needed? | true/false | -| `composability` | How other skills use it | "Called by quality scanners for validation" | +| Field | Description | Example | +| --------------- | ----------------------------------- | ------------------------------------------- | +| `input-format` | What it accepts | JSON file path, stdin text | +| `output-format` | What it returns | Validated JSON, error report | +| `standalone` | Fully standalone, no config needed? | true/false | +| `composability` | How other skills use it | "Called by quality scanners for validation" | ## Simple Workflow Fields -| Field | Description | Example | -|-------|-------------|---------| -| `steps` | Numbered inline steps | "1. Load config 2. Read input 3. Process" | -| `tools-used` | CLIs/tools/scripts | gh, jq, python scripts | -| `output` | What it produces | PR, report, file | +| Field | Description | Example | +| ------------ | --------------------- | ----------------------------------------- | +| `steps` | Numbered inline steps | "1. Load config 2. Read input 3. Process" | +| `tools-used` | CLIs/tools/scripts | gh, jq, python scripts | +| `output` | What it produces | PR, report, file | ## Complex Workflow Fields -| Field | Description | Example | -|-------|-------------|---------| -| `stages` | Named numbered stages | "01-discover, 02-plan, 03-build" | -| `progression-conditions` | When stages complete | "User approves outline" | -| `headless-mode` | Supports autonomous? | true/false | -| `config-variables` | Beyond core vars | `planning_artifacts`, `output_folder` | -| `output-artifacts` | What it creates (output-location) | "PRD document", "agent skill" | +| Field | Description | Example | +| ------------------------ | --------------------------------- | ------------------------------------- | +| `stages` | Named numbered stages | "01-discover, 02-plan, 03-build" | +| `progression-conditions` | When stages complete | "User approves outline" | +| `headless-mode` | Supports autonomous? | true/false | +| `config-variables` | Beyond core vars | `planning_artifacts`, `output_folder` | +| `output-artifacts` | What it creates (output-location) | "PRD document", "agent skill" | ## Overview Section Format The Overview is the first section after the title — it primes the AI for everything that follows. **3-part formula:** + 1. **What** — What this workflow/skill does 2. **How** — How it works (approach, key stages) 3. **Why/Outcome** — Value delivered, quality standard @@ -57,16 +58,19 @@ The Overview is the first section after the title — it primes the AI for every **Templates by skill type:** **Complex Workflow:** + ```markdown This skill helps you {outcome} through {approach}. Act as {role-guidance}, guiding users through {key stages}. Your output is {deliverable}. ``` **Simple Workflow:** + ```markdown This skill {what it does} by {approach}. Act as {role-guidance}. Use when {trigger conditions}. Produces {output}. ``` **Simple Utility:** + ```markdown This skill {what it does}. Use when {when to use}. Returns {output format} with {key feature}. ``` @@ -76,11 +80,13 @@ This skill {what it does}. Use when {when to use}. Returns {output format} with The frontmatter `description` is the PRIMARY trigger mechanism — it determines when the AI invokes this skill. Most BMad skills are **explicitly invoked** by name (`/skill-name` or direct request), so descriptions should be conservative to prevent accidental triggering. **Format:** Two parts, one sentence each: + ``` [What it does in 5-8 words]. [Use when user says 'specific phrase' or 'specific phrase'.] ``` **The trigger clause** uses one of these patterns depending on the skill's activation style: + - **Explicit invocation (default):** `Use when the user requests to 'create a PRD' or 'edit an existing PRD'.` — Quotes around specific phrases the user would actually say. Conservative — won't fire on casual mentions. - **Organic/reactive:** `Trigger when code imports anthropic SDK, or user asks to use Claude API.` — For lightweight skills that should activate on contextual signals, not explicit requests. @@ -99,9 +105,11 @@ Bad: `Use on any mention of workflows, building, or creating things.` — Over-b ## Role Guidance Format Every generated workflow SKILL.md includes a brief role statement in the Overview or as a standalone line: + ```markdown Act as {role-guidance}. {brief expertise/approach description}. ``` + This provides quick prompt priming for expertise and tone. Workflows may also use full Identity/Communication Style/Principles sections when personality serves the workflow's purpose. ## Path Rules @@ -109,6 +117,7 @@ This provides quick prompt priming for expertise and tone. Workflows may also us ### Skill-Internal Files All references to files within the skill use `./` prefix: + - `./references/reference.md` - `./references/discover.md` - `./scripts/validate.py` @@ -116,14 +125,19 @@ All references to files within the skill use `./` prefix: This distinguishes skill-internal files from `{project-root}` paths — without the `./` prefix the LLM may confuse them. ### Project `_bmad` Paths + Use `{project-root}/_bmad/...`: + - `{project-root}/_bmad/planning/prd.md` ### Config Variables + Use directly — they already contain `{project-root}` in their resolved values: + - `{output_folder}/file.md` - `{planning_artifacts}/prd.md` **Never:** + - `{project-root}/{output_folder}/file.md` (WRONG — double-prefix, config var already has path) - `_bmad/planning/prd.md` (WRONG — bare `_bmad` must have `{project-root}` prefix) diff --git a/skills/bmad-workflow-builder/references/template-substitution-rules.md b/skills/bmad-workflow-builder/references/template-substitution-rules.md index 4ba8d6d..27c31dd 100644 --- a/skills/bmad-workflow-builder/references/template-substitution-rules.md +++ b/skills/bmad-workflow-builder/references/template-substitution-rules.md @@ -11,12 +11,14 @@ The SKILL-template provides a minimal skeleton: frontmatter, overview, and activ ## Module Conditionals ### For Module-Based Skills + - `{if-module}` ... `{/if-module}` → Keep the content inside - `{if-standalone}` ... `{/if-standalone}` → Remove the entire block including markers - `{module-code}` → Module code without trailing hyphen (e.g., `bmb`) - `{module-setup-skill}` → Name of the module's setup skill (e.g., `bmad-builder-setup`) ### For Standalone Skills + - `{if-module}` ... `{/if-module}` → Remove the entire block including markers - `{if-standalone}` ... `{/if-standalone}` → Keep the content inside @@ -27,6 +29,7 @@ The builder determines the rest of the skill structure — body sections, phases ## Path References All generated skills use `./` prefix for skill-internal paths: + - `./references/{reference}.md` — Reference documents loaded on demand - `./references/{stage}.md` — Stage prompts (complex workflows) - `./scripts/` — Python/shell scripts for deterministic operations diff --git a/skills/bmad-workflow-builder/report-quality-scan-creator.md b/skills/bmad-workflow-builder/report-quality-scan-creator.md index cbc2124..8a94284 100644 --- a/skills/bmad-workflow-builder/report-quality-scan-creator.md +++ b/skills/bmad-workflow-builder/report-quality-scan-creator.md @@ -14,6 +14,7 @@ Your job is **synthesis, not transcription.** Don't list findings by scanner. Id ### Step 1: Read Everything Read all files in `{quality-report-dir}`: + - `*-temp.json` — Lint script output (structured JSON with findings arrays) - `*-prepass.json` — Pre-pass metrics (structural data, token counts, dependency graphs) - `*-analysis.md` — LLM scanner analyses (free-form markdown with assessments, findings, strengths) @@ -25,6 +26,7 @@ This is the most important step. Look across ALL scanner output for **findings t Ask: "If I fixed X, how many findings across all scanners would this resolve?" Group related findings into 3-5 themes. A theme has: + - **Name** — clear description of the root cause (e.g., "Over-specification of LLM capabilities") - **Description** — what's happening and why it matters (2-3 sentences) - **Severity** — highest severity of constituent findings @@ -37,6 +39,7 @@ Findings that don't fit any theme become standalone items. ### Step 3: Assess Overall Quality Synthesize a grade and narrative: + - **Grade:** Excellent (no high+ issues, few medium) / Good (some high or several medium) / Fair (multiple high) / Poor (critical issues) - **Narrative:** 2-3 sentences capturing the skill's primary strength and primary opportunity. This is what the user reads first — make it count. @@ -81,6 +84,7 @@ A narrative markdown report. Structure: **Fix:** {One coherent action to address the root cause.} **Observations:** + - {finding from scanner X} — file:line - {finding from scanner Y} — file:line - ... @@ -94,21 +98,27 @@ A narrative markdown report. Structure: ## Detailed Analysis ### Structure & Integrity + {Assessment + any findings not covered by themes} ### Craft & Writing Quality + {Assessment + prompt health + any remaining findings} ### Cohesion & Design + {Assessment + dimension scores + any remaining findings} ### Execution Efficiency + {Assessment + any remaining findings} ### User Experience + {Journeys, headless assessment, edge cases} ### Script Opportunities + {Assessment + token savings estimates} ## Recommendations @@ -226,6 +236,7 @@ Every `"..."` below is a placeholder for your content. Replace with actual value ``` **Self-check before writing report-data.json:** + 1. Is `meta.skill_name` present (not `meta.skill` or `meta.name`)? 2. Is `meta.scanner_count` a number (not an array of scanner names)? 3. Is every strength an object `{"title": "...", "detail": "..."}` (not a plain string)? diff --git a/website/src/styles/custom.css b/website/src/styles/custom.css index bc56292..34900b3 100644 --- a/website/src/styles/custom.css +++ b/website/src/styles/custom.css @@ -21,8 +21,8 @@ /* Primary accent colors - purple to match BMAD */ --sl-color-accent-low: #e0e0ff; - --sl-color-accent: #8C8CFF; - --sl-color-accent-high: #4141FF; + --sl-color-accent: #8c8cff; + --sl-color-accent-high: #4141ff; /* Text colors */ --sl-color-white: #1e293b; @@ -35,8 +35,7 @@ --sl-color-black: #f8fafc; /* Font settings */ - --sl-font: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', - Arial, sans-serif; + --sl-font: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; --sl-text-base: 1rem; --sl-line-height: 1.7; @@ -53,8 +52,8 @@ /* Primary accent colors - purple to match BMAD */ --sl-color-accent-low: #2a2a5a; - --sl-color-accent: #8C8CFF; - --sl-color-accent-high: #B9B9FF; + --sl-color-accent: #8c8cff; + --sl-color-accent-high: #b9b9ff; /* Background colors */ --sl-color-bg: #1b1b1d; @@ -396,7 +395,7 @@ blockquote { } .starlight-aside--note .starlight-aside__title { - color: #8C8CFF; + color: #8c8cff; } :root[data-theme='dark'] .starlight-aside--note { @@ -404,7 +403,7 @@ blockquote { } :root[data-theme='dark'] .starlight-aside--note .starlight-aside__title { - color: #8C8CFF; + color: #8c8cff; } /* Caution aside */