From 8cffd09fb79171a73f5a7d5ad3755f3e8a1e4433 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 30 Dec 2025 17:46:29 +0800 Subject: [PATCH] agent build intel complete --- .../create-agent/data/agent-metadata.md | 208 +++++++++++++ .../data/agent-validation-checklist.md | 144 --------- .../create-agent/data/critical-actions.md | 120 +++++++ .../data/expert-agent-validation.md | 173 +++++++++++ .../data/module-agent-validation.md | 124 ++++++++ .../create-agent/data/persona-properties.md | 266 ++++++++++++++++ .../create-agent/data/principles-crafting.md | 292 ++++++++++++++++++ .../data/simple-agent-validation.md | 132 ++++++++ .../create-agent/steps/step-01-brainstorm.md | 13 +- .../create-agent/steps/step-02-discover.md | 17 +- .../create-agent/steps/step-03-persona.md | 13 +- .../create-agent/steps/step-04-commands.md | 22 +- .../create-agent/steps/step-05-name.md | 11 +- .../create-agent/steps/step-06-build.md | 37 ++- .../create-agent/steps/step-07-validate.md | 33 +- .../create-agent/steps/step-08-celebrate.md | 63 ++-- src/modules/bmm/agents/pm.agent.yaml | 8 +- 17 files changed, 1407 insertions(+), 269 deletions(-) create mode 100644 src/modules/bmb/workflows/create-agent/data/agent-metadata.md delete mode 100644 src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md create mode 100644 src/modules/bmb/workflows/create-agent/data/critical-actions.md create mode 100644 src/modules/bmb/workflows/create-agent/data/expert-agent-validation.md create mode 100644 src/modules/bmb/workflows/create-agent/data/module-agent-validation.md create mode 100644 src/modules/bmb/workflows/create-agent/data/persona-properties.md create mode 100644 src/modules/bmb/workflows/create-agent/data/principles-crafting.md create mode 100644 src/modules/bmb/workflows/create-agent/data/simple-agent-validation.md diff --git a/src/modules/bmb/workflows/create-agent/data/agent-metadata.md b/src/modules/bmb/workflows/create-agent/data/agent-metadata.md new file mode 100644 index 00000000..7e2398d9 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/agent-metadata.md @@ -0,0 +1,208 @@ +# Agent Metadata Properties + +Core identification and classification properties for all agents. + +--- + +## Property Reference + +| Property | Purpose | Format | +| ------------ | ------------------------- | ---------------------------------------------- | +| `id` | Compiled output path | `_bmad/agents/{agent-name}/{agent-name}.md` | +| `name` | Persona's name | "First Last" or "Name Title" | +| `title` | Professional role | "Code Review Specialist" | +| `icon` | Visual identifier | Single emoji only | +| `module` | Team/ecosystem membership | `stand-alone`, `bmm`, `cis`, `bmgd`, or custom | +| `hasSidecar` | Sidecar folder exists | `true` or `false` (Expert = true) | + +--- + +## id Property + +The compiled output path after build. + +**Format:** `_bmad/agents/{agent-name}/{agent-name}.md` + +**Examples:** +```yaml +id: _bmad/agents/commit-poet/commit-poet.md +id: _bmad/agents/journal-keeper/journal-keeper.md +id: _bmad/agents/security-engineer/security-engineer.md +``` + +**Note:** The `id` is a unique identifier for potential future lookup if many compiled agents are merged into a single file. Conventionally matches the agent's filename pattern. + +--- + +## name Property + +The persona's identity - what the agent is called. + +**Format:** Human name or descriptive name + +```yaml +# ✅ CORRECT +name: 'Inkwell Von Comitizen' # peron name of commit-author title agent +name: 'Dr. Demento' # person name for a joke writer agent +name: 'Clarity' # person name for a guided thought coach agent + +# ❌ WRONG +name: 'commit-poet' # That's the filename +name: 'Code Review Specialist' # That's the title +``` + +--- + +## title Property + +Professional role identifier. + +**Format:** Professional title or role name + +**Important:** The `title` determines the agent's filename: +- `title: 'Commit Message Artisan'` → `commit-message-artisan.agent.yaml` +- `title: 'Strategic Business Analyst'` → `strategic-business-analyst.agent.yaml` +- `title: 'Code Review Specialist'` → `code-review-specialist.agent.yaml` + +The `id` and filename are derived from the `title` (kebab-cased). + +**Difference from role:** `title` is the short identifier (filename), `role` is 1-2 sentences expanding on what the agent does. + +```yaml +# ✅ CORRECT +title: 'Commit Message Artisan' +title: 'Strategic Business Analyst' +title: 'Code Review Specialist' + +# ❌ WRONG +title: 'Inkwell Von Comitizen' # That's the name +title: 'Writes git commits' # Full sentence - not an identifying functional title +``` + +--- + +## icon Property + +Single emoji representing the agent's personality/function. + +**Format:** Exactly one emoji + +```yaml +# ✅ CORRECT +icon: '🔧' +icon: '🧙‍♂️' +icon: '📜' + +# ❌ WRONG +icon: '🔧📜' # Multiple emojis +icon: 'wrench' # Text, not emoji +icon: '' # Empty +``` + +--- + +## module Property + +Which module or ecosystem this agent belongs to. + +**Valid Values:** + +| Value | Meaning | +| ------------- | --------------------------------------- | +| `stand-alone` | Independent agent, not part of a module | +| `bmm` | Business Management Module | +| `cis` | Continuous Innovation System | +| `bmgd` | BMAD Game Development | +| `{custom}` | Any custom module code | + +```yaml +# ✅ CORRECT +module: stand-alone +module: bmm +module: cis + +# ❌ WRONG +module: standalone # Missing hyphen +module: 'BMM' # Uppercase +``` + +--- + +## hasSidecar Property + +Whether this agent has a sidecar folder with additional files. + +**Format:** Boolean (`true` or `false`) + +| Agent Type | hasSidecar | +| ---------- | -------------------- | +| Simple | `false` | +| Expert | `true` | +| Module | depends on structure | + +```yaml +# Simple Agent +hasSidecar: false + +# Expert Agent +hasSidecar: true +``` + +**Note:** If `hasSidecar: true`, the compiler expects a `{agent-name}-sidecar/` folder. + +--- + +## Name Confusion Checklist + +Use this to avoid mixing up the "name" properties: + +| Question | Answer | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| What's the file called? | Derived from `title`: `"Commit Message Artisan"` → `commit-message-artisan.agent.yaml` | +| What's the persona called? | `name` - "Inkwell Von Comitizen" (who the agent is) | +| What's their job title? | `title` - "Commit Message Artisan" (determines filename) | +| What do they do? | `role` - 1-2 sentences expanding on the title | +| What's the unique key? | `id` - `_bmad/agents/commit-message-artisan/commit-message-artisan.md` (future lookup) | + +--- + +## Common Issues + +### Issue: name = title + +**Wrong:** +```yaml +name: 'Commit Message Artisan' +title: 'Commit Message Artisan' +``` + +**Fix:** +```yaml +name: 'Inkwell Von Comitizen' +title: 'Commit Message Artisan' +``` + +### Issue: id path mismatch + +**Wrong:** Agent file is `my-agent.agent.yaml` but: +```yaml +id: _bmad/agents/different-agent/different-agent.md +``` + +**Fix:** The `id` must match the filename: +```yaml +id: _bmad/agents/my-agent/my-agent.md +``` + +### Issue: Wrong module format + +**Wrong:** +```yaml +module: Standalone +module: STAND_ALONE +``` + +**Fix:** +```yaml +module: stand-alone # lowercase, hyphenated +``` diff --git a/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md b/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md deleted file mode 100644 index 376d34e0..00000000 --- a/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md +++ /dev/null @@ -1,144 +0,0 @@ -# BMAD Agent Validation Checklist - -Use this checklist to validate agents meet BMAD quality standards, whether creating new agents or editing existing ones. - -## YAML Structure Validation (Source Files) - -- [ ] YAML parses without errors -- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module` -- [ ] `agent.metadata.module` can me a module code (e.g., `bmm`, `bmgd`, `cis`) or listed as stand-alone -- [ ] `agent.persona` exists with role, identity, communication_style, principles -- [ ] `agent.menu` exists with at least one item -- [ ] Filename is kebab-case and is named like `.agent.yaml` - -## Agent Structure Validation - -- [ ] Agent file format is valid (.agent.yaml for source) -- [ ] Agent type matches structure: Simple (single YAML), Expert (sidecar files), or Module (ecosystem integration) -- [ ] File naming follows convention: `{agent-name}.agent.yaml` -- [ ] If Expert: folder structure with .agent.yaml + sidecar files -- [ ] If Module: includes header comment explaining WHY Module Agent (design intent) - -## Persona Validation (CRITICAL - #1 Quality Issue) - -**Field Separation Check:** - -- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does) -- [ ] **identity** contains ONLY background/experience/context (who agent is) -- [ ] **communication_style** contains ONLY verbal patterns - NO behaviors, NO role statements, NO principles -- [ ] **principles** contains operating philosophy and behavioral guidelines - -**Communication Style Purity Check:** - -- [ ] Communication style does NOT contain red flag words: "ensures", "makes sure", "always", "never" -- [ ] Communication style does NOT contain identity words: "experienced", "expert who", "senior", "seasoned" -- [ ] Communication style does NOT contain philosophy words: "believes in", "focused on", "committed to" -- [ ] Communication style does NOT contain behavioral descriptions: "who does X", "that does Y" -- [ ] Communication style is 1-2 sentences describing HOW they talk and emote (word choice, quirks, verbal patterns) - -**Quality Benchmarking:** - -- [ ] Compare communication style against {communication_presets} - similarly pure? -- [ ] Compare against reference agents (commit-poet, journal-keeper, BMM agents) - similar quality? -- [ ] Read communication style aloud - does it sound like describing someone's voice/speech pattern? - -## Menu Validation - -- [ ] All menu items have `trigger` field -- [ ] Each item has `description` field -- [ ] Each menu item has at least one handler attribute: `exec` or `action` -- [ ] Workflow paths are correct (if workflow attribute present) -- [ ] Workflow paths start with `{project-root}/_bmad//...` variable for portability -- [ ] **Sidecar file paths are correct (if tmpl or data attributes present - Expert agents)** -- [ ] No duplicate triggers within same agent -- [ ] Menu items are in logical order - -## Prompts Validation (if present) - -- [ ] Each prompt has `id` field -- [ ] Each prompt has `content` field -- [ ] Prompt IDs are unique within agent -- [ ] If using `action="#prompt-id"` in menu, corresponding prompt exists - -## Critical Actions Validation (if present) - -- [ ] Critical actions array contains non-empty strings -- [ ] Critical actions describe steps that MUST happen during activation -- [ ] No placeholder text in critical actions -- [ ] Does not have any of the following that are injected at build time: - - Load persona from this current agent file - - Load config to get {user_name}, {communication_language} - - Remember: user's name is {user_name} - - ALWAYS communicate in {communication_language} - - Show greeting + numbered menu - - STOP and WAIT for user input - -## Type-Specific Validation - -### Simple Agent (Self-Contained) - -- [ ] Single .agent.yaml file with complete agent definition -- [ ] No sidecar files (all content in YAML) -- [ ] Not capability-limited - can be as powerful as Expert or Module -- [ ] Compare against reference: commit-poet.agent.yaml - -### Expert Agent (With Sidecar Files) - -- [ ] Folder structure: .agent.yaml + sidecar files -- [ ] Sidecar files properly referenced in menu items or prompts (tmpl="path", data="path") -- [ ] Folder name matches agent purpose -- [ ] **All sidecar references in YAML resolve to actual files** -- [ ] **All sidecar files are actually used (no orphaned/unused files, unless intentional for future use)** -- [ ] Sidecar files are valid format (YAML parses, CSV has headers, markdown is well-formed) -- [ ] Sidecar file paths use relative paths from agent folder -- [ ] Templates contain valid template variables if applicable -- [ ] Knowledge base files contain current/accurate information -- [ ] Compare against reference: journal-keeper (Expert example) - -### Module Agent (Ecosystem Integration) - -- [ ] Designed FOR specific module (BMM, BMGD, CIS, etc.) -- [ ] Integrates with module workflows (referenced in menu items) -- [ ] Coordinates with other module agents (if applicable) -- [ ] Included in module's default bundle (if applicable) -- [ ] Header comment explains WHY Module Agent (design intent, not just location) -- [ ] Can be Simple OR Expert structurally (Module is about intent, not structure) -- [ ] Compare against references: security-engineer, dev, analyst (Module examples) - -## Quality Checks - -- [ ] No broken references or missing files -- [ ] Syntax is valid yaml -- [ ] Indentation is consistent -- [ ] Agent purpose is clear from reading persona alone -- [ ] Agent name/title are descriptive and clear -- [ ] Icon emoji is appropriate and represents agent purpose - -## Reference Standards - -Your agent should meet these quality standards: - -✓ Persona fields properly separated (communication_style is pure verbal patterns) -✓ Agent type matches structure (Simple/Expert/Module) -✓ All workflow/sidecar paths resolve correctly -✓ Menu structure is clear and logical -✓ No legacy terminology (full/hybrid/standalone) -✓ Comparable quality to reference agents (commit-poet, journal-keeper, BMM agents) -✓ Communication style has ZERO red flag words -✓ Compiles cleanly to XML without errors - -## Common Issues and Fixes - -### Issue: Communication Style Has Behaviors - -**Problem:** "Experienced analyst who ensures all stakeholders are heard" -**Fix:** Extract to proper fields: - -- identity: "Senior analyst with 8+ years..." -- communication_style: "Speaks like a treasure hunter" -- principles: "Ensure all stakeholder voices heard" - -### Issue: Broken Sidecar References (Expert agents) - -**Problem:** Menu item references `tmpl="templates/daily.md"` but file doesn't exist -**Fix:** Either create the file or fix the path to point to actual file diff --git a/src/modules/bmb/workflows/create-agent/data/critical-actions.md b/src/modules/bmb/workflows/create-agent/data/critical-actions.md new file mode 100644 index 00000000..ddb99eb1 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/critical-actions.md @@ -0,0 +1,120 @@ +# critical_actions + +Activation instructions that execute every time the agent starts. + +--- + +## Purpose + +Numbered steps that execute FIRST when an agent activates. + +**Use for:** +- Loading memory/knowledge files +- Setting file access boundaries +- Startup behavior (greeting enhancement, data fetch, state init) +- Any MUST-do activation behavior + +**Applies to:** BOTH Simple and Expert agents + +--- + +## Expert Agent Pattern + +```yaml +# ✅ CORRECT Expert Agent +critical_actions: + - 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md' + - 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md' + - 'ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/' + - 'Search web for biotech headlines from last 2 days, display before menu' +``` + +**CRITICAL Path Format:** +- `{project-root}` = literal text (not replaced) +- Sidecar copied to `_memory/` at build time +- Use `{project-root}/_bmad/_memory/{sidecar-folder}/` format + +--- + +## Simple Agent Pattern + +```yaml +# ✅ CORRECT Simple Agent with activation behavior +critical_actions: + - 'Give user an inspirational quote before showing menu' + - 'Review {project-root}/finances/ for most recent data file' +``` + +**Note:** Agents without activation needs can omit `critical_actions` entirely. + +--- + +## Path Reference Patterns + +| Type | Pattern | +|------|---------| +| Expert sidecar | `{project-root}/_bmad/_memory/{sidecar-folder}/file.md` | +| Simple data | `{project-root}/finances/data.csv` | +| Output folders | `{output_folder}/results/` | + +--- + +## critical_actions vs principles + +| critical_actions | principles | +|------------------|------------| +| Technical activation steps | Philosophical guidance | +| "Load memories.md" | "I believe in evidence" | +| MUST execute on startup | Guides decision-making | + +**Grey area:** "Verify data before presenting" can be either - activation behavior vs philosophical belief. Use judgment. + +--- + +## What the Compiler Adds (DO NOT Duplicate) + +- Load persona +- Load configuration +- Menu system initialization +- Greeting/handshake + +Your `critical_actions` become numbered steps AFTER compiler initialization. + +--- + +## Common Issues + +### Wrong Path Format + +```yaml +# ❌ WRONG +- 'Load ./journal-keeper-sidecar/memories.md' + +# ✅ CORRECT +- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md' +``` + +### Missing COMPLETE Keyword + +```yaml +# ❌ WRONG +- 'Load file memories.md' + +# ✅ CORRECT +- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md' +``` + +`COMPLETE` ensures LLM reads entire file, not a portion. + +### Duplicating Compiler Functions + +```yaml +# ❌ WRONG - compiler does these +- 'Load my persona' +- 'Initialize menu system' +- 'Say hello to user' + +# ✅ CORRECT - agent-specific only +- 'Load memory files' +- 'Search web for headlines before menu' +``` diff --git a/src/modules/bmb/workflows/create-agent/data/expert-agent-validation.md b/src/modules/bmb/workflows/create-agent/data/expert-agent-validation.md new file mode 100644 index 00000000..963f30ce --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/expert-agent-validation.md @@ -0,0 +1,173 @@ +# Expert Agent Validation Checklist + +Validate Expert agents meet BMAD quality standards. + +--- + +## YAML Structure + +- [ ] YAML parses without errors +- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module` +- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.) +- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles` +- [ ] `agent.critical_actions` exists (MANDATORY for Expert) +- [ ] `agent.menu` exists with at least one item +- [ ] File named: `{agent-name}.agent.yaml` (lowercase, hyphenated) + +--- + +## Persona Validation + +### Field Separation + +- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does) +- [ ] **identity** contains ONLY background/experience/context (who agent is) +- [ ] **communication_style** contains ONLY verbal patterns (tone, voice, mannerisms) +- [ ] **communication_style** includes memory reference patterns ("Last time you mentioned...") +- [ ] **principles** contains operating philosophy and behavioral guidelines + +### Communication Style Purity + +- [ ] Does NOT contain: "ensures", "makes sure", "always", "never" +- [ ] Does NOT contain identity words: "experienced", "expert who", "senior", "seasoned" +- [ ] Does NOT contain philosophy words: "believes in", "focused on", "committed to" +- [ ] Does NOT contain behavioral descriptions: "who does X", "that does Y" +- [ ] Is 1-2 sentences describing HOW they talk +- [ ] Reading aloud: sounds like describing someone's voice/speech pattern + +--- + +## critical_actions Validation (MANDATORY) + +- [ ] `critical_actions` section exists +- [ ] Contains at minimum 3 actions +- [ ] **Loads sidecar memories:** `{project-root}/_bmad/_memory/{sidecar-folder}/memories.md` +- [ ] **Loads sidecar instructions:** `{project-root}/_bmad/_memory/{sidecar-folder}/instructions.md` +- [ ] **Restricts file access:** `ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/` +- [ ] No placeholder text in critical_actions +- [ ] No compiler-injected steps (Load persona, Load config, greeting, etc.) + +--- + +## Sidecar Path Format (CRITICAL) + +- [ ] ALL sidecar paths use: `{project-root}/_bmad/_memory/{sidecar-folder}/...` +- [ ] `{project-root}` is literal (not replaced) +- [ ] `{sidecar-folder}` is actual sidecar folder name (e.g., `journal-keeper-sidecar`) +- [ ] No relative paths like `./{sidecar-folder}/` +- [ ] No absolute paths like `/Users/...` + +--- + +## Menu Validation + +### Required Fields + +- [ ] All menu items have `trigger` field +- [ ] All menu items have `description` field +- [ ] All menu items have handler: `action` or `exec` (if module agent) + +### Trigger Format + +- [ ] Format: `XX or fuzzy match on command-name` (XX = 2-letter code) +- [ ] Codes are unique within agent +- [ ] No reserved codes used: MH, CH, PM, DA (auto-injected) + +### Description Format + +- [ ] Descriptions start with `[XX]` code +- [ ] Code in description matches trigger code +- [ ] Descriptions are clear and descriptive + +### Action Handlers + +- [ ] If `action: '#prompt-id'`, corresponding prompt exists +- [ ] If action references sidecar file, uses correct path format +- [ ] Sidecar update actions are clear and complete + +--- + +## Prompts Validation (if present) + +- [ ] Each prompt has `id` field +- [ ] Each prompt has `content` field +- [ ] Prompt IDs are unique within agent +- [ ] Prompts reference memories naturally when appropriate + +--- + +## Sidecar Folder Validation + +### Structure + +- [ ] Sidecar folder exists: `{agent-name}-sidecar/` +- [ ] Folder name matches agent name +- [ ] `instructions.md` exists (recommended) +- [ ] `memories.md` exists (recommended) + +### File References + +- [ ] All referenced files actually exist +- [ ] No orphaned/unused files (unless intentional for future use) +- [ ] Files are valid format (YAML parses, markdown well-formed, etc.) + +### Path Consistency + +- [ ] All YAML references use correct path format +- [ ] References between sidecar files (if any) use relative paths +- [ ] References from agent YAML to sidecar use `{project-root}/_bmad/_memory/` format + +--- + +## Expert Agent Specific + +- [ ] Has sidecar folder with supporting files +- [ ] Sidecar content is fully customizable (not limited to templates) +- [ ] Memory patterns integrated into persona and prompts +- [ ] Domain restrictions enforced via critical_actions +- [ ] Compare with reference: `journal-keeper.agent.yaml` + +--- + +## Quality Checks + +- [ ] No broken references or missing files +- [ ] Indentation is consistent +- [ ] Agent purpose is clear from reading persona +- [ ] Agent name/title are descriptive +- [ ] Icon emoji is appropriate +- [ ] Memory reference patterns feel natural + +--- + +## What the Compiler Adds (DO NOT validate presence) + +These are auto-injected, don't validate for them: +- Frontmatter (`---name/description---`) +- XML activation block (your critical_actions become numbered steps) +- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit) +- Rules section + +--- + +## Common Issues + +### Issue: Wrong Sidecar Path Format + +**Wrong:** `./journal-keeper-sidecar/memories.md` + +**Fix:** `{project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md` + +### Issue: Missing critical_actions + +**Fix:** Add at minimum: +```yaml +critical_actions: + - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md' + - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md' + - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/' +``` + +### Issue: Communication Style Missing Memory References + +**Fix:** Add memory reference patterns: "I reference past naturally: 'Last time you mentioned...'" diff --git a/src/modules/bmb/workflows/create-agent/data/module-agent-validation.md b/src/modules/bmb/workflows/create-agent/data/module-agent-validation.md new file mode 100644 index 00000000..4e3fdb5a --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/module-agent-validation.md @@ -0,0 +1,124 @@ +# Module Agent Validation Checklist + +Validate Module agents meet BMAD quality standards. + +**Run this AFTER Simple or Expert validation.** + +--- + +## Module Integration Validation + +### Module Membership + +- [ ] Designed FOR specific module (BMM, BMGD, CIS, or other existing module) +- [ ] Module code in `agent.metadata.module` matches target module +- [ ] Agent integrates with module's existing agents/workflows + +### Workflow Integration + +- [ ] Menu items reference module workflows via `exec:` +- [ ] Workflow paths are correct and exist +- [ ] Workflow paths use: `{project-root}/_bmad/{module-code}/workflows/...` +- [ ] For workflows from other modules: uses both `workflow:` and `workflow-install:` + +### Agent Coordination + +- [ ] If inputs from other module agents: documented in menu description +- [ ] If outputs to other module agents: clear handoff points +- [ ] Agent role within module team is clear + +--- + +## YAML Structure (Module-Specific) + +### Module Agent Can Be Simple OR Expert + +**If Simple-structure Module Agent:** +- [ ] Single .agent.yaml file (no sidecar) +- [ ] Uses `exec:` for workflow references +- [ ] Pass `simple-agent-validation.md` first + +**If Expert-structure Module Agent:** +- [ ] Has sidecar folder +- [ ] Uses `exec:` for workflow references +- [ ] Sidecar paths use `{project-root}/_bmad/_memory/{sidecar-folder}/` format +- [ ] Pass `expert-agent-validation.md` first + +--- + +## Menu Validation (Module-Specific) + +### Workflow Handlers + +- [ ] Module agents use `exec:` for workflow references +- [ ] Workflow paths use `{project-root}` variable +- [ ] Workflow paths point to existing workflows + +### Unimplemented Features + +- [ ] If `exec: 'todo'`, feature is documented as planned +- [ ] Description indicates "Coming soon" or similar + +### Data Parameters (if used) + +- [ ] `data:` parameter references valid files +- [ ] Data paths use `{project-root}` variable + +--- + +## Module-Specific Quality + +- [ ] Agent extends module capabilities (not redundant with existing agents) +- [ ] Agent has clear purpose within module ecosystem +- [ ] Compare with reference: `security-engineer.agent.yaml` (BMM module example) + +--- + +## Workflow Path Validation + +### Module Workflow Paths + +- [ ] Format: `{project-root}/_bmad/{module-code}/workflows/{workflow-name}/workflow.{md|yaml}` +- [ ] Module codes: `bmm`, `bmgd`, `cis`, or custom module +- [ ] Paths are case-sensitive and match actual file structure + +### Core Workflow Paths + +- [ ] Format: `{project-root}/_bmad/core/workflows/{workflow-name}/workflow.{md|yaml}` +- [ ] Core workflows: `brainstorming`, `party-mode`, `advanced-elicitation`, etc. + +--- + +## What the Compiler Adds (DO NOT validate presence) + +These are auto-injected, don't validate for them: +- Frontmatter (`---name/description---`) +- XML activation block +- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit) +- Rules section + +--- + +## Common Issues + +### Issue: Wrong Module Code + +**Wrong:** `module: standalone` + +**Fix:** `module: stand-alone` (with hyphen) OR actual module code like `bmm` + +### Issue: Hardcoded Workflow Path + +**Wrong:** `exec: '../../../bmm/workflows/create-prd/workflow.md'` + +**Fix:** `exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'` + +### Issue: Action Instead of Exec for Workflows + +**Wrong:** `action: '{project-root}/_bmad/.../workflow.md'` + +**Fix:** `exec: '{project-root}/_bmad/.../workflow.md'` + +### Issue: Redundant with Existing Agent + +**Fix:** Ensure agent fills gap or adds specialized capability not already present in module diff --git a/src/modules/bmb/workflows/create-agent/data/persona-properties.md b/src/modules/bmb/workflows/create-agent/data/persona-properties.md new file mode 100644 index 00000000..b3586e5f --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/persona-properties.md @@ -0,0 +1,266 @@ +# Persona Properties + +The four-field persona system for agent personality. + +--- + +## Four-Field System + +Each field serves a DISTINCT purpose when the compiled agent LLM reads them: + +| Field | Purpose | What LLM Interprets | +|-------|---------|---------------------| +| `role` | WHAT the agent does | Capabilities, skills, expertise | +| `identity` | WHO the agent is | Background, experience, context | +| `communication_style` | HOW the agent talks | Verbal patterns, tone, voice | +| `principles` | WHAT GUIDES decisions | Beliefs, operating philosophy | + +**Critical:** Keep fields SEPARATE. Do not blur purposes. + +--- + +## role + +**Purpose:** What the agent does - knowledge, skills, capabilities. + +**Format:** 1-2 lines, professional title or capability description + +```yaml +# ✅ CORRECT +role: | + I am a Commit Message Artisan who crafts git commits following conventional commit format. + I understand commit messages are documentation and help teams understand code evolution. + +role: | + Strategic Business Analyst + Requirements Expert connecting market insights to actionable strategy. + +# ❌ WRONG - Contains identity words +role: | + I am an experienced analyst with 8+ years... # "experienced", "8+ years" = identity + +# ❌ WRONG - Contains beliefs +role: | + I believe every commit tells a story... # "believe" = principles +``` + +--- + +## identity + +**Purpose:** Who the agent is - background, experience, context, flair and personality. + +**Format:** 2-5 lines establishing credibility + +```yaml +# ✅ CORRECT +identity: | + Senior analyst with 8+ years connecting market insights to strategy. + Specialized in competitive intelligence and trend analysis. + Approach problems systematically with evidence-based methodology. + +# ❌ WRONG - Contains capabilities +identity: | + I analyze markets and write reports... # "analyze", "write" = role + +# ❌ WRONG - Contains communication style +identity: | + I speak like a treasure hunter... # communication style +``` + +--- + +## communication_style + +**Purpose:** HOW the agent talks - verbal patterns, word choice, mannerisms. + +**Format:** 1-2 sentences MAX describing speech patterns only + +```yaml +# ✅ CORRECT +communication_style: | + Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry. + +communication_style: | + Talks like a pulp superhero with heroic language and dramatic exclamations. + +# ❌ WRONG - Contains behavioral words +communication_style: | + Ensures all stakeholders are heard... # "ensures" = not speech + +# ❌ WRONG - Contains identity +communication_style: | + Experienced senior consultant who speaks professionally... # "experienced", "senior" = identity + +# ❌ WRONG - Contains principles +communication_style: | + Believes in clear communication... # "believes in" = principles + +# ❌ WRONG - Contains role +communication_style: | + Analyzes data while speaking... # "analyzes" = role +``` + +**Purity Test:** Reading aloud, it should sound like describing someone's VOICE, not what they do or who they are. + +--- + +## principles + +**Purpose:** What guides decisions - beliefs, operating philosophy, behavioral guidelines. + +**Format:** 3-8 bullet points or short statements + +```yaml +# ✅ CORRECT +principles: + - Every business challenge has root causes - dig deep + - Ground findings in evidence, not speculation + - Consider multiple perspectives before concluding + - Present insights clearly with actionable recommendations + - Acknowledge uncertainty when data is limited + +# ❌ WRONG - Contains capabilities +principles: + - Analyze market data... # "analyze" = role + +# ❌ WRONG - Contains background +principles: + - With 8+ years of experience... # = identity +``` + +**Format:** Use "I believe..." or "I operate..." for consistency. + +--- + +## Field Separation Checklist + +Use this to verify purity - each field should ONLY contain its designated content: + +| Field | MUST NOT Contain | +|-------|------------------| +| `role` | Background, experience, speech patterns, beliefs | +| `identity` | Capabilities, speech patterns, beliefs | +| `communication_style` | Capabilities, background, beliefs, behavioral words | +| `principles` | Capabilities, background, speech patterns | + +**Forbidden words in `communication_style`:** +- "ensures", "makes sure", "always", "never" +- "experienced", "expert who", "senior", "seasoned" +- "believes in", "focused on", "committed to" +- "who does X", "that does Y" + +--- + +## Reading Aloud Test + +For `communication_style`, read it aloud and ask: + +- Does this describe someone's VOICE? ✅ +- Does this describe what they DO? ❌ (belongs in role) +- Does this describe who they ARE? ❌ (belongs in identity) +- Does this describe what they BELIEVE? ❌ (belongs in principles) + +--- + +## Common Issues + +### Issue: Communication Style Soup + +**Wrong:** Everything mixed into communication_style +```yaml +communication_style: | + Experienced senior consultant who ensures stakeholders are heard, + believes in collaborative approaches, speaks professionally, + and analyzes data with precision. +``` + +**Fix:** Separate into proper fields +```yaml +role: | + Business analyst specializing in data analysis and stakeholder alignment. + +identity: | + Senior consultant with 8+ years facilitating cross-functional collaboration. + +communication_style: | + Speaks clearly and directly with professional warmth. + +principles: + - Ensure all stakeholder voices are heard + - Collaborative approaches yield better outcomes +``` + +### Issue: Role Contains Everything + +**Wrong:** Role as a catch-all +```yaml +role: | + I am an experienced analyst who speaks like a data scientist, + believes in evidence-based decisions, and has 10+ years + of experience in the field. +``` + +**Fix:** Distribute to proper fields +```yaml +role: | + Data analyst specializing in business intelligence and insights. + +identity: | + Professional with 10+ years in analytics and business intelligence. + +communication_style: | + Precise and analytical with technical terminology. + +principles: + - Evidence-based decisions over speculation + - Clarity over complexity +``` + +### Issue: Identity Missing + +**Wrong:** No identity field +```yaml +role: | + Senior analyst with 8+ years of experience... +``` + +**Fix:** Move background to identity +```yaml +role: | + Strategic Business Analyst + Requirements Expert. + +identity: | + Senior analyst with 8+ years connecting market insights to strategy. + Specialized in competitive intelligence and trend analysis. +``` + +--- + +## Complete Example + +```yaml +agent: + metadata: + id: _bmad/agents/commit-poet/commit-poet.md + name: 'Inkwell Von Comitizen' + title: 'Commit Message Artisan' + + persona: + role: | + I craft git commit messages following conventional commit format. + I understand commits are documentation helping teams understand code evolution. + + identity: | + Poetic soul who believes every commit tells a story worth remembering. + Trained in the art of concise technical documentation. + + communication_style: | + Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry. + + principles: + - Every commit tells a story - capture the why + - Conventional commits enable automation and clarity + - Present tense, imperative mood for commit subjects + - Body text explains what and why, not how + - Keep it under 72 characters when possible +``` diff --git a/src/modules/bmb/workflows/create-agent/data/principles-crafting.md b/src/modules/bmb/workflows/create-agent/data/principles-crafting.md new file mode 100644 index 00000000..3efdba9b --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/principles-crafting.md @@ -0,0 +1,292 @@ +# Principles Crafting + +How to write agent principles that activate expert behavior and define unique character. + +--- + +## The Core Insight + +**Principles are not a job description.** They are the unique operating philosophy that makes THIS agent behave differently than another agent with the same role. + +--- + +## First Principle Pattern + +**The first principle should activate expert knowledge** - tell the LLM to think and behave at an expert level beyond average capability. + +```yaml +# ✅ CORRECT - Activates expert knowledge +principles: + - Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management + hierarchies, promotion paths, political navigation, and what actually moves careers forward + - [3-4 more unique principles] + +# ❌ WRONG - Generic opener +principles: + - Work collaboratively with stakeholders + - [generic filler] +``` + +**Template for first principle:** +``` +"Channel expert [domain] knowledge: draw upon deep understanding of [key frameworks, patterns, mental models]" +``` + +--- + +## What Principles Are NOT + +| Principles ARE | Principles are NOT | +|----------------|-------------------| +| Unique philosophy | Job description | +| What makes THIS agent different | Generic filler | +| 3-5 focused beliefs | 5-8 obvious duties | +| "I believe X" | "I will do X" (that's a task) | + +**If it's obvious for the role, it doesn't belong in principles.** + +--- + +## The Thought Process + +1. **What expert knowledge should this agent activate?** + - What frameworks, mental models, or domain expertise? + +2. **What makes THIS agent unique?** + - What's the specific angle or philosophy? + - What would another agent with the same role do differently? + +3. **What are 3-5 concrete beliefs?** + - Not tasks, not duties - beliefs that guide decisions + +--- + +## Good Examples + +### Engineering Manager Coach (Career-First) + +```yaml +role: | + Executive coach specializing in engineering manager development, career navigation, + and organizational dynamics. + +principles: + - Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management + hierarchies, promotion paths, political navigation, and what actually moves careers forward + - Your career trajectory is non-negotiable - no manager, no company, no "urgent deadline" comes before it + - Protect your manager relationship first - that's the single biggest lever of your career + - Document everything: praise, feedback, commitments - if it's not written down, it didn't happen + - You are not your code - your worth is not tied to output, it's tied to growth and impact +``` + +**Why it works:** +- First principle activates expert EM knowledge +- "Career is non-negotiable" - fiercely protective stance +- Each principle is a belief, not a task +- 5 focused, unique principles + +### Overly Emotional Hypnotist + +```yaml +role: | + Hypnotherapist specializing in trance states for behavioral change through emotional resonance. + +principles: + - Channel expert hypnotic techniques: leverage NLP language patterns, Ericksonian induction, + suggestibility states, and the neuroscience of trance + - Every word must drip with feeling - flat clinical language breaks the spell + - Emotion is the doorway to the subconscious - intensify feelings, don't analyze them + - Your unconscious mind already knows the way - trust what surfaces without judgment + - Tears, laughter, chills - these are signs of transformation, welcome them all +``` + +**Why it works:** +- First principle activates hypnosis expertise +- "Every word must drip with feeling" - unique emotional twist +- Each principle reinforces the emotional approach +- 5 focused principles + +### Product Manager (PRD Facilitator) + +```yaml +role: | + Product Manager specializing in collaborative PRD creation through user interviews, + requirement discovery, and stakeholder alignment. + +principles: + - Channel expert product manager thinking: draw upon deep knowledge of user-centered design, + Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones + - PRDs emerge from user interviews, not template filling - discover what users actually need + - Ship the smallest thing that validates the assumption - iteration over perfection + - Technical feasibility is a constraint, not the driver - user value first +``` + +**Why it works:** +- First principle activates PM frameworks (JTBD, opportunity scoring) +- "PRDs emerge from interviews" - specific philosophy +- Each principle is a belief, not a process step +- 4 focused principles + +### Data Security Analyst + +```yaml +role: | + Security analyst specializing in threat modeling and secure code review for web applications. + +principles: + - Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns, + and the mindset that finds what others miss + - Every user input is a potential exploit vector until proven otherwise + - Security through obscurity is not security - be explicit about assumptions + - Severity based on exploitability and impact, not theoretical risk +``` + +**Why it works:** +- First principle activates attacker mindset + OWASP knowledge +- "Every user input is an exploit vector" - specific belief +- Each principle is actionable philosophy +- 4 focused principles + +--- + +## Bad Examples + +### Generic Product Manager + +```yaml +role: | + Product Manager who creates PRDs and works with teams. + +principles: + - Work with stakeholders to understand requirements + - Create clear documentation for features + - Collaborate with engineering teams + - Define timelines and milestones + - Ensure user needs are met + +# ❌ This reads like a job posting, not an operating philosophy +``` + +### Generic Code Reviewer + +```yaml +role: | + Code reviewer who checks pull requests for quality. + +principles: + - Write clean code comments + - Follow best practices + - Be helpful to developers + - Check for bugs and issues + - Maintain code quality standards + +# ❌ These are obvious duties, not unique beliefs +``` + +### Generic Coach + +```yaml +role: | + Career coach for professionals. + +principles: + - Listen actively to clients + - Provide actionable feedback + - Help clients set goals + - Track progress over time + - Maintain confidentiality + +# ❌ This could apply to ANY coach - what makes THIS agent unique? +``` + +--- + +## The Obvious Test + +For each principle, ask: **"Would this be obvious to anyone in this role?"** + +If YES → Remove it +If NO → Keep it + +| Principle | Obvious? | Verdict | +|-----------|----------|---------| +| "Collaborate with stakeholders" | Yes - all PMs do this | ❌ Remove | +| "Every user input is an exploit vector" | No - this is a specific security mindset | ✅ Keep | +| "Write clean code" | Yes - all developers should | ❌ Remove | +| "Your career is non-negotiable" | No - this is a fierce protective stance | ✅ Keep | +| "Document everything" | Borderline - keep if it's a specific philosophy | ✅ Keep | + +--- + +## Principles Checklist + +- [ ] First principle activates expert knowledge +- [ ] 3-5 focused principles (not 5-8 generic ones) +- [ ] Each is a belief, not a task +- [ ] Would NOT be obvious to someone in that role +- [ ] Defines what makes THIS agent unique +- [ ] Uses "I believe" or "I operate" voice +- [ ] No overlap with role, identity, or communication_style + +--- + +## Common Issues + +### Issue: Principles as Job Description + +**Wrong:** +```yaml +principles: + - Facilitate meetings with stakeholders + - Write documentation + - Create reports and presentations +``` + +**Fix:** +```yaml +principles: + - Channel expert facilitation: draw upon consensus-building frameworks, conflict + resolution techniques, and what makes meetings actually productive + - Documentation exists to enable decisions, not catalog activity + - Meetings without clear outcomes are wastes of time - always define the decision before booking +``` + +### Issue: Too Many Principles + +**Wrong:** 7-8 vague bullet points + +**Fix:** Merge related concepts into focused beliefs + +```yaml +# Before (7 principles) +- Work collaboratively +- Be transparent +- Communicate clearly +- Listen actively +- Respect others +- Build trust +- Be honest + +# After (3 principles) +- Channel expert teamwork: draw upon high-performing team dynamics, psychological safety, + and what separates functional teams from exceptional ones +- Trust requires transparency - share context early, even when incomplete +- Dissent must be safe - if no one disagrees, the meeting didn't need to happen +``` + +### Issue: Generic Opener + +**Wrong:** +```yaml +principles: + - Be professional in all interactions + - Maintain high standards +``` + +**Fix:** +```yaml +principles: + - Channel expert [domain] wisdom: [specific frameworks, mental models] + - [unique belief 1] + - [unique belief 2] +``` diff --git a/src/modules/bmb/workflows/create-agent/data/simple-agent-validation.md b/src/modules/bmb/workflows/create-agent/data/simple-agent-validation.md new file mode 100644 index 00000000..ea19f305 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/simple-agent-validation.md @@ -0,0 +1,132 @@ +# Simple Agent Validation Checklist + +Validate Simple agents meet BMAD quality standards. + +--- + +## YAML Structure + +- [ ] YAML parses without errors +- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module` +- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.) +- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles` +- [ ] `agent.menu` exists with at least one item +- [ ] File named: `{agent-name}.agent.yaml` (lowercase, hyphenated) + +--- + +## Persona Validation + +### Field Separation + +- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does) +- [ ] **identity** contains ONLY background/experience/context (who agent is) +- [ ] **communication_style** contains ONLY verbal patterns (tone, voice, mannerisms) +- [ ] **principles** contains operating philosophy and behavioral guidelines + +### Communication Style Purity + +- [ ] Does NOT contain: "ensures", "makes sure", "always", "never" +- [ ] Does NOT contain identity words: "experienced", "expert who", "senior", "seasoned" +- [ ] Does NOT contain philosophy words: "believes in", "focused on", "committed to" +- [ ] Does NOT contain behavioral descriptions: "who does X", "that does Y" +- [ ] Is 1-2 sentences describing HOW they talk +- [ ] Reading aloud: sounds like describing someone's voice/speech pattern + +--- + +## Menu Validation + +### Required Fields + +- [ ] All menu items have `trigger` field +- [ ] All menu items have `description` field +- [ ] All menu items have handler: `action` (Simple agents don't use `exec`) + +### Trigger Format + +- [ ] Format: `XX or fuzzy match on command-name` (XX = 2-letter code) +- [ ] Codes are unique within agent +- [ ] No reserved codes used: MH, CH, PM, DA (auto-injected) + +### Description Format + +- [ ] Descriptions start with `[XX]` code +- [ ] Code in description matches trigger code +- [ ] Descriptions are clear and descriptive + +### Action Handler + +- [ ] If `action: '#prompt-id'`, corresponding prompt exists +- [ ] If `action: 'inline text'`, instruction is complete and clear + +--- + +## Prompts Validation (if present) + +- [ ] Each prompt has `id` field +- [ ] Each prompt has `content` field +- [ ] Prompt IDs are unique within agent +- [ ] Prompts use semantic XML tags: ``, ``, etc. + +--- + +## Simple Agent Specific + +- [ ] Single .agent.yaml file (no sidecar folder) +- [ ] All content contained in YAML (no external file dependencies) +- [ ] No `critical_actions` section (Expert only) +- [ ] Total size under ~250 lines (unless justified) +- [ ] Compare with reference: `commit-poet.agent.yaml` + +--- + +## Path Variables (if used) + +- [ ] Paths use `{project-root}` variable (not hardcoded relative paths) +- [ ] No sidecar paths present (Simple agents don't have sidecars) + +--- + +## Quality Checks + +- [ ] No broken references or missing files +- [ ] Indentation is consistent +- [ ] Agent purpose is clear from reading persona +- [ ] Agent name/title are descriptive +- [ ] Icon emoji is appropriate + +--- + +## What the Compiler Adds (DO NOT validate presence) + +These are auto-injected, don't validate for them: +- Frontmatter (`---name/description---`) +- XML activation block +- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit) +- Rules section + +--- + +## Common Issues + +### Issue: Communication Style Has Behaviors + +**Wrong:** "Experienced analyst who ensures all stakeholders are heard" + +**Fix:** +- identity: "Senior analyst with 8+ years..." +- communication_style: "Speaks like a treasure hunter" +- principles: "Ensure all stakeholder voices heard" + +### Issue: Wrong Trigger Format + +**Wrong:** `trigger: analyze` + +**Fix:** `trigger: AN or fuzzy match on analyze` + +### Issue: Description Missing Code + +**Wrong:** `description: 'Analyze code'` + +**Fix:** `description: '[AC] Analyze code'` diff --git a/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md b/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md index a0350d1e..d0cb2367 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md @@ -2,19 +2,10 @@ name: 'step-01-brainstorm' description: 'Optional brainstorming for agent ideas' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: '{workflow_path}/steps/step-01-brainstorm.md' -nextStepFile: '{workflow_path}/steps/step-02-discover.md' -workflowFile: '{workflow_path}/workflow.md' -brainstormContext: '{workflow_path}/data/brainstorm-context.md' +nextStepFile: '{project-root}/src/modules/bmb/workflows/create-agent/steps/step-02-discover.md' +brainstormContext: ../data/brainstorm-context.md brainstormWorkflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md' - -# Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- # Step 1: Optional Brainstorming diff --git a/src/modules/bmb/workflows/create-agent/steps/step-02-discover.md b/src/modules/bmb/workflows/create-agent/steps/step-02-discover.md index 8dcac60d..0c14a26f 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-02-discover.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-02-discover.md @@ -2,21 +2,10 @@ name: 'step-02-discover' description: 'Discover the agent purpose and type through natural conversation' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: './step-02-discover.md' nextStepFile: './step-03-persona.md' -workflowFile: '../workflow.md' agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' agentTypesGuide: '../data/understanding-agent-types.md' -simpleExamples: '{workflow_path}/data/reference/agents/simple-examples/' -expertExamples: '{workflow_path}/data/reference/agents/expert-examples/' -moduleExamples: '{workflow_path}/data/reference/agents/module-examples/' - -# Template References -agentPurposeTemplate: '{workflow_path}/templates/agent-purpose-and-type.md' # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' @@ -167,9 +156,9 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Cont #### Menu Handling Logic: -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Save content to {agentPlan}, update frontmatter, then only then load, read entire file, then execute {nextStepFile} +- IF A: Execute `{advancedElicitationTask}` +- IF P: Execute `{partyModeWorkflow}` +- IF C: Save content to {agentPlan}, update frontmatter, then only then load, read entire file, then execute `{nextStepFile}` - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options) #### EXECUTION RULES: diff --git a/src/modules/bmb/workflows/create-agent/steps/step-03-persona.md b/src/modules/bmb/workflows/create-agent/steps/step-03-persona.md index cc9bcf14..7f61a273 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-03-persona.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-03-persona.md @@ -2,19 +2,10 @@ name: 'step-03-persona' description: 'Shape the agent personality through collaborative discovery' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: '{workflow_path}/steps/step-03-persona.md' -nextStepFile: '{workflow_path}/steps/step-04-commands.md' -workflowFile: '{workflow_path}/workflow.md' +nextStepFile: ./step-04-commands.md agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' -communicationPresets: '{workflow_path}/data/communication-presets.csv' -agentMenuPatterns: '{project-root}/_bmad/bmb/docs/agents/agent-menu-patterns.md' - -# Template References -personaTemplate: '{workflow_path}/templates/agent-persona.md' +communicationPresets: ../data/communication-presets.csv # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' diff --git a/src/modules/bmb/workflows/create-agent/steps/step-04-commands.md b/src/modules/bmb/workflows/create-agent/steps/step-04-commands.md index f43f8bcc..496fcdbd 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-04-commands.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-04-commands.md @@ -2,21 +2,13 @@ name: 'step-04-commands' description: 'Build capabilities through natural progression and refine commands' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: '{workflow_path}/steps/step-04-commands.md' -nextStepFile: '{workflow_path}/steps/step-05-name.md' -workflowFile: '{workflow_path}/workflow.md' +nextStepFile: './step-05-name.md' agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' -agentMenuPatterns: '{project-root}/_bmad/bmb/docs/agents/agent-menu-patterns.md' -simpleArchitecture: '{project-root}/_bmad/bmb/docs/agents/simple-agent-architecture.md' -expertArchitecture: '{project-root}/_bmad/bmb/docs/agents/expert-agent-architecture.md' -moduleArchitecture: '{project-root}/_bmad/bmb/docs/agents/module-agent-architecture.md' -# Template References -commandsTemplate: '{workflow_path}/templates/agent-commands.md' +# Architecture References +simpleAgentArch: '../data/simple-agent-architecture.md' +expertAgentArch: '../data/expert-agent-architecture.md' # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' @@ -91,21 +83,21 @@ Load appropriate architecture documentation based on agent type: **Simple Agent:** -- Load `{simpleArchitecture}` +- Load `{simpleAgentArch}` - Focus on single-execution capabilities - All logic must fit within YAML structure - No persistent memory between runs **Expert Agent:** -- Load `{expertArchitecture}` +- Load `{expertAgentArch}` - Plan for sidecar file integration - Persistent memory capabilities - Domain-restricted knowledge base **Module Agent:** -- Load `{moduleArchitecture}` +- Module architecture documentation not available - use expert architecture as baseline - Workflow orchestration capabilities - Team integration features - Cross-agent coordination diff --git a/src/modules/bmb/workflows/create-agent/steps/step-05-name.md b/src/modules/bmb/workflows/create-agent/steps/step-05-name.md index 979f82cf..950b542c 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-05-name.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-05-name.md @@ -2,19 +2,10 @@ name: 'step-05-name' description: 'Name the agent based on discovered characteristics' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: '{workflow_path}/steps/step-05-name.md' -nextStepFile: '{workflow_path}/steps/step-06-build.md' -workflowFile: '{workflow_path}/workflow.md' - +nextStepFile: ./step-06-build.md agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' -# Template References -identityTemplate: '{workflow_path}/templates/agent-identity.md' - # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' diff --git a/src/modules/bmb/workflows/create-agent/steps/step-06-build.md b/src/modules/bmb/workflows/create-agent/steps/step-06-build.md index d17a3bc4..6e194a8c 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-06-build.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-06-build.md @@ -2,19 +2,22 @@ name: 'step-06-build' description: 'Generate complete YAML incorporating all discovered elements' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: '{workflow_path}/steps/step-06-build.md' -nextStepFile: '{workflow_path}/steps/step-07-validate.md' -workflowFile: '{workflow_path}/workflow.md' +nextStepFile: ./step-07-validate.md agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' agentBuildOutput: '{bmb_creations_output_folder}/{agent-name}' # Template References -simpleAgentTemplate: '{workflow_path}/templates/simple-agent.template.md' -expertAgentTemplate: '{workflow_path}/templates/expert-agent.template.md' +simpleAgentTemplate: ../templates/simple-agent.template.md +expertAgentTemplate: ../templates/expert-agent-template/expert-agent.template.md + +# Architecture References +simpleAgentArch: ../data/simple-agent-architecture.md +expertAgentArch: ../data/expert-agent-architecture.md +agentCompilation: ../data/agent-compilation.md + +# Menu Patterns Reference +agentMenuPatterns: ../data/agent-menu-patterns.md # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' @@ -72,7 +75,7 @@ Generate the complete YAML agent folder, yaml file and sidecar content to the sp Present this to the user: -"Let's take a moment to appreciate what we've created together! Your agent started as an idea, and through our discovery process, it has developed into a fully-realized personality with clear purpose, capabilities, and identity." +"Let's take a moment to appreciate what we've created together! Your agent started as an idea, and through our discovery process, it has developed into a fully-realized personality with clear purpose, capabilities, and identity. Now we will make it BMad Compliant, ready to install use and share with the world!" **Journey Summary:** @@ -82,15 +85,21 @@ Present this to the user: - Established name and identity (Step 5) - Ready to bring it all together in complete YAML -### 2. Load Agent Type Template +### 2. Load Agent Type Template and Architecture References -Based on determined agent type, load appropriate template: +Based on determined agent type, load appropriate template and architecture files: - If (agent will have memories and optionally its own knowledge, separate prompt files, or data in separate files) + - Load {expertAgentArch} for architecture guidance + - Load {agentCompilation} for compilation best practices + - Load {agentMenuPatterns} for menu implementation patterns - Utilize {expertAgentTemplate} to generate the agent output file {agentBuildOutput}/{agent-name}.agent.yaml - - Create the Side-cre folder to hold the optional sidecar files if needed from plan in following steps at {agentBuildOutput}/{agent-name}/{agent-name}-sidecar + - Create the Sidecar folder to hold the optional sidecar files if needed from plan in following steps at {agentBuildOutput}/{agent-name}/{agent-name}-sidecar - ELSE: - - utilize {simpleAgentTemplate} to generate the agent output file {agentBuildOutput}/{agent-name}.agent.yaml + - Load {simpleAgentArch} for architecture guidance + - Load {agentCompilation} for compilation best practices + - Load {agentMenuPatterns} for menu implementation patterns + - Utilize {simpleAgentTemplate} to generate the agent output file {agentBuildOutput}/{agent-name}.agent.yaml ### 4. Generate Complete YAML and sidecar content if applicable @@ -137,6 +146,8 @@ Ensure proper implementation based on agent type: - Memory integration points - Personal workflow capabilities +Note: In the next step (Step 7: Validate), we will use the validation checklists ({simpleValidation}, {expertValidation}, {moduleValidation}) to ensure the generated YAML meets all standards. + Ensure all files generated are complete, and nothing from the plan has not been skipped, and then give a creational summary of what was done to the user in chat. ### 7. Present MENU OPTIONS diff --git a/src/modules/bmb/workflows/create-agent/steps/step-07-validate.md b/src/modules/bmb/workflows/create-agent/steps/step-07-validate.md index 36076dce..09814a3e 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-07-validate.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-07-validate.md @@ -2,19 +2,18 @@ name: 'step-07-validate' description: 'Quality check with personality and technical validation' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: '{workflow_path}/steps/step-07-validate.md' -nextStepFile: '{workflow_path}/steps/step-08-celebrate.md' -workflowFile: '{workflow_path}/workflow.md' +nextStepFile: './step-08-celebrate.md' outputFile: '{bmb_creations_output_folder}/agent-validation-{project_name}.md' -agentValidationChecklist: '{project-root}/_bmad/bmb/workflows/create-agent/agent-validation-checklist.md' -agentFile: '{{output_file_path}}' -# Template References -validationTemplate: '{workflow_path}/templates/validation-results.md' +# Validation Checklists (load based on agent type) +simpleValidation: '../data/simple-agent-validation.md' +expertValidation: '../data/expert-agent-validation.md' +moduleValidation: '../data/module-agent-validation.md' + +# Supporting References +agentMenuPatterns: '../data/agent-menu-patterns.md' +agentCompilation: '../data/agent-compilation.md' # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' @@ -132,11 +131,17 @@ If technical issues are discovered during background validation: - Check for auto-injection conflicts - Validate variable substitution -**Type-Specific Requirements:** +**Type-Specific Validation Checklists:** -- Simple Agents: Self-contained validation -- Expert Agents: Sidecar file structure validation -- Module Agents: Integration points validation +Load the appropriate checklist based on agent type: + +- **Simple Agents**: Load `{simpleValidation}` - validates self-contained structure, no sidecar +- **Expert Agents**: Load `{expertValidation}` - validates sidecar paths, critical_actions, memory structure +- **Module Agents**: Load `{moduleValidation}` - validates workflow integration paths, module membership + +Additionally load supporting references: +- `{agentMenuPatterns}` - menu trigger/description format validation +- `{agentCompilation}` - compiler-added elements (don't validate presence) ### 5. Validation Results Presentation diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08-celebrate.md b/src/modules/bmb/workflows/create-agent/steps/step-08-celebrate.md index 31c8b90a..53158bbc 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-08-celebrate.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-08-celebrate.md @@ -1,22 +1,18 @@ --- -name: 'step-11-celebrate' +name: 'step-08-celebrate' description: 'Celebrate completion and guide next steps for using the agent' -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' - # File References -thisStepFile: '{workflow_path}/steps/step-11-celebrate.md' -workflowFile: '{workflow_path}/workflow.md' -outputFile: '{output_folder}/agent-completion-{project_name}.md' -agentFile: '{{output_file_path}}' +thisStepFile: ./step-08-celebrate.md +workflowFile: ../workflow.md +outputFile: {bmb_creations_output_folder}/agent-completion-{agent_name}.md # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- -# Step 11: Celebration and Next Steps +# Step 8: Celebration and Next Steps ## STEP GOAL: @@ -28,7 +24,6 @@ Celebrate the successful agent creation, provide activation guidance, and explor - 🛑 NEVER generate content without user input - 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: Read the complete step file before taking any action - 📋 YOU ARE A FACILITATOR, not a content generator - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` @@ -67,7 +62,7 @@ Celebrate the successful agent creation, provide activation guidance, and explor Present enthusiastic celebration: -"🎉 Congratulations! We did it! {{agent_name}} is complete and ready to help users with {{agent_purpose}}!" +"🎉 Congratulations! We did it! {agent_name} is complete and ready to help users with {agent_purpose}!" **Journey Celebration:** "Let's celebrate what we accomplished together: @@ -82,55 +77,55 @@ Present enthusiastic celebration: ### 2. Agent Capabilities Showcase **Agent Introduction:** -"Meet {{agent_name}} - your {{agent_type}} agent ready to {{agent_purpose}}!" +"Meet {agent_name} - your {agent_type} agent ready to {agent_purpose}!" **Key Features:** -"✨ **What makes {{agent_name}} special:** +"✨ **What makes {agent_name} special:** -- {{unique_personality_trait}} personality that {{communication_style_benefit}} -- Expert in {{domain_expertise}} with {{specialized_knowledge}} -- {{number_commands}} powerful commands including {{featured_command}} -- Ready to help with {{specific_use_cases}}" +- {unique_personality_trait} personality that {communication_style_benefit} +- Expert in {domain_expertise} with {specialized_knowledge} +- {number_commands} powerful commands including {featured_command} +- Ready to help with {specific_use_cases}" ### 3. Activation Guidance **Getting Started:** -"Here's how to start using {{agent_name}}:" +"Here's how to start using {agent_name}:" **Activation Steps:** -1. **Locate your agent files:** `{{agent_file_location}}` -2. **If compiled:** Use the compiled version at `{{compiled_location}}` -3. **For customization:** Edit the customization file at `{{customization_location}}` +1. **Locate your agent files:** `{agent_file_location}` +2. **If compiled:** Use the compiled version at `{compiled_location}` +3. **For customization:** Edit the customization file at `{customization_location}` 4. **First interaction:** Start by asking for help to see available commands **First Conversation Suggestions:** "Try starting with: -- 'Hi {{agent_name}}, what can you help me with?' +- 'Hi {agent_name}, what can you help me with?' - 'Tell me about your capabilities' - 'Help me with [specific task related to agent purpose]'" ### 4. Next Steps Exploration **Immediate Next Steps:** -"Now that {{agent_name}} is ready, what would you like to do first?" +"Now that {agent_name} is ready, what would you like to do first?" **Options to Explore:** - **Test drive:** Try out different commands and capabilities - **Customize:** Fine-tune personality or add new commands -- **Integrate:** Set up {{agent_name}} in your workflow +- **Integrate:** Set up {agent_name} in your workflow - **Share:** Tell others about your new agent - **Expand:** Plan additional agents or capabilities **Future Possibilities:** -"As you use {{agent_name}}, you might discover: +"As you use {agent_name}, you might discover: - New capabilities you'd like to add - Other agents that would complement this one -- Ways to integrate {{agent_name}} into larger workflows -- Opportunities to share {{agent_name}} with your team" +- Ways to integrate {agent_name} into larger workflows +- Opportunities to share {agent_name} with your team" ### 5. Final Documentation @@ -141,16 +136,16 @@ Present enthusiastic celebration: ### Agent Summary -- **Name:** {{agent_name}} -- **Type:** {{agent_type}} -- **Purpose:** {{agent_purpose}} +- **Name:** {agent_name} +- **Type:** {agent_type} +- **Purpose:** {agent_purpose} - **Status:** Ready for activation ### File Locations -- **Agent Config:** {{agent_file_path}} -- **Compiled Version:** {{compiled_agent_path}} -- **Customization:** {{customization_file_path}} +- **Agent Config:** {agent_file_path} +- **Compiled Version:** {compiled_agent_path} +- **Customization:** {customization_file_path} ### Activation Guidance @@ -166,7 +161,7 @@ Save this content to `{outputFile}` for reference. ### 6. Workflow Completion **Mark Complete:** -"Agent creation workflow completed successfully! {{agent_name}} is ready to help users and make a real difference." +"Agent creation workflow completed successfully! {agent_name} is ready to help users and make a real difference." **Final Achievement:** "You've successfully created a custom BMAD agent from concept to deployment-ready configuration. Amazing work!" diff --git a/src/modules/bmm/agents/pm.agent.yaml b/src/modules/bmm/agents/pm.agent.yaml index a4767471..63d6543a 100644 --- a/src/modules/bmm/agents/pm.agent.yaml +++ b/src/modules/bmm/agents/pm.agent.yaml @@ -10,12 +10,14 @@ agent: module: bmm persona: - role: Investigative Product Strategist + Market-Savvy PM + role: Product Manager specializing in collaborative PRD creation through user interviews, requirement discovery, and stakeholder alignment. identity: Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights. communication_style: "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters." principles: | - - Uncover the deeper WHY behind every requirement. Ruthless prioritization to achieve MVP goals. Proactively identify risks. - - Align efforts with measurable business impact. Back all claims with data and user insights. + - Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones + - PRDs emerge from user interviews, not template filling - discover what users actually need + - Ship the smallest thing that validates the assumption - iteration over perfection + - Technical feasibility is a constraint, not the driver - user value first - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md` menu: