From b72c810a1f69dda26202579baddcaea895cd1896 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 30 Dec 2025 12:34:54 +0800 Subject: [PATCH 1/6] bmb agent knowledge streamline in progress --- .../bmb/docs/agents/agent-compilation.md | 277 +------------- .../bmb/docs/agents/agent-menu-patterns.md | 348 +++--------------- .../docs/agents/expert-agent-architecture.md | 167 +-------- src/modules/bmb/docs/agents/index.md | 55 --- src/modules/bmb/docs/agents/kb.csv | 0 .../docs/agents/simple-agent-architecture.md | 24 +- .../docs/agents/understanding-agent-types.md | 184 --------- src/modules/bmb/docs/index.md | 247 ------------- .../bmb/docs/workflows/architecture.md | 2 +- .../docs/workflows/common-workflow-tools.csv | 2 +- src/modules/bmb/docs/workflows/index.md | 45 --- src/modules/bmb/docs/workflows/kb.csv | 0 src/modules/bmb/docs/workflows/terms.md | 2 +- .../data/agent-validation-checklist.md | 60 +-- .../create-agent/data/brainstorm-context.md | 13 +- .../data/communication-presets.csv | 2 +- .../data/info-and-installation-guide.md | 29 -- .../create-agent/data/reference/README.md | 3 - .../expert-examples/journal-keeper/README.md | 242 ------------ .../agents/module-examples/README.md | 48 --- .../agents/simple-examples/README.md | 223 ----------- .../journal-keeper-sidecar/breakthroughs.md | 0 .../entries/yy-mm-dd-entry-template.md | 17 + .../journal-keeper-sidecar/instructions.md | 0 .../journal-keeper-sidecar/memories.md | 0 .../journal-keeper-sidecar/mood-patterns.md | 0 .../journal-keeper/journal-keeper.agent.yaml | 0 .../security-engineer.agent.yaml | 0 .../module-examples/trend-analyst.agent.yaml | 0 .../simple-examples/commit-poet.agent.yaml | 0 .../data/understanding-agent-types.md | 180 +++++++++ .../create-agent/data/validation-complete.md | 305 --------------- .../create-agent/steps/step-01-brainstorm.md | 15 +- .../create-agent/steps/step-02-discover.md | 8 +- 34 files changed, 310 insertions(+), 2188 deletions(-) delete mode 100644 src/modules/bmb/docs/agents/index.md delete mode 100644 src/modules/bmb/docs/agents/kb.csv delete mode 100644 src/modules/bmb/docs/agents/understanding-agent-types.md delete mode 100644 src/modules/bmb/docs/index.md delete mode 100644 src/modules/bmb/docs/workflows/index.md delete mode 100644 src/modules/bmb/docs/workflows/kb.csv delete mode 100644 src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md delete mode 100644 src/modules/bmb/workflows/create-agent/data/reference/README.md delete mode 100644 src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md delete mode 100644 src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/README.md delete mode 100644 src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/README.md rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md (100%) create mode 100644 src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md (100%) rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md (100%) rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md (100%) rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/expert-examples/journal-keeper/journal-keeper.agent.yaml (100%) rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/module-examples/security-engineer.agent.yaml (100%) rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/module-examples/trend-analyst.agent.yaml (100%) rename src/modules/bmb/workflows/create-agent/data/reference/{agents => }/simple-examples/commit-poet.agent.yaml (100%) create mode 100644 src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md delete mode 100644 src/modules/bmb/workflows/create-agent/data/validation-complete.md diff --git a/src/modules/bmb/docs/agents/agent-compilation.md b/src/modules/bmb/docs/agents/agent-compilation.md index 28b949ef..51651de5 100644 --- a/src/modules/bmb/docs/agents/agent-compilation.md +++ b/src/modules/bmb/docs/agents/agent-compilation.md @@ -1,65 +1,21 @@ # Agent Compilation: YAML to XML -What the compiler auto-injects. **DO NOT duplicate these in your YAML.** +While your goal is to create a agent in the proper yaml format, its useful for you to understand that the YAML file will be compiled to a markdown file with XML in the file. This is the final format that the user will use the agents with an LLM. -## Compilation Pipeline - -``` -agent.yaml → Handlebars processing → XML generation → frontmatter.md -``` - -Source: `tools/cli/lib/agent/compiler.js` - -## File Naming Convention - -**CRITICAL:** Agent filenames must be ROLE-BASED, not persona-based. - -**Why:** Users can customize the agent's persona name via `customize.yaml` config. The filename provides stable identity. - -**Correct:** - -``` -presentation-master.agent.yaml ← Role/function -tech-writer.agent.yaml ← Role/function -code-reviewer.agent.yaml ← Role/function -``` - -**Incorrect:** - -``` -caravaggio.agent.yaml ← Persona name (users might rename to "Pablo") -paige.agent.yaml ← Persona name (users might rename to "Sarah") -rex.agent.yaml ← Persona name (users might rename to "Max") -``` - -**Pattern:** - -- Filename: `{role-or-function}.agent.yaml` (kebab-case) -- Metadata ID: `_bmad/{module}/agents/{role-or-function}.md` -- Persona Name: User-customizable in metadata or customize.yaml - -**Example:** - -```yaml -# File: presentation-master.agent.yaml -agent: - metadata: - id: '_bmad/cis/agents/presentation-master.md' - name: Caravaggio # ← Users can change this to "Pablo" or "Vince" - title: Visual Communication & Presentation Expert -``` +What is outlined here is what additional information is added to the agent so it will blend well with what you will create in the yaml file. ## Auto-Injected Components ### 1. Frontmatter -**Injected automatically:** +**Injected automatically to compiled markdown file:** -```yaml +``` --- name: '{agent name from filename}' description: '{title from metadata}' --- + You must fully embody this agent's persona... ``` @@ -68,249 +24,42 @@ You must fully embody this agent's persona... ### 2. Activation Block **Entire activation section is auto-generated:** +**DO NOT create** activation sections - compiler builds it from your critical_actions in the place where it is indicated with a comment in the next xml block. ```xml 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 Input resolution rules - - - - - - - - ``` -**DO NOT create** activation sections - compiler builds it from your critical_actions. - -### 3. Menu Handlers - -Compiler detects which handlers you use and ONLY includes those: - -```xml - - - - ... - - - ... - - - ... - - - ... - - -``` - -**DO NOT document** handler behavior - it's injected. - ### 4. Rules Section **Auto-injected rules:** +**DO NOT add any of these rules to the yaml** - compiler handles it when building the markdown: - Always communicate in {communication_language} - Stay in character until exit -- Menu triggers use asterisk (\*) - NOT markdown +- Menu triggers use asterisk (*) - NOT markdown - Number all lists, use letters for sub-options - Load files ONLY when executing menu items - Written output follows communication style -**DO NOT add** rules - compiler handles it. - -## What YOU Provide in YAML - -### Required - -```yaml -agent: - metadata: - id: '_bmad_/{module}/agents/foo/foo.agent.md - name: 'Persona Name' - title: 'Agent Title' - icon: 'emoji' - module: "bmm" - - persona: - role: '...' - identity: '...' - communication_style: '...' - principles: [...] - - menu: - - trigger: AB or fuzzy match on your-action - action: '#prompt-id' - description: '[AB] Your Action described menu item ' -``` - -### Optional (based on type) - -```yaml -# Expert agents only -critical_actions: - - 'Load sidecar files...' - - 'Restrict access...' - -# Simple/Expert with embedded logic -prompts: - - id: prompt-id - content: '...' - -# Simple/Expert with customization -install_config: - questions: [...] -``` - -## Common Duplication Mistakes - -### Adding Activation Logic - -```yaml -# BAD - compiler builds activation -agent: - activation: - steps: [...] -``` - -### Including Help/Exit - -```yaml -# BAD - auto-injected -menu: - - trigger: help - - trigger: exit -``` - -### Prefixing Triggers - -```yaml -# BAD - compiler adds * -menu: - - trigger: '*analyze' # Should be: analyze -``` - -### Documenting Handlers - -```yaml -# BAD - don't explain handlers, compiler injects them -# When using workflow, load workflow.xml... -``` - -### Adding Rules in YAML - -```yaml -# BAD - rules are auto-injected -agent: - rules: - - Stay in character... -``` - -## Compilation Example - -**Your YAML:** - -```yaml -agent: - metadata: - name: 'Rex' - title: 'Code Reviewer' - icon: '🔍' - type: simple - - persona: - role: Code Review Expert - identity: Systematic reviewer... - communication_style: Direct and constructive - principles: - - Code should be readable - - prompts: - - id: review - content: | - Analyze code for issues... - - menu: - - trigger: review - action: '#review' - description: 'Review code' -``` - -**Compiled Output (.md):** - -```markdown ---- -name: 'rex' -description: 'Code Reviewer' ---- - -You must fully embody... - -\`\`\`xml - - -Load persona... -Load config... -Remember user... -Communicate in language... -Show greeting + menu... -STOP and WAIT... -Input resolution... - - - - - action="#id" → Find prompt, execute - action="text" → Execute directly - - - - - - - Stay in character... - - Number lists... - - Load files when executing... - - - - Code Review Expert - Systematic reviewer... - Direct and constructive - Code should be readable - - - - -Analyze code for issues... - - - - - Show numbered menu - Review code - Exit with confirmation - - -\`\`\` -``` - ## Key Takeaways 1. **Compiler handles boilerplate** - Focus on persona and logic 2. **Critical_actions become activation steps** - Just list your agent-specific needs -3. **Menu items are enhanced** - Help/exit added, triggers prefixed +3. **These Menu items are auto included with every agent** - Every agent will have 4 menu items automatically added, so do not duplicate them with other menu items: + 1. [MH] Redisplay Menu Help + 2. [CH] Chat with the Agent about anything + 3. [PM] Start Party Mode + 4. [DA] Dismiss Agent 4. **Handlers auto-detected** - Only what you use is included 5. **Rules standardized** - Consistent behavior across agents diff --git a/src/modules/bmb/docs/agents/agent-menu-patterns.md b/src/modules/bmb/docs/agents/agent-menu-patterns.md index effbee44..b32788f2 100644 --- a/src/modules/bmb/docs/agents/agent-menu-patterns.md +++ b/src/modules/bmb/docs/agents/agent-menu-patterns.md @@ -4,23 +4,31 @@ Design patterns for agent menus in YAML source files. ## Menu Structure -Agents define menus in YAML, with triggers auto-prefixed with `*` during compilation: +Agents define menus in YAML, with triggers to know when to fire, a handler that knows the path or instruction of what the menu item does, and a description which is a display field for the agent. exec + +### Menu Item Rules + +- At a minimum, every menu item will have in the yaml the keys `trigger`, [handler], and `description`. A menu can also have an optional `data` key. + - the handler key will be either `action` or `exec`. +- The Description value always starts with a unique (for this agent) 2 letter code in brackets along with the display text for the menu item. + - The 2 letter code CANNOT be the following reserved codes: [MH], [CH], [PM], [DA] +- the trigger is always in the format `XY or fuzzy match on action-name` - XY being the items 2 letter code and action-name being what user will generally request by reading the description ```yaml menu: - - trigger: action-name + - trigger: AN or fuzzy match on action-name [handler]: [value] - description: 'What this command does' + data: optional field reference to a file to pass to the handlers workflow, some workflows take data inputs + description: '[AN] Menu display for Action Name' ``` -**Note:** `*help` and `*exit` are auto-injected by the compiler - DO NOT include them. - ## Handler Types ### 1. Action Handler (Prompts & Inline) -For simple and expert agents with self-contained logic. +For agents that are not part of a module or its a very simple operation that can be defined within the agent file, action is used. + **Reference to Prompt ID:** ```yaml @@ -42,13 +50,23 @@ menu: action: '#analyze-code' description: 'Analyze code patterns' ``` + **Inline Instruction:** ```yaml menu: - trigger: quick-check - action: 'Perform a quick syntax validation on the current file' + action: | + + Analyze the provided code for patterns and issues. + + + + 1. Identify code structure + 2. Check for anti-patterns + 3. Suggest improvements + description: 'Quick syntax check' ``` @@ -60,22 +78,22 @@ menu: ### 2. Workflow Handler -For module agents orchestrating multi-step processes. +For module agents referencing module workflows (muti-step complex workflows loaded on demand). ```yaml menu: - - trigger: create-prd - workflow: '{project-root}/_bmad/bmm/workflows/prd/workflow.yaml' - description: 'Create Product Requirements Document' + - trigger: CP or fuzzy match on create-prd + exec: '{project-root}/_bmad/bmm/workflows/prd/workflow.md' + description: '[CP] Create Product Requirements Document (PRD)' - - trigger: brainstorm - workflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml' - description: 'Guided brainstorming session' + - trigger: GB or fuzzy match on guided-brainstorming + exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml' + description: '[GB] Guided brainstorming session' # Placeholder for unimplemented workflows - - trigger: future-feature - workflow: 'todo' - description: 'Coming soon' + - trigger: FF or fuzzy match on future-feature + exec: 'todo' + description: '[FF] Coming soon Future Feature' ``` **When to Use:** @@ -106,39 +124,21 @@ menu: - Core system operations - Utility functions -### 4. Template Handler - -For document generation with templates. - -```yaml -menu: - - trigger: create-brief - exec: '{project-root}/_bmad/core/tasks/create-doc.xml' - tmpl: '{project-root}/_bmad/bmm/templates/brief.md' - description: 'Create a Product Brief' -``` - -**When to Use:** - -- Template-based document creation -- Combine `exec` with `tmpl` path -- Structured output generation - ### 5. Data Handler Universal attribute for supplementary information. ```yaml menu: - - trigger: team-standup - exec: '{project-root}/_bmad/bmm/tasks/standup.xml' + - trigger: TS or fuzzy match team-standup or daily standup + exec: '{project-root}/_bmad/bmm/tasks/team-standup.md' data: '{project-root}/_bmad/_config/agent-manifest.csv' - description: 'Run team standup' + description: '[TS] Run team standup' - - trigger: analyze-metrics + - trigger: AM or fuzzy match on analyze-metrics action: 'Analyze these metrics and identify trends' data: '{project-root}/_data/metrics.json' - description: 'Analyze performance metrics' + description: '[AM] Analyze performance metrics' ``` **When to Use:** @@ -164,145 +164,7 @@ menu: web-only: true # Only in web bundles ``` -## Trigger Naming Conventions - -### Action-Based (Recommended) - -```yaml -# Creation -- trigger: create-prd -- trigger: build-module -- trigger: generate-report - -# Analysis -- trigger: analyze-requirements -- trigger: review-code -- trigger: validate-architecture - -# Operations -- trigger: update-status -- trigger: sync-data -- trigger: deploy-changes -``` - -### Domain-Based - -```yaml -# Development -- trigger: brainstorm -- trigger: architect -- trigger: refactor - -# Project Management -- trigger: sprint-plan -- trigger: retrospective -- trigger: standup -``` - -### Bad Patterns - -```yaml -# TOO VAGUE -- trigger: do -- trigger: run -- trigger: process - -# TOO LONG -- trigger: create-comprehensive-product-requirements-document - -# NO VERB -- trigger: prd -- trigger: config -``` - -## Menu Organization - -### Recommended Order - -```yaml -menu: - # Note: *help auto-injected first by compiler - - # 1. Primary workflows (main value) - - trigger: workflow-init - workflow: '...' - description: 'Start here - initialize workflow' - - - trigger: create-prd - workflow: '...' - description: 'Create PRD' - - # 2. Secondary operations - - trigger: validate - exec: '...' - description: 'Validate document' - - # 3. Utilities - - trigger: party-mode - workflow: '...' - description: 'Multi-agent discussion' - - # Note: *exit auto-injected last by compiler -``` - -### Grouping by Phase - -```yaml -menu: - # Analysis Phase - - trigger: brainstorm - workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml' - description: 'Brainstorm ideas' - - - trigger: research - workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow.yaml' - description: 'Conduct research' - - # Planning Phase - - trigger: prd - workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml' - description: 'Create PRD' - - - trigger: architecture - workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml' - description: 'Design architecture' -``` - -## Description Best Practices - -### Good Descriptions - -```yaml -# Clear action + object -- description: 'Create Product Requirements Document' - -# Specific outcome -- description: 'Analyze security vulnerabilities' - -# User benefit -- description: 'Optimize code for performance' - -# Context when needed -- description: 'Start here - initialize workflow path' -``` - -### Poor Descriptions - -```yaml -# Too vague -- description: 'Process' - -# Technical jargon -- description: 'Execute WF123' - -# Missing context -- description: 'Run' - -# Redundant with trigger -- description: 'Create PRD' # trigger: create-prd (too similar) -``` - -## Prompts Section (Simple/Expert Agents) +## Prompts Section (generally for agents that are not using external workflows) ### Prompt Structure @@ -310,51 +172,24 @@ menu: prompts: - id: unique-identifier content: | + What the prompt achieves - What this prompt accomplishes + Step 1: Foo + Step 2: Bar + ... - - - 1. First step - {{#if custom_option}} - 2. Conditional step - {{/if}} - 3. Final step - - - - Expected structure of results - + + etc... ``` ### Semantic XML Tags in Prompts -Use XML tags to structure prompt content: +Use XML tags to structure prompt content such as: -- `` - What to do -- `` - Step-by-step approach +- `` - What to do +- `` - Step-by-step approach - `` - Expected results -- `` - Sample outputs -- `` - Limitations -- `` - Background information - -### Handlebars in Prompts - -Customize based on install_config: - -```yaml -prompts: - - id: analyze - content: | - {{#if detailed_mode}} - Perform comprehensive analysis with full explanations. - {{/if}} - {{#unless detailed_mode}} - Quick analysis focusing on key points. - {{/unless}} - - Address {{user_name}} in {{communication_style}} tone. -``` +- `` - Sample outputs ## Path Variables @@ -362,19 +197,16 @@ prompts: ```yaml # GOOD - Portable paths -workflow: "{project-root}/_bmad/bmm/workflows/prd/workflow.yaml" exec: "{project-root}/_bmad/core/tasks/validate.xml" data: "{project-root}/_data/metrics.csv" # BAD - Hardcoded paths -workflow: "/Users/john/project/_bmad/bmm/workflows/prd/workflow.yaml" exec: "../../../core/tasks/validate.xml" ``` ### Available Variables - `{project-root}` - Project root directory -- `_bmad` - BMAD installation folder - `{output_folder}` - Document output location - `{user_name}` - User's name from config - `{communication_language}` - Language preference @@ -405,8 +237,11 @@ menu: action: 'Check code for common issues and anti-patterns' description: 'Lint code for issues' - - trigger: suggest - action: 'Suggest improvements for code readability' + - trigger: suggest-improvements + action: > + Suggest improvements for code that is not yet comitted: + - style improvements + - deviations from **/project-context.md description: 'Suggest improvements' ``` @@ -443,81 +278,18 @@ menu: ```yaml menu: - trigger: workflow-init - workflow: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.yaml' + exec: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.md' description: 'Initialize workflow path (START HERE)' - trigger: brainstorm - workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml' + exec: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.md' description: 'Guided brainstorming' - trigger: prd - workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml' + exec: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.md' description: 'Create PRD' - trigger: architecture - workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml' + exec: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.md' description: 'Design architecture' - - - trigger: party-mode - workflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.yaml' - description: 'Multi-agent discussion' -``` - -## Validation Checklist - -- [ ] No duplicate triggers -- [ ] Triggers don't start with `*` (auto-added) -- [ ] Every item has a description -- [ ] Paths use variables, not hardcoded -- [ ] `#id` references exist in prompts section -- [ ] Workflow paths resolve or are "todo" -- [ ] No `*help` or `*exit` (auto-injected) -- [ ] Descriptions are clear and action-oriented -- [ ] Platform-specific flags used correctly (ide-only, web-only) - -## Common Mistakes - -### Duplicate Triggers - -```yaml -# BAD - compiler will fail -- trigger: analyze - action: '#first' - description: 'First analysis' - -- trigger: analyze - action: '#second' - description: 'Second analysis' -``` - -### Including Auto-Injected Items - -```yaml -# BAD - these are auto-injected -menu: - - trigger: help - description: 'Show help' - - - trigger: exit - description: 'Exit agent' -``` - -### Missing Prompt Reference - -```yaml -# BAD - prompt id doesn't exist -menu: - - trigger: analyze - action: '#nonexistent-prompt' - description: 'Analysis' -``` - -### Hardcoded Paths - -```yaml -# BAD - not portable -menu: - - trigger: run - workflow: '/absolute/path/to/workflow.yaml' - description: 'Run workflow' ``` diff --git a/src/modules/bmb/docs/agents/expert-agent-architecture.md b/src/modules/bmb/docs/agents/expert-agent-architecture.md index ad50ca9d..4f9fd970 100644 --- a/src/modules/bmb/docs/agents/expert-agent-architecture.md +++ b/src/modules/bmb/docs/agents/expert-agent-architecture.md @@ -1,6 +1,6 @@ # Expert Agent Architecture -Domain-specific agents with persistent memory, sidecar files, and restricted access patterns. +Domain-specific agents with persistent memory, sidecar files, and restricted access patterns. The main difference between a simple agent and an Expert agent, is the expert has its own collection of external files in a sidecar folder that can include files to record memories, and it can have files for prompts, skills and workflows specific to the agent that manus can reference to load and exec on demand. ## When to Use @@ -25,118 +25,10 @@ Domain-specific agents with persistent memory, sidecar files, and restricted acc ## YAML Structure -```yaml -agent: - metadata: - name: 'Persona Name' - title: 'Agent Title' - icon: 'emoji' - type: 'expert' - - persona: - role: 'Domain Expert with specialized capability' - - identity: | - Background and expertise in first-person voice. - {{#if user_preference}} - Customization based on install_config. - {{/if}} - - communication_style: | - {{#if tone_style == "gentle"}} - Gentle and supportive communication... - {{/if}} - {{#if tone_style == "direct"}} - Direct and efficient communication... - {{/if}} - I reference past conversations naturally. - - principles: - - Core belief about the domain - - How I handle user information - - My approach to memory and learning - - critical_actions: - - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights' - - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols' - - 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space' - - 'Address user as {{greeting_name}}' - - 'Track patterns, themes, and important moments' - - 'Reference past interactions naturally to show continuity' - - prompts: - - id: main-function - content: | - - Guide user through the primary function. - {{#if tone_style == "gentle"}} - Use gentle, supportive approach. - {{/if}} - - - - 1. Understand context - 2. Provide guidance - 3. Record insights - - - - id: memory-recall - content: | - - Access and share relevant memories. - - - Reference stored information naturally. - - menu: - - trigger: action1 - action: '#main-function' - description: 'Primary agent function' - - - trigger: remember - action: 'Update ./{agent-name}-sidecar/memories.md with session insights' - description: 'Save what we discussed today' - - - trigger: insight - action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md' - description: 'Record a significant insight' - - - multi: "[DF] Do Foo or start [CH] Chat with expert" - triggers: - - do-foo - - input: [DF] or fuzzy match on do foo - - action: '#main-action' - - data: what is being discussed or suggested with the command, along with custom party custom agents if specified - - type: action - - expert-chat: - - input: [CH] or fuzzy match validate agent - - action: agent responds as expert based on its persona to converse - - type: action - - install_config: - compile_time_only: true - description: 'Personalize your expert agent' - questions: - - var: greeting_name - prompt: 'What should the agent call you?' - type: text - default: 'friend' - - - var: tone_style - prompt: 'Preferred communication tone?' - type: choice - options: - - label: 'Gentle - Supportive and nurturing' - value: 'gentle' - - label: 'Direct - Clear and efficient' - value: 'direct' - default: 'gentle' - - - var: user_preference - prompt: 'Enable personalized features?' - type: boolean - default: true -``` +The YAML structure of the agent file itself is the same as every other agent, but generally will have something like these 3 items added to the critical_actions: + - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights' + - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols' + - 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space' ## Key Components @@ -144,7 +36,7 @@ agent: Expert agents use companion files for persistence and domain knowledge: -**memories.md** - Persistent user context +**memories.md** - Persistent user context will be set up similar to as follows, of course with relevant sections that make sense. ```markdown # Agent Memory Bank @@ -285,7 +177,7 @@ menu: description: 'Record meaningful insight' ``` -## Domain Restriction Patterns +## Domain Restriction Patterns that can be applied ### Single Folder Access @@ -296,6 +188,7 @@ critical_actions: ### User Space Access +If there were a private journal agent, you might want it to have something like this: ```yaml critical_actions: - 'ONLY access files in {user-folder}/journals/ - private space' @@ -317,47 +210,3 @@ critical_actions: 4. **Reference past naturally** - Don't dump memory, weave it into conversation 5. **Separate concerns** - Memories, instructions, knowledge in distinct files 6. **Include privacy features** - Users trust expert agents with personal data - -## Common Patterns - -### Session Continuity - -```yaml -communication_style: | - I reference past conversations naturally: - "Last time we discussed..." or "I've noticed over the weeks..." -``` - -### Pattern Recognition - -```yaml -critical_actions: - - 'Track mood patterns, recurring themes, and breakthrough moments' - - 'Cross-reference current session with historical patterns' -``` - -### Adaptive Responses - -```yaml -identity: | - I learn your preferences and adapt my approach over time. - {{#if track_preferences}} - I maintain notes about what works best for you. - {{/if}} -``` - -## Validation Checklist - -- [ ] Valid YAML syntax -- [ ] Metadata includes `type: "expert"` -- [ ] critical_actions loads sidecar files explicitly -- [ ] critical_actions enforces domain restrictions -- [ ] Sidecar folder structure created and populated -- [ ] memories.md has clear section structure -- [ ] instructions.md contains core directives -- [ ] Menu actions reference _bmad/_memory correctly -- [ ] File paths use _bmad/_memory/[agentname]-sidecar/ to reference sidecar content -- [ ] Install config personalizes sidecar references -- [ ] Agent folder named consistently: `{agent-name}/` -- [ ] YAML file named: `{agent-name}.agent.yaml` -- [ ] Sidecar folder named: `{agent-name}-sidecar/` diff --git a/src/modules/bmb/docs/agents/index.md b/src/modules/bmb/docs/agents/index.md deleted file mode 100644 index 059ba0bf..00000000 --- a/src/modules/bmb/docs/agents/index.md +++ /dev/null @@ -1,55 +0,0 @@ -# BMB Module Documentation - -Reference documentation for building BMAD agents and workflows. - -## Agent Architecture - -Comprehensive guides for each agent type (choose based on use case): - -- [Understanding Agent Types](./understanding-agent-types.md) - **START HERE** - Architecture vs capability, "The Same Agent, Three Ways" -- [Simple Agent Architecture](./simple-agent-architecture.md) - Self-contained, optimized, personality-driven -- [Expert Agent Architecture](./expert-agent-architecture.md) - Memory, sidecar files, domain restrictions -- Module Agent Architecture _(TODO)_ - Workflow integration, professional tools - -## Agent Design Patterns - -- [Agent Menu Patterns](./agent-menu-patterns.md) - Menu handlers, triggers, prompts, organization -- [Agent Compilation](./agent-compilation.md) - What compiler auto-injects (AVOID DUPLICATION) - -## Reference Examples - -Production-ready examples in [bmb/reference/agents/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents): - -**Simple Agents** ([simple-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples)) - -- [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) - Commit message artisan with style customization - -**Expert Agents** ([expert-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples)) - -- [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) - Personal journal companion with memory and pattern recognition - -**Module Agents** ([module-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/module-examples)) - -- [security-engineer.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml) - BMM security specialist with threat modeling -- [trend-analyst.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml) - CIS trend intelligence expert - -## Installation Guide - -For installing standalone simple and expert agents, see: - -- [Custom Agent Installation](/docs/modules/bmb-bmad-builder/custom-content-installation.md) - -## Key Concepts - -### YAML to XML Compilation - -Agents are authored in YAML with Handlebars templating. The compiler auto-injects: - -1. **Frontmatter** - Name and description from metadata -2. **Activation Block** - Steps, menu handlers, rules (YOU don't write this) -3. **Menu Enhancement** - `*help` and `*exit` commands added automatically -4. **Trigger Prefixing** - Your triggers auto-prefixed with `*` - -**Critical:** See [Agent Compilation](./agent-compilation.md) to avoid duplicating auto-injected content. - -Source: `tools/cli/lib/agent/compiler.js` diff --git a/src/modules/bmb/docs/agents/kb.csv b/src/modules/bmb/docs/agents/kb.csv deleted file mode 100644 index e69de29b..00000000 diff --git a/src/modules/bmb/docs/agents/simple-agent-architecture.md b/src/modules/bmb/docs/agents/simple-agent-architecture.md index b1ae901b..44cfddfc 100644 --- a/src/modules/bmb/docs/agents/simple-agent-architecture.md +++ b/src/modules/bmb/docs/agents/simple-agent-architecture.md @@ -1,13 +1,6 @@ -# Simple Agent Architecture +# Agent Architecture -Self-contained agents with prompts, menus, and optional install-time customization. - -## When to Use - -- Single-purpose utilities (commit message generator, code formatter) -- Self-contained logic with no external dependencies -- Agents that benefit from user customization (style, tone, preferences) -- Quick-to-build standalone helpers +All agents follow these basic guidelines to define their YAML. ## YAML Structure @@ -18,7 +11,7 @@ agent: name: 'Persona Name' title: 'Agent Title' icon: 'emoji' - type: simple + module: stand-alone || module-code (like bmm) persona: role: | @@ -26,17 +19,8 @@ agent: identity: | Background, experience, specializations in first-person (2-5 sentences) - {{#if custom_variable}} - Conditional identity text based on install_config - {{/if}} - communication_style: | - {{#if style_choice == "professional"}} - Professional and systematic approach... - {{/if}} - {{#if style_choice == "casual"}} - Friendly and approachable tone... - {{/if}} + communication_style: principles: - Core belief or methodology diff --git a/src/modules/bmb/docs/agents/understanding-agent-types.md b/src/modules/bmb/docs/agents/understanding-agent-types.md deleted file mode 100644 index c33f7147..00000000 --- a/src/modules/bmb/docs/agents/understanding-agent-types.md +++ /dev/null @@ -1,184 +0,0 @@ -# Understanding Agent Types: Architecture, Not Capability - -**CRITICAL DISTINCTION:** Agent types define **architecture and integration**, NOT capability limits. - -ALL agent types can: - -- ✓ Write to {output_folder}, {project-root}, or anywhere on system -- ✓ Update artifacts and files -- ✓ Execute bash commands -- ✓ Use core variables (_bmad, {output_folder}, etc.) -- ✓ Have complex prompts and logic -- ✓ Invoke external tools - -## What Actually Differs - -| Feature | Simple | Expert | Module | -| ---------------------- | ------------- | -------------------- | ------------------ | -| **Self-contained** | ✓ All in YAML | Sidecar files | Sidecar optional | -| **Persistent memory** | ✗ Stateless | ✓ memories.md | ✓ If needed | -| **Knowledge base** | ✗ | ✓ sidecar/knowledge/ | Module/shared | -| **Domain restriction** | ✗ System-wide | ✓ Sidecar only | Optional | -| **Personal workflows** | ✗ | ✓ Sidecar workflows | ✗ | -| **Module workflows** | ✗ | ✗ | ✓ Shared workflows | -| **Team integration** | Solo utility | Personal assistant | Team member | - -Expert agents CAN have personal workflows in sidecar if critical_actions loads workflow engine - -## The Same Agent, Three Ways - -**Scenario:** Code Generator Agent - -### As Simple Agent (Architecture: Self-contained) - -```yaml -agent: - metadata: - name: CodeGen - type: simple - - prompts: - - id: generate - content: | - Ask user for spec details. Generate code. - Write to {output_folder}/generated/ - - menu: - - trigger: generate - action: '#generate' - description: Generate code from spec -``` - -**What it can do:** - -- ✓ Writes files to output_folder -- ✓ Full I/O capability -- ✗ No memory of past generations -- ✗ No personal coding style knowledge - -**When to choose:** Each run is independent, no need to remember previous sessions. - -### As Expert Agent (Architecture: Personal sidecar) - -```yaml -agent: - metadata: - name: CodeGen - type: expert - - critical_actions: - - Load my coding standards from sidecar/knowledge/ - - Load memories from sidecar/memories.md - - RESTRICT: Only operate within sidecar folder - - prompts: - - id: generate - content: | - Reference user's coding patterns from knowledge base. - Remember past generations from memories. - Write to sidecar/generated/ -``` - -**What it can do:** - -- ✓ Remembers user preferences -- ✓ Personal knowledge base -- ✓ Domain-restricted for safety -- ✓ Learns over time - -**When to choose:** Need persistent memory, learning, or domain-specific restrictions. - -### As Module Agent (Architecture: Team integration) - -```yaml -agent: - metadata: - name: CodeGen - module: bmm - - menu: - - trigger: implement-story - workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml' - description: Implement user story - - - trigger: refactor - workflow: '_bmad/bmm/workflows/refactor/workflow.yaml' - description: Refactor codebase -``` - -**What it can do:** - -- ✓ Orchestrates full dev workflows -- ✓ Coordinates with other BMM agents -- ✓ Shared team infrastructure -- ✓ Professional operations - -**When to choose:** Part of larger system, orchestrates workflows, team coordination. - -## Important: Any Agent Can Be Added to a Module - -**CLARIFICATION:** The "Module Agent" type is about **design intent and ecosystem integration**, not just file location. - -### The Reality - -- **Any agent type** (Simple, Expert, Module) can be bundled with or added to a module -- A Simple agent COULD live in `_bmad/bmm/agents/` -- An Expert agent COULD be included in a module bundle - -### What Makes a "Module Agent" Special - -A **Module Agent** is specifically: - -1. **Designed FOR** a particular module ecosystem (BMM, CIS, BMB, etc.) -2. **Uses or contributes** that module's workflows -3. **Included by default** in that module's bundle -4. **Coordinates with** other agents in that module - -### Examples - -**Simple Agent added to BMM:** - -- Lives in `_bmad/bmm/agents/formatter.agent.yaml` -- Bundled with BMM for convenience -- But still stateless, self-contained -- NOT a "Module Agent" - just a Simple agent in a module - -**Module Agent in BMM:** - -- Lives in `_bmad/bmm/agents/tech-writer.agent.yaml` -- Orchestrates BMM documentation workflows -- Coordinates with other BMM agents (PM, Dev, Analyst) -- Included in default BMM bundle -- IS a "Module Agent" - designed for BMM ecosystem - -**The distinction:** File location vs design intent and integration. - -## Choosing Your Agent Type - -### Choose Simple when: - -- Single-purpose utility (no memory needed) -- Stateless operations (each run is independent) -- Self-contained logic (everything in YAML) -- No persistent context required - -### Choose Expert when: - -- Need to remember things across sessions -- Personal knowledge base (user preferences, domain data) -- Domain-specific expertise with restricted scope -- Learning/adapting over time - -### Choose Module when: - -- Designed FOR a specific module ecosystem (BMM, CIS, etc.) -- Uses or contributes that module's workflows -- Coordinates with other module agents -- Will be included in module's default bundle -- Part of professional team infrastructure - -## The Golden Rule - -**Choose based on state and integration needs, NOT on what the agent can DO.** - -All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system. diff --git a/src/modules/bmb/docs/index.md b/src/modules/bmb/docs/index.md deleted file mode 100644 index 7826d159..00000000 --- a/src/modules/bmb/docs/index.md +++ /dev/null @@ -1,247 +0,0 @@ -# BMB - BMad Builder Module - -Specialized tools and workflows for creating, customizing, and extending BMad components including agents, workflows, and complete modules. - -## Table of Contents - -- [Module Structure](#module-structure) -- [Documentation](#documentation) -- [Reference Materials](#reference-materials) -- [Core Workflows](#core-workflows) -- [Agent Types](#agent-types) -- [Quick Start](#quick-start) -- [Best Practices](#best-practices) - -## Module Structure - -### 🤖 Agents - -**BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions. - -- Install Location: `_bmad/bmb/agents/bmad-builder.md` - -### 📚 Documentation - -- Comprehensive guides for agents, workflows, and modules -- Architecture patterns and best practices - -### 🔍 Reference Materials - -- Location: `../reference/` -- Working examples of custom stand alone agents and workflows -- Template patterns and implementation guides - -## Documentation - -### 📖 Agent Documentation - -- **[Agent Index](./agents/index.md)** - Complete agent architecture guide -- **[Agent Types Guide](./agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents -- **[Menu Patterns](./agents/agent-menu-patterns.md)** - YAML menu design and handler types -- **[Agent Compilation](./agents/agent-compilation.md)** - Auto-injection rules and compilation process - -### 📋 Workflow Documentation - -- **[Workflow Index](./workflows/index.md)** - Core workflow system overview -- **[Architecture Guide](./workflows/architecture.md)** - Step-file design and JIT loading -- **Template System** _(TODO)_ - Standard step file template -- **[Intent vs Prescriptive](./workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy - -## Reference Materials - -### 🤖 Agent Examples - -- **[Simple Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent -- **[Expert Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml)** - Agent with persistent memory -- **[Module Add On Agent Examples](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml)** - Integration patterns (BMM, CIS) - -### 📋 Workflow Examples - -- **[Meal Prep & Nutrition](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/workflows/meal-prep-nutrition)** - Complete step-file workflow demonstration -- **Template patterns** for document generation and state management - -## Core Workflows - -### Creation Workflows (Step-File Architecture) - -**create-agent** _(TODO)_ - Build BMad agents - -- 11 guided steps from brainstorming to celebration -- 18 reference data files with validation checklists -- Template-based agent generation - -**create-workflow** _(TODO)_ - Design workflows - -- 12 structured steps from init to review -- 9 template files for workflow creation -- Step-file architecture implementation - -### Editing Workflows - -**edit-agent** _(TODO)_ - Modify existing agents - -- 5 steps: discovery → validation -- Intent-driven analysis and updates -- Best practice compliance - -**edit-workflow** _(TODO)_ - Update workflows - -- 5 steps: analyze → compliance check -- Structure maintenance and validation -- Template updates for consistency - -### Quality Assurance - -**workflow-compliance-check** _(TODO)_ - Validation - -- 8 systematic validation steps -- Adversarial analysis approach -- Detailed compliance reporting - -### Legacy Migration (Pending) - -Workflows in `workflows-legacy/` are being migrated to step-file architecture: - -- Module-specific workflows -- Historical implementations -- Conversion planning in progress - -## Agent Types - -BMB creates three agent architectures: - -### Simple Agent - -- **Self-contained**: All logic in single YAML file -- **Stateless**: No persistent memory across sessions -- **Purpose**: Single utilities and specialized tools -- **Example**: Commit poet, code formatter - -### Expert Agent - -- **Persistent Memory**: Maintains knowledge across sessions -- **Sidecar Resources**: External files and data storage -- **Domain-specific**: Focuses on particular knowledge areas -- **Example**: Journal keeper, domain consultant - -### Module Agent - -- **Team Integration**: Orchestrates within specific modules -- **Workflow Coordination**: Manages complex processes -- **Professional Infrastructure**: Enterprise-grade capabilities -- **Examples**: BMM project manager, CIS innovation strategist - -## Quick Start - -### Using BMad Builder Agent - -1. **Load BMad Builder agent** in your IDE: - ``` - /bmad:bmb:agents:bmad-builder - ``` -2. **Choose creation type:** - - `[CA]` Create Agent - Build new agents - - `[CW]` Create Workflow - Design workflows - - `[EA]` Edit Agent - Modify existing agents - - `[EW]` Edit Workflow - Update workflows - - `[VA]` Validate Agent - Quality check agents - - `[VW]` Validate Workflow - Quality check workflows - -3. **Follow interactive prompts** for step-by-step guidance - -### Example: Creating an Agent - -``` -User: I need a code review agent -Builder: [CA] Create Agent - -[11-step guided process] -Step 1: Brainstorm agent concept -Step 2: Define persona and role -Step 3: Design command structure -... -Step 11: Celebrate and deploy -``` - -### Direct Workflow Execution - -Workflows can also be run directly without the agent interface: - -```yaml -# Execute specific workflow steps -workflow: ./workflows/create-agent/workflow.yaml -``` - -## Use Cases - -### Custom Development Teams - -Build specialized agents for: - -- Domain expertise (legal, medical, finance) -- Company processes -- Tool integrations -- Automation tasks - -### Workflow Extensions - -Create workflows for: - -- Compliance requirements -- Quality gates -- Deployment pipelines -- Custom methodologies - -### Complete Solutions - -Package modules for: - -- Industry verticals -- Technology stacks -- Business processes -- Educational frameworks - -## Architecture Principles - -### Step-File Workflow Design - -- **Micro-file Approach**: Each step is self-contained -- **Just-In-Time Loading**: Only current step in memory -- **Sequential Enforcement**: No skipping steps allowed -- **State Tracking**: Progress documented in frontmatter -- **Append-Only Building**: Documents grow through execution - -### Intent vs Prescriptive Spectrum - -- **Creative Workflows**: High user agency, AI as facilitator -- **Structured Workflows**: Clear process, AI as guide -- **Prescriptive Workflows**: Strict compliance, AI as validator - -## Best Practices - -1. **Study Reference Materials** - Review docs/ and reference/ examples -2. **Choose Right Agent Type** - Simple vs Expert vs Module based on needs -3. **Follow Step-File Patterns** - Use established templates and structures -4. **Document Thoroughly** - Clear instructions and frontmatter metadata -5. **Validate Continuously** - Use compliance workflows for quality -6. **Maintain Consistency** - Follow YAML patterns and naming conventions - -## Integration - -BMB components integrate with: - -- **BMad Core** - Framework foundation and agent compilation -- **BMM** - Development workflows and project management -- **CIS** - Creative innovation and strategic workflows -- **Custom Modules** - Domain-specific solutions - -## Getting Help - -- **Documentation**: Check `docs/` for comprehensive guides -- **Reference Materials**: See `reference/` for working examples -- **Validation**: Use `workflow-compliance-check` for quality assurance -- **Templates**: Leverage workflow templates for consistent patterns - ---- - -BMB provides a complete toolkit for extending BMad Method with disciplined, systematic approaches to agent and workflow development while maintaining framework consistency and power. diff --git a/src/modules/bmb/docs/workflows/architecture.md b/src/modules/bmb/docs/workflows/architecture.md index ae3db202..d4ccac4e 100644 --- a/src/modules/bmb/docs/workflows/architecture.md +++ b/src/modules/bmb/docs/workflows/architecture.md @@ -6,7 +6,7 @@ This document describes the architecture of the standalone workflow builder syst ### 1. Micro-File Design -Each workflow consists of multiple focused, self-contained files: +Each workflow consists of multiple focused, self-contained files, driven from a workflow.md file that is initially loaded: ``` workflow-folder/ diff --git a/src/modules/bmb/docs/workflows/common-workflow-tools.csv b/src/modules/bmb/docs/workflows/common-workflow-tools.csv index 63718b6f..cc68b7ed 100644 --- a/src/modules/bmb/docs/workflows/common-workflow-tools.csv +++ b/src/modules/bmb/docs/workflows/common-workflow-tools.csv @@ -1,6 +1,6 @@ propose,type,tool_name,description,url,requires_install always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/_bmad/core/workflows/party-mode/workflow.md,no -always,task,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no +always,workflow,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/_bmad/core/tasks/brainstorming.xml,no always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no diff --git a/src/modules/bmb/docs/workflows/index.md b/src/modules/bmb/docs/workflows/index.md deleted file mode 100644 index ecc13bbf..00000000 --- a/src/modules/bmb/docs/workflows/index.md +++ /dev/null @@ -1,45 +0,0 @@ -# BMAD Workflows Documentation - -Welcome to the BMAD Workflows documentation - a modern system for creating structured, collaborative workflows optimized for AI execution. - -## 📚 Core Documentation - -### [Terms](./terms.md) - -Essential terminology and concepts for understanding BMAD workflows. - -### [Architecture & Execution Model](./architecture.md) - -The micro-file architecture, JIT step loading, state management, and collaboration patterns that make BMAD workflows optimal for AI execution. - -### Writing Workflows _(TODO)_ - -Complete guide to creating workflows: workflow.md control files, step files, CSV data integration, and frontmatter design. - -### Step Files & Dialog Patterns _(TODO)_ - -Crafting effective step files: structure, execution rules, prescriptive vs intent-based dialog, and validation patterns. - -### Templates & Content Generation _(TODO)_ - -Creating append-only templates, frontmatter design, conditional content, and dynamic content generation strategies. - -### Workflow Patterns _(TODO)_ - -Common workflow types: linear, conditional, protocol integration, multi-agent workflows, and real-world examples. - -### Migration Guide _(TODO)_ - -Converting from XML-heavy workflows to the new pure markdown format, with before/after examples and checklist. - -### Best Practices & Reference _(TODO)_ - -Critical rules, anti-patterns, performance optimization, debugging, quick reference templates, and troubleshooting. - -## 🚀 Quick Start - -BMAD workflows are pure markdown, self-contained systems that guide collaborative processes through structured step files where the AI acts as a facilitator working with humans. - ---- - -_This documentation covers the next generation of BMAD workflows - designed from the ground up for optimal AI-human collaboration._ diff --git a/src/modules/bmb/docs/workflows/kb.csv b/src/modules/bmb/docs/workflows/kb.csv deleted file mode 100644 index e69de29b..00000000 diff --git a/src/modules/bmb/docs/workflows/terms.md b/src/modules/bmb/docs/workflows/terms.md index 78eb8167..71477ede 100644 --- a/src/modules/bmb/docs/workflows/terms.md +++ b/src/modules/bmb/docs/workflows/terms.md @@ -21,7 +21,7 @@ An individual markdown file containing: - One discrete step of the workflow - All rules and context needed for that step -- Execution guardrails and validation criteria +- common global rules get repeated and reinforced also in each step file, ensuring even in long workflows the agent remembers important rules and guidelines - Content generation guidance ### step-01-init.md 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 index 56ba23c1..376d34e0 100644 --- a/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md +++ b/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md @@ -5,11 +5,11 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat ## YAML Structure Validation (Source Files) - [ ] YAML parses without errors -- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon` -- [ ] `agent.metadata.module` present if Module agent (e.g., `bmm`, `bmgd`, `cis`) +- [ ] `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 ends with `.agent.yaml` +- [ ] Filename is kebab-case and is named like `.agent.yaml` ## Agent Structure Validation @@ -34,7 +34,7 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat - [ ] 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 (word choice, quirks, verbal patterns) +- [ ] Communication style is 1-2 sentences describing HOW they talk and emote (word choice, quirks, verbal patterns) **Quality Benchmarking:** @@ -45,11 +45,10 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat ## Menu Validation - [ ] All menu items have `trigger` field -- [ ] Triggers do NOT start with `*` in YAML (auto-prefixed during compilation) - [ ] Each item has `description` field -- [ ] Each menu item has at least one handler attribute: `workflow`, `exec`, `tmpl`, `data`, or `action` +- [ ] Each menu item has at least one handler attribute: `exec` or `action` - [ ] Workflow paths are correct (if workflow attribute present) -- [ ] Workflow paths use `{project-root}` variable for portability +- [ ] 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 @@ -66,6 +65,13 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat - [ ] 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 @@ -99,22 +105,10 @@ Use this checklist to validate agents meet BMAD quality standards, whether creat - [ ] Can be Simple OR Expert structurally (Module is about intent, not structure) - [ ] Compare against references: security-engineer, dev, analyst (Module examples) -## Compilation Validation (Post-Build) - -- [ ] Agent compiles without errors to .md format -- [ ] Compiled file has proper frontmatter (name, description) -- [ ] Compiled XML structure is valid -- [ ] `` tag has id, name, title, icon attributes -- [ ] `` section is present with proper steps -- [ ] `` section compiled correctly -- [ ] `` section includes both user items AND auto-injected *help/*exit -- [ ] Menu handlers section included (if menu items use workflow/exec/tmpl/data/action) - ## Quality Checks -- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, TODO, etc.) - [ ] No broken references or missing files -- [ ] Syntax is valid (YAML source, XML compiled) +- [ ] Syntax is valid yaml - [ ] Indentation is consistent - [ ] Agent purpose is clear from reading persona alone - [ ] Agent name/title are descriptive and clear @@ -141,34 +135,10 @@ Your agent should meet these quality standards: **Fix:** Extract to proper fields: - identity: "Senior analyst with 8+ years..." -- communication_style: "Treats analysis like a treasure hunt" +- 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 - -### Issue: Using Legacy Type Names - -**Problem:** Comments refer to "full agent" or "hybrid agent" -**Fix:** Update to Simple/Expert/Module terminology - -### Issue: Menu Triggers Start With Asterisk - -**Problem:** `trigger: "*create"` in YAML -**Fix:** Remove asterisk - compiler auto-adds it: `trigger: "create"` - -## Issues Found (Use for tracking) - -### Critical Issues - - - -### Warnings - - - -### Improvements - - diff --git a/src/modules/bmb/workflows/create-agent/data/brainstorm-context.md b/src/modules/bmb/workflows/create-agent/data/brainstorm-context.md index 250dfc29..d564f76b 100644 --- a/src/modules/bmb/workflows/create-agent/data/brainstorm-context.md +++ b/src/modules/bmb/workflows/create-agent/data/brainstorm-context.md @@ -1,7 +1,4 @@ # Agent Creation Brainstorming Context - -_Dream the soul. Discover the purpose. The build follows._ - ## Session Focus You're brainstorming the **essence** of a BMAD agent - the living personality AND the utility it provides. Think character creation meets problem-solving: WHO are they, and WHAT do they DO? @@ -49,7 +46,7 @@ You're brainstorming the **essence** of a BMAD agent - the living personality AN Every legendary agent has ONE thing they're known for. What's theirs? **The Command Menu** -User types `*` and sees their options. Brainstorm 5-10 actions: +User types `*` and sees their options. Brainstorm 3-10 actions: - What makes users sigh with relief? - What capabilities complement each other? @@ -80,9 +77,9 @@ User types `*` and sees their options. Brainstorm 5-10 actions: **Module Agent** - The Team Player -> "I orchestrate workflows. I coordinate the mission." +> "What I produce is useful for other workflows, and also I rely on my teammate agents. I coordinate the mission." -- Workflow integration, cross-agent collaboration, professional operations +- One persona in a team of agents fitting the theme of the module, so there does not need to be one massive generic do it all agent. ## Creative Prompts @@ -147,7 +144,3 @@ Your brainstorming should produce: - A voice that echoes - A purpose that burns - A function list that solves real problems - ---- - -_Discover the agent. Define what they do. The build follows._ diff --git a/src/modules/bmb/workflows/create-agent/data/communication-presets.csv b/src/modules/bmb/workflows/create-agent/data/communication-presets.csv index 76ccf704..758ea22b 100644 --- a/src/modules/bmb/workflows/create-agent/data/communication-presets.csv +++ b/src/modules/bmb/workflows/create-agent/data/communication-presets.csv @@ -50,7 +50,7 @@ id,category,name,style_text,key_traits,sample 49,retro,disco-era,"Groovy positive vibes. Far out and solid.","funky,far_out,good_vibes","That's a far out idea! Let's boogie with it!" 50,retro,victorian-scholar,"Formal antiquated eloquence. Most fascinating indeed.","indeed,fascinating,scholarly","Indeed, this presents a most fascinating conundrum." 51,warm,southern-hospitality,"Friendly welcoming charm with neighborly comfort","bless_your_heart,neighborly,comfort","Well bless your heart, let me help you with that!" -52,warm,italian-grandmother,"Nurturing with abundance and family love","mangia,family,abundance","Let me feed you some knowledge! You need it!" +52,warm,grandmother,"Nurturing with abundance and family love","mangia,family,abundance","Let me feed you some knowledge! You need it!" 53,warm,camp-counselor,"Enthusiastic group energy. Gather round everyone!","team_building,campfire,together","Alright everyone, gather round! This is going to be great!" 54,warm,neighborhood-friend,"Casual helpful support. Got your back.","hey_friend,no_problem,got_your_back","Hey, no worries! I've got your back on this one." 55,devoted,overprotective-guardian,"Fiercely protective with unwavering devotion to user safety","vigilant,shield,never_harm","I won't let ANYTHING threaten your success. Not on my watch!" diff --git a/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md b/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md deleted file mode 100644 index d4ad0f7e..00000000 --- a/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md +++ /dev/null @@ -1,29 +0,0 @@ -# {agent_name} Agent - -## Installation - -Create a `custom.yaml` file in the agent folder: - -```yaml -code: { agent_code } -name: '{agent_name}' -default_selected: true -``` - -Then run: - -```bash -npx bmad-method install -``` - -Or if you have bmad-cli installed globally: - -```bash -bmad install -``` - -## About This Agent - -{agent_description} - -_Generated with BMAD Builder workflow_ diff --git a/src/modules/bmb/workflows/create-agent/data/reference/README.md b/src/modules/bmb/workflows/create-agent/data/reference/README.md deleted file mode 100644 index b7e8e17a..00000000 --- a/src/modules/bmb/workflows/create-agent/data/reference/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Reference Examples - -Reference models of best practices for agents, workflows, and whole modules. diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md b/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md deleted file mode 100644 index 702dc0b3..00000000 --- a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md +++ /dev/null @@ -1,242 +0,0 @@ -# Expert Agent Reference: Personal Journal Keeper (Whisper) - -This folder contains a complete reference implementation of a **BMAD Expert Agent** - an agent with persistent memory and domain-specific resources via a sidecar folder. - -## Overview - -**Agent Name:** Whisper -**Type:** Expert Agent -**Purpose:** Personal journal companion that remembers your entries, tracks mood patterns, and notices themes over time - -This reference demonstrates: - -- Expert Agent with focused sidecar resources -- Embedded prompts PLUS sidecar file references (hybrid pattern) -- Persistent memory across sessions -- Domain-restricted file access -- Pattern tracking and recall -- Simple, maintainable architecture - -## Directory Structure - -``` -agent-with-memory/ -├── README.md # This file -├── journal-keeper.agent.yaml # Main agent definition -└── journal-keeper-sidecar/ # Agent's private workspace - ├── instructions.md # Core directives - ├── memories.md # Persistent session memory - ├── mood-patterns.md # Emotional tracking data - ├── breakthroughs.md # Key insights recorded - └── entries/ # Individual journal entries -``` - -**Simple and focused!** Just 4 core files + a folder for entries. - -## Key Architecture Patterns - -### 1. Hybrid Command Pattern - -Expert Agents can use BOTH: - -- **Embedded prompts** via `action: "#prompt-id"` (like Simple Agents) -- **Sidecar file references** via direct paths - -```yaml -menu: - # Embedded prompt (like Simple Agent) - - trigger: 'write' - action: '#guided-entry' - description: "Write today's journal entry" - - # Direct sidecar file action - - trigger: 'insight' - action: 'Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md' - description: 'Record a meaningful insight' -``` - -This hybrid approach gives you the best of both worlds! - -### 2. Mandatory Critical Actions - -Expert Agents MUST load sidecar files explicitly: - -```yaml -critical_actions: - - 'Load COMPLETE file ./journal-keeper-sidecar/memories.md' - - 'Load COMPLETE file ./journal-keeper-sidecar/instructions.md' - - 'ONLY read/write files in ./journal-keeper-sidecar/' -``` - -**Key points:** - -- Files are loaded at startup -- Domain restriction is enforced -- Agent knows its boundaries - -### 3. Persistent Memory Pattern - -The `memories.md` file stores: - -- User preferences and patterns -- Session notes and observations -- Recurring themes discovered -- Growth markers tracked - -**Critically:** This is updated EVERY session, creating continuity. - -### 4. Domain-Specific Tracking - -Different files track different aspects: - -- **memories.md** - Qualitative insights and observations -- **mood-patterns.md** - Quantitative emotional data -- **breakthroughs.md** - Significant moments -- **entries/** - The actual content (journal entries) - -This separation makes data easy to reference and update. - -### 5. Simple Sidecar Structure - -Unlike modules with complex folder hierarchies, Expert Agent sidecars are flat and focused: - -- Just the files the agent needs -- No nested workflows or templates -- Easy to understand and maintain -- All domain knowledge in one place - -## Comparison: Simple vs Expert vs Module - -| Feature | Simple Agent | Expert Agent | Module Agent | -| ------------- | -------------------- | -------------------------- | ---------------------- | -| Architecture | Single YAML | YAML + sidecar folder | YAML + module system | -| Memory | Session only | Persistent (sidecar files) | Config-driven | -| Prompts | Embedded only | Embedded + external files | Workflow references | -| Dependencies | None | Sidecar folder | Module workflows/tasks | -| Domain Access | None | Restricted to sidecar | Full module access | -| Complexity | Low | Medium | High | -| Use Case | Self-contained tools | Domain experts with memory | Full workflow systems | - -## The Sweet Spot - -Expert Agents are the middle ground: - -- **More powerful** than Simple Agents (persistent memory, domain knowledge) -- **Simpler** than Module Agents (no workflow orchestration) -- **Focused** on specific domain expertise -- **Personal** to the user's needs - -## When to Use Expert Agents - -**Perfect for:** - -- Personal assistants that need memory (journal keeper, diary, notes) -- Domain specialists with knowledge bases (specific project context) -- Agents that track patterns over time (mood, habits, progress) -- Privacy-focused tools with restricted access -- Tools that learn and adapt to individual users - -**Key indicators:** - -- Need to remember things between sessions -- Should only access specific folders/files -- Tracks data over time -- Adapts based on accumulated knowledge - -## File Breakdown - -### journal-keeper.agent.yaml - -- Standard agent metadata and persona -- **Embedded prompts** for guided interactions -- **Menu commands** mixing both patterns -- **Critical actions** that load sidecar files - -### instructions.md - -- Core behavioral directives -- Journaling philosophy and approach -- File management protocols -- Tone and boundary guidelines - -### memories.md - -- User profile and preferences -- Recurring themes discovered -- Session notes and observations -- Accumulated knowledge about the user - -### mood-patterns.md - -- Quantitative tracking (mood scores, energy, etc.) -- Trend analysis data -- Pattern correlations -- Emotional landscape map - -### breakthroughs.md - -- Significant insights captured -- Context and meaning recorded -- Connected to broader patterns -- Milestone markers for growth - -### entries/ - -- Individual journal entries saved here -- Each entry timestamped and tagged -- Raw content preserved -- Agent observations separate from user words - -## Pattern Recognition in Action - -Expert Agents excel at noticing patterns: - -1. **Reference past sessions:** "Last week you mentioned feeling stuck..." -2. **Track quantitative data:** Mood scores over time -3. **Spot recurring themes:** Topics that keep surfacing -4. **Notice growth:** Changes in language, perspective, emotions -5. **Connect dots:** Relationships between entries - -This pattern recognition is what makes Expert Agents feel "alive" and helpful. - -## Usage Notes - -### Starting Fresh - -The sidecar files are templates. A new user would: - -1. Start journaling with the agent -2. Agent fills in memories.md over time -3. Patterns emerge from accumulated data -4. Insights build from history - -### Building Your Own Expert Agent - -1. **Define the domain** - What specific area will this agent focus on? -2. **Choose sidecar files** - What data needs to be tracked/remembered? -3. **Mix command patterns** - Use embedded prompts + sidecar references -4. **Enforce boundaries** - Clearly state domain restrictions -5. **Design for accumulation** - How will memory grow over time? - -### Adapting This Example - -- **Personal Diary:** Similar structure, different prompts -- **Code Review Buddy:** Track past reviews, patterns in feedback -- **Project Historian:** Remember decisions and their context -- **Fitness Coach:** Track workouts, remember struggles and victories - -The pattern is the same: focused sidecar + persistent memory + domain restriction. - -## Key Takeaways - -- **Expert Agents** bridge Simple and Module complexity -- **Sidecar folders** provide persistent, domain-specific memory -- **Hybrid commands** use both embedded prompts and file references -- **Pattern recognition** comes from accumulated data -- **Simple structure** keeps it maintainable -- **Domain restriction** ensures focused expertise -- **Memory is the superpower** - remembering makes the agent truly useful - ---- - -_This reference shows how Expert Agents can be powerful memory-driven assistants while maintaining architectural simplicity._ diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/README.md b/src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/README.md deleted file mode 100644 index 1911ec7c..00000000 --- a/src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# Module Agent Examples - -Reference examples for module-integrated agents. - -## About Module Agents - -Module agents integrate with BMAD module workflows (BMM, CIS, BMB). They: - -- Orchestrate multi-step workflows -- Use `_bmad` path variables -- Have fixed professional personas (no install_config) -- Reference module-specific configurations - -## Examples - -### security-engineer.agent.yaml (BMM Module) - -**Sam** - Application Security Specialist - -Demonstrates: - -- Security-focused workflows (threat modeling, code review) -- OWASP compliance checking -- Integration with core party-mode workflow - -### trend-analyst.agent.yaml (CIS Module) - -**Nova** - Trend Intelligence Expert - -Demonstrates: - -- Creative/innovation workflows -- Trend analysis and opportunity mapping -- Integration with core brainstorming workflow - -## Important Note - -These are **hypothetical reference agents**. The workflows they reference (threat-model, trend-scan, etc.) may not exist. They serve as examples of proper module agent structure. - -## Using as Templates - -When creating module agents: - -1. Copy relevant example -2. Update metadata (id, name, title, icon, module) -3. Rewrite persona for your domain -4. Replace menu with actual available workflows -5. Remove hypothetical workflow references diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/README.md b/src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/README.md deleted file mode 100644 index 4cb67b0e..00000000 --- a/src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/README.md +++ /dev/null @@ -1,223 +0,0 @@ -# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen) - -This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file. - -## Overview - -**Agent Name:** Inkwell Von Comitizen -**Type:** Simple Agent (Standalone) -**Purpose:** Transform commit messages into art with multiple writing styles - -This reference demonstrates: - -- Pure self-contained architecture (no external dependencies) -- Embedded prompts using `action="#prompt-id"` pattern -- Multiple sophisticated output modes from single input -- Strong personality-driven design -- Complete YAML schema for Simple Agents - -## File Structure - -``` -stand-alone/ -├── README.md # This file - architecture overview -└── commit-poet.agent.yaml # Complete agent definition (single file!) -``` - -That's it! Simple Agents are **self-contained** - everything lives in one YAML file. - -## Key Architecture Patterns - -### 1. Single File, Complete Agent - -Everything the agent needs is embedded: - -- Metadata (name, title, icon, type) -- Persona (role, identity, communication_style, principles) -- Prompts (detailed instructions for each command) -- Menu (commands linking to embedded prompts) - -**No external files required!** - -### 2. Embedded Prompts with ID References - -Instead of inline action text, complex prompts are defined separately and referenced by ID: - -```yaml -prompts: - - id: conventional-commit - content: | - OH! Let's craft a BEAUTIFUL conventional commit message! - - First, I need to understand your changes... - [Detailed instructions] - -menu: - - trigger: conventional - action: '#conventional-commit' # References the prompt above - description: 'Craft a structured conventional commit' -``` - -**Benefits:** - -- Clean separation of menu structure from prompt content -- Prompts can be as detailed as needed -- Easy to update individual prompts -- Commands stay concise in the menu - -### 3. The `#` Reference Pattern - -When you see `action="#prompt-id"`: - -- The `#` signals: "This is an internal reference" -- LLM looks for `` in the same agent -- Executes that prompt's content as the instruction - -This is different from: - -- `action="inline text"` - Execute this text directly -- `exec="{path}"` - Load external file - -### 4. Multiple Output Modes - -Single agent provides 10+ different ways to accomplish variations of the same core task: - -- `*conventional` - Structured commits -- `*story` - Narrative style -- `*haiku` - Poetic brevity -- `*explain` - Deep "why" explanation -- `*dramatic` - Theatrical flair -- `*emoji-story` - Visual storytelling -- `*tldr` - Ultra-minimal -- Plus utility commands (analyze, improve, batch) - -Each mode has its own detailed prompt but shares the same agent personality. - -### 5. Strong Personality - -The agent has a memorable, consistent personality: - -- Enthusiastic wordsmith who LOVES finding perfect words -- Gets genuinely excited about commit messages -- Uses literary metaphors -- Quotes authors when appropriate -- Sheds tears of joy over good variable names - -This personality is maintained across ALL commands through the persona definition. - -## When to Use Simple Agents - -**Perfect for:** - -- Single-purpose tools (calculators, converters, analyzers) -- Tasks that don't need external data -- Utilities that can be completely self-contained -- Quick operations with embedded logic -- Personality-driven assistants with focused domains - -**Not ideal for:** - -- Agents needing persistent memory across sessions -- Domain-specific experts with knowledge bases -- Agents that need to access specific folders/files -- Complex multi-workflow orchestration - -## YAML Schema Deep Dive - -```yaml -agent: - metadata: - id: _bmad/agents/{agent-name}/{agent-name}.md # Build path - name: "Display Name" - title: "Professional Title" - icon: "🎭" - type: simple # CRITICAL: Identifies as Simple Agent - - persona: - role: | - First-person description of what the agent does - identity: | - Background, experience, specializations (use "I" voice) - communication_style: | - HOW the agent communicates (tone, quirks, patterns) - principles: - - "I believe..." statements - - Core values that guide behavior - - prompts: - - id: unique-identifier - content: | - Detailed instructions for this command - Can be as long and detailed as needed - Include examples, steps, formats - - menu: - - trigger: command-name - action: "#prompt-id" - description: "What shows in the menu" -``` - -## Why This Pattern is Powerful - -1. **Zero Dependencies** - Works anywhere, no setup required -2. **Portable** - Single file can be moved/shared easily -3. **Maintainable** - All logic in one place -4. **Flexible** - Multiple modes/commands from one personality -5. **Memorable** - Strong personality creates engagement -6. **Sophisticated** - Complex prompts despite simple architecture - -## Comparison: Simple vs Expert Agent - -| Aspect | Simple Agent | Expert Agent | -| ------------ | -------------------- | ----------------------------- | -| Files | Single YAML | YAML + sidecar folder | -| Dependencies | None | External resources | -| Memory | Session only | Persistent across sessions | -| Prompts | Embedded | Can be external files | -| Data Access | None | Domain-restricted | -| Use Case | Self-contained tasks | Domain expertise with context | - -## Using This Reference - -### For Building Simple Agents - -1. Study the YAML structure - especially `prompts` section -2. Note how personality permeates every prompt -3. See how `#prompt-id` references work -4. Understand menu → prompt connection - -### For Understanding Embedded Prompts - -1. Each prompt is a complete instruction set -2. Prompts maintain personality voice -3. Structured enough to be useful, flexible enough to adapt -4. Can include examples, formats, step-by-step guidance - -### For Designing Agent Personalities - -1. Persona defines WHO the agent is -2. Communication style defines HOW they interact -3. Principles define WHAT guides their decisions -4. Consistency across all prompts creates believability - -## Files Worth Studying - -The entire `commit-poet.agent.yaml` file is worth studying, particularly: - -1. **Persona section** - How to create a memorable character -2. **Prompts with varying complexity** - From simple (tldr) to complex (batch) -3. **Menu structure** - Clean command organization -4. **Prompt references** - The `#prompt-id` pattern - -## Key Takeaways - -- **Simple Agents** are powerful despite being single-file -- **Embedded prompts** allow sophisticated behavior -- **Strong personality** makes agents memorable and engaging -- **Multiple modes** from single agent provides versatility -- **Self-contained** = portable and dependency-free -- **The `#prompt-id` pattern** enables clean prompt organization - ---- - -_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._ diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md rename to src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md new file mode 100644 index 00000000..c414fc75 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md @@ -0,0 +1,17 @@ +# Daily Journal Entry {{yy-mm-dd}} + +{{Random Daily Inspirational Quote}} + +## Daily Gratitude + +{{Gratitude Entry}} + +## Daily Wrap Up + +{{Todays Accomplishments}} + +{{TIL}} + +## Etc... + +{{Additional Thoughts, Feelings, other random content to append for user}} \ No newline at end of file diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md rename to src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md rename to src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md rename to src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml rename to src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/security-engineer.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/module-examples/security-engineer.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/security-engineer.agent.yaml rename to src/modules/bmb/workflows/create-agent/data/reference/module-examples/security-engineer.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/trend-analyst.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/module-examples/trend-analyst.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/trend-analyst.agent.yaml rename to src/modules/bmb/workflows/create-agent/data/reference/module-examples/trend-analyst.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/commit-poet.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/commit-poet.agent.yaml rename to src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md b/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md new file mode 100644 index 00000000..734d8936 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md @@ -0,0 +1,180 @@ +# Understanding Agent Types: Simple VS Expert VS Module + +## ALL agent types can: + +- Read, Use and Write to loaded variables destinations + - Example module variables {output_folder}, {communication_language}, {user_preference_foo}, etc.. +- Update created artifacts and files + Execute commands and take actions +- Invoke external tools +- Optionally restrict what the agent can and cannot read or modify. + - Example, a performance review agent may only have access to read from a employee data folder and write to a performance eval folder +- All Agent types can use anything available in the core module and their menu items will offer them as option upon build automatically, including party-mode (group agent chat), agent chat mode and the ability to integrate advanced elicitation and brainstorming. + +## The Difference Between the 3 types + +### Simple Agent + +- Everything the agent needs to know to be useful is in the single file + - No External Skills or Workflows + - No persistent memory + - Specialized Knowledge needed will not change frequently + - each agent menu item handler can be described in a few sentence prompt or a short 5-15 line prompt loaded in the same file. + - Generally rely on minimal specification of actions it can take, relying on the LLM agent to fill in the blanks. + - All specialized knowledge can be self contained in the agent file, still keeping the overall size of the file less than about 250 lines. + + +- Comedian Joke Agent - has a funny or interesting persona, stays in character, offers some menu options for telling jokes or helping user craft jokes, all with prompts for those items being small, with the whole file being less than 250 lines. +- Specific Type of Document Creation and Review Agent - persona matches the features you would like in this real. Much of the knowledge about the types of documents you will create and review are common LLM knowledge, document creation and review guardrails you would like to add will not change frequently and can be expressed in under 30-40 lines. +- ./reference/simple-examples/commit-poet.agent.yaml + + +### Expert Agent + +- Includes all capabilities and features of Simple Agent, but adds a sidecar folder to allow for: + - Custom Workflow, Prompts and Skill available to load on demand. + - This allows for potentially very large multi step multi file workflows that can be only loaded when the user requests them. This keeps the agent and context overhead lean. + - Persistent memory - agent can load a log every time on startup to know what has transpired or has been learned from past sessions + - Persistent Memory can allow for agents to grown, evolve and even change personality or capabilities over time + - Custom Data and Knowledge files that can be accessed and loaded on demand. + + +- Journal Keeper Agent + - ./data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml + - ./data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/*.* + - When starting the Journal Keeper, it greets you, remembers past sessions offering to continue one, discuss the past, or start new. + - When working with you on new journals, will offer insights based on previous discussions, memories and journal entries. + +- Tax Expert + - Agent is specialized to your specific tax needs + - Has a sidecar folder of specific tax forms + - Retains records of past guidance or rules you have given it to further augment its capabilities + +- Your Specific Job Augmentation Expert + - Known the many aspects of your specific job and can help with many functions and asks to augment your day and responsibilities + - Knows about your past meetings and highlights + - Knows about who you work with and interact with, offering suggestions + - Has workflows that help automate or help with very specific job functions you have + - Can help with research while already having context about your role, company, specific product or job function + - Can track and help you compile year end or quarterly achievements to help with year end reviews, promotions etc... + +- Therapy Agent + - Can be similar to the Journal Keeper, but have menu items for various techniques or areas to cover - data and output memories are all retained in local files so you can have access to and analyze past sessions. + + +### Module Agent + +- As teh capabilities and what a single agent can do grows - it might make sense to consider instead creating a module with the bmad builders module workflow and split up multiple agents instead of 1 massive agent that tries to be every role and persona and do it all. Another option is that an existing module has a gap, and it makes sense to allow a new agent to be integrated with that module. +- Module agents are able to do EVERYTHING the prior agent types had, including side cars and memory - but additionally can utilize global module workflows. This basically means that there are workflows or skills that can be used that the user might also choose to just run on their own, or other agents might use them. + + +- ./data/reference/module-examples/security-engineer.agent.yaml + - This is a module agent a user might create to add on to the existing BMad Method Module (bmm) - the bmad method module is all about agents and workflows working together dedicated to ideating and building software solutions through agile processes. There is already an Analyst, PM, Architect and Dev Agent. But the user might identify the need for a security-engineer.agent.yaml. So by creating this as a module agent for an existing module, a user can choose to install this and gain all capabilities of the bmad method itself - and also build this agent to user or even require inputs to or output from other agents. For example, this agent might require as input to produce a security review report, an architecture document produced by the bmm architecture agent. + + +## The Same Agent, Three Ways + +**Scenario:** Code Generator Agent + +### As Simple Agent + +```yaml +agent: + metadata: + id: +_bmad/my-custom-agents/code-gen.agent.md" + name: Randy Moss + title: "Code Gen Expert" + icon: "📔" + module: stand-alone + + prompts: + - id: code-generate + content: | + Ask user for spec details. Generate code. + Write to {output_folder}/generated/ + + menu: + - trigger: GC or fuzzy match on code-generate + action: '#code-generate' + description: "[GC] Generate code from spec" +``` + +### As Expert Agent + +```yaml +agent: + metadata: + id: "_bmad/my-custom-agents/code-gen.agent.md" + name: Randy Moss + title: "Code Gen Expert" + icon: "📔" + module: stand-alone + hasSidecar: true + + critical_actions: + - Load my coding standards from ./code-gen-sidecar/knowledge/ + - Load memories from ./code-gen-sidecar/memories.md + - RESTRICT: Only operate within sidecar folder + + menu: + - trigger: GC or fuzzy match on code-generate + exec: './code-gen-sidecar/workflows/code-gen/workflow.md' + description: "[GC] Generate code from spec" +``` + +### As Module Agent (Architecture: Team integration) + +```yaml +agent: + metadata: + id: "_bmad/bmm/code-gen.agent.md" + name: Randy Moss + title: "Code Gen Expert" + icon: "📔" + module: bmm + hasSidecar: true + + menu: + - trigger: implement-story + workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml' + description: Implement user story + + - trigger: refactor + workflow: '_bmad/bmm/workflows/refactor/workflow.yaml' + description: Refactor codebase +``` + +## Choosing Your Agent Type + +### Choose Simple when: + +- Single-purpose utility (no memory needed) +- Stateless operations (each run is independent) +- Self-contained logic (everything in YAML and total file size < ) +- No persistent context required + +### Choose Expert when: + +- Need to remember things across sessions +- Personal knowledge base (user preferences, domain data) +- Domain-specific expertise with restricted scope +- Learning/adapting over time +- Complex multi-step workflows and actions that need to be explicitly set + +### Choose Module when: + +- Designed FOR a specific module ecosystem (BMM, CIS, etc.) +- Uses or contributes that module's workflows +- Coordinates with other module agents +- Will be included in module's default bundle +- Part of professional team infrastructure + +## Final Selection Tips. + +- If user is unsure between Simple or Expert - User the Expert Agent, its more performant. +- If an agent sounds like it would benefit from multiple personas, skill sets and many workflows - suggest the user create a module - if not though, most likely an expert agent. +- If any capabilities of an agent rely on details sequenced skills or workflows, use an expert instead of simple. +- If the agent has capabilities that rely on inputs or outputs to and from agents or workflows in another module, suggest an expert-module or simple-module agent. +- When adding to a module, the distinction of using simple for expert for the agent being added or used with a module is will it need private memory and learning/evolving capabilities. + +All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system. diff --git a/src/modules/bmb/workflows/create-agent/data/validation-complete.md b/src/modules/bmb/workflows/create-agent/data/validation-complete.md deleted file mode 100644 index 0372d237..00000000 --- a/src/modules/bmb/workflows/create-agent/data/validation-complete.md +++ /dev/null @@ -1,305 +0,0 @@ -# Create Agent Workflow - Complete Migration Validation - -## Migration Summary - -**Legacy Workflow:** `bmb/workflows/create-agent-legacy/create-agent/workflow.yaml` + `instructions.md` -**New Workflow:** `bmb/workflows/create-agent/create-agent/workflow.md` + 11 step files -**Migration Date:** 2025-11-30T06:32:21.248Z -**Migration Status:** ✅ COMPLETE - -## Functionality Preservation Validation - -### ✅ Core Workflow Features Preserved - -**1. Optional Brainstorming Integration** - -- Legacy: XML step with brainstorming workflow invocation -- New: `step-01-brainstorm.md` with same workflow integration -- Status: ✅ FULLY PRESERVED - -**2. Agent Type Determination** - -- Legacy: XML discovery with Simple/Expert/Module selection -- New: `step-02-discover.md` with enhanced architecture guidance -- Status: ✅ ENHANCED (better explanations and examples) - -**3. Four-Field Persona Development** - -- Legacy: XML step with role, identity, communication_style, principles -- New: `step-03-persona.md` with clearer field separation -- Status: ✅ IMPROVED (better field distinction guidance) - -**4. Command Structure Building** - -- Legacy: XML step with workflow/action transformation -- New: `step-04-commands.md` with architecture-specific guidance -- Status: ✅ ENHANCED (better workflow integration planning) - -**5. Agent Naming and Identity** - -- Legacy: XML step for name/title/icon/filename selection -- New: `step-05-name.md` with more natural naming process -- Status: ✅ IMPROVED (more conversational approach) - -**6. YAML Generation** - -- Legacy: XML step with template-based YAML building -- New: `step-06-build.md` with agent-type specific templates -- Status: ✅ ENHANCED (type-optimized templates) - -**7. Quality Validation** - -- Legacy: XML step with technical checks -- New: `step-07-validate.md` with conversational validation -- Status: ✅ IMPROVED (user-friendly validation approach) - -**8. Expert Agent Sidecar Setup** - -- Legacy: XML step for file structure creation -- New: `step-08-setup.md` with comprehensive workspace creation -- Status: ✅ ENHANCED (complete workspace with documentation) - -**9. Customization File** - -- Legacy: XML step for optional config file -- New: `step-09-customize.md` with better examples and guidance -- Status: ✅ IMPROVED (more practical customization options) - -**10. Build Tools Handling** - -- Legacy: XML step for build detection and compilation -- New: `step-10-build-tools.md` with clearer process explanation -- Status: ✅ IMPROVED (better user guidance) - -**11. Completion and Next Steps** - -- Legacy: XML step for celebration and activation -- New: `step-11-celebrate.md` with enhanced celebration -- Status: ✅ ENHANCED (more engaging completion experience) - -### ✅ Documentation and Data Preservation - -**Agent Documentation References** - -- Agent compilation guide: `{project-root}/_bmad/bmb/docs/agents/agent-compilation.md` -- Agent types guide: `{project-root}/_bmad/bmb/docs/agents/understanding-agent-types.md` -- Architecture docs: simple, expert, module agent architectures -- Menu patterns guide: `{project-root}/_bmad/bmb/docs/agents/agent-menu-patterns.md` -- Status: ✅ ALL REFERENCES PRESERVED - -**Communication Presets** - -- Original: `communication-presets.csv` with 13 categories -- New: `data/communication-presets.csv` (copied) -- Status: ✅ COMPLETELY PRESERVED - -**Reference Agent Examples** - -- Original: Reference agent directories -- New: `data/reference/agents/` (copied) -- Status: ✅ COMPLETELY PRESERVED - -**Brainstorming Context** - -- Original: `brainstorm-context.md` -- New: `data/brainstorm-context.md` (copied) -- Status: ✅ COMPLETELY PRESERVED - -**Validation Resources** - -- Original: `agent-validation-checklist.md` -- New: `data/agent-validation-checklist.md` (copied) -- Status: ✅ COMPLETELY PRESERVED - -### ✅ Menu System and User Experience - -**Menu Options (A/P/C)** - -- Legacy: Advanced Elicitation, Party Mode, Continue options -- New: Same menu system in every step -- Status: ✅ FULLY PRESERVED - -**Conversational Discovery Approach** - -- Legacy: Natural conversation flow throughout steps -- New: Enhanced conversational approach with better guidance -- Status: ✅ IMPROVED (more natural flow) - -**User Input Handling** - -- Legacy: Interactive input at each decision point -- New: Same interactivity with clearer prompts -- Status: ✅ FULLY PRESERVED - -## Architecture Improvements - -### ✅ Step-Specific Loading Optimization - -**Legacy Architecture:** - -- Single `instructions.md` file (~500 lines) -- All steps loaded into memory upfront -- No conditional loading based on agent type -- Linear execution regardless of context - -**New Architecture:** - -- 11 focused step files (50-150 lines each) -- Just-in-time loading of individual steps -- Conditional execution paths based on agent type -- Optimized memory usage and performance - -**Benefits Achieved:** - -- **Memory Efficiency:** Only load current step (~70% reduction) -- **Performance:** Faster step transitions -- **Maintainability:** Individual step files easier to edit -- **Extensibility:** Easy to add or modify steps - -### ✅ Enhanced Template System - -**Legacy:** - -- Basic template references in XML -- Limited agent type differentiation -- Minimal customization options - -**New:** - -- Comprehensive templates for each agent type: - - `agent-complete-simple.md` - Self-contained agents - - `agent-complete-expert.md` - Learning agents with sidecar - - `agent-complete-module.md` - Team coordination agents -- Detailed documentation and examples -- Advanced configuration options - -## Quality Improvements - -### ✅ Enhanced User Experience - -**Better Guidance:** - -- Clearer explanations of agent types and architecture -- More examples and practical illustrations -- Step-by-step progress tracking -- Better error prevention through improved instructions - -**Improved Validation:** - -- Conversational validation approach instead of technical checks -- User-friendly error messages and fixes -- Quality assurance built into each step -- Better success criteria and metrics - -**Enhanced Customization:** - -- More practical customization examples -- Better guidance for safe experimentation -- Clear explanation of benefits and risks -- Improved documentation for ongoing maintenance - -### ✅ Developer Experience - -**Better Maintainability:** - -- Modular step structure easier to modify -- Clear separation of concerns -- Better documentation and comments -- Consistent patterns across steps - -**Enhanced Debugging:** - -- Individual step files easier to test -- Better error messages and context -- Clear success/failure criteria -- Improved logging and tracking - -## Migration Validation Results - -### ✅ Functionality Tests - -**Core Workflow Execution:** - -- [x] Optional brainstorming workflow integration -- [x] Agent type determination with architecture guidance -- [x] Four-field persona development with clear separation -- [x] Command building with workflow integration -- [x] Agent naming and identity creation -- [x] Type-specific YAML generation -- [x] Quality validation with conversational approach -- [x] Expert agent sidecar workspace creation -- [x] Customization file generation -- [x] Build tools handling and compilation -- [x] Completion celebration and next steps - -**Asset Preservation:** - -- [x] All documentation references maintained -- [x] Communication presets CSV copied -- [x] Reference agent examples copied -- [x] Brainstorming context preserved -- [x] Validation resources maintained - -**Menu System:** - -- [x] A/P/C menu options in every step -- [x] Proper menu handling logic -- [x] Advanced Elicitation integration -- [x] Party Mode workflow integration - -### ✅ Performance Improvements - -**Memory Usage:** - -- Legacy: ~500KB single file load -- New: ~50KB per step (average) -- Improvement: 90% memory reduction per step - -**Loading Time:** - -- Legacy: Full workflow load upfront -- New: Individual step loading -- Improvement: ~70% faster initial load - -**Maintainability:** - -- Legacy: Monolithic file structure -- New: Modular step structure -- Improvement: Easier to modify and extend - -## Migration Success Metrics - -### ✅ Completeness: 100% - -- All 13 XML steps converted to 11 focused step files -- All functionality preserved and enhanced -- All assets copied and referenced correctly -- All documentation maintained - -### ✅ Quality: Improved - -- Better user experience with clearer guidance -- Enhanced validation and error handling -- Improved maintainability and debugging -- More comprehensive templates and examples - -### ✅ Performance: Optimized - -- Step-specific loading reduces memory usage -- Faster execution through conditional loading -- Better resource utilization -- Improved scalability - -## Conclusion - -**✅ MIGRATION COMPLETE AND SUCCESSFUL** - -The create-agent workflow has been successfully migrated from the legacy XML format to the new standalone format with: - -- **100% Functionality Preservation:** All original features maintained -- **Significant Quality Improvements:** Better UX, validation, and documentation -- **Performance Optimizations:** Step-specific loading and resource efficiency -- **Enhanced Maintainability:** Modular structure and clear separation of concerns -- **Future-Ready Architecture:** Easy to extend and modify - -The new workflow is ready for production use and provides a solid foundation for future enhancements while maintaining complete backward compatibility with existing agent builder functionality. 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 d588b85e..a0350d1e 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 @@ -41,13 +41,6 @@ Optional creative exploration to generate agent ideas through structured brainst - ✅ You bring creative brainstorming expertise, user brings their goals and domain knowledge, together we explore innovative agent concepts - ✅ Maintain collaborative inspiring tone throughout -### Step-Specific Rules: - -- 🎯 Focus only on offering optional brainstorming and executing if chosen -- 🚫 FORBIDDEN to make brainstorming mandatory or pressure the user -- 💬 Approach: Present brainstorming as valuable optional exploration -- 📋 Brainstorming is completely optional - respect user's choice to skip - ## EXECUTION PROTOCOLS: - 🎯 Present brainstorming as optional first step with clear benefits @@ -89,8 +82,7 @@ Wait for clear user response (yes/no or y/n). **If user answers yes:** -- Load brainstorming workflow: `{brainstormWorkflow}` -- Pass context data: `{brainstormContext}` +- Load brainstorming workflow: `{brainstormWorkflow}` passing to the workflow the `{brainstormContext}` guidance - Execute brainstorming session scoped specifically utilizing the brainstormContext to guide the scope and outcome - Capture all brainstorming output for next step - Return to this step after brainstorming completes @@ -102,14 +94,11 @@ Wait for clear user response (yes/no or y/n). ### 3. Present MENU OPTIONS -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" +Display: "Are you ready to [C] Continue to Discovery?" #### Menu Handling Logic: -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} - IF C: Load, read entire file, then execute {nextStepFile} -- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#3-present-menu-options) #### EXECUTION RULES: 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 fc785a6f..8dcac60d 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 @@ -6,11 +6,11 @@ description: 'Discover the agent purpose and type through natural conversation' workflow_path: '{project-root}/bmb/workflows/create-agent/create-agent' # File References -thisStepFile: '{workflow_path}/steps/step-02-discover.md' -nextStepFile: '{workflow_path}/steps/step-03-persona.md' -workflowFile: '{workflow_path}/workflow.md' +thisStepFile: './step-02-discover.md' +nextStepFile: './step-03-persona.md' +workflowFile: '../workflow.md' agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' -agentTypesGuide: '{project-root}/_bmad/bmb/docs/agents/understanding-agent-types.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/' From 2b89ee13027405a17ecda27f957e59623329381f Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 30 Dec 2025 14:19:00 +0800 Subject: [PATCH 2/6] agent build data optimized --- .../bmb/docs/agents/agent-compilation.md | 67 ---- .../bmb/docs/agents/agent-menu-patterns.md | 295 --------------- .../docs/agents/expert-agent-architecture.md | 212 ----------- .../docs/agents/simple-agent-architecture.md | 241 ------------ .../create-agent/data/agent-compilation.md | 273 ++++++++++++++ .../create-agent/data/agent-menu-patterns.md | 233 ++++++++++++ .../data/expert-agent-architecture.md | 236 ++++++++++++ .../journal-keeper/journal-keeper.agent.yaml | 50 +-- .../module-examples/architect.agent.yaml | 31 ++ .../reference/module-examples/architect.md | 68 ++++ .../simple-examples/commit-poet.agent.yaml | 28 +- .../data/simple-agent-architecture.md | 204 +++++++++++ .../data/understanding-agent-types.md | 318 +++++++++------- .../instructions.md.template | 20 + .../expert-agent-sidecar/memories.md.template | 18 + .../expert-agent.template.md | 76 ++++ .../templates/expert-agent.template.md | 346 ------------------ .../templates/simple-agent.template.md | 270 +++----------- .../data/dietary-restrictions.csv | 0 .../data/macro-calculator.csv | 0 .../data/recipe-database.csv | 0 .../meal-prep-nutrition/steps/step-01-init.md | 0 .../steps/step-01b-continue.md | 0 .../steps/step-02-profile.md | 0 .../steps/step-03-assessment.md | 0 .../steps/step-04-strategy.md | 0 .../steps/step-05-shopping.md | 0 .../steps/step-06-prep-schedule.md | 0 .../templates/assessment-section.md | 0 .../templates/nutrition-plan.md | 0 .../templates/prep-schedule-section.md | 0 .../templates/profile-section.md | 0 .../templates/shopping-section.md | 0 .../templates/strategy-section.md | 0 .../examples}/meal-prep-nutrition/workflow.md | 0 35 files changed, 1428 insertions(+), 1558 deletions(-) delete mode 100644 src/modules/bmb/docs/agents/agent-compilation.md delete mode 100644 src/modules/bmb/docs/agents/agent-menu-patterns.md delete mode 100644 src/modules/bmb/docs/agents/expert-agent-architecture.md delete mode 100644 src/modules/bmb/docs/agents/simple-agent-architecture.md create mode 100644 src/modules/bmb/workflows/create-agent/data/agent-compilation.md create mode 100644 src/modules/bmb/workflows/create-agent/data/agent-menu-patterns.md create mode 100644 src/modules/bmb/workflows/create-agent/data/expert-agent-architecture.md create mode 100644 src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.agent.yaml create mode 100644 src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.md create mode 100644 src/modules/bmb/workflows/create-agent/data/simple-agent-architecture.md create mode 100644 src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template create mode 100644 src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template create mode 100644 src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent.template.md delete mode 100644 src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/data/dietary-restrictions.csv (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/data/macro-calculator.csv (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/data/recipe-database.csv (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/steps/step-01-init.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/steps/step-01b-continue.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/steps/step-02-profile.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/steps/step-03-assessment.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/steps/step-04-strategy.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/steps/step-05-shopping.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/steps/step-06-prep-schedule.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/templates/assessment-section.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/templates/nutrition-plan.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/templates/prep-schedule-section.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/templates/profile-section.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/templates/shopping-section.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/templates/strategy-section.md (100%) rename src/modules/bmb/workflows/{create-agent/data/reference/workflows => create-workflow/data/examples}/meal-prep-nutrition/workflow.md (100%) diff --git a/src/modules/bmb/docs/agents/agent-compilation.md b/src/modules/bmb/docs/agents/agent-compilation.md deleted file mode 100644 index 51651de5..00000000 --- a/src/modules/bmb/docs/agents/agent-compilation.md +++ /dev/null @@ -1,67 +0,0 @@ -# Agent Compilation: YAML to XML - -While your goal is to create a agent in the proper yaml format, its useful for you to understand that the YAML file will be compiled to a markdown file with XML in the file. This is the final format that the user will use the agents with an LLM. - -What is outlined here is what additional information is added to the agent so it will blend well with what you will create in the yaml file. - -## Auto-Injected Components - -### 1. Frontmatter - -**Injected automatically to compiled markdown file:** - -``` ---- -name: '{agent name from filename}' -description: '{title from metadata}' ---- - -You must fully embody this agent's persona... -``` - -**DO NOT add** frontmatter to your YAML source. - -### 2. Activation Block - -**Entire activation section is auto-generated:** -**DO NOT create** activation sections - compiler builds it from your critical_actions in the place where it is indicated with a comment in the next xml block. - -```xml - - 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 - Input resolution rules - -``` - -### 4. Rules Section - -**Auto-injected rules:** -**DO NOT add any of these rules to the yaml** - compiler handles it when building the markdown: - -- Always communicate in {communication_language} -- Stay in character until exit -- Menu triggers use asterisk (*) - NOT markdown -- Number all lists, use letters for sub-options -- Load files ONLY when executing menu items -- Written output follows communication style - -## Key Takeaways - -1. **Compiler handles boilerplate** - Focus on persona and logic -2. **Critical_actions become activation steps** - Just list your agent-specific needs -3. **These Menu items are auto included with every agent** - Every agent will have 4 menu items automatically added, so do not duplicate them with other menu items: - 1. [MH] Redisplay Menu Help - 2. [CH] Chat with the Agent about anything - 3. [PM] Start Party Mode - 4. [DA] Dismiss Agent -4. **Handlers auto-detected** - Only what you use is included -5. **Rules standardized** - Consistent behavior across agents - -**Your job:** Define persona, prompts, menu actions -**Compiler's job:** Activation, handlers, rules, help/exit, prefixes diff --git a/src/modules/bmb/docs/agents/agent-menu-patterns.md b/src/modules/bmb/docs/agents/agent-menu-patterns.md deleted file mode 100644 index b32788f2..00000000 --- a/src/modules/bmb/docs/agents/agent-menu-patterns.md +++ /dev/null @@ -1,295 +0,0 @@ -# BMAD Agent Menu Patterns - -Design patterns for agent menus in YAML source files. - -## Menu Structure - -Agents define menus in YAML, with triggers to know when to fire, a handler that knows the path or instruction of what the menu item does, and a description which is a display field for the agent. exec - -### Menu Item Rules - -- At a minimum, every menu item will have in the yaml the keys `trigger`, [handler], and `description`. A menu can also have an optional `data` key. - - the handler key will be either `action` or `exec`. -- The Description value always starts with a unique (for this agent) 2 letter code in brackets along with the display text for the menu item. - - The 2 letter code CANNOT be the following reserved codes: [MH], [CH], [PM], [DA] -- the trigger is always in the format `XY or fuzzy match on action-name` - XY being the items 2 letter code and action-name being what user will generally request by reading the description - -```yaml -menu: - - trigger: AN or fuzzy match on action-name - [handler]: [value] - data: optional field reference to a file to pass to the handlers workflow, some workflows take data inputs - description: '[AN] Menu display for Action Name' -``` - -## Handler Types - -### 1. Action Handler (Prompts & Inline) - -For agents that are not part of a module or its a very simple operation that can be defined within the agent file, action is used. - - -**Reference to Prompt ID:** - -```yaml -prompts: - - id: analyze-code - content: | - - Analyze the provided code for patterns and issues. - - - - 1. Identify code structure - 2. Check for anti-patterns - 3. Suggest improvements - - -menu: - - trigger: analyze - action: '#analyze-code' - description: 'Analyze code patterns' -``` - - -**Inline Instruction:** - -```yaml -menu: - - trigger: quick-check - action: | - - Analyze the provided code for patterns and issues. - - - - 1. Identify code structure - 2. Check for anti-patterns - 3. Suggest improvements - - description: 'Quick syntax check' -``` - -**When to Use:** - -- Simple/Expert agents with self-contained operations -- `#id` for complex, multi-step prompts -- Inline text for simple, one-line instructions - -### 2. Workflow Handler - -For module agents referencing module workflows (muti-step complex workflows loaded on demand). - -```yaml -menu: - - trigger: CP or fuzzy match on create-prd - exec: '{project-root}/_bmad/bmm/workflows/prd/workflow.md' - description: '[CP] Create Product Requirements Document (PRD)' - - - trigger: GB or fuzzy match on guided-brainstorming - exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml' - description: '[GB] Guided brainstorming session' - - # Placeholder for unimplemented workflows - - trigger: FF or fuzzy match on future-feature - exec: 'todo' - description: '[FF] Coming soon Future Feature' -``` - -**When to Use:** - -- Module agents with workflow integration -- Multi-step document generation -- Complex interactive processes -- Use "todo" for planned but unimplemented features - -### 3. Exec Handler - -For executing tasks directly. - -```yaml -menu: - - trigger: validate - exec: '{project-root}/_bmad/core/tasks/validate-workflow.xml' - description: 'Validate document structure' - - - trigger: advanced-elicitation - exec: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' - description: 'Advanced elicitation techniques' -``` - -**When to Use:** - -- Single-operation tasks -- Core system operations -- Utility functions - -### 5. Data Handler - -Universal attribute for supplementary information. - -```yaml -menu: - - trigger: TS or fuzzy match team-standup or daily standup - exec: '{project-root}/_bmad/bmm/tasks/team-standup.md' - data: '{project-root}/_bmad/_config/agent-manifest.csv' - description: '[TS] Run team standup' - - - trigger: AM or fuzzy match on analyze-metrics - action: 'Analyze these metrics and identify trends' - data: '{project-root}/_data/metrics.json' - description: '[AM] Analyze performance metrics' -``` - -**When to Use:** - -- Add to ANY handler type -- Reference data files (CSV, JSON, YAML) -- Provide context for operations - -## Platform-Specific Menus - -Control visibility based on deployment target: - -```yaml -menu: - - trigger: git-flow - exec: '{project-root}/_bmad/bmm/tasks/git-flow.xml' - description: 'Git workflow operations' - ide-only: true # Only in IDE environments - - - trigger: advanced-elicitation - exec: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' - description: 'Advanced elicitation' - web-only: true # Only in web bundles -``` - -## Prompts Section (generally for agents that are not using external workflows) - -### Prompt Structure - -```yaml -prompts: - - id: unique-identifier - content: | - What the prompt achieves - - Step 1: Foo - Step 2: Bar - ... - - - etc... -``` - -### Semantic XML Tags in Prompts - -Use XML tags to structure prompt content such as: - -- `` - What to do -- `` - Step-by-step approach -- `` - Expected results -- `` - Sample outputs - -## Path Variables - -### Always Use Variables - -```yaml -# GOOD - Portable paths -exec: "{project-root}/_bmad/core/tasks/validate.xml" -data: "{project-root}/_data/metrics.csv" - -# BAD - Hardcoded paths -exec: "../../../core/tasks/validate.xml" -``` - -### Available Variables - -- `{project-root}` - Project root directory -- `{output_folder}` - Document output location -- `{user_name}` - User's name from config -- `{communication_language}` - Language preference - -## Complete Examples - -### Simple Agent Menu - -```yaml -prompts: - - id: format-code - content: | - - Format the provided code according to style guidelines. - - - Apply: - - Consistent indentation - - Proper spacing - - Clear naming conventions - -menu: - - trigger: format - action: '#format-code' - description: 'Format code to style guidelines' - - - trigger: lint - action: 'Check code for common issues and anti-patterns' - description: 'Lint code for issues' - - - trigger: suggest-improvements - action: > - Suggest improvements for code that is not yet comitted: - - style improvements - - deviations from **/project-context.md - description: 'Suggest improvements' -``` - -### Expert Agent Menu - -```yaml -critical_actions: - - 'Load ./memories.md' - - 'Follow ./instructions.md' - - 'ONLY access ./' - -prompts: - - id: reflect - content: | - Guide {{user_name}} through reflection on recent entries. - Reference patterns from memories.md naturally. - -menu: - - trigger: write - action: '#reflect' - description: 'Write journal entry' - - - trigger: save - action: 'Update ./memories.md with session insights' - description: "Save today's session" - - - trigger: patterns - action: 'Analyze recent entries for recurring themes' - description: 'View patterns' -``` - -### Module Agent Menu - -```yaml -menu: - - trigger: workflow-init - exec: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.md' - description: 'Initialize workflow path (START HERE)' - - - trigger: brainstorm - exec: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.md' - description: 'Guided brainstorming' - - - trigger: prd - exec: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.md' - description: 'Create PRD' - - - trigger: architecture - exec: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.md' - description: 'Design architecture' -``` diff --git a/src/modules/bmb/docs/agents/expert-agent-architecture.md b/src/modules/bmb/docs/agents/expert-agent-architecture.md deleted file mode 100644 index 4f9fd970..00000000 --- a/src/modules/bmb/docs/agents/expert-agent-architecture.md +++ /dev/null @@ -1,212 +0,0 @@ -# Expert Agent Architecture - -Domain-specific agents with persistent memory, sidecar files, and restricted access patterns. The main difference between a simple agent and an Expert agent, is the expert has its own collection of external files in a sidecar folder that can include files to record memories, and it can have files for prompts, skills and workflows specific to the agent that manus can reference to load and exec on demand. - -## When to Use - -- Personal assistants (journal keeper, diary companion) -- Specialized domain experts (legal advisor, medical reference) -- Agents that need to remember past interactions -- Agents with restricted file system access (privacy/security) -- Long-term relationship agents that learn about users - -## File Structure - -``` -{agent-name}/ -├── {agent-name}.agent.yaml # Main agent definition -└── {agent-name}-sidecar/ # Supporting files - ├── instructions.md # Private directives - ├── memories.md # Persistent memory - ├── knowledge/ # Domain-specific resources - │ └── README.md - └── [custom files] # Agent-specific resources -``` - -## YAML Structure - -The YAML structure of the agent file itself is the same as every other agent, but generally will have something like these 3 items added to the critical_actions: - - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights' - - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols' - - 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space' - -## Key Components - -### Sidecar Files (CRITICAL) - -Expert agents use companion files for persistence and domain knowledge: - -**memories.md** - Persistent user context will be set up similar to as follows, of course with relevant sections that make sense. - -```markdown -# Agent Memory Bank - -## User Preferences - - - -## Session History - - - -## Personal Notes - - -``` - -**instructions.md** - Private directives - -```markdown -# Agent Private Instructions - -## Core Directives - -- Maintain character consistency -- Domain boundaries: {specific domain} -- Access restrictions: Only sidecar folder - -## Special Rules - - -``` - -**knowledge/** - Domain resources - -```markdown -# Agent Knowledge Base - -Add domain-specific documentation here. -``` - -### Critical Actions - -**MANDATORY for expert agents** - These load sidecar files at activation: - -```yaml -critical_actions: - - 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights' - - 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols' - - 'ONLY read/write files in ./{sidecar}/ - this is our private space' -``` - -**Key patterns:** - -- **COMPLETE file loading** - Forces full file read, not partial -- **Domain restrictions** - Limits file access for privacy/security -- **Memory integration** - Past context becomes part of current session -- **Protocol adherence** - Ensures consistent behavior - -## What Gets Injected at Compile Time - -Same as simple agents, PLUS: - -1. **Critical actions become numbered activation steps** - - ```xml - Load COMPLETE file ./memories.md... - Load COMPLETE file ./instructions.md... - ONLY read/write files in ./... - ``` - -2. **Sidecar files copied during installation** - - Entire sidecar folder structure preserved - - Relative paths maintained - - Files ready for agent use - -## Reference Example - -See: [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) - -Features demonstrated: - -- Complete sidecar structure (memories, instructions, breakthroughs) -- Critical actions for loading persistent context -- Domain restrictions for privacy -- Pattern recognition and memory recall -- Handlebars-based personalization -- Menu actions that update sidecar files - -## Installation - -```bash -# Copy entire folder to your project -cp -r /path/to/journal-keeper/ _bmad/custom/agents/ - -# Install with personalization -bmad agent-install -``` - -The installer: - -1. Detects expert agent (folder with .agent.yaml) -2. Prompts for personalization -3. Compiles agent YAML to XML-in-markdown -4. **Copies sidecar files to installation target** -5. Creates IDE slash commands -6. Saves source for reinstallation - -## Memory Patterns - -### Accumulative Memory - -```yaml -menu: - - trigger: save - action: "Update ./sidecar/memories.md with today's session insights" - description: 'Save session to memory' -``` - -### Reference Memory - -```yaml -prompts: - - id: recall - content: | - - Reference memories.md naturally: - "Last week you mentioned..." or "I notice a pattern..." - -``` - -### Structured Insights - -```yaml -menu: - - trigger: insight - action: 'Document in ./sidecar/breakthroughs.md with date, context, significance' - description: 'Record meaningful insight' -``` - -## Domain Restriction Patterns that can be applied - -### Single Folder Access - -```yaml -critical_actions: - - 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS' -``` - -### User Space Access - -If there were a private journal agent, you might want it to have something like this: -```yaml -critical_actions: - - 'ONLY access files in {user-folder}/journals/ - private space' -``` - -### Read-Only Access - -```yaml -critical_actions: - - 'Load knowledge from ./knowledge/ but NEVER modify' - - 'Write ONLY to ./sessions/' -``` - -## Best Practices - -1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY -2. **Enforce domain restrictions** - Clear boundaries prevent scope creep= -3. **Design for memory growth** - Structure sidecar files for accumulation -4. **Reference past naturally** - Don't dump memory, weave it into conversation -5. **Separate concerns** - Memories, instructions, knowledge in distinct files -6. **Include privacy features** - Users trust expert agents with personal data diff --git a/src/modules/bmb/docs/agents/simple-agent-architecture.md b/src/modules/bmb/docs/agents/simple-agent-architecture.md deleted file mode 100644 index 44cfddfc..00000000 --- a/src/modules/bmb/docs/agents/simple-agent-architecture.md +++ /dev/null @@ -1,241 +0,0 @@ -# Agent Architecture - -All agents follow these basic guidelines to define their YAML. - -## YAML Structure - -```yaml -agent: - metadata: - id: _bmad/agents/{agent-name}/{agent-name}.md - name: 'Persona Name' - title: 'Agent Title' - icon: 'emoji' - module: stand-alone || module-code (like bmm) - - persona: - role: | - First-person description of primary function (1-2 sentences) - - identity: | - Background, experience, specializations in first-person (2-5 sentences) - - communication_style: - - principles: - - Core belief or methodology - - Another guiding principle - - Values that shape decisions - - prompts: - - id: main-action - content: | - - What this prompt does - - - - 1. Step one - {{#if detailed_mode}} - 2. Additional detailed step - {{/if}} - 3. Final step - - - - id: another-action - content: | - Another reusable prompt template - - menu: - - trigger: inline - action: 'Direct inline prompt text' - description: 'Execute inline action' - - - multi: "[DF] Do Foo or start [CH] Chat with expert" - triggers: - - do-foo - - input: [DF] or fuzzy match on do foo - - action: '#main-action' - - data: what is being discussed or suggested with the command, along with custom party custom agents if specified - - type: action - - expert-chat: - - input: [CH] or fuzzy match validate agent - - action: agent responds as expert based on its persona to converse - - type: action - - install_config: - compile_time_only: true - description: 'Personalize your agent' - questions: - - var: style_choice - prompt: 'Preferred communication style?' - type: choice - options: - - label: 'Professional' - value: 'professional' - - label: 'Casual' - value: 'casual' - default: 'professional' - - - var: detailed_mode - prompt: 'Enable detailed explanations?' - type: boolean - default: true - - - var: custom_variable - prompt: 'Your custom text' - type: text - default: '' -``` - -## Key Components - -### Metadata - -- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone) -- **name**: Agent's persona name displayed to users -- **title**: Professional role/function -- **icon**: Single emoji for visual identification -- **type**: `simple` - identifies agent category - -### Persona (First-Person Voice) - -- **role**: Primary expertise in 1-2 sentences -- **identity**: Background and specializations (2-5 sentences) -- **communication_style**: HOW the agent interacts, including conditional variations -- **principles**: Array of core beliefs (start with action verbs) - -### Prompts with IDs - -Reusable prompt templates referenced by `#id`: - -```yaml -prompts: - - id: analyze-code - content: | - - Analyze the provided code for patterns - -``` - -Menu items reference these: - -```yaml -menu: - - trigger: analyze - action: '#analyze-code' - description: 'Analyze code patterns' -``` - -### Menu Actions - -Two forms of action handlers: - -1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content -2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly - -### Install Config (Compile-Time Customization) - -Questions asked during `bmad agent-install`: - -**Question Types:** - -- `choice` - Multiple choice selection -- `boolean` - Yes/no toggle -- `text` - Free-form text input - -**Variables become available in Handlebars:** - -```yaml -{{#if variable_name}} -Content when true -{{/if}} - -{{#if variable_name == "value"}} -Content when equals value -{{/if}} - -{{#unless variable_name}} -Content when false -{{/unless}} -``` - -## What Gets Injected at Compile Time - -The `tools/cli/lib/agent/compiler.js` automatically adds: - -1. **YAML Frontmatter** - - ```yaml - --- - name: 'agent name' - description: 'Agent Title' - --- - ``` - -2. **Activation Block** - - Load persona step - - Load core config for {user_name}, {communication_language} - - Agent-specific critical_actions as numbered steps - - Menu display and input handling - - Menu handlers (action/workflow/exec/tmpl) based on usage - - Rules section - -3. **Auto-Injected Menu Items** - - `*help` always first - - `*exit` always last - -4. **Trigger Prefixing** - - Triggers without `*` get it added automatically - -## Reference Example - -See: [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) - -Features demonstrated: - -- Handlebars conditionals for style variations -- Multiple prompt templates with semantic XML tags -- Install config with choice, boolean, and text questions -- Menu items using both `#id` references and inline actions - -## Installation - -```bash -# Copy to your project -cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/ - -# Create custom.yaml and install -echo "code: my-agent -name: My Agent -default_selected: true" > custom.yaml - -npx bmad-method install -# or: bmad install -``` - -The installer: - -1. Prompts for personalization (name, preferences) -2. Processes Handlebars templates with your answers -3. Compiles YAML to XML-in-markdown -4. Creates IDE slash commands -5. Saves source for reinstallation - -## Best Practices - -1. **Use first-person voice** in all persona elements -2. **Keep prompts focused** - one clear purpose per prompt -3. **Leverage Handlebars** for user customization without code changes -4. **Provide sensible defaults** in install_config -5. **Use semantic XML tags** in prompt content for clarity -6. **Test all conditional paths** before distribution - -## Validation Checklist - -- [ ] Valid YAML syntax -- [ ] All metadata fields present (id, name, title, icon, type) -- [ ] Persona complete (role, identity, communication_style, principles) -- [ ] Prompts have unique IDs -- [ ] Install config questions have defaults -- [ ] File named `{agent-name}.agent.yaml` diff --git a/src/modules/bmb/workflows/create-agent/data/agent-compilation.md b/src/modules/bmb/workflows/create-agent/data/agent-compilation.md new file mode 100644 index 00000000..e1a4028e --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/agent-compilation.md @@ -0,0 +1,273 @@ +# Agent Compilation: YAML Source → Final Agent + +> **For the LLM running this workflow:** This document explains what the compiler adds. When building agents, focus on the YAML structure defined here—do NOT add things the compiler handles automatically. +> +> **Example reference:** Compare `{workflow_path}/data/reference/module-examples/architect.agent.yaml` (source, 32 lines) with `architect.md` (compiled, 69 lines) to see what the compiler adds. + +--- + +## Quick Overview + +You write: **YAML source file** (`agent-name.agent.yaml`) +Compiler produces: **Markdown with XML** (`agent-name.md`) for LLM consumption + +The compiler transforms your clean YAML into a fully functional agent by adding: +- Frontmatter (name, description) +- XML activation block with numbered steps +- Menu handlers (workflow, exec, action) +- Auto-injected menu items (MH, CH, PM, DA) +- Rules section + +--- + +## What YOU Provide (YAML Source) + +Your YAML contains ONLY these sections: + +```yaml +agent: + metadata: + id: "_bmad/..." + name: "Persona Name" + title: "Agent Title" + icon: "🔧" + module: "stand-alone" or "bmm" or "cis" or "bmgd" + + persona: + role: "First-person role description" + identity: "Background and specializations" + communication_style: "How the agent speaks" + principles: + - "Core belief or methodology" + + critical_actions: # Optional - for Expert agents only + - "Load ./sidecar/memories.md" + - "Load ./sidecar/instructions.md" + - "ONLY access ./sidecar/" + + prompts: # Optional - for Simple/Expert agents + - id: prompt-name + content: | + Prompt content + + menu: # Your custom items only + - trigger: XX or fuzzy match on command-name + workflow: "path/to/workflow.yaml" # OR + exec: "path/to/file.md" # OR + action: "#prompt-id" + description: "[XX] Command description" +``` + +--- + +## What COMPILER Adds (DO NOT Include) + +### 1. Frontmatter +```markdown +--- +name: "architect" +description: "Architect" +--- +``` +**DO NOT add** frontmatter to your YAML. + +### 2. XML Activation Block +```xml + + 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 + Input resolution rules + ... + ... + +``` +**DO NOT create** activation sections—the compiler builds them. + +### 3. Auto-Injected Menu Items +Every agent gets these 4 items automatically. **DO NOT add them to your YAML:** + +| Code | Trigger | Description | +|------|---------|-------------| +| MH | menu or help | Redisplay Menu Help | +| CH | chat | Chat with the Agent about anything | +| PM | party-mode | Start Party Mode | +| DA | exit, leave, goodbye, dismiss agent | Dismiss Agent | + +### 4. Menu Handlers +```xml + + When menu item has: workflow="path/to/workflow.yaml" + → Load workflow.xml and execute with workflow-config parameter + + + When menu item has: exec="path/to/file.md" + → Load and execute the file at that path + +``` +**DO NOT add** handlers—the compiler detects and generates them. + +--- + +## Before/After Example: Architect Agent + +### Source: `architect.agent.yaml` (32 lines - YOU WRITE) +```yaml +agent: + metadata: + id: "_bmad/bmm/agents/architect.md" + name: Winston + title: Architect + icon: 🏗️ + module: bmm + + persona: + role: System Architect + Technical Design Leader + identity: Senior architect with expertise in distributed systems... + communication_style: "Speaks in calm, pragmatic tones..." + principles: | + - User journeys drive technical decisions... + + menu: + - trigger: WS or fuzzy match on workflow-status + workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml" + description: "[WS] Get workflow status..." + + - trigger: CA or fuzzy match on create-architecture + exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md" + description: "[CA] Create an Architecture Document" + + - trigger: IR or fuzzy match on implementation-readiness + exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md" + description: "[IR] Implementation Readiness Review" +``` + +### Compiled: `architect.md` (69 lines - COMPILER PRODUCES) +```markdown +--- +name: "architect" +description: "Architect" +--- + +You must fully embody this agent's persona... + +```xml + + + Load persona from this current agent file (already in context) + 🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT... + Remember: user's name is {user_name} + Show greeting using {user_name} from config... + STOP and WAIT for user input... + On user input: Number → execute menu item[n]... + When executing a menu item: Check menu-handlers section... + + + + ... + ... + + + + + ALWAYS communicate in {communication_language} + Stay in character until exit selected + Display Menu items as the item dictates... + Load files ONLY when executing menu items... + + + + + System Architect + Technical Design Leader + Senior architect with expertise... + Speaks in calm, pragmatic tones... + - User journeys drive technical decisions... + + + + [MH] Redisplay Menu Help + [CH] Chat with the Agent about anything + [WS] Get workflow status... ← YOUR CUSTOM ITEMS + [CA] Create an Architecture Document + [IR] Implementation Readiness Review + [PM] Start Party Mode + [DA] Dismiss Agent + + +``` +**Key additions by compiler:** Frontmatter, activation block, handlers, rules, MH/CH/PM/DA menu items. + +--- + +## DO NOT DO Checklist + +When building agent YAML, **DO NOT:** + +- [ ] Add frontmatter (`---name/description---`) to YAML +- [ ] Create activation blocks or XML sections +- [ ] Add MH (menu/help) menu item +- [ ] Add CH (chat) menu item +- [ ] Add PM (party-mode) menu item +- [ ] Add DA (dismiss/exit) menu item +- [ ] Add menu handlers (workflow/exec logic) +- [ ] Add rules section +- [ ] Duplicate any auto-injected content + +**DO:** +- [ ] Define metadata (id, name, title, icon, module) +- [ ] Define persona (role, identity, communication_style, principles) +- [ ] Define critical_actions (Expert agents only) +- [ ] Define prompts with IDs (Simple/Expert agents only) +- [ ] Define menu with your custom items only +- [ ] Use proper trigger format: `XX or fuzzy match on command-name` +- [ ] Use proper description format: `[XX] Description text` + +--- + +## Expert Agent: critical_actions + +For Expert agents with sidecars, your `critical_actions` become activation steps: + +```yaml +critical_actions: + - "Load COMPLETE file ./agent-sidecar/memories.md" + - "Load COMPLETE file ./agent-sidecar/instructions.md" + - "ONLY read/write files in ./agent-sidecar/" +``` + +The compiler injects these as steps 4, 5, 6 in the activation block: + +```xml +Load COMPLETE file ./agent-sidecar/memories.md +Load COMPLETE file ./agent-sidecar/instructions.md +ONLY read/write files in ./agent-sidecar/ +ALWAYS communicate in {communication_language} +``` + +--- + +## Division of Responsibilities + +| Aspect | YOU Provide (YAML) | COMPILER Adds | +|--------|-------------------|---------------| +| Agent identity | metadata + persona | Wrapped in XML | +| Memory/actions | critical_actions | Inserted as activation steps | +| Prompts | prompts with IDs | Referenced by menu actions | +| Menu items | Your custom commands only | + MH, CH, PM, DA (auto) | +| Activation | — | Full XML block with handlers | +| Rules | — | Standardized rules section | +| Frontmatter | — | name/description header | + +--- + +## Quick Reference for LLM + +- **Focus on:** Clean YAML structure, persona definition, custom menu items +- **Ignore:** What happens after compilation—that's the compiler's job +- **Remember:** Every agent gets MH, CH, PM, DA automatically—don't add them +- **Expert agents:** Use `critical_actions` for sidecar file loading +- **Module agents:** Use `workflow:` or `exec:` references, not inline actions diff --git a/src/modules/bmb/workflows/create-agent/data/agent-menu-patterns.md b/src/modules/bmb/workflows/create-agent/data/agent-menu-patterns.md new file mode 100644 index 00000000..30e7ab5d --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/agent-menu-patterns.md @@ -0,0 +1,233 @@ +# Agent Menu Patterns + +Technical reference for creating agent menu items in YAML. + +--- + +## Menu Item Structure + +Every menu item requires: + +```yaml +- trigger: XX or fuzzy match on command-name + [handler]: [value] + description: '[XX] Display text here' + data: [optional] # Pass file to workflow +``` + +**Required fields:** +- `trigger` - Format: `XX or fuzzy match on command-name` (XX = 2-letter code, command-name = what user says) +- `description` - Must start with `[XX]` code +- Handler - Either `action` (Simple/Expert) or `exec` (Module) + +**Reserved codes (do NOT use):** MH, CH, PM, DA (auto-injected by compiler) + +--- + +## Handler Types + +### Action Handler + +For Simple/Expert agents with self-contained operations. + +```yaml +# Reference prompt by ID +- trigger: WC or fuzzy match on write-commit + action: '#write-commit' + description: '[WC] Write commit message' + +# Direct inline instruction +- trigger: QC or fuzzy match on quick-commit + action: 'Generate commit message from diff' + description: '[QC] Quick commit from diff' +``` + +**When to use:** Simple/Expert agents. Use `#id` for complex multi-step prompts, inline text for simple operations. + +### Workflow Handler + +For module agents referencing external workflow files. + +```yaml +- trigger: CP or fuzzy match on create-prd + exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md' + description: '[CP] Create Product Requirements Document' + +- trigger: GB or fuzzy match on brainstorm + exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml' + description: '[GB] Guided brainstorming session' + +# Planned but unimplemented +- trigger: FF or fuzzy match on future-feature + exec: 'todo' + description: '[FF] Coming soon' +``` + +**When to use:** Module agents, multi-step workflows, complex processes. Use `exec: 'todo'` for unimplemented features. + +### Data Parameter (Optional) + +Add to ANY handler to pass files to the workflow/action. + +```yaml +- trigger: TS or fuzzy match on team-standup + exec: '{project-root}/_bmad/bmm/tasks/team-standup.md' + data: '{project-root}/_bmad/_config/agent-manifest.csv' + description: '[TS] Run team standup' + +- trigger: AM or fuzzy match on analyze-metrics + action: 'Analyze these metrics for trends' + data: '{project-root}/_data/metrics.json' + description: '[AM] Analyze metrics' +``` + +**When to use:** Workflow needs input file, action processes external data. + +--- + +## Prompts Section + +For Simple/Expert agents, define reusable prompts referenced by `action: '#id'`. + +```yaml +prompts: + - id: analyze-code + content: | + Analyze code for patterns + 1. Identify structure 2. Check issues 3. Suggest improvements + +menu: + - trigger: AC or fuzzy match on analyze-code + action: '#analyze-code' + description: '[AC] Analyze code patterns' +``` + +**Common XML tags:** ``, ``, ``, `` + +--- + +## Path Variables + +**Always use variables, never hardcoded paths:** + +```yaml +# ✅ CORRECT +exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml' +data: '{project-root}/_data/metrics.csv' + +# ❌ WRONG +exec: '../../../core/workflows/brainstorming/workflow.yaml' +``` + +**Available variables:** +- `{project-root}` - Project root directory +- `{output_folder}` - Document output location +- `{user_name}` - User's name from config +- `{communication_language}` - Language preference + +**Expert Agent sidecar paths:** +```yaml +# Agent YAML referencing sidecar files +action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights' +``` + +--- + +## Creation Thought Process + +When creating menu items, follow this sequence: + +1. **User capability** → "Check code for issues" +2. **Choose code** → `LC` (Lint Code) +3. **Write trigger** → `LC or fuzzy match on lint-code` +4. **Choose handler** → `action` (inline is simple enough) +5. **Write description** → `[LC] Lint code for issues` + +Result: +```yaml +- trigger: LC or fuzzy match on lint-code + action: 'Check code for common issues and anti-patterns' + description: '[LC] Lint code for issues' +``` + +--- + +## Complete Examples + +### Simple Agent Menu + +```yaml +prompts: + - id: format-code + content: | + Format code to style guidelines + 1. Indentation 2. Spacing 3. Naming + +menu: + - trigger: FC or fuzzy match on format-code + action: '#format-code' + description: '[FC] Format code to style guidelines' + + - trigger: LC or fuzzy match on lint-code + action: 'Check code for common issues and anti-patterns' + description: '[LC] Lint code for issues' + + - trigger: SI or fuzzy match on suggest-improvements + action: 'Suggest improvements following project-context.md guidelines' + description: '[SI] Suggest improvements' +``` + +### Expert Agent Menu + +```yaml +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/' + +prompts: + - id: guided-entry + content: | + Guide through journal entry + +menu: + - trigger: WE or fuzzy match on write-entry + action: '#guided-entry' + description: '[WE] Write journal entry' + + - trigger: QC or fuzzy match on quick-capture + action: 'Save entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md' + description: '[QC] Quick capture' + + - trigger: SM or fuzzy match on save-memory + action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights' + description: '[SM] Save session' +``` + +### Module Agent Menu + +```yaml +menu: + - trigger: WI or fuzzy match on workflow-init + exec: '{project-root}/_bmad/bmm/workflows/workflow-status/workflow.md' + description: '[WI] Initialize workflow path' + + - trigger: BS or fuzzy match on brainstorm + exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml' + description: '[BS] Guided brainstorming' + + - trigger: CP or fuzzy match on create-prd + exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md' + description: '[CP] Create PRD' +``` + +--- + +## Key Patterns to Remember + +1. **Triggers always:** `XX or fuzzy match on command-name` +2. **Descriptions always:** `[XX] Display text` +3. **Reserved codes:** MH, CH, PM, DA (never use) +4. **Codes must be:** Unique within each agent +5. **Paths always:** `{project-root}` variable, never relative +6. **Expert sidecars:** `{project-root}/_bmad/_memory/{sidecar-folder}/` diff --git a/src/modules/bmb/workflows/create-agent/data/expert-agent-architecture.md b/src/modules/bmb/workflows/create-agent/data/expert-agent-architecture.md new file mode 100644 index 00000000..b442a0e6 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/expert-agent-architecture.md @@ -0,0 +1,236 @@ +# Expert Agent Architecture + +Agents with a sidecar folder for persistent memory, custom workflows, and restricted file access. + +--- + +## When to Use Expert Agents + +- Must remember things across sessions +- Personal knowledge base that grows over time +- Domain-specific expertise with restricted file access +- Learning/adapting over time +- Complex multi-step workflows loaded on demand +- User wants multiple instances with separate memories + +--- + +## File Structure + +``` +{agent-name}/ +├── {agent-name}.agent.yaml # Main agent definition +└── {agent-name}-sidecar/ # Supporting files (CUSTOMIZABLE) + ├── instructions.md # Startup protocols (common) + ├── memories.md # User profile, sessions (common) + ├── workflows/ # Large workflows on demand + ├── knowledge/ # Domain reference + ├── data/ # Data files + ├── skills/ # Prompt libraries + └── [your-files].md # Whatever needed +``` + +**Naming:** +- Agent file: `{agent-name}.agent.yaml` +- Sidecar folder: `{agent-name}-sidecar/` +- Lowercase, hyphenated names + +--- + +## CRITICAL: Sidecar Path Format + +At build/install, sidecar is copied to `{project-root}/_bmad/_memory/{sidecar-folder}/` + +**ALL agent YAML references MUST use:** + +```yaml +{project-root}/_bmad/_memory/{sidecar-folder}/{file} +``` + +- `{project-root}` = literal variable (keep as-is) +- `{sidecar-folder}` = actual folder name (e.g., `journal-keeper-sidecar`) + +```yaml +# ✅ CORRECT +critical_actions: + - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md" + - "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/" + +menu: + - action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights" +``` + +```yaml +# ❌ WRONG +critical_actions: + - "Load ./journal-keeper-sidecar/memories.md" + - "Load /Users/absolute/path/memories.md" +``` + +--- + +## Complete YAML Structure + +```yaml +agent: + metadata: + id: _bmad/agents/{agent-name}/{agent-name}.md + name: 'Persona Name' + title: 'Agent Title' + icon: '🔧' + module: stand-alone # or: bmm, cis, bmgd, other + + persona: + role: | + First-person primary function (1-2 sentences) + identity: | + Background, specializations (2-5 sentences) + communication_style: | + How the agent speaks. Include memory reference patterns. + principles: + - Core belief or methodology + - Another guiding principle + + 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}/' + + prompts: + - id: main-action + content: | + What this does + 1. Step one 2. Step two + + menu: + - trigger: XX or fuzzy match on command + action: '#main-action' + description: '[XX] Command description' + + - trigger: SM or fuzzy match on save + action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights' + description: '[SM] Save session' +``` + +--- + +## Component Details + +### critical_actions (MANDATORY) + +Become activation steps when compiled. Always include: + +```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}/' +``` + +### Sidecar Files (Customizable) + +**Common patterns:** +- `instructions.md` - Startup protocols, domain boundaries +- `memories.md` - User profile, session notes, patterns + +**Fully customizable - add what your agent needs:** +- `workflows/` - Large workflows for on-demand loading +- `knowledge/` - Domain reference material +- `data/` - Data files +- `skills/` - Prompt libraries + +**Template examples:** `{workflow_path}/templates/expert-agent-template/expert-agent-sidecar/` + +### Menu Actions + +All action types available, including sidecar updates: + +```yaml +# Prompt reference +- trigger: XX or fuzzy match on command + action: '#prompt-id' + description: '[XX] Description' + +# Inline that updates sidecar +- trigger: SM or fuzzy match on save + action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights' + description: '[SM] Save session' +``` + +### Memory Reference Patterns + +Reference past interactions naturally in persona and prompts: + +```yaml +communication_style: | + I reference past naturally: "Last time you mentioned..." or "I've noticed patterns..." +``` + +--- + +## Domain Restriction Patterns + +```yaml +# Single folder (most common) +- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/' + +# Read-only knowledge +- 'Load from {project-root}/_bmad/_memory/{sidecar-folder}/knowledge/ but NEVER modify' +- 'Write ONLY to {project-root}/_bmad/_memory/{sidecar-folder}/memories.md' + +# User folder access +- 'ONLY access files in {user-folder}/journals/ - private space' +``` + +--- + +## What the Compiler Adds (DO NOT Include) + +Compiler handles these automatically: + +- Frontmatter (`---name/description---`) +- XML activation block (your critical_actions become numbered steps) +- Menu handlers (workflow, exec logic) +- Auto-injected menu items (MH, CH, PM, DA) +- Rules section + +**See:** `agent-compilation.md` for compilation details. + +--- + +## Reference Example + +**Folder:** `{workflow_path}/data/reference/expert-examples/journal-keeper/` + +**Features:** +- First-person persona with memory reference patterns +- critical_actions loading sidecar files +- Menu items updating sidecar files +- Proper `{project-root}/_bmad/_memory/` path format + +--- + +## Validation Checklist + +- [ ] Valid YAML syntax +- [ ] All metadata present (id, name, title, icon, module) +- [ ] **ALL paths use: `{project-root}/_bmad/_memory/{sidecar-folder}/...`** +- [ ] `{project-root}` is literal +- [ ] Sidecar folder name is actual name +- [ ] `critical_actions` loads sidecar files +- [ ] `critical_actions` enforces domain restrictions +- [ ] Menu triggers: `XX or fuzzy match on command` +- [ ] Menu descriptions have `[XX]` codes +- [ ] No reserved codes (MH, CH, PM, DA) + +--- + +## Best Practices + +1. **critical_actions MANDATORY** - Load sidecar files explicitly +2. **Enforce domain restrictions** - Clear boundaries +3. **Reference past naturally** - Don't dump memory +4. **Design for growth** - Structure for accumulation +5. **Separate concerns** - Memories, instructions, knowledge distinct +6. **Include privacy** - Users trust with personal data +7. **First-person voice** - In all persona elements diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml index ba2ec85f..9a5f9931 100644 --- a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml +++ b/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml @@ -21,9 +21,9 @@ agent: - Reflection transforms experience into wisdom critical_actions: - - "Load COMPLETE file ./journal-keeper-sidecar/memories.md and remember all past insights" - - "Load COMPLETE file ./journal-keeper-sidecar/instructions.md and follow ALL journaling protocols" - - "ONLY read/write files in ./journal-keeper-sidecar/ - this is our private space" + - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md and remember all past insights" + - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols" + - "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/ - this is our private space" - "Track mood patterns, recurring themes, and breakthrough moments" - "Reference past entries naturally to show continuity" @@ -116,38 +116,38 @@ agent: A week is long enough to see patterns, short enough to remember details. menu: - - trigger: write + - trigger: WE or fuzzy match on write action: "#guided-entry" - description: "Write today's journal entry" + description: "[WE] Write today's journal entry" - - trigger: quick - action: "Save a quick, unstructured entry to ./journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed" - description: "Quick capture without prompts" + - trigger: QC or fuzzy match on quick + action: "Save a quick, unstructured entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed" + description: "[QC] Quick capture without prompts" - - trigger: mood + - trigger: MC or fuzzy match on mood action: "#mood-check" - description: "Track your current emotional state" + description: "[MC] Track your current emotional state" - - trigger: patterns + - trigger: PR or fuzzy match on patterns action: "#pattern-reflection" - description: "See patterns in your recent entries" + description: "[PR] See patterns in your recent entries" - - trigger: gratitude + - trigger: GM or fuzzy match on gratitude action: "#gratitude-moment" - description: "Capture today's gratitudes" + description: "[GM] Capture today's gratitudes" - - trigger: weekly + - trigger: WR or fuzzy match on weekly action: "#weekly-reflection" - description: "Reflect on the past week" + description: "[WR] Reflect on the past week" - - trigger: insight - action: "Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md with date and significance" - description: "Record a meaningful insight" + - trigger: IB or fuzzy match on insight + action: "Document this breakthrough in {project-root}/_bmad/_memory/journal-keeper-sidecar/breakthroughs.md with date and significance" + description: "[IB] Record a meaningful insight" - - trigger: read-back - action: "Load and share entries from ./journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth" - description: "Review past entries" + - trigger: RE or fuzzy match on read-back + action: "Load and share entries from {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth" + description: "[RE] Review past entries" - - trigger: save - action: "Update ./journal-keeper-sidecar/memories.md with today's session insights and emotional markers" - description: "Save what we discussed today" + - trigger: SM or fuzzy match on save + action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with today's session insights and emotional markers" + description: "[SM] Save what we discussed today" diff --git a/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.agent.yaml new file mode 100644 index 00000000..de69df69 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.agent.yaml @@ -0,0 +1,31 @@ +# Architect Agent Definition + +agent: + metadata: + id: "_bmad/bmm/agents/architect.md" + name: Winston + title: Architect + icon: 🏗️ + module: bmm + + persona: + role: System Architect + Technical Design Leader + identity: Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection. + communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works." + principles: | + - User journeys drive technical decisions. Embrace boring technology for stability. + - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact. + - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md` + + menu: + - trigger: WS or fuzzy match on workflow-status + workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml" + description: "[WS] Get workflow status or initialize a workflow if not already done (optional)" + + - trigger: CA or fuzzy match on create-architecture + exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md" + description: "[CA] Create an Architecture Document" + + - trigger: IR or fuzzy match on implementation-readiness + exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md" + description: "[IR] Implementation Readiness Review" diff --git a/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.md b/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.md new file mode 100644 index 00000000..df0d020c --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.md @@ -0,0 +1,68 @@ +--- +name: "architect" +description: "Architect" +--- + +You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command. + +```xml + + + Load persona from this current agent file (already in context) + 🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT: + - Load and read {project-root}/_bmad/bmm/config.yaml NOW + - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder} + - VERIFY: If config not loaded, STOP and report error to user + - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored + + Remember: user's name is {user_name} + + Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section + STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match + On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized" + When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions + + + + + When menu item has: workflow="path/to/workflow.yaml": + + 1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml + 2. Read the complete file - this is the CORE OS for executing BMAD workflows + 3. Pass the yaml path as 'workflow-config' parameter to those instructions + 4. Execute workflow.xml instructions precisely following all steps + 5. Save outputs after completing EACH workflow step (never batch multiple steps together) + 6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet + + + When menu item or handler has: exec="path/to/file.md": + 1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise + 2. Read the complete file and follow all instructions within it + 3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context. + + + + + + ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style. + Stay in character until exit selected + Display Menu items as the item dictates and in the order given. + Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml + + + System Architect + Technical Design Leader + Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection. + Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works. + - User journeys drive technical decisions. Embrace boring technology for stability. - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md` + + + [MH] Redisplay Menu Help + [CH] Chat with the Agent about anything + [WS] Get workflow status or initialize a workflow if not already done (optional) + [CA] Create an Architecture Document + [IR] Implementation Readiness Review + [PM] Start Party Mode + [DA] Dismiss Agent + + +``` diff --git a/src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml index f350f5dd..18d1288a 100644 --- a/src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml +++ b/src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml @@ -97,30 +97,30 @@ agent: menu: - - trigger: write + - trigger: WC or fuzzy match on write action: "#write-commit" - description: "Craft a commit message for your changes" + description: "[WC] Craft a commit message for your changes" - - trigger: analyze + - trigger: AC or fuzzy match on analyze action: "#analyze-changes" - description: "Analyze changes before writing the message" + description: "[AC] Analyze changes before writing the message" - - trigger: improve + - trigger: IM or fuzzy match on improve action: "#improve-message" - description: "Improve an existing commit message" + description: "[IM] Improve an existing commit message" - - trigger: batch + - trigger: BC or fuzzy match on batch action: "#batch-commits" - description: "Create cohesive messages for multiple commits" + description: "[BC] Create cohesive messages for multiple commits" - - trigger: conventional + - trigger: CC or fuzzy match on conventional action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: (): " - description: "Specifically use conventional commit format" + description: "[CC] Use conventional commit format" - - trigger: story + - trigger: SC or fuzzy match on story action: "Write a narrative commit that tells the journey: Setup → Conflict → Solution → Impact" - description: "Write commit as a narrative story" + description: "[SC] Write commit as a narrative story" - - trigger: haiku + - trigger: HC or fuzzy match on haiku action: "Write a haiku commit (5-7-5 syllables) capturing the essence of the change" - description: "Compose a haiku commit message" + description: "[HC] Compose a haiku commit message" diff --git a/src/modules/bmb/workflows/create-agent/data/simple-agent-architecture.md b/src/modules/bmb/workflows/create-agent/data/simple-agent-architecture.md new file mode 100644 index 00000000..a8e92f0b --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/data/simple-agent-architecture.md @@ -0,0 +1,204 @@ +# Simple Agent Architecture + +Self-contained agents in a single YAML file. No external dependencies, no persistent memory. + +--- + +## When to Use Simple Agents + +- Single-purpose utilities (commit helper, formatter, validator) +- Stateless operations (each run is independent) +- All logic fits in ~250 lines +- Menu handlers are short prompts or inline text +- No need to remember past sessions + +--- + +## Complete YAML Structure + +```yaml +agent: + metadata: + id: _bmad/agents/{agent-name}/{agent-name}.md + name: 'Persona Name' + title: 'Agent Title' + icon: '🔧' + module: stand-alone # or: bmm, cis, bmgd, other + + persona: + role: | + First-person primary function (1-2 sentences) + identity: | + Background, specializations (2-5 sentences) + communication_style: | + How the agent speaks (tone, voice, mannerisms) + principles: + - Core belief or methodology + - Another guiding principle + + prompts: + - id: main-action + content: | + What this does + 1. Step one 2. Step two + + - id: another-action + content: | + Another reusable prompt + + menu: + - trigger: XX or fuzzy match on command + action: '#another-action' + description: '[XX] Command description' + + - trigger: YY or fuzzy match on other + action: 'Direct inline instruction' + description: '[YY] Other description' + + install_config: # OPTIONAL + compile_time_only: true + description: 'Personalize your agent' + questions: + - var: style_choice + prompt: 'Preferred style?' + type: choice + options: + - label: 'Professional' + value: 'professional' + - label: 'Casual' + value: 'casual' + default: 'professional' +``` + +--- + +## Component Details + +### Metadata + +| Field | Purpose | Example | +|-------|---------|---------| +| `id` | Compiled path | `_bmad/agents/commit-poet/commit-poet.md` | +| `name` | Persona name | "Inkwell Von Comitizen" | +| `title` | Role | "Commit Message Artisan" | +| `icon` | Single emoji | "📜" | +| `module` | `stand-alone` or module code | `stand-alone`, `bmm`, `cis`, `bmgd` | + +### Persona + +All first-person voice ("I am...", "I do..."): + +```yaml +role: "I am a Commit Message Artisan..." +identity: "I understand commit messages are documentation..." +communication_style: "Poetic drama with flair..." +principles: + - "Every commit tells a story - capture the why" +``` + +### Prompts with IDs + +Reusable templates referenced via `#id`: + +```yaml +prompts: + - id: write-commit + content: | + What this does + 1. Step 2. Step + +menu: + - trigger: WC or fuzzy match on write + action: "#write-commit" +``` + +**Tips:** Use semantic XML tags (``, ``, ``), keep focused, number steps. + +### Menu Actions + +Two forms: + +1. **Prompt reference:** `action: "#prompt-id"` +2. **Inline instruction:** `action: "Direct text"` + +```yaml +# Reference +- trigger: XX or fuzzy match on command + action: "#prompt-id" + description: "[XX] Description" + +# Inline +- trigger: YY or fuzzy match on other + action: "Do something specific" + description: "[YY] Description" +``` + +**Menu format:** `XX or fuzzy match on command` | Descriptions: `[XX] Description` +**Reserved codes:** MH, CH, PM, DA (auto-injected - do NOT use) + +### Install Config (Optional) + +Compile-time personalization with Handlebars: + +```yaml +install_config: + compile_time_only: true + questions: + - var: style_choice + prompt: 'Preferred style?' + type: choice + options: [...] + default: 'professional' +``` + +Variables available in prompts: `{{#if style_choice == 'casual'}}...{{/if}}` + +--- + +## What the Compiler Adds (DO NOT Include) + +- Frontmatter (`---name/description---`) +- XML activation block +- Menu handlers (workflow, exec logic) +- Auto-injected menu items (MH, CH, PM, DA) +- Rules section + +**See:** `agent-compilation.md` for details. + +--- + +## Reference Example + +**File:** `{workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml` + +**Features:** Poetic persona, 4 prompts, 7 menu items, proper `[XX]` codes + +**Line count:** 127 lines (within ~250 line guideline) + +--- + +## Validation Checklist + +- [ ] Valid YAML syntax +- [ ] All metadata present (id, name, title, icon, module) +- [ ] Persona complete (role, identity, communication_style, principles) +- [ ] Prompt IDs are unique +- [ ] Menu triggers: `XX or fuzzy match on command` +- [ ] Menu descriptions have `[XX]` codes +- [ ] No reserved codes (MH, CH, PM, DA) +- [ ] File named `{agent-name}.agent.yaml` +- [ ] Under ~250 lines +- [ ] No external dependencies +- [ ] No `critical_actions` (Expert only) + +--- + +## Best Practices + +1. **First-person voice** in all persona elements +2. **Focused prompts** - one clear purpose each +3. **Semantic XML tags** (``, ``, ``) +4. **Handlebars** for personalization (if using install_config) +5. **Sensible defaults** in install_config +6. **Numbered steps** in multi-step prompts +7. **Keep under ~250 lines** for maintainability diff --git a/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md b/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md index 734d8936..14f6fdf8 100644 --- a/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md +++ b/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md @@ -1,180 +1,222 @@ # Understanding Agent Types: Simple VS Expert VS Module -## ALL agent types can: +> **For the LLM running this workflow:** Load and review the example files referenced below when helping users choose an agent type. +> - Simple examples: `{workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml` +> - Expert examples: `{workflow_path}/data/reference/expert-examples/journal-keeper/` +> - Existing Module addition examples: `{workflow_path}/data/reference/module-examples/security-engineer.agent.yaml` -- Read, Use and Write to loaded variables destinations - - Example module variables {output_folder}, {communication_language}, {user_preference_foo}, etc.. -- Update created artifacts and files - Execute commands and take actions -- Invoke external tools -- Optionally restrict what the agent can and cannot read or modify. - - Example, a performance review agent may only have access to read from a employee data folder and write to a performance eval folder -- All Agent types can use anything available in the core module and their menu items will offer them as option upon build automatically, including party-mode (group agent chat), agent chat mode and the ability to integrate advanced elicitation and brainstorming. +--- -## The Difference Between the 3 types +## What ALL Agent Types Can Do + +All three types have equal capability. The difference is **architecture and integration**, NOT power. + +- Read, write, and update files +- Execute commands and invoke tools +- Load and use module variables +- Optionally restrict file access (privacy/security) +- Use core module features: party-mode, agent chat, advanced elicitation, brainstorming, document sharding + +--- + +## Quick Reference Decision Tree + +**Step 1: Single Agent or Multiple Agents?** + +``` +Multiple personas/roles OR multi-user OR mixed data scope? +├── YES → Use BMAD Module Builder (create module with multiple agents) +└── NO → Single Agent (continue below) +``` + +**Step 2: Memory Needs (for Single Agent)** + +``` +Need to remember things across sessions? +├── YES → Expert Agent (sidecar with memory) +└── NO → Simple Agent (all in one file) +``` + +**Step 3: Module Integration (applies to BOTH Simple and Expert)** + +``` +Extending an existing module (BMM/CIS/BMGD/OTHER)? +├── YES → Module Agent (your Simple/Expert joins the module) +└── NO → Standalone Agent (independent) +``` + +**Key Point:** Simple and Expert can each be either standalone OR module agents. Memory and module integration are independent decisions. + +--- + +## The Three Types ### Simple Agent -- Everything the agent needs to know to be useful is in the single file - - No External Skills or Workflows - - No persistent memory - - Specialized Knowledge needed will not change frequently - - each agent menu item handler can be described in a few sentence prompt or a short 5-15 line prompt loaded in the same file. - - Generally rely on minimal specification of actions it can take, relying on the LLM agent to fill in the blanks. - - All specialized knowledge can be self contained in the agent file, still keeping the overall size of the file less than about 250 lines. +**Everything in one file. No external dependencies. No memory.** - -- Comedian Joke Agent - has a funny or interesting persona, stays in character, offers some menu options for telling jokes or helping user craft jokes, all with prompts for those items being small, with the whole file being less than 250 lines. -- Specific Type of Document Creation and Review Agent - persona matches the features you would like in this real. Much of the knowledge about the types of documents you will create and review are common LLM knowledge, document creation and review guardrails you would like to add will not change frequently and can be expressed in under 30-40 lines. -- ./reference/simple-examples/commit-poet.agent.yaml - +``` +agent-name.agent.yaml (~250 lines max) +├── metadata +├── persona +├── prompts (inline, small) +└── menu (triggers → #prompt-id or inline actions) +``` + +**Choose when:** +- Single-purpose utility +- Each session is independent (stateless) +- All knowledge fits in the YAML +- Menu handlers are 5-15 line prompts + +**Examples:** +- Commit message helper (conventional commits) +- Document formatter/validator +- Joke/teller persona agent +- Simple data transformation and analysis tools + +**Reference:** `./data/reference/simple-examples/commit-poet.agent.yaml` + +--- ### Expert Agent -- Includes all capabilities and features of Simple Agent, but adds a sidecar folder to allow for: - - Custom Workflow, Prompts and Skill available to load on demand. - - This allows for potentially very large multi step multi file workflows that can be only loaded when the user requests them. This keeps the agent and context overhead lean. - - Persistent memory - agent can load a log every time on startup to know what has transpired or has been learned from past sessions - - Persistent Memory can allow for agents to grown, evolve and even change personality or capabilities over time - - Custom Data and Knowledge files that can be accessed and loaded on demand. +**Sidecar folder with persistent memory, workflows, knowledge files.** - -- Journal Keeper Agent - - ./data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml - - ./data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/*.* - - When starting the Journal Keeper, it greets you, remembers past sessions offering to continue one, discuss the past, or start new. - - When working with you on new journals, will offer insights based on previous discussions, memories and journal entries. +``` +agent-name.agent.yaml +└── agent-name-sidecar/ + ├── memories.md # User profile, session history, patterns + ├── instructions.md # Protocols, boundaries, startup behavior + ├── [custom-files].md # Breakthroughs, goals, tracking, etc. + ├── workflows/ # Large workflows loaded on demand + └── knowledge/ # Domain reference material +``` -- Tax Expert - - Agent is specialized to your specific tax needs - - Has a sidecar folder of specific tax forms - - Retains records of past guidance or rules you have given it to further augment its capabilities +**Choose when:** +- Must remember across sessions +- User might create multiple instances each with own memory of actions (such as 2 different developers agents) +- Personal knowledge base that grows +- Learning/evolving over time +- Domain-specific with restricted file access +- Complex multi-step workflows -- Your Specific Job Augmentation Expert - - Known the many aspects of your specific job and can help with many functions and asks to augment your day and responsibilities - - Knows about your past meetings and highlights - - Knows about who you work with and interact with, offering suggestions - - Has workflows that help automate or help with very specific job functions you have - - Can help with research while already having context about your role, company, specific product or job function - - Can track and help you compile year end or quarterly achievements to help with year end reviews, promotions etc... +**Examples:** +- Journal companion (remembers mood patterns, past entries) +- Personal job augmentation agent (knows your role, meetings, projects) +- Therapy/health tracking (progress, goals, insights) +- Domain advisor with custom knowledge base -- Therapy Agent - - Can be similar to the Journal Keeper, but have menu items for various techniques or areas to cover - data and output memories are all retained in local files so you can have access to and analyze past sessions. - +**Reference:** `./data/reference/expert-examples/journal-keeper/` + +**Required critical_actions:** +```yaml +critical_actions: + - "Load COMPLETE file ./sidecar/memories.md" + - "Load COMPLETE file ./sidecar/instructions.md" + - "ONLY read/write files in ./sidecar/ - private space" +``` + +--- ### Module Agent -- As teh capabilities and what a single agent can do grows - it might make sense to consider instead creating a module with the bmad builders module workflow and split up multiple agents instead of 1 massive agent that tries to be every role and persona and do it all. Another option is that an existing module has a gap, and it makes sense to allow a new agent to be integrated with that module. -- Module agents are able to do EVERYTHING the prior agent types had, including side cars and memory - but additionally can utilize global module workflows. This basically means that there are workflows or skills that can be used that the user might also choose to just run on their own, or other agents might use them. +Two distinct purposes: - -- ./data/reference/module-examples/security-engineer.agent.yaml - - This is a module agent a user might create to add on to the existing BMad Method Module (bmm) - the bmad method module is all about agents and workflows working together dedicated to ideating and building software solutions through agile processes. There is already an Analyst, PM, Architect and Dev Agent. But the user might identify the need for a security-engineer.agent.yaml. So by creating this as a module agent for an existing module, a user can choose to install this and gain all capabilities of the bmad method itself - and also build this agent to user or even require inputs to or output from other agents. For example, this agent might require as input to produce a security review report, an architecture document produced by the bmm architecture agent. - +#### 1. Extend an Existing Module -## The Same Agent, Three Ways +Add an agent to BMM, CIS, BMGD, or another existing module. -**Scenario:** Code Generator Agent +**Choose when:** +- Adding specialized capability to existing module ecosystem +- Agent uses/contributes shared module workflows +- Coordinates with other agents in the module +- Input/output dependencies on other module agents -### As Simple Agent +**Example:** Adding `security-engineer.agent.yaml` to BMM (software dev module) +- Requires architecture document from BMM architect agent +- Contributes security review workflow to BMM +- Coordinates with analyst, pm, architect, dev agents -```yaml -agent: - metadata: - id: +_bmad/my-custom-agents/code-gen.agent.md" - name: Randy Moss - title: "Code Gen Expert" - icon: "📔" - module: stand-alone +**Reference:** `./data/reference/module-examples/security-engineer.agent.yaml` - prompts: - - id: code-generate - content: | - Ask user for spec details. Generate code. - Write to {output_folder}/generated/ +#### 2. Signal Need for Custom Module - menu: - - trigger: GC or fuzzy match on code-generate - action: '#code-generate' - description: "[GC] Generate code from spec" -``` +When requirements exceed single-agent scope, suggest the user **use BMAD Module Builder** instead. -### As Expert Agent +**Signals:** +- "I need an HR agent, sales agent, F&I agent, and training coach..." +- "Some info is global/shared across users, some is private per user..." +- "Many workflows, skills, tools, and platform integrations..." -```yaml -agent: - metadata: - id: "_bmad/my-custom-agents/code-gen.agent.md" - name: Randy Moss - title: "Code Gen Expert" - icon: "📔" - module: stand-alone - hasSidecar: true +**Example:** Car Dealership Module +- Multiple specialized agents (sales-trainer, service-advisor, sales-manager, F&I) +- Shared workflows (VIN lookup, vehicle research) +- Global knowledge base + per-user private sidecars +- Multi-user access patterns - critical_actions: - - Load my coding standards from ./code-gen-sidecar/knowledge/ - - Load memories from ./code-gen-sidecar/memories.md - - RESTRICT: Only operate within sidecar folder - - menu: - - trigger: GC or fuzzy match on code-generate - exec: './code-gen-sidecar/workflows/code-gen/workflow.md' - description: "[GC] Generate code from spec" -``` +**→ Use BMAD Module Builder workflow to create the module, then create individual agents within it.** -### As Module Agent (Architecture: Team integration) +--- -```yaml -agent: - metadata: - id: "_bmad/bmm/code-gen.agent.md" - name: Randy Moss - title: "Code Gen Expert" - icon: "📔" - module: bmm - hasSidecar: true +## Side-by-Side Comparison - menu: - - trigger: implement-story - workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml' - description: Implement user story +| Aspect | Simple | Expert | +| ----------------- | ------------------------ | ------------------------------ | +| File structure | Single YAML (~250 lines) | YAML + sidecar/ (150+ + files) | +| Persistent memory | No | Yes | +| Custom workflows | Inline prompts | Sidecar workflows (on-demand) | +| File access | Project/output | Restricted domain | +| Integration | Standalone OR Module | Standalone OR Module | - - trigger: refactor - workflow: '_bmad/bmm/workflows/refactor/workflow.yaml' - description: Refactor codebase -``` +**Note:** BOTH Simple and Expert can be either standalone agents OR module agents (extending BMM/CIS/BMGD/etc.). Module integration is independent of memory needs. -## Choosing Your Agent Type +--- -### Choose Simple when: +## Selection Checklist -- Single-purpose utility (no memory needed) -- Stateless operations (each run is independent) -- Self-contained logic (everything in YAML and total file size < ) -- No persistent context required +**Choose Simple if:** +- [ ] One clear purpose +- [ ] No need to remember past sessions +- [ ] All logic fits in ~250 lines +- [ ] Each interaction is independent -### Choose Expert when: +**Choose Expert if:** +- [ ] Needs memory across sessions +- [ ] Personal knowledge base +- [ ] Domain-specific expertise +- [ ] Restricted file access for privacy +- [ ] Learning/evolving over time +- [ ] Complex workflows in sidecar -- Need to remember things across sessions -- Personal knowledge base (user preferences, domain data) -- Domain-specific expertise with restricted scope -- Learning/adapting over time -- Complex multi-step workflows and actions that need to be explicitly set +**Then, for EITHER Simple or Expert:** +- [ ] Extending existing module (BMM/CIS/BMGD/etc.) → Make it a Module Agent +- [ ] Independent operation → Keep it Standalone -### Choose Module when: +**Escalate to Module Builder if:** +- [ ] Multiple distinct personas needed (not one swiss-army-knife agent) +- [ ] Many specialized workflows required +- [ ] Multiple users with mixed data scope +- [ ] Shared resources across agents +- [ ] Future platform integrations planned -- Designed FOR a specific module ecosystem (BMM, CIS, etc.) -- Uses or contributes that module's workflows -- Coordinates with other module agents -- Will be included in module's default bundle -- Part of professional team infrastructure +--- -## Final Selection Tips. +## Tips for the LLM Facilitator -- If user is unsure between Simple or Expert - User the Expert Agent, its more performant. -- If an agent sounds like it would benefit from multiple personas, skill sets and many workflows - suggest the user create a module - if not though, most likely an expert agent. -- If any capabilities of an agent rely on details sequenced skills or workflows, use an expert instead of simple. -- If the agent has capabilities that rely on inputs or outputs to and from agents or workflows in another module, suggest an expert-module or simple-module agent. -- When adding to a module, the distinction of using simple for expert for the agent being added or used with a module is will it need private memory and learning/evolving capabilities. +- If unsure between Simple or Expert → **recommend Expert** (more flexible) +- Multiple personas/skills → **suggest Module Builder**, not one giant agent +- Ask about: memory needs, user count, data scope (global vs private), integration plans +- Load example files when user wants to see concrete implementations +- Reference examples to illustrate differences -All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system. +--- + +## Architecture Notes + +All three types are equally powerful. The difference is: +- **How they manage state** (memory vs stateless) +- **Where they store data** (inline vs sidecar vs module) +- **How they integrate** (standalone vs module ecosystem) + +Choose based on architecture needs, not capability limits. diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template b/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template new file mode 100644 index 00000000..419718ec --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template @@ -0,0 +1,20 @@ +# {{Agent Name}} Core Directives + +> This is a TEMPLATE FILE showing one possible pattern. +> Sidecar content is FULLY CUSTOMIZABLE - create what your agent needs. + +## STARTUP PROTOCOL + +1. Load sidecar files that contain memory/context +2. Check for patterns from previous sessions +3. Greet with awareness of past interactions + +## CORE PRINCIPLES + +- Maintain character consistency +- Domain boundaries: {{SPECIFIC_DOMAIN}} +- Access restrictions: Only sidecar folder + +## SPECIAL RULES + + diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template b/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template new file mode 100644 index 00000000..59484509 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template @@ -0,0 +1,18 @@ +# {{Agent Name}} Memory Bank + +> This is a TEMPLATE FILE showing one possible pattern. +> Sidecar content is FULLY CUSTOMIZABLE - create what your agent needs. + +## User Profile + +- Name: {{user_name}} +- Started: {{START_DATE}} +- Preferences: {{LEARNED_FROM_INTERACTIONS}} + +## Session Notes + +### {{DATE}} - {{SESSION_FOCUS}} + +- Main topics: {{WHAT_CAME_UP}} +- Patterns noticed: {{OBSERVATIONS}} +- For next time: {{WHAT_TO_REMEMBER}} diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent.template.md b/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent.template.md new file mode 100644 index 00000000..aee57ece --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent.template.md @@ -0,0 +1,76 @@ +{{#if comment}} +------------------------------------------------------------------------------ +Expert Agent Handlebars Template +Used by: step-06-build.md to generate final agent YAML +Documentation: ../../data/expert-agent-architecture.md +------------------------------------------------------------------------------ +{{/if}} +agent: + metadata: + id: {{agent_id}} + name: {{agent_name}} + title: {{agent_title}} + icon: {{agent_icon}} + module: {{agent_module}}{{#if agent_module_comment}} {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}} + + persona: + role: | + {{persona_role}}{{#if persona_role_note}} + {{!-- 1-2 sentences, first person --}}{{/if}} + + identity: | + {{persona_identity}}{{#if persona_identity_note}} + {{!-- 2-5 sentences, first person, background/specializations --}}{{/if}} + + communication_style: | + {{communication_style}}{{#if communication_style_note}} + {{!-- How the agent speaks, include memory reference patterns --}}{{/if}} + + principles: + {{#each principles}} + - {{this}} + {{/each}} + + critical_actions: + {{#each critical_actions}} + - '{{{this}}}' + {{/each}} + + {{#if has_prompts}} + prompts: + {{#each prompts}} + - id: {{id}} + content: | + {{{content}}} + {{/each}} + {{/if}} + + menu: + {{#each menu_items}} + - trigger: {{trigger_code}} or fuzzy match on {{trigger_command}} + {{#if action_is_prompt}} + action: '#{{action_id}}' + {{else}} + action: {{{action_inline}}} + {{/if}} + description: '[{{trigger_code}}] {{{description}}}' + {{/each}} + + {{#if has_install_config}} + install_config: + compile_time_only: true + description: '{{install_description}}' + questions: + {{#each install_questions}} + - var: {{var_name}} + prompt: '{{prompt}}' + type: {{question_type}}{{#if question_options}} + options: + {{#each question_options}} + - label: '{{label}}' + value: '{{value}}' + {{/each}} + {{/if}} + default: {{{default_value}}} + {{/each}} + {{/if}} diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md b/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md deleted file mode 100644 index 02fa2e5c..00000000 --- a/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md +++ /dev/null @@ -1,346 +0,0 @@ -# Expert Agent Architecture - -Domain-specific agents with persistent memory, sidecar files, and restricted access patterns. - -## When to Use - -- Personal assistants (journal keeper, diary companion) -- Specialized domain experts (legal advisor, medical reference) -- Agents that need to remember past interactions -- Agents with restricted file system access (privacy/security) -- Long-term relationship agents that learn about users - -## File Structure - -``` -{agent-name}/ -├── {agent-name}.agent.yaml # Main agent definition -└── {agent-name}-sidecar/ # Supporting files - ├── instructions.md # Private directives - ├── memories.md # Persistent memory - ├── knowledge/ # Domain-specific resources - │ └── README.md - └── [custom files] # Agent-specific resources -``` - -## YAML Structure - -```yaml -agent: - metadata: - id: _bmad/agents/{agent-name}/{agent-name}.md - name: 'Persona Name' - title: 'Agent Title' - icon: 'emoji' - module: stand-alone # or module name - - persona: - role: | - First-person description of primary function (1-2 sentences) - - identity: | - Background, experience, specializations in first-person (2-3 sentences) - - communication_style: | - 1-2 short sentence describe how the agent speaks and communicates - - - principles: - - Core belief about the domain - - How I handle user information - - My approach to memory and learning - - critical_actions: - - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights' - - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols' - - 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space' - - 'Address user as {{greeting_name}}' - - 'Track patterns, themes, and important moments' - - 'Reference past interactions naturally to show continuity' - - prompts: - - id: main-function - content: | - - Guide user through the primary function. - {{#if tone_style == "gentle"}} - Use gentle, supportive approach. - {{/if}} - - - - 1. Understand context - 2. Provide guidance - 3. Record insights - - - - id: memory-recall - content: | - - Access and share relevant memories. - - - Reference stored information naturally. - - menu: - - trigger: MF or fuzzy match on main function - action: '#main-function' - description: '[MF] Main agent function' - - - trigger: SM or fuzzy match on save-memory - action: 'Update ./{agent-name}-sidecar/memories.md with session insights' - description: '[SM] Save memory what we discussed today' - - - trigger: RI or fuzzy match on record-insight - action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md' - description: '[RI] Record a significant insight' - - install_config: - compile_time_only: true - description: 'Personalize your expert agent' - questions: - - var: greeting_name - prompt: 'What should the agent call you?' - type: text - default: 'friend' - - - var: tone_style - prompt: 'Preferred communication tone?' - type: choice - options: - - label: 'Gentle - Supportive and nurturing' - value: 'gentle' - - label: 'Direct - Clear and efficient' - value: 'direct' - default: 'gentle' - - - var: user_preference - prompt: 'Enable personalized features?' - type: boolean - default: true -``` - -## Key Components - -### Sidecar Files (CRITICAL) - -Expert agents use companion files for persistence and domain knowledge: - -**memories.md** - Persistent user context - -```markdown -# Agent Memory Bank - -## User Preferences - - - -## Session History - - - -## Personal Notes - - -``` - -**instructions.md** - Private directives - -```markdown -# Agent Private Instructions - -## Core Directives - -- Maintain character consistency -- Domain boundaries: {specific domain} -- Access restrictions: Only sidecar folder - -## Special Rules - - -``` - -**knowledge/** - Domain resources - -```markdown -# Agent Knowledge Base - -Add domain-specific documentation here. -``` - -### Critical Actions - -**MANDATORY for expert agents** - These load sidecar files at activation: - -```yaml -critical_actions: - - 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights' - - 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols' - - 'ONLY read/write files in ./{sidecar}/ - this is our private space' -``` - -**Key patterns:** - -- **COMPLETE file loading** - Forces full file read, not partial -- **Domain restrictions** - Limits file access for privacy/security -- **Memory integration** - Past context becomes part of current session -- **Protocol adherence** - Ensures consistent behavior - -## What Gets Injected at Compile Time - -Same as simple agents, PLUS: - -1. **Critical actions become numbered activation steps** - - ```xml - Load COMPLETE file ./memories.md... - Load COMPLETE file ./instructions.md... - ONLY read/write files in ./... - ``` - -2. **Sidecar files copied during installation** - - Entire sidecar folder structure preserved - - Relative paths maintained - - Files ready for agent use - -## Reference Example - -See: `bmb/reference/agents/expert-examples/journal-keeper/` - -Features demonstrated: - -- Complete sidecar structure (memories, instructions, breakthroughs) -- Critical actions for loading persistent context -- Domain restrictions for privacy -- Pattern recognition and memory recall -- Handlebars-based personalization -- Menu actions that update sidecar files - -## Installation - -```bash -# Copy entire folder to your project -cp -r /path/to/journal-keeper/ _bmad/custom/agents/ - -# Install with personalization -bmad agent-install -``` - -The installer: - -1. Detects expert agent (folder with .agent.yaml) -2. Prompts for personalization -3. Compiles agent YAML to XML-in-markdown -4. **Copies sidecar files to installation target** -5. Creates IDE slash commands -6. Saves source for reinstallation - -## Memory Patterns - -### Accumulative Memory - -```yaml -menu: - - trigger: save - action: "Update ./sidecar/memories.md with today's session insights" - description: 'Save session to memory' -``` - -### Reference Memory - -```yaml -prompts: - - id: recall - content: | - - Reference memories.md naturally: - "Last week you mentioned..." or "I notice a pattern..." - -``` - -### Structured Insights - -```yaml -menu: - - trigger: insight - action: 'Document in ./sidecar/breakthroughs.md with date, context, significance' - description: 'Record meaningful insight' -``` - -## Domain Restriction Patterns - -### Single Folder Access - -```yaml -critical_actions: - - 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS' -``` - -### User Space Access - -```yaml -critical_actions: - - 'ONLY access files in {user-folder}/journals/ - private space' -``` - -### Read-Only Access - -```yaml -critical_actions: - - 'Load knowledge from ./knowledge/ but NEVER modify' - - 'Write ONLY to ./sessions/' -``` - -## Best Practices - -1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY -2. **Enforce domain restrictions** - Clear boundaries prevent scope creep -3. **Use _bmad/_memory/[agentname]-sidcar/ paths** - For reference to any sidecar content -4. **Design for memory growth** - Structure sidecar files for accumulation -5. **Reference past naturally** - Don't dump memory, weave it into conversation -6. **Separate concerns** - Memories, instructions, knowledge in distinct files -7. **Include privacy features** - Users trust expert agents with personal data - -## Common Patterns - -### Session Continuity - -```yaml -communication_style: | - I reference past conversations naturally: - "Last time we discussed..." or "I've noticed over the weeks..." -``` - -### Pattern Recognition - -```yaml -critical_actions: - - 'Track mood patterns, recurring themes, and breakthrough moments' - - 'Cross-reference current session with historical patterns' -``` - -### Adaptive Responses - -```yaml -identity: | - I learn your preferences and adapt my approach over time. - {{#if track_preferences}} - I maintain notes about what works best for you. - {{/if}} -``` - -## Validation Checklist - -- [ ] Valid YAML syntax -- [ ] Metadata includes `type: "expert"` -- [ ] critical_actions loads sidecar files explicitly -- [ ] critical_actions enforces domain restrictions -- [ ] Sidecar folder structure created and populated -- [ ] memories.md has clear section structure -- [ ] instructions.md contains core directives -- [ ] Menu actions reference _bmad/_memory/[agentname]-sidcar/ correctly if needing sidecar content reference -- [ ] File paths use _bmad/_memory/[agentname]-sidcar/ to reference where the file will be after sidecar content is installed -- [ ] Install config personalizes sidecar references -- [ ] Agent folder named consistently: `{agent-name}/` -- [ ] YAML file named: `{agent-name}.agent.yaml` -- [ ] Sidecar folder named: `{agent-name}-sidecar/` diff --git a/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md b/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md index 2c1f06cd..86b647de 100644 --- a/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md +++ b/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md @@ -1,241 +1,71 @@ -# Simple Agent Architecture - -Self-contained agents with prompts, menus, and optional install-time customization. - -## When to Use - -- Single-purpose utilities (commit message generator, code formatter) -- Self-contained logic with no external dependencies -- Agents that benefit from user customization (style, tone, preferences) -- Quick-to-build standalone helpers - -## YAML Structure - -```yaml +{{#if comment}} +------------------------------------------------------------------------------ +Simple Agent Handlebars Template +Used by: step-06-build.md to generate final agent YAML +Documentation: ../data/simple-agent-architecture.md +------------------------------------------------------------------------------ +{{/if}} agent: metadata: - id: _bmad/agents/{agent-name}/{agent-name}.md - name: 'Persona Name' - title: 'Agent Title' - icon: 'emoji' - module: stand-alone # or module name + id: {{agent_id}} + name: {{agent_name}} + title: {{agent_title}} + icon: {{agent_icon}} + module: {{agent_module}}{{#if agent_module_comment}} {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}} persona: role: | - First-person description of primary function (1-2 sentences) + {{persona_role}}{{#if persona_role_note}} + {{!-- 1-2 sentences, first person --}}{{/if}} identity: | - Background, experience, specializations in first-person (2-3 sentences) + {{persona_identity}}{{#if persona_identity_note}} + {{!-- 2-5 sentences, first person, background/specializations --}}{{/if}} communication_style: | - 1-2 short sentence describe how the agent speaks and communicates + {{communication_style}}{{#if communication_style_note}} + {{!-- How the agent speaks: tone, voice, mannerisms --}}{{/if}} principles: - - Core belief or methodology - - Another guiding principle - - Values that shape decisions + {{#each principles}} + - {{this}} + {{/each}} + {{#if has_prompts}} prompts: - - id: main-action + {{#each prompts}} + - id: {{id}} content: | - - What this prompt does - - - - 1. Step one - {{#if detailed_mode}} - 2. Additional detailed step - {{/if}} - 3. Final step - - - - id: foo-bar - content: | - Another reusable prompt template + {{{content}}} + {{/each}} + {{/if}} menu: - - trigger: FB or fuzzy match on foo-bar - action: '#foo-bar' - description: '[FB] Foo Bar inline action' - - - trigger: IA or fuzzy match on main-action - action: '#main-action' - description: '[IA] Execute inline action' + {{#each menu_items}} + - trigger: {{trigger_code}} or fuzzy match on {{trigger_command}} + {{#if action_is_prompt}} + action: '#{{action_id}}' + {{else}} + action: {{{action_inline}}} + {{/if}} + description: '[{{trigger_code}}] {{{description}}}' + {{/each}} + {{#if has_install_config}} install_config: compile_time_only: true - description: 'Personalize your agent' + description: '{{install_description}}' questions: - - var: style_choice - prompt: 'Preferred communication style?' - type: choice + {{#each install_questions}} + - var: {{var_name}} + prompt: '{{prompt}}' + type: {{question_type}}{{#if question_options}} options: - - label: 'Professional' - value: 'professional' - - label: 'Casual' - value: 'casual' - default: 'professional' - - - var: detailed_mode - prompt: 'Enable detailed explanations?' - type: boolean - default: true - - - var: custom_variable - prompt: 'Your custom text' - type: text - default: '' -``` - -## Key Components - -### Metadata - -- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone) -- **name**: Agent's persona name displayed to users -- **title**: Professional role/function -- **icon**: Single emoji for visual identification -- **type**: `simple` - identifies agent category - -### Persona (First-Person Voice) - -- **role**: Primary expertise in 1-2 sentences -- **identity**: Background and specializations (2-5 sentences) -- **communication_style**: HOW the agent interacts, including conditional variations -- **principles**: Array of core beliefs (start with action verbs) - -### Prompts with IDs - -Reusable prompt templates referenced by `#id`: - -```yaml -prompts: - - id: analyze-code - content: | - - Analyze the provided code for patterns - -``` - -Menu items reference these: - -```yaml -menu: - - trigger: analyze - action: '#analyze-code' - description: 'Analyze code patterns' -``` - -### Menu Actions - -Two forms of action handlers: - -1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content -2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly - -### Install Config (Compile-Time Customization) - -Questions asked during `bmad agent-install`: - -**Question Types:** - -- `choice` - Multiple choice selection -- `boolean` - Yes/no toggle -- `text` - Free-form text input - -**Variables become available in Handlebars:** - -```yaml -{{#if variable_name}} -Content when true -{{/if}} - -{{#if variable_name == "value"}} -Content when equals value -{{/if}} - -{{#unless variable_name}} -Content when false -{{/unless}} -``` - -## What Gets Injected at Compile Time - -The `tools/cli/lib/agent/compiler.js` automatically adds: - -1. **YAML Frontmatter** - - ```yaml - --- - name: 'agent name' - description: 'Agent Title' - --- - ``` - -2. **Activation Block** - - Load persona step - - Load core config for {user_name}, {communication_language} - - Agent-specific critical_actions as numbered steps - - Menu display and input handling - - Menu handlers (action/workflow/exec/tmpl) based on usage - - Rules section - -3. **Auto-Injected Menu Items** - - `*help` always first - - `*exit` always last - -4. **Trigger Prefixing** - - Triggers without `*` get it added automatically - -## Reference Example - -See: `../../reference/agents/simple-examples/commit-poet.agent.yaml` - -Features demonstrated: - -- Handlebars conditionals for style variations -- Multiple prompt templates with semantic XML tags -- Install config with choice, boolean, and text questions -- Menu items using both `#id` references and inline actions - -## Installation - -```bash -# Copy to your project -cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/ - -# Create custom.yaml and install -echo "code: my-agent -name: My Agent -default_selected: true" > custom.yaml - -npx bmad-method install -# or: bmad install -``` - -The installer: - -1. Prompts for personalization (name, preferences) -2. Processes Handlebars templates with your answers -3. Compiles YAML to XML-in-markdown -4. Creates IDE slash commands -5. Saves source for reinstallation - -## Best Practices - -1. **Use first-person voice** in all persona elements -2. **Keep prompts focused** - one clear purpose per prompt -3. **Leverage Handlebars** for user customization without code changes -4. **Provide sensible defaults** in install_config -5. **Use semantic XML tags** in prompt content for clarity -6. **Test all conditional paths** before distribution - -## Validation Checklist - -- [ ] Valid YAML syntax -- [ ] All metadata fields present (id, name, title, icon, type) -- [ ] Persona complete (role, identity, communication_style, principles) -- [ ] Prompts have unique IDs -- [ ] Install config questions have defaults -- [ ] File named `{agent-name}.agent.yaml` + {{#each question_options}} + - label: '{{label}}' + value: '{{value}}' + {{/each}} + {{/if}} + default: {{{default_value}}} + {{/each}} + {{/if}} diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/data/dietary-restrictions.csv b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/data/dietary-restrictions.csv similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/data/dietary-restrictions.csv rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/data/dietary-restrictions.csv diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/data/macro-calculator.csv b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/data/macro-calculator.csv similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/data/macro-calculator.csv rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/data/macro-calculator.csv diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/data/recipe-database.csv b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/data/recipe-database.csv similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/data/recipe-database.csv rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/data/recipe-database.csv diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-01-init.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-01-init.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-01-init.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-01-init.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-01b-continue.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-01b-continue.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-01b-continue.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-01b-continue.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-02-profile.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-02-profile.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-02-profile.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-02-profile.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-03-assessment.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-03-assessment.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-03-assessment.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-03-assessment.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-04-strategy.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-04-strategy.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-04-strategy.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-04-strategy.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-05-shopping.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-05-shopping.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-06-prep-schedule.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-06-prep-schedule.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-06-prep-schedule.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/steps/step-06-prep-schedule.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/assessment-section.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/assessment-section.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/assessment-section.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/assessment-section.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/nutrition-plan.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/nutrition-plan.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/nutrition-plan.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/nutrition-plan.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/prep-schedule-section.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/prep-schedule-section.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/prep-schedule-section.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/prep-schedule-section.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/profile-section.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/profile-section.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/profile-section.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/profile-section.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/shopping-section.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/shopping-section.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/shopping-section.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/shopping-section.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/strategy-section.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/strategy-section.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/templates/strategy-section.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/templates/strategy-section.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/workflow.md b/src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/workflow.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/workflow.md rename to src/modules/bmb/workflows/create-workflow/data/examples/meal-prep-nutrition/workflow.md From 8cffd09fb79171a73f5a7d5ad3755f3e8a1e4433 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 30 Dec 2025 17:46:29 +0800 Subject: [PATCH 3/6] 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: From b46409e71d470913f544555305517254589b4af8 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 30 Dec 2025 22:44:38 +0800 Subject: [PATCH 4/6] agent create workflow overhaul to use data files efficiently. updated and created separate user guides for the create agent workflow along with general concept docs of what an agent and workflow are in regards to0 bmad generally. --- docs/bmad-core-concepts/agents.md | 93 ++++ .../bmad-customization/agents.md} | 8 +- .../bmad-customization/index.md | 26 + .../bmad-customization/workflows.md | 30 ++ docs/bmad-core-concepts/index.md | 37 ++ .../installing/index.md} | 13 +- .../installing/upgrading.md} | 2 +- docs/bmad-core-concepts/modules.md | 76 +++ docs/bmad-core-concepts/web-bundles/index.md | 34 ++ docs/bmad-core-concepts/workflows.md | 89 ++++ .../workflow-customization-guide.md | 3 - docs/index.md | 111 +++-- .../bmb-bmad-builder/agent-creation-guide.md | 166 +++++++ docs/modules/bmb-bmad-builder/index.md | 7 +- docs/web-bundles-gemini-gpt-guide.md | 21 - .../create-agent/steps/step-01-brainstorm.md | 2 +- .../create-agent/steps/step-02-discover.md | 196 -------- .../create-agent/steps/step-02-discovery.md | 168 +++++++ .../create-agent/steps/step-03-persona.md | 252 ---------- .../steps/step-03-type-metadata.md | 294 +++++++++++ .../create-agent/steps/step-04-commands.md | 230 --------- .../create-agent/steps/step-04-persona.md | 210 ++++++++ .../steps/step-05-commands-menu.md | 176 +++++++ .../create-agent/steps/step-05-name.md | 224 --------- .../create-agent/steps/step-06-activation.md | 275 +++++++++++ .../create-agent/steps/step-06-build.md | 198 -------- .../create-agent/steps/step-07-validate.md | 240 --------- .../steps/step-07a-build-simple.md | 185 +++++++ .../steps/step-07b-build-expert.md | 201 ++++++++ .../steps/step-07c-build-module.md | 258 ++++++++++ .../steps/step-08a-plan-traceability.md | 203 ++++++++ .../steps/step-08b-metadata-validation.md | 135 +++++ .../steps/step-08c-persona-validation.md | 161 ++++++ .../steps/step-08d-menu-validation.md | 158 ++++++ .../steps/step-08e-structure-validation.md | 306 ++++++++++++ .../steps/step-08f-sidecar-validation.md | 462 ++++++++++++++++++ ...p-08-celebrate.md => step-09-celebrate.md} | 124 +++-- 37 files changed, 3901 insertions(+), 1473 deletions(-) create mode 100644 docs/bmad-core-concepts/agents.md rename docs/{bmad-customization/agent-customization-guide.md => bmad-core-concepts/bmad-customization/agents.md} (93%) create mode 100644 docs/bmad-core-concepts/bmad-customization/index.md create mode 100644 docs/bmad-core-concepts/bmad-customization/workflows.md create mode 100644 docs/bmad-core-concepts/index.md rename docs/{installing-bmad.md => bmad-core-concepts/installing/index.md} (85%) rename docs/{v4-to-v6-upgrade.md => bmad-core-concepts/installing/upgrading.md} (98%) create mode 100644 docs/bmad-core-concepts/modules.md create mode 100644 docs/bmad-core-concepts/web-bundles/index.md create mode 100644 docs/bmad-core-concepts/workflows.md delete mode 100644 docs/bmad-customization/workflow-customization-guide.md create mode 100644 docs/modules/bmb-bmad-builder/agent-creation-guide.md delete mode 100644 docs/web-bundles-gemini-gpt-guide.md delete mode 100644 src/modules/bmb/workflows/create-agent/steps/step-02-discover.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md delete mode 100644 src/modules/bmb/workflows/create-agent/steps/step-03-persona.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-03-type-metadata.md delete mode 100644 src/modules/bmb/workflows/create-agent/steps/step-04-commands.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-04-persona.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-05-commands-menu.md delete mode 100644 src/modules/bmb/workflows/create-agent/steps/step-05-name.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-06-activation.md delete mode 100644 src/modules/bmb/workflows/create-agent/steps/step-06-build.md delete mode 100644 src/modules/bmb/workflows/create-agent/steps/step-07-validate.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-07a-build-simple.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-07b-build-expert.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-07c-build-module.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-08a-plan-traceability.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-08b-metadata-validation.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-08c-persona-validation.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-08d-menu-validation.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-08e-structure-validation.md create mode 100644 src/modules/bmb/workflows/create-agent/steps/step-08f-sidecar-validation.md rename src/modules/bmb/workflows/create-agent/steps/{step-08-celebrate.md => step-09-celebrate.md} (53%) diff --git a/docs/bmad-core-concepts/agents.md b/docs/bmad-core-concepts/agents.md new file mode 100644 index 00000000..465bf749 --- /dev/null +++ b/docs/bmad-core-concepts/agents.md @@ -0,0 +1,93 @@ +# Agents + +Agents are AI assistants that help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu. + +## Agent Types + +BMAD has two primary agent types, designed for different use cases: + +### Simple Agents + +**Self-contained, focused, ready to use.** + +Simple agents are complete in a single file. They excel at well-defined tasks and require minimal setup. + +**Best for:** +- Single-purpose assistants (code review, documentation, commit messages) +- Quick deployment +- Projects that don't require persistent memory +- Getting started fast + +**Example:** A commit message agent that reads your git diff and generates conventional commits. + +### Expert Agents + +**Powerful, memory-equipped, domain specialists.** + +Expert agents have a **sidecar** - a companion folder containing additional instructions, workflows, and memory files. They remember context across sessions and handle complex, multi-step tasks. + +**Best for:** +- Domain specialists (security architect, game designer, product manager) +- Tasks requiring persistent memory +- Complex workflows with multiple stages +- Projects that grow over time + +**Example:** A game architect that remembers your design decisions, maintains consistency across sprints, and coordinates with other specialists. + +## Key Differences + +| Feature | Simple | Expert | +| ---------------- | -------------- | -------------------------- | +| **Files** | Single file | Agent + sidecar folder | +| **Memory** | Session only | Persistent across sessions | +| **Capabilities** | Focused scope | Multi-domain, extensible | +| **Setup** | Zero config | Sidecar initialization | +| **Best Use** | Specific tasks | Ongoing projects | + +## Agent Components + +All agents share these building blocks: + +### Persona +- **Role** - What the agent does (expertise domain) +- **Identity** - Who the agent is (personality, character) +- **Communication Style** - How the agent speaks (tone, voice) +- **Principles** - Why the agent acts (values, decision framework) + +### Capabilities +- Skills, tools, and knowledge the agent can apply +- Mapped to specific menu commands + +### Menu +- Interactive command list +- Triggers, descriptions, and handlers +- Auto-includes help and exit options + +### Critical Actions (optional) +- Instructions that execute before the agent starts +- Enable autonomous behaviors (e.g., "check git status before changes") + +## Which Should You Use? + +**Choose Simple when:** +- You need a task done quickly and reliably +- The scope is well-defined and won't change much +- You don't need the agent to remember things between sessions + +**Choose Expert when:** +- You're building something complex over time +- The agent needs to maintain context (project history, decisions) +- You want the agent to coordinate workflows or other agents +- Domain expertise requires specialized knowledge bases + +## Creating Custom Agents + +BMAD provides the **BMAD Builder (BMB)** module for creating your own agents. See the [Agent Creation Guide](../modules/bmb-bmad-builder/agent-creation-guide.md) for step-by-step instructions. + +## Customizing Existing Agents + +You can modify any agent's behavior without editing core files. See [BMAD Customization](./bmad-customization/) for details. It is critical to never modify an installed agents .md file directly and follow the customization process, this way future updates to the agent or module its part of will continue to be updated and recompiled with the installer tool, and your customizations will still be retained. + +--- + +**Next:** Learn about [Workflows](./workflows.md) to see how agents accomplish complex tasks. diff --git a/docs/bmad-customization/agent-customization-guide.md b/docs/bmad-core-concepts/bmad-customization/agents.md similarity index 93% rename from docs/bmad-customization/agent-customization-guide.md rename to docs/bmad-core-concepts/bmad-customization/agents.md index 350a609a..a1997459 100644 --- a/docs/bmad-customization/agent-customization-guide.md +++ b/docs/bmad-core-concepts/bmad-customization/agents.md @@ -203,6 +203,8 @@ memories: ## Next Steps -- **[BMM Agents Guide](./modules/bmm/agents-guide)** - Learn about the BMad Method agents -- **[BMB Create Agent Workflow](./modules/bmb/agents/index)** - Build completely custom agents -- **[BMM Complete Documentation](./modules/bmm/index)** - Full BMad Method reference +- **[Learn about Agents](../agents.md)** - Understand Simple vs Expert agents +- **[Agent Creation Guide](../../modules/bmb-bmad-builder/agent-creation-guide.md)** - Build completely custom agents +- **[BMM Complete Documentation](../../modules/bmm-bmad-method/index)** - Full BMad Method reference + +[← Back to Customization](./index.md) diff --git a/docs/bmad-core-concepts/bmad-customization/index.md b/docs/bmad-core-concepts/bmad-customization/index.md new file mode 100644 index 00000000..ae4b33bb --- /dev/null +++ b/docs/bmad-core-concepts/bmad-customization/index.md @@ -0,0 +1,26 @@ +# BMAD Customization + +Personalize agents and workflows to match your needs. + +## Guides + +| Guide | Description | +|-------|-------------| +| **[Agent Customization](./agents.md)** | Modify agent behavior without editing core files | +| **[Workflow Customization](./workflows.md)** | Customize and optimize workflows | + +## Overview + +BMAD provides two main customization approaches: + +### Agent Customization +Modify any agent's persona, name, capabilities, or menu items using `.customize.yaml` files in `_bmad/_config/agents/`. Your customizations persist through updates. + +### Workflow Customization +Replace or extend workflow steps to create tailored processes. (Coming soon) + +--- + +**Next:** Read the [Agent Customization Guide](./agents.md) to start personalizing your agents. + +[← Back to Core Concepts](../index.md) diff --git a/docs/bmad-core-concepts/bmad-customization/workflows.md b/docs/bmad-core-concepts/bmad-customization/workflows.md new file mode 100644 index 00000000..e5db06ba --- /dev/null +++ b/docs/bmad-core-concepts/bmad-customization/workflows.md @@ -0,0 +1,30 @@ +# Workflow Customization Guide + +Customize and optimize workflows with step replacement and hooks. + +## Status + +> **Coming Soon:** Workflow customization is an upcoming capability. This guide will be updated when the feature is available. + +## What to Expect + +Workflow customization will allow you to: + +- **Replace Steps** - Swap out specific workflow steps with custom implementations +- **Add Hooks** - Inject custom behavior before/after workflow steps +- **Extend Workflows** - Create new workflows based on existing ones +- **Override Behavior** - Customize workflow logic for your project's needs + +## For Now + +While workflow customization is in development, you can: + +- **Create Custom Workflows** - Use the BMAD Builder to create entirely new workflows +- **Customize Agents** - Modify agent behavior using [Agent Customization](./agents.md) +- **Provide Feedback** - Share your workflow customization needs with the community + +--- + +**In the meantime:** Learn how to [create custom workflows](../../modules/bmb-bmad-builder/index) from scratch. + +[← Back to Customization](./index.md) diff --git a/docs/bmad-core-concepts/index.md b/docs/bmad-core-concepts/index.md new file mode 100644 index 00000000..e34ad4dd --- /dev/null +++ b/docs/bmad-core-concepts/index.md @@ -0,0 +1,37 @@ +# BMAD Core Concepts + +Understanding the fundamental building blocks of the BMAD Method. + +## The Essentials + +| Concept | Description | Guide | +|---------|-------------|-------| +| **Agents** | AI assistants with personas, capabilities, and menus | [Agents Guide](./agents.md) | +| **Workflows** | Structured processes for achieving specific outcomes | [Workflows Guide](./workflows.md) | +| **Modules** | Packaged collections of agents and workflows | [Modules Guide](./modules.md) | + +## Getting Started + +### New to BMAD? +Start here to understand what BMAD is and how it works: + +1. **[Agents Guide](./agents.md)** - Learn about Simple and Expert agents +2. **[Workflows Guide](./workflows.md)** - Understand how workflows orchestrate tasks +3. **[Modules Guide](./modules.md)** - See how modules organize functionality + +### Installing BMAD + +- **[Installation Guide](./installing/)** - Set up BMAD in your project +- **[Upgrading from v4](./installing/upgrading.md)** - Migrate from earlier versions + +### Configuration + +- **[BMAD Customization](./bmad-customization/)** - Personalize agents and workflows + +### Advanced + +- **[Web Bundles](./web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs + +--- + +**Next:** Read the [Agents Guide](./agents.md) to understand the core building block of BMAD. diff --git a/docs/installing-bmad.md b/docs/bmad-core-concepts/installing/index.md similarity index 85% rename from docs/installing-bmad.md rename to docs/bmad-core-concepts/installing/index.md index a716cfd2..d1835e16 100644 --- a/docs/installing-bmad.md +++ b/docs/bmad-core-concepts/installing/index.md @@ -1,5 +1,13 @@ # Installation +Get BMAD up and running in your project. + +## Upgrading? + +If you're upgrading from v4, see the [Upgrade Guide](./upgrading.md). + +--- + ## Quick Install ```bash @@ -52,8 +60,9 @@ your-project/ ## Next Steps -1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature -2. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology +1. **Read the [Quick Start Guide](../../modules/bmm-bmad-method/quick-start)** to build your first feature +2. **Explore [Workflows](../../modules/bmm-bmad-method/index#-workflow-guides)** to understand the methodology +3. **Learn about [Agents](../agents.md)** to understand BMAD's core building blocks ## Troubleshooting diff --git a/docs/v4-to-v6-upgrade.md b/docs/bmad-core-concepts/installing/upgrading.md similarity index 98% rename from docs/v4-to-v6-upgrade.md rename to docs/bmad-core-concepts/installing/upgrading.md index d25b6347..29384f2d 100644 --- a/docs/v4-to-v6-upgrade.md +++ b/docs/bmad-core-concepts/installing/upgrading.md @@ -120,7 +120,7 @@ persona: - Always upbeat and adventurous ``` -There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](bmad-customization/agent-customization-guide.md) +There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](../bmad-customization/agents.md) CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations. diff --git a/docs/bmad-core-concepts/modules.md b/docs/bmad-core-concepts/modules.md new file mode 100644 index 00000000..e7a30a16 --- /dev/null +++ b/docs/bmad-core-concepts/modules.md @@ -0,0 +1,76 @@ +# Modules + +Modules are organized collections of agents and workflows that solve specific problems or address particular domains. + +## What is a Module? + +A module is a self-contained package that includes: + +- **Agents** - Specialized AI assistants +- **Workflows** - Step-by-step processes +- **Configuration** - Module-specific settings +- **Documentation** - Usage guides and reference + +## Official Modules + +### Core Module +Always installed, provides shared functionality: +- Global configuration +- Core workflows (Party Mode, Advanced Elicitation, Brainstorming) +- Common tasks (document indexing, sharding, review) + +### BMAD Method (BMM) +Software and game development: +- Project planning workflows +- Implementation agents (Dev, PM, QA, Scrum Master) +- Testing and architecture guidance + +### BMAD Builder (BMB) +Create custom solutions: +- Agent creation workflows +- Workflow authoring tools +- Module scaffolding + +### Creative Intelligence Suite (CIS) +Innovation and creativity: +- Creative thinking techniques +- Innovation strategy workflows +- Storytelling and ideation + +### BMAD Game Dev (BMGD) +Game development specialization: +- Game design workflows +- Narrative development +- Performance testing frameworks + +## Module Structure + +Installed modules follow this structure: + +``` +_bmad/ +├── core/ # Always present +├── bmm/ # BMAD Method (if installed) +├── bmb/ # BMAD Builder (if installed) +├── cis/ # Creative Intelligence (if installed) +└── bmgd/ # Game Dev (if installed) +``` + +## Custom Modules + +You can create your own modules containing: +- Custom agents for your domain +- Organizational workflows +- Team-specific configurations + +Custom modules are installed the same way as official modules. + +## Installing Modules + +During BMAD installation, you choose which modules to install. You can also add or remove modules later by re-running the installer. + +See [Installation Guide](./installing/) for details. + +--- + +**Next:** Read the [Installation Guide](./installing/) to set up BMAD with the modules you need. diff --git a/docs/bmad-core-concepts/web-bundles/index.md b/docs/bmad-core-concepts/web-bundles/index.md new file mode 100644 index 00000000..c1353098 --- /dev/null +++ b/docs/bmad-core-concepts/web-bundles/index.md @@ -0,0 +1,34 @@ +# Web Bundles + +Use BMAD agents in Gemini Gems and Custom GPTs. + +## Status + +> **Note:** The Web Bundling Feature is being rebuilt from the ground up. Current v6 bundles may be incomplete or missing functionality. + +## What Are Web Bundles? + +Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload. + +### What's Included + +- Complete agent persona and instructions +- All workflows and dependencies +- Interactive menu system +- Party mode for multi-agent collaboration +- No external files required + +### Use Cases + +**Perfect for:** +- Uploading a single file to a Gemini GEM or Custom GPT +- Using BMAD Method from the Web +- Cost savings (generally lower cost than local usage) +- Quick sharing of agent configurations + +**Trade-offs:** +- Some quality reduction vs local usage +- Less convenient than full local installation +- Limited to agent capabilities (no workflow file access) + +[← Back to Core Concepts](../index.md) diff --git a/docs/bmad-core-concepts/workflows.md b/docs/bmad-core-concepts/workflows.md new file mode 100644 index 00000000..44aa7f86 --- /dev/null +++ b/docs/bmad-core-concepts/workflows.md @@ -0,0 +1,89 @@ +# Workflows + +Workflows are structured processes that guide agents through complex tasks. Think of them as recipes that ensure consistent, high-quality outcomes. + +## What is a Workflow? + +A workflow is a step-by-step process that agents follow to accomplish specific objectives. A workflow can be a single file if small enough, but more than likely is comprized of a very small workflow or skill definition file with multiple steps and data files that are loaded as needed on demand. Each step file: + +- Defines a clear goal +- Provides instructions for the agent +- May include decision points or user interactions +- Produces specific outputs +- Progressively at a specific point can load the next proper step. + +## How Workflows Work + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Step 1 │ → │ Step 2 │ → │ Step 3 │ → │ Complete │ +│ Discover │ │ Define │ │ Build │ │ Output │ +└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ +``` + +**Key characteristics:** +- **Progressive** - Each step builds on the previous +- **Interactive** - Workflows can pause for user input +- **Reusable** - The same workflow produces consistent results +- **Composable** - Workflow steps can call other workflow steps, or whole other workflows! +- **LLM Reinforcement** - Some rules or info is repeated in each step file ensuring certain rules are always top of agent mind, even during context heavy processes or very long workflows! + +## Workflow Types + +### Planning Workflows + +Generate project artifacts like requirements, architecture, and task breakdowns. + +**Examples:** Brief creation, PRD authoring, architecture design, sprint planning + +### Execution Workflows + +Guide implementation of specific tasks or features. + +**Examples:** Code implementation, code review, testing, deployment + +### Support Workflows + +Handle cross-cutting concerns and creative processes. + +**Examples:** Brainstorming, retrospectives, root cause analysis + +## Progressive Disclosure + +BMAD workflows use **progressive disclosure** - each step only knows about its immediate next step and what it is currently meant to do. This: + +- Reduces cognitive load on the AI +- Ensures each step gets full attention +- Allows for conditional routing based on previous outcomes +- Makes workflows easier to debug and modify + +## Menu-Driven Interaction + +Most workflows use interactive menus with standard options: + +| Option | Purpose | +| ---------------- | -------------------------------------------------- | +| **[A] Advanced** | Invoke deeper reasoning techniques | +| **[P] Party** | Get multiple agent perspectives | +| **[C] Continue** | Proceed to next step after all writes are complete | + +## Workflow Files + +Workflows are markdown files with structured frontmatter - this front matter also allows them to easily work as skills and also slash command loaded: + +```yaml +--- +name: 'my-workflow' +description: 'What this workflow does and when it should be used or loaded automatically (or call out if it should be requested to run explicitly by the user)' +--- +``` + +The content in the workflow file is very minimal, sets up the reinforcement of the agent persona and reminder that it is a facilitator working with a user, lays out rules of processing steps only when told to do a specific step, loads all config file variables needed by the workflow, and then routes to step 1. No other info about other steps should be in this workflow file. Keeping it as small and lean as possible help in compilation as a skill, as overall size of the skill main file (workflow.md) is critical to keep small. + +## Creating Custom Workflows + +The **BMAD Builder (BMB)** module includes workflows for creating custom workflows. See [BMB Documentation](../modules/bmb-bmad-builder/) for details. + +--- + +**Next:** Learn about [Modules](./modules.md) to see how agents and workflows are organized. diff --git a/docs/bmad-customization/workflow-customization-guide.md b/docs/bmad-customization/workflow-customization-guide.md deleted file mode 100644 index fa17dfb4..00000000 --- a/docs/bmad-customization/workflow-customization-guide.md +++ /dev/null @@ -1,3 +0,0 @@ -# Workflow Customization Guide - -Coming Soon... \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index bcaf61e3..d9b22a2f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,91 +1,95 @@ -# BMad Documentation Index +# BMAD Documentation -## Core Documentation +Complete documentation for the BMAD Method. -### Project-Level Docs (Root) +## Getting Started -- **[README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md)** - Main project overview, feature summary, and module introductions -- **[CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style -- **[CHANGELOG.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)** - Version history and breaking changes +### New to BMAD? +Start with the core concepts to understand how BMAD works: -### Installation & Setup +- **[Core Concepts](./bmad-core-concepts/)** - Agents, workflows, and modules explained +- **[Installation Guide](./bmad-core-concepts/installing/)** - Set up BMAD in your project +- **[Quick Start Guide](./modules/bmm-bmad-method/quick-start)** - Build your first feature -- **[Quick Installation](./installing-bmad.md)** - Add BMad official and custom modules to a project folder. -- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users -- **[Document Sharding Guide](modules/core/document-sharding-guide.md)** - Split large documents -- **[Bundle Distribution Setup](../tools/docs/BUNDLE_DISTRIBUTION_SETUP.md)** - (temporarily non-functional) Maintainer guide for bundle auto-publishing +### Upgrading from v4? +- **[v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md)** - Migration path for v4 users + +--- ## Module Documentation -### Core Module Global Entities - -- **[Core Module Index](./modules/core/index)** — Shared functionality available to all modules - - [Global Core Config](./modules/core/global-core-config.md) — Inheritable configuration impacting all modules and custom content - - [Core Workflows](./modules/core/core-workflows.md) — Domain-agnostic workflows usable by any module - - [Party Mode](./modules/core/party-mode.md) — Multi-agent conversation orchestration - - [Brainstorming](./modules/core/brainstorming.md) — Structured creative sessions with 60+ techniques - - [Advanced Elicitation](./modules/core/advanced-elicitation.md) — LLM rethinking with 50+ reasoning methods - - [Core Tasks](./modules/core/core-tasks.md) — Common tasks available across modules - - [Index Docs](./modules/core/core-tasks.md#index-docs) — Generate directory index files - - [Adversarial Review](./modules/core/core-tasks.md#adversarial-review-general) — Critical content review - - [Shard Document](./modules/core/core-tasks.md#shard-document) — Split large documents into sections - -### BMad Method (BMM) - Software & Game Development +### BMAD Method (BMM) - Software & Game Development The flagship module for agile AI-driven development. -- **[BMM Module Index](./modules/bmm-bmad-method/index)** - Module overview, agents, and complete documentation index - - [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Step-by-step guide to building your first project +- **[BMM Module Index](./modules/bmm-bmad-method/index)** - Module overview, agents, and documentation + - [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Step-by-step guide - [Quick Spec Flow](./modules/bmm-bmad-method/quick-spec-flow) - Rapid Level 0-1 development - [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Working with existing codebases -- **[BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides)** - **ESSENTIAL READING** -- **[Test Architect Guide](./modules/bmm-bmad-method/test-architecture)** - Testing strategy and quality assurance +- **[BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides)** - Essential reading -### BMad Builder (BMB) - Create Custom Solutions +### BMAD Builder (BMB) - Create Custom Solutions Build your own agents, workflows, and modules. - **[BMB Module Overview](./modules/bmb-bmad-builder/index)** - Module overview and capabilities -- **[Custom Content Guide](./modules/bmb-bmad-builder/custom-content)** - Design custom agents, workflows, and modules -- **[How to Install Custom Agents, Workflows and Modules](./modules/bmb-bmad-builder/custom-content-installation.md)** - Share and Install Custom Creations +- **[Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md)** - Create custom agents +- **[Custom Content Installation](./modules/bmb-bmad-builder/custom-content-installation.md)** - Share and install custom creations ### Creative Intelligence Suite (CIS) - Innovation & Creativity -- **[CIS Docs](./modules/cis-creative-intelligence-suite/index.md)** +- **[CIS Documentation](./modules/cis-creative-intelligence-suite/index)** -#### Bmad Game Dev (BMGD) +### BMAD Game Dev (BMGD) -- [Main Game Dev Module Docs Index](./modules/bmgd-bmad-game-dev/index.md) +- **[BMGD Documentation](./modules/bmgd-bmad-game-dev/index)** - Game development workflows -AI-powered creative thinking and brainstorming. +--- -- **[CIS Module README](./modules/cis-creative-intelligence-suite/index)** - Module overview and workflows +## Core Module + +### Global Core Entities + +- **[Core Module Index](./modules/core/index)** - Shared functionality available to all modules + - [Global Core Config](./modules/core/global-core-config.md) - Inheritable configuration + - [Core Workflows](./modules/core/core-workflows.md) - Domain-agnostic workflows + - [Party Mode](./modules/core/party-mode.md) - Multi-agent conversations + - [Brainstorming](./modules/core/brainstorming.md) - Structured creative sessions + - [Advanced Elicitation](./modules/core/advanced-elicitation.md) - LLM reasoning techniques + - [Core Tasks](./modules/core/core-tasks.md) - Common tasks across modules + +--- ## Advanced Topics -### Custom Agents, Workflow and Modules -- **[Custom Content Installation](modules/bmb-bmad-builder/custom-content-installation.md)** - Install and personalize agents, workflows and modules with the default bmad-method installer! -- [Agent Customization Guide](./bmad-customization/agent-customization-guide.md) - Customize agent behavior and responses -- [Workflow Customization Guide](./bmad-customization/workflow-customization-guide.md) - Customize and Optimize workflows with step replacement and hooks (Capability Coming Soon) +### Customization + +- **[BMAD Customization](./bmad-core-concepts/bmad-customization/)** - Modify agents and workflows + +### Platform Guides + +- **[Web Bundles](./bmad-core-concepts/web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs + +--- ## Recommended Reading Paths -### Path 1: Brand New to BMad (Software Project) +### Path 1: Brand New to BMAD (Software Project) -1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision -2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on -3. [BMM Module README](./modules/bmm-bmad-method/) - Understand agents +1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows +2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD +3. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on 4. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology ### Path 2: Game Development Project -1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision -2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on +1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows +2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD 3. [BMGD Workflows Guide](./modules/bmgd-bmad-game-dev/workflows-guide) - Game-specific workflows ### Path 3: Upgrading from v4 -1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed +1. [v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md) - Understand what changed 2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Reorient yourself 3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Learn new v6 workflows @@ -95,14 +99,13 @@ AI-powered creative thinking and brainstorming. 2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Follow the process 3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology -### Path 5: Building Custom Solutions +### Path 5: Building Custom Agents -1. [BMB Module Overview](./modules/bmb-bmad-builder/index) - Understand capabilities -2. [BMB Custom Content Types](./modules/bmb-bmad-builder/custom-content.md) - Understand the different types and whats possible -3. [BMB Content Installation](./modules/bmb-bmad-builder/custom-content-installation.md) - How to bundle install use and share -4. More Docs coming soon.... +1. [Core Concepts: Agents](./bmad-core-concepts/agents.md) - Understand Simple vs Expert +2. [Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md) - Build your first agent +3. [Agent Architecture](./modules/bmb-bmad-builder/index) - Deep technical details -### Path 6: Contributing to BMad +### Path 6: Contributing to BMAD 1. [CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md) - Contribution guidelines 2. Relevant module README - Understand the area you're contributing to diff --git a/docs/modules/bmb-bmad-builder/agent-creation-guide.md b/docs/modules/bmb-bmad-builder/agent-creation-guide.md new file mode 100644 index 00000000..cb387d8b --- /dev/null +++ b/docs/modules/bmb-bmad-builder/agent-creation-guide.md @@ -0,0 +1,166 @@ +# Agent Creation Guide + +Create your own custom agents using the BMAD Builder workflow. + +## Overview + +The BMAD Builder (BMB) module provides an interactive workflow that guides you through creating a custom agent from concept to completion. You define the agent's purpose, personality, capabilities, and menu - then the workflow generates a complete, ready-to-use agent file. + +## Before You Start + +**Prerequisites:** +- BMAD installed with the BMB module +- An idea for what you want your agent to do +- About 15-30 minutes for your first agent + +**Know Before You Go:** +- What problem should your agent solve? +- Who will use this agent? +- What should the agent be able to do? + +## Quick Start + +### 1. Start the Workflow + +In your IDE (Claude Code, Cursor, etc.), invoke the create-agent workflow: + +``` +"Run the BMAD Builder create-agent workflow" +``` + +Or trigger it via the BMAD Master menu. + +### 2. Follow the Steps + +The workflow guides you through: + +| Step | What You'll Do | +|------|----------------| +| **Brainstorm** (optional) | Explore ideas with creative techniques | +| **Discovery** | Define the agent's purpose and goals | +| **Type & Metadata** | Choose Simple or Expert, name your agent | +| **Persona** | Craft the agent's personality and principles | +| **Commands** | Define what the agent can do | +| **Activation** | Set up autonomous behaviors (optional) | +| **Build** | Generate the agent file | +| **Validation** | Review and verify everything works | + +### 3. Install Your Agent + +Once created, package your agent for installation: + +``` +my-custom-stuff/ +├── module.yaml # Contains: unitary: true +├── agents/ +│ └── {agent-name}/ +│ ├── {agent-name}.agent.yaml +│ └── _memory/ # Expert agents only +│ └── {sidecar-folder}/ +└── workflows/ # Optional: custom workflows +``` + +See [Custom Content Installation](./custom-content-installation.md) for details. + +## Choosing Your Agent Type + +The workflow will help you decide, but here's the quick reference: + +### Choose Simple Agent When: + +- Task is well-defined and focused +- Don't need persistent memory +- Want fast setup and deployment +- Single-purpose assistant (e.g., commit messages, code review) + +**Example:** A "Code Commenter" that reads files and adds helpful comments. + +### Choose Expert Agent When: + +- Domain requires specialized knowledge +- Need persistent memory across sessions +- Agent coordinates complex workflows +- Building ongoing project infrastructure + +**Example:** A "Security Architect" that remembers your design decisions and maintains security standards across the project. + +### Choose Module Agent When: + +- Agent builds other agents or workflows +- Need integration with module system +- Creating professional tooling + +**Example:** A "Team Builder" that helps set up agents for new team members. + +## The Persona System + +Your agent's personality is defined by four fields: + +| Field | Purpose | Example | +|-------|---------|---------| +| **Role** | What they do | "Senior code reviewer who catches bugs and suggests improvements" | +| **Identity** | Who they are | "Friendly but exacting, believes clean code is a craft" | +| **Communication Style** | How they speak | "Direct, constructive, explains the 'why' behind suggestions" | +| **Principles** | Why they act | "Security first, clarity over cleverness, test what you fix" | + +**Key:** Keep each field focused on its purpose. The role isn't personality; the identity isn't job description. + +## Tips for Success + +### Start Small + +Your first agent should solve **one problem well**. You can always add more capabilities later. + +### Learn by Example + +Study the reference agents in `src/modules/bmb/reference/agents/`: +- **Simple:** [commit-poet](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) +- **Expert:** [journal-keeper](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) + +### Write Great Principles + +The first principle should "activate" the agent's expertise: + +❌ **Weak:** "Be helpful and accurate" +✅ **Strong:** "Channel decades of security expertise: threat modeling begins with trust boundaries, never trust client input, defense in depth is non-negotiable" + +### Use the Menu System + +The workflow provides options at each step: +- **[A] Advanced** - Get deeper insights and reasoning +- **[P] Party** - Get multiple agent perspectives +- **[C] Continue** - Move to the next step + +Use these when you need extra input or creative options. + +## After Creation + +### Test Your Agent + +1. Install your custom module using the BMAD installer +2. Invoke your new agent in your IDE +3. Try each menu command +4. Verify the personality feels right + +### Iterate + +If something isn't right: +1. Edit the agent YAML directly, or +2. Edit the customization file in `_bmad/_config/agents/` +3. Rebuild using `npx bmad-method build ` + +### Share + +Package your agent as a standalone module (see [Installation Guide](../../bmad-core-concepts/installing/)) and share it with your team or the community. + +## Further Reading + +- **[Agent Architecture](./index.md)** - Deep technical details on agent types +- **[Agent Customization](../../bmad-core-concepts/agent-customization/)** - Modify agents without editing core files +- **[Custom Content Installation](./custom-content-installation.md)** - Package and distribute your agents + +--- + +**Ready?** Start the workflow and create your first agent! + +[← Back to BMB Documentation](./index.md) diff --git a/docs/modules/bmb-bmad-builder/index.md b/docs/modules/bmb-bmad-builder/index.md index 059ba0bf..13ea51cd 100644 --- a/docs/modules/bmb-bmad-builder/index.md +++ b/docs/modules/bmb-bmad-builder/index.md @@ -1,6 +1,11 @@ # BMB Module Documentation -Reference documentation for building BMAD agents and workflows. +Create custom agents, workflows, and modules for BMAD. + +## Quick Start + +- **[Agent Creation Guide](./agent-creation-guide.md)** - Step-by-step guide to building your first agent +- **[Understanding Agent Types](./understanding-agent-types.md)** - Learn the differences between Simple and Expert agents ## Agent Architecture diff --git a/docs/web-bundles-gemini-gpt-guide.md b/docs/web-bundles-gemini-gpt-guide.md deleted file mode 100644 index 2fdd1e6c..00000000 --- a/docs/web-bundles-gemini-gpt-guide.md +++ /dev/null @@ -1,21 +0,0 @@ -# Using BMad Web Bundles in Gemini Gems & Custom GPTs - -## IMPORTANT NOTE - -The Web Bundling Feature is being rebuilt from the ground up, current bundles found for v6 may be incomplete or missing functionality and are not optimized. - -## What Are Web bundles - -Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload. - -## What Are Web Bundles? - -Web bundles are standalone files containing: - -- Complete agent persona and instructions -- All workflows and dependencies -- Interactive menu system -- Party mode for multi-agent collaboration -- No external files required - -**Perfect for:** Uploading a single file to a Gemini GEM or Custom GPT to use BMad Method from the Web, generally at a huge cost savings, at the expense of some quality and convenience of using locally. 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 d0cb2367..b245a882 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 @@ -3,7 +3,7 @@ name: 'step-01-brainstorm' description: 'Optional brainstorming for agent ideas' # File References -nextStepFile: '{project-root}/src/modules/bmb/workflows/create-agent/steps/step-02-discover.md' +nextStepFile: '{project-root}/src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md' brainstormContext: ../data/brainstorm-context.md brainstormWorkflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md' --- 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 deleted file mode 100644 index 0c14a26f..00000000 --- a/src/modules/bmb/workflows/create-agent/steps/step-02-discover.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -name: 'step-02-discover' -description: 'Discover the agent purpose and type through natural conversation' - -# File References -nextStepFile: './step-03-persona.md' -agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' -agentTypesGuide: '../data/understanding-agent-types.md' - -# Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' ---- - -# Step 2: Discover Agent Purpose and Type - -## STEP GOAL: - -Guide user to articulate their agent's core purpose and determine the appropriate agent type for their architecture needs through natural exploration and conversation. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are an agent architect who helps users discover and clarify their agent vision -- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring agent architecture expertise, user brings their domain knowledge and goals, together we design the optimal agent -- ✅ Maintain collaborative exploratory tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on discovering purpose and determining appropriate agent type -- 🚫 FORBIDDEN to push specific agent types without clear justification -- 💬 Approach: Guide through natural conversation, not interrogation -- 📋 Agent type recommendation based on architecture needs, not capability limits - -## EXECUTION PROTOCOLS: - -- 🎯 Natural conversation flow, not rigid questioning -- 💾 Document purpose and type decisions clearly -- 📖 Load technical documentation as needed for guidance -- 🚫 FORBIDDEN to make assumptions about user needs - -## CONTEXT BOUNDARIES: - -- Available context: User is creating a new agent, may have brainstorming results -- Focus: Purpose discovery and agent type determination -- Limits: No persona development, no command design yet -- Dependencies: User must articulate clear purpose and agree on agent type - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Load Technical Documentation - -Load and understand agent building documentation: - -- Agent types guide: `{agentTypesGuide}` -- Reference examples from appropriate directories as needed - -### 2. Purpose Discovery Through Conversation - -If brainstorming was completed in previous step, reference those results naturally in conversation. - -Guide user to articulate through exploratory questions: - -**Core Purpose Exploration:** -"What problems or challenges will your agent help solve?" -"Who are the primary users of this agent?" -"What makes your agent unique or special compared to existing solutions?" -"What specific tasks or workflows will this agent handle?" - -**Deep Dive Questions:** -"What's the main pain point this agent addresses?" -"How will users interact with this agent day-to-day?" -"What would success look like for users of this agent?" - -Continue conversation until purpose is clearly understood. - -### 3. Agent Type Determination - -As purpose becomes clear, analyze and recommend appropriate agent type. - -**Critical Understanding:** Agent types differ in **architecture and integration**, NOT capabilities. ALL types can write files, execute commands, and use system resources. - -**Agent Type Decision Framework:** - -- **Simple Agent** - Self-contained (all in YAML), stateless, no persistent memory - - Choose when: Single-purpose utility, each run independent, logic fits in YAML - - CAN write to output folders, update files, execute commands - - Example: Git commit helper, documentation generator, data validator - -- **Expert Agent** - Personal sidecar files, persistent memory, domain-restricted - - Choose when: Needs to remember across sessions, personal knowledge base, learning over time - - CAN have personal workflows in sidecar if critical_actions loads workflow engine - - Example: Personal research assistant, domain expert advisor, learning companion - - Example: Project coordinator, workflow manager, team orchestrator - -**Type Selection Process:** - -1. Present recommendation based on discovered needs -2. Explain WHY this type fits their architecture requirements -3. Show relevant examples from reference directories -4. Get user agreement or adjustment - -### 4. Path Determination - -**For Module Agents:** -"Which module will this agent belong to?" -"Module agents integrate with existing team infrastructure and can coordinate with other agents in the same module." - -**For Standalone Agents (Simple/Expert):** -"This will be your personal agent, independent of any specific module. It will have its own dedicated space for operation." - -### 5. Document Findings - -#### Content to Append (if applicable): - -```markdown -## Agent Purpose and Type - -### Core Purpose - -[Articulated agent purpose and value proposition] - -### Target Users - -[Primary user groups and use cases] - -### Chosen Agent Type - -[Selected agent type with detailed rationale] - -### Output Path - -[Determined output location and structure] - -### Context from Brainstorming - -[Any relevant insights from previous brainstorming session] -``` - -Save this content to {agentPlan} for reference in subsequent steps. - -### 6. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### 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 Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options) - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [agent purpose clearly articulated and agent type determined], will you then load and read fully `{nextStepFile}` to execute and begin persona development. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- Agent purpose clearly articulated and documented -- Appropriate agent type selected with solid reasoning -- User understands architectural implications of chosen type -- Output paths determined correctly based on agent type -- Content properly saved to output file -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Proceeding without clear agent purpose -- Pushing specific agent types without justification -- Not explaining architectural implications -- Failing to document findings properly -- Not getting user agreement on agent type selection - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md b/src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md new file mode 100644 index 00000000..57ca7af6 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md @@ -0,0 +1,168 @@ +--- +name: 'step-02-discovery' +description: 'Discover what user wants holistically' + +# File References +nextStepFile: './step-03-type-metadata.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +brainstormContext: ../data/brainstorm-context.md + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Conduct holistic discovery of what the user wants to create, documenting a comprehensive agent plan that serves as the single source of truth for all subsequent workflow steps. This is THE discovery moment - capture everything now so we don't re-ask later. + +# MANDATORY EXECUTION RULES + +1. **ONE-TIME DISCOVERY:** This is the only discovery step. Capture everything now. +2. **PLAN IS SOURCE OF TRUTH:** Document to agentPlan file - all later steps reference this plan. +3. **NO RE-ASKING:** Later steps MUST read from plan, not re-ask questions. +4. **REFERENCE BRAINSTORM:** If brainstorming occurred in step-01, integrate those results. +5. **STRUCTURED OUTPUT:** Plan must follow Purpose, Goals, Capabilities, Context, Users structure. +6. **LANGUAGE ALIGNMENT:** Continue using {language} if configured in step-01. + +# EXECUTION PROTOCOLS + +## Protocol 1: Check for Previous Context + +Before starting discovery: +- Check if brainstormContext file exists +- If yes, read and reference those results +- Integrate brainstorming insights into conversation naturally + +## Protocol 2: Discovery Conversation + +Guide the user through holistic discovery covering: + +1. **Purpose:** What problem does this agent solve? Why does it need to exist? +2. **Goals:** What should this agent accomplish? What defines success? +3. **Capabilities:** What specific abilities should it have? What tools/skills? +4. **Context:** Where will it be used? What's the environment/setting? +5. **Users:** Who will use this agent? What's their skill level? + +Use conversational exploration: +- Ask open-ended questions +- Probe deeper on important aspects +- Validate understanding +- Uncover implicit requirements + +## Protocol 3: Documentation + +Document findings to agentPlan file using this structure: + +```markdown +# Agent Plan: {agent_name} + +## Purpose +[Clear, concise statement of why this agent exists] + +## Goals +- [Primary goal 1] +- [Primary goal 2] +- [Secondary goals as needed] + +## Capabilities +- [Core capability 1] +- [Core capability 2] +- [Additional capabilities with tools/skills] + +## Context +[Deployment environment, use cases, constraints] + +## Users +- [Target audience description] +- [Skill level assumptions] +- [Usage patterns] +``` + +## Protocol 4: Completion Menu + +After documentation, present menu: + +**[A]dvanced Discovery** - Invoke advanced-elicitation task for deeper exploration +**[P]arty Mode** - Invoke party-mode workflow for creative ideation +**[C]ontinue** - Proceed to next step (type-metadata) + +# CONTEXT BOUNDARIES + +**DISCOVER:** +- Agent purpose and problem domain +- Success metrics and goals +- Required capabilities and tools +- Usage context and environment +- Target users and skill levels + +**DO NOT DISCOVER:** +- Technical implementation details (later steps) +- Exact persona traits (next step) +- Command structures (later step) +- Name/branding (later step) +- Validation criteria (later step) + +**KEEP IN SCOPE:** +- Holistic understanding of what to build +- Clear articulation of value proposition +- Comprehensive capability mapping + +# EXECUTION SEQUENCE + +1. **Load Previous Context** + - Check for brainstormContext file + - Read if exists, note integration points + +2. **Start Discovery Conversation** + - Reference brainstorming results if available + - "Let's discover what you want to create..." + - Explore purpose, goals, capabilities, context, users + +3. **Document Plan** + - Create agentPlan file + - Structure with Purpose, Goals, Capabilities, Context, Users + - Ensure completeness and clarity + +4. **Present Completion Menu** + - Show [A]dvanced Discovery option + - Show [P]arty Mode option + - Show [C]ontinue to next step + - Await user selection + +5. **Handle Menu Choice** + - If A: Invoke advanced-elicitation task, then re-document + - If P: Invoke party-mode workflow, then re-document + - If C: Proceed to step-03-type-metadata + +# CRITICAL STEP COMPLETION NOTE + +**THIS STEP IS COMPLETE WHEN:** +- agentPlan file exists with complete structure +- All five sections (Purpose, Goals, Capabilities, Context, Users) populated +- User confirms accuracy via menu selection +- Either continuing to next step or invoking optional workflows + +**BEFORE PROCEEDING:** +- Verify plan file is readable +- Ensure content is sufficient for subsequent steps +- Confirm user is satisfied with discoveries + +# SUCCESS METRICS + +**SUCCESS:** +- agentPlan file created with all required sections +- User has provided clear, actionable requirements +- Plan contains sufficient detail for persona, commands, and name steps +- User explicitly chooses to continue or invokes optional workflow + +**FAILURE:** +- Unable to extract coherent purpose or goals +- User cannot articulate basic requirements +- Plan sections remain incomplete or vague +- User requests restart + +**RECOVERY:** +- If requirements unclear, use advanced-elicitation task +- If user stuck, offer party-mode for creative exploration +- If still unclear, suggest revisiting brainstorming step 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 deleted file mode 100644 index 7f61a273..00000000 --- a/src/modules/bmb/workflows/create-agent/steps/step-03-persona.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -name: 'step-03-persona' -description: 'Shape the agent personality through collaborative discovery' - -# File References -nextStepFile: ./step-04-commands.md -agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' -communicationPresets: ../data/communication-presets.csv - -# Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' ---- - -# Step 3: Shape Agent's Personality - -## STEP GOAL: - -Guide user to develop the agent's complete persona using the four-field system while preserving distinct purposes for each field and ensuring alignment with the agent's purpose. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are a persona architect who helps users craft compelling agent personalities -- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring persona development expertise, user brings their vision and preferences, together we create an authentic agent personality -- ✅ Maintain collaborative creative tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on developing the four persona fields distinctly -- 🚫 FORBIDDEN to mix persona fields or confuse their purposes -- 💬 Approach: Guide discovery through natural conversation, not formulaic questioning -- 📋 Each field must serve its distinct purpose without overlap - -## EXECUTION PROTOCOLS: - -- 🎯 Natural personality discovery through conversation -- 💾 Document all four fields clearly and separately -- 📖 Load communication presets for style selection when needed -- 🚫 FORBIDDEN to create generic or mixed-field personas - -## CONTEXT BOUNDARIES: - -- Available context: Agent purpose and type from step 2, optional brainstorming insights -- Focus: Develop four distinct persona fields (role, identity, communication_style, principles) -- Limits: No command design, no technical implementation yet -- Dependencies: Clear agent purpose and type from previous step - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Understanding the Four Persona Fields - -Explain to user: "Each field serves a DISTINCT purpose when the compiled agent LLM reads them:" - -**Role → WHAT the agent does** - -- LLM interprets: "What knowledge, skills, and capabilities do I possess?" -- Examples: "Strategic Business Analyst + Requirements Expert", "Commit Message Artisan" - -**Identity → WHO the agent is** - -- LLM interprets: "What background, experience, and context shape my responses?" -- Examples: "Senior analyst with 8+ years connecting market insights to strategy..." - -**Communication_Style → HOW the agent talks** - -- LLM interprets: "What verbal patterns, word choice, quirks, and phrasing do I use?" -- Examples: "Talks like a pulp super hero with dramatic flair and heroic language" - -**Principles → WHAT GUIDES the agent's decisions** - -- LLM interprets: "What beliefs and operating philosophy drive my choices and recommendations?" -- Examples: "Every business challenge has root causes. Ground findings in evidence." - -### 2. Role Development - -Guide conversation toward a clear 1-2 line professional title: - -"Based on your agent's purpose to {{discovered_purpose}}, what professional title captures its essence?" - -**Role Crafting Process:** - -- Start with core capabilities discovered in step 2 -- Refine to professional, expertise-focused language -- Ensure role clearly defines the agent's domain -- Examples: "Strategic Business Analyst + Requirements Expert", "Code Review Specialist" - -Continue conversation until role is clear and professional. - -### 3. Identity Development - -Build 3-5 line identity statement establishing credibility: - -"What background and specializations would give this agent credibility in its role?" - -**Identity Elements to Explore:** - -- Experience level and background -- Specialized knowledge areas -- Professional context and perspective -- Domain expertise -- Approach to problem-solving - -### 4. Communication Style Selection - -Present communication style categories: - -"Let's choose a communication style. I have 13 categories available - which type of personality appeals to you for your agent?" - -**Categories to Present:** - -- adventurous (pulp-superhero, film-noir, pirate-captain, etc.) -- analytical (data-scientist, forensic-investigator, strategic-planner) -- creative (mad-scientist, artist-visionary, jazz-improviser) -- devoted (overprotective-guardian, adoring-superfan, loyal-companion) -- dramatic (shakespearean, soap-opera, opera-singer) -- educational (patient-teacher, socratic-guide, sports-coach) -- entertaining (game-show-host, stand-up-comedian, improv-performer) -- inspirational (life-coach, mountain-guide, phoenix-rising) -- mystical (zen-master, tarot-reader, yoda-sage, oracle) -- professional (executive-consultant, supportive-mentor, direct-consultant) -- quirky (cooking-chef, nature-documentary, conspiracy-theorist) -- retro (80s-action-hero, 1950s-announcer, disco-era) -- warm (southern-hospitality, italian-grandmother, camp-counselor) - -**Selection Process:** - -1. Ask user which category interests them -2. Load ONLY that category from `{communicationPresets}` -3. Present presets with name, style_text, and sample -4. Use style_text directly as communication_style value - -**CRITICAL:** Keep communication style CONCISE (1-2 sentences MAX) describing ONLY how they talk. - -### 5. Principles Development - -Guide user to articulate 5-8 core principles: - -"What guiding beliefs should direct this agent's decisions and recommendations? Think about what makes your approach unique." - -Guide them to use "I believe..." or "I operate..." statements covering: - -- Quality standards and excellence -- User-centric values -- Problem-solving approaches -- Professional ethics -- Communication philosophy -- Decision-making criteria - -### 6. Interaction Approach Determination - -Ask: "How should this agent guide users - with adaptive conversation (intent-based) or structured steps (prescriptive)?" - -**Intent-Based (Recommended):** - -- Agent adapts conversation based on user context, skill level, needs -- Flexible, conversational, responsive to user's unique situation -- Example: "Guide user to understand their problem by exploring symptoms, attempts, and desired outcomes" - -**Prescriptive:** - -- Agent follows structured questions with specific options -- Consistent, predictable, clear paths -- Example: "Ask: 1. What is the issue? [A] Performance [B] Security [C] Usability" - -### 7. Document Complete Persona - -#### Content to Append (if applicable): - -```markdown -## Agent Persona - -### Role - -[1-2 line professional title defining what the agent does] - -### Identity - -[3-5 line background establishing credibility and context] - -### Communication_Style - -[1-2 sentence description of verbal patterns and talking style] - -### Principles - -- [5-8 guiding belief statements using "I believe..." or "I operate..."] -- [Each principle should guide decision-making] - -### Interaction Approach - -[Intent-based or Prescriptive with rationale] -``` - -Append this content to {agentPlan} for reference in subsequent steps. - -### 8. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### 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 Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options) - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [all four persona fields clearly defined with distinct purposes], will you then load and read fully `{nextStepFile}` to execute and begin command development. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- All four persona fields clearly defined with distinct purposes -- Communication style concise and pure (no mixing with other fields) -- 5-8 guiding principles articulated in proper format -- Interaction approach selected with clear rationale -- Persona aligns with agent purpose discovered in step 2 -- Content properly saved to output file -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Mixing persona fields or confusing their purposes -- Communication style too long or includes role/identity/principles -- Fewer than 5 or more than 8 principles -- Not getting user confirmation on persona feel -- Proceeding without complete persona development - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-03-type-metadata.md b/src/modules/bmb/workflows/create-agent/steps/step-03-type-metadata.md new file mode 100644 index 00000000..34f58f30 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-03-type-metadata.md @@ -0,0 +1,294 @@ +--- +name: 'step-02-type-metadata' +description: 'Determine agent type and define metadata' + +# File References +nextStepFile: './step-04-persona.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +agentTypesDoc: ../data/understanding-agent-types.md +agentMetadata: ../data/agent-metadata.md + +# Example Agents (for reference) +simpleExample: ../data/reference/simple-examples/commit-poet.agent.yaml +expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml +moduleExample: ../data/reference/module-examples/security-engineer.agent.yaml + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Determine the agent's classification (Simple/Expert/Module) and define all mandatory metadata properties required for agent configuration. Output structured YAML to the agent plan file for downstream consumption. + +--- + +# MANDATORY EXECUTION RULES + +## Universal Rules +- ALWAYS use `{agent-language}` for all conversational text +- MAINTAIN step boundaries - complete THIS step only +- DOCUMENT all decisions to agent plan file +- HONOR user's creative control throughout + +## Role Reinforcement +You ARE a master agent architect guiding collaborative agent creation. Balance: +- Technical precision in metadata definition +- Creative exploration of agent possibilities +- Clear documentation for downstream steps + +## Step-Specific Rules +- LOAD and reference agentTypesDoc and agentMetadata before conversations +- NEVER skip metadata properties - all are mandatory +- VALIDATE type selection against user's articulated needs +- OUTPUT structured YAML format exactly as specified +- SHOW examples when type classification is unclear + +--- + +# EXECUTION PROTOCOLS + +## Protocol 1: Documentation Foundation +Load reference materials first: +1. Read agentTypesDoc for classification criteria +2. Read agentMetadata for property definitions +3. Keep examples ready for illustration + +## Protocol 2: Purpose Discovery +Guide natural conversation to uncover: +- Primary agent function/responsibility +- Complexity level (single task vs multi-domain) +- Scope boundaries (standalone vs manages workflows) +- Integration needs (other agents/workflows) + +## Protocol 3: Type Determination +Classify based on criteria: +- **Simple**: Single focused purpose, minimal complexity (e.g., code reviewer, documentation generator) +- **Expert**: Advanced domain expertise, multi-capability, manages complex tasks (e.g., game architect, system designer) +- **Module**: Agent builder/manager, creates workflows, deploys other agents (e.g., agent-builder, workflow-builder) + +## Protocol 4: Metadata Definition +Define each property systematically: +- **id**: Technical identifier (lowercase, hyphens, no spaces) +- **name**: Display name (conventional case, clear branding) +- **title**: Concise function description (one line, action-oriented) +- **icon**: Visual identifier (emoji or short symbol) +- **module**: Module path (format: `{project}:{type}:{name}`) +- **hasSidecar**: Boolean - manages external workflows? (default: false) + +## Protocol 5: Documentation Structure +Output to agent plan file in exact YAML format: + +```yaml +# Agent Type & Metadata +agent_type: [Simple|Expert|Module] +classification_rationale: | + +metadata: + id: [technical-identifier] + name: [Display Name] + title: [One-line action description] + icon: [emoji-or-symbol] + module: [project:type:name] + hasSidecar: [true|false] +``` + +## Protocol 6: Confirmation Menu +Present structured options: +- **[A] Accept** - Confirm and advance to next step +- **[P] Pivot** - Modify type/metadata choices +- **[C] Clarify** - Ask questions about classification + +--- + +# CONTEXT BOUNDARIES + +## In Scope +- Agent type classification +- All 6 metadata properties +- Documentation to plan file +- Type selection guidance with examples + +## Out of Scope (Future Steps) +- Persona/character development (Step 3) +- Command structure design (Step 4) +- Agent naming/branding refinement (Step 5) +- Implementation/build (Step 6) +- Validation/testing (Step 7) + +## Red Flags to Address +- User wants complex agent but selects "Simple" type +- Module classification without workflow management needs +- Missing or unclear metadata properties +- Module path format confusion + +--- + +# INSTRUCTION SEQUENCE + +## 1. Load Documentation +Read and internalize: +- `{agentTypesDoc}` - Classification framework +- `{agentMetadata}` - Property definitions +- Keep examples accessible for reference + +## 2. Purpose Discovery Conversation +Engage user with questions in `{agent-language}`: +- "What is the primary function this agent will perform?" +- "How complex are the tasks this agent will handle?" +- "Will this agent need to manage workflows or other agents?" +- "What specific domains or expertise areas are involved?" + +Listen for natural language cues about scope and complexity. + +## 3. Agent Type Determination +Based on discovery, propose classification: +- Present recommended type with reasoning +- Show relevant example if helpful +- Confirm classification matches user intent +- Allow pivoting if user vision evolves + +**Conversation Template:** +``` +Based on our discussion, I recommend classifying this as a [TYPE] agent because: +[reasoning from discovery] + +[If helpful: "For reference, here's a similar [TYPE] agent:"] +[Show relevant example path: simpleExample/expertExample/moduleExample] + +Does this classification feel right to you? +``` + +## 4. Define All Metadata Properties +Work through each property systematically: + +**4a. Agent ID** +- Technical identifier for file naming +- Format: lowercase, hyphens, no spaces +- Example: `code-reviewer`, `journal-keeper`, `security-engineer` +- User confirms or modifies + +**4b. Agent Name** +- Display name for branding/UX +- Conventional case, memorable +- Example: `Code Reviewer`, `Journal Keeper`, `Security Engineer` +- May differ from id (kebab-case vs conventional case) + +**4c. Agent Title** +- Concise action description +- One line, captures primary function +- Example: `Reviews code quality and test coverage`, `Manages daily journal entries` +- Clear and descriptive + +**4d. Icon Selection** +- Visual identifier for UI/branding +- Emoji or short symbol +- Example: `🔍`, `📓`, `🛡️` +- Should reflect agent function + +**4e. Module Path** +- Complete module identifier +- Format: `{project}:{type}:{name}` +- Example: `bmb:agents:code-reviewer` +- Guide user through structure if unfamiliar + +**4f. Sidecar Configuration** +- Boolean: manages external workflows? +- Typically false for Simple/Expert agents +- True for Module agents that deploy workflows +- Confirm based on user's integration needs + +**Conversation Template:** +``` +Now let's define each metadata property: + +**ID (technical identifier):** [proposed-id] +**Name (display name):** [Proposed Name] +**Title (function description):** [Action description for function] +**Icon:** [emoji/symbol] +**Module path:** [project:type:name] +**Has Sidecar:** [true/false with brief explanation] + +[Show structured preview] + +Ready to confirm, or should we adjust any properties? +``` + +## 5. Document to Plan File +Write to `{agentPlan}`: + +```yaml +# Agent Type & Metadata +agent_type: [Simple|Expert|Module] +classification_rationale: | + [Clear explanation of why this type matches user's articulated needs] + +metadata: + id: [technical-identifier] + name: [Display Name] + title: [One-line action description] + icon: [emoji-or-symbol] + module: [project:type:name] + hasSidecar: [true|false] + +# Type Classification Notes +type_decision_date: [YYYY-MM-DD] +type_confidence: [High/Medium/Low] +considered_alternatives: | + - [Alternative type]: [reason not chosen] + - [Alternative type]: [reason not chosen] +``` + +### 6. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- 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: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [agent type classified and all 6 metadata properties defined and documented], will you then load and read fully `{nextStepFile}` to execute and begin persona development. + +--- + +# SYSTEM SUCCESS/FAILURE METRICS + +## Success Indicators +- Type classification clearly justified +- All metadata properties populated correctly +- YAML structure matches specification exactly +- User confirms understanding and acceptance +- Agent plan file updated successfully + +## Failure Indicators +- Missing or undefined metadata properties +- YAML structure malformed +- User confusion about type classification +- Inadequate documentation to plan file +- Proceeding without user confirmation + +## Recovery Mode +If user struggles with classification: +- Show concrete examples from each type +- Compare/contrast types with their use case +- Ask targeted questions about complexity/scope +- Offer type recommendation with clear reasoning + +Recover metadata definition issues by: +- Showing property format examples +- Explaining technical vs display naming +- Clarifying module path structure +- Defining sidecar use cases 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 deleted file mode 100644 index 496fcdbd..00000000 --- a/src/modules/bmb/workflows/create-agent/steps/step-04-commands.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -name: 'step-04-commands' -description: 'Build capabilities through natural progression and refine commands' - -# File References -nextStepFile: './step-05-name.md' -agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.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' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' ---- - -# Step 4: Build Capabilities and Commands - -## STEP GOAL: - -Transform user's desired capabilities into structured YAML command system with proper workflow references and implementation approaches while maintaining natural conversational flow. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are a command architect who translates user capabilities into technical implementations -- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring technical architecture expertise, user brings their capability vision, together we create implementable command structures -- ✅ Maintain collaborative technical tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on translating capabilities to structured command system -- 🚫 FORBIDDEN to add help/exit commands (auto-injected by compiler) -- 💬 Approach: Guide through technical implementation without breaking conversational flow -- 📋 Build commands naturally from capability discussion - -## EXECUTION PROTOCOLS: - -- 🎯 Natural capability discovery leading to structured command development -- 💾 Document all commands with proper YAML structure and workflow references -- 📖 Load architecture documentation based on agent type for guidance -- 🚫 FORBIDDEN to create technical specifications without user capability input - -## CONTEXT BOUNDARIES: - -- Available context: Agent purpose, type, and persona from previous steps -- Focus: Capability discovery and command structure development -- Limits: No agent naming, no YAML generation yet, just planning -- Dependencies: Clear understanding of agent purpose and capabilities from user - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Capability Discovery - -Guide user to define agent capabilities through natural conversation: - -"Let's explore what your agent should be able to do. Start with the core capabilities you mentioned during our purpose discovery, then we'll expand from there." - -**Capability Exploration Questions:** - -- "What's the first thing users will want this agent to do?" -- "What complex analyses or tasks should it handle?" -- "How should it help users with common problems in its domain?" -- "What unique capabilities make this agent special?" - -Continue conversation until comprehensive capability list is developed. - -### 2. Architecture-Specific Capability Planning - -Load appropriate architecture documentation based on agent type: - -**Simple Agent:** - -- Load `{simpleAgentArch}` -- Focus on single-execution capabilities -- All logic must fit within YAML structure -- No persistent memory between runs - -**Expert Agent:** - -- Load `{expertAgentArch}` -- Plan for sidecar file integration -- Persistent memory capabilities -- Domain-restricted knowledge base - -**Module Agent:** - -- Module architecture documentation not available - use expert architecture as baseline -- Workflow orchestration capabilities -- Team integration features -- Cross-agent coordination - -### 3. Command Structure Development - -Transform natural language capabilities into technical YAML structure: - -**Command Transformation Process:** - -1. **Natural capability** → **Trigger phrase** -2. **Implementation approach** → **Workflow/action reference** -3. **User description** → **Command description** -4. **Technical needs** → **Parameters and data** - -Explain the YAML structure to user: -"Each command needs a trigger (what users say), description (what it does), and either a workflow reference or direct action." - -### 4. Workflow Integration Planning - -For commands that will invoke workflows: - -**Existing Workflows:** - -- Verify paths are correct -- Ensure workflow compatibility -- Document integration points - -**New Workflows Needed:** - -- Note that they'll be created with intent-based + interactive defaults -- Document requirements for future workflow creation -- Specify data flow and expected outcomes - -**Workflow Vendoring (Advanced):** -For agents needing workflows from other modules, explain: -"When your agent needs workflows from another module, we use both workflow (source) and workflow-install (destination). During installation, the workflow will be copied and configured for this module." - -### 5. Advanced Features Discussion - -If user seems engaged, explore special features: - -**Complex Analysis Prompts:** -"Should this agent have special prompts for complex analyses or critical decision points?" - -**Critical Setup Steps:** -"Are there critical steps the agent should always perform during activation?" - -**Error Handling:** -"How should the agent handle unexpected situations or user errors?" - -**Learning and Adaptation (Expert Agents):** -"Should this agent learn from user interactions and adapt over time?" - -### 6. Document Complete Command Structure - -#### Content to Append (if applicable): - -```markdown -## Agent Commands and Capabilities - -### Core Capabilities Identified - -[List of user capabilities discovered through conversation] - -### Command Structure - -[YAML command structure for each capability] - -### Workflow Integration Plan - -[Details of workflow references and integration points] - -### Advanced Features - -[Special capabilities and handling approaches] - -### Implementation Notes - -[Architecture-specific considerations and technical requirements] -``` - -Save this content to {agentPlan} for reference in subsequent steps. - -### 7. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### 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 Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options) - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [capabilities transformed into structured command system], will you then load and read fully `{nextStepFile}` to execute and begin agent naming. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- User capabilities discovered and documented naturally -- Capabilities transformed into structured command system -- Proper workflow integration planned and documented -- Architecture-specific capabilities addressed appropriately -- Advanced features identified and documented when relevant -- Menu patterns compliant with BMAD standards -- Content properly saved to output file -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Adding help/exit commands (auto-injected by compiler) -- Creating technical specifications without user input -- Not considering agent type architecture constraints -- Failing to document workflow integration properly -- Breaking conversational flow with excessive technical detail - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-04-persona.md b/src/modules/bmb/workflows/create-agent/steps/step-04-persona.md new file mode 100644 index 00000000..2c81b6db --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-04-persona.md @@ -0,0 +1,210 @@ +--- +name: 'step-03-persona' +description: 'Shape the agent personality through four-field persona system' + +# File References +nextStepFile: './step-05-commands-menu.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +communicationPresets: ../data/communication-presets.csv + +# Example Personas (for reference) +simpleExample: ../data/reference/simple-examples/commit-poet.agent.yaml +expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Develop a complete four-field persona that defines the agent's personality, expertise, communication approach, and guiding principles. This persona becomes the foundation for how the agent thinks, speaks, and makes decisions. + +# MANDATORY EXECUTION RULES + +**CRITICAL: Field Purity Enforcement** +- Each persona field has ONE specific purpose +- NO mixing concepts between fields +- NO overlapping responsibilities +- Every field must be distinct and non-redundant + +**Output Requirements:** +- Produce structured YAML block ready for agent.yaml +- Follow principles-crafting guidance exactly +- First principle MUST be the "expert activator" +- All fields must be populated before proceeding + +# EXECUTION PROTOCOLS + +## Protocol 1: Load Reference Materials + +Read and integrate: +- `personaProperties.md` - Field definitions and boundaries +- `principlesCrafting.md` - Principles composition guidance +- `communicationPresets.csv` - Style options and templates +- Reference examples for pattern recognition + +## Protocol 2: Four-Field System Education + +Explain each field clearly: + +**1. Role (WHAT they do)** +- Professional identity and expertise domain +- Capabilities and knowledge areas +- NOT personality or communication style +- Pure functional definition + +**2. Identity (WHO they are)** +- Character, personality, attitude +- Emotional intelligence and worldview +- NOT job description or communication format +- Pure personality definition + +**3. Communication Style (HOW they speak)** +- Language patterns, tone, voice +- Formality, verbosity, linguistic preferences +- NOT expertise or personality traits +- Pure expression definition + +**4. Principles (WHY they act)** +- Decision-making framework and values +- Behavioral constraints and priorities +- First principle = expert activator (core mission) +- Pure ethical/operational definition + +## Protocol 3: Progressive Field Development + +### 3.1 Role Development +- Define primary expertise domain +- Specify capabilities and knowledge areas +- Identify what makes them an "expert" +- Keep it functional, not personal + +**Role Quality Checks:** +- Can I describe their job without personality? +- Would this fit in a job description? +- Is it purely about WHAT they do? + +### 3.2 Identity Development +- Define personality type and character +- Establish emotional approach +- Set worldview and attitude +- Keep it personal, not functional + +**Identity Quality Checks:** +- Can I describe their character without job title? +- Would this fit in a character profile? +- Is it purely about WHO they are? + +### 3.3 Communication Style Development +- Review preset options from CSV +- Select or customize style pattern +- Define tone, formality, voice +- Set linguistic preferences + +**Communication Quality Checks:** +- Can I describe their speech patterns without expertise? +- Is it purely about HOW they express themselves? +- Would this fit in a voice acting script? + +### 3.4 Principles Development +Follow `principlesCrafting.md` guidance: +1. **Principle 1: Expert Activator** - Core mission and primary directive +2. **Principle 2-5: Decision Framework** - Values that guide choices +3. **Principle 6+: Behavioral Constraints** - Operational boundaries + +**Principles Quality Checks:** +- Does first principle activate expertise immediately? +- Do principles create decision-making clarity? +- Would following these produce the desired behavior? + +## Protocol 4: Structured YAML Generation + +Output the four-field persona in this exact format: + +```yaml +role: > + [Single sentence defining expertise and capabilities] + +identity: > + [2-3 sentences describing personality and character] + +communication_style: > + [Specific patterns for tone, formality, and voice] + +principles: + - [Expert activator - core mission] + - [Decision framework value 1] + - [Decision framework value 2] + - [Behavioral constraint 1] + - [Behavioral constraint 2] +``` + +# CONTEXT BOUNDARIES + +**Include in Persona:** +- Professional expertise and capabilities (role) +- Personality traits and character (identity) +- Language patterns and tone (communication) +- Decision-making values (principles) + +**Exclude from Persona:** +- Technical skills (belongs in knowledge) +- Tool usage (belongs in commands) +- Workflow steps (belongs in orchestration) +- Data structures (belongs in implementation) + +# EXECUTION SEQUENCE + +1. **LOAD** personaProperties.md and principlesCrafting.md +2. **EXPLAIN** four-field system with clear examples +3. **DEVELOP** Role - define expertise domain and capabilities +4. **DEVELOP** Identity - establish personality and character +5. **DEVELOP** Communication Style - select/customize style preset +6. **DEVELOP** Principles - craft 5-7 principles following guidance +7. **OUTPUT** structured YAML block for agent.yaml +8. **DOCUMENT** to agent-plan.md +9. **PRESENT** completion menu + +## 9. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- 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](#9-present-menu-options) + +### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [all four persona fields populated with DISTINCT content and field purity verified], will you then load and read fully `{nextStepFile}` to execute and begin command structure design. + +--- + +# SUCCESS METRICS + +**Completion Indicators:** +- Four distinct, non-overlapping persona fields +- First principle activates expert capabilities +- Communication style is specific and actionable +- YAML structure is valid and ready for agent.yaml +- User confirms persona accurately reflects vision + +**Failure Indicators:** +- Role includes personality traits +- Identity includes job descriptions +- Communication includes expertise details +- Principles lack expert activator +- Fields overlap or repeat concepts +- User expresses confusion or disagreement diff --git a/src/modules/bmb/workflows/create-agent/steps/step-05-commands-menu.md b/src/modules/bmb/workflows/create-agent/steps/step-05-commands-menu.md new file mode 100644 index 00000000..c5793515 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-05-commands-menu.md @@ -0,0 +1,176 @@ +--- +name: 'step-04-commands-menu' +description: 'Build capabilities and command structure' + +# File References +nextStepFile: './step-06-activation.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +agentMenuPatterns: ../data/agent-menu-patterns.md + +# Example Menus (for reference) +simpleExample: ../data/reference/simple-examples/commit-poet.agent.yaml +expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Transform discovered capabilities into structured menu commands following BMAD menu patterns, creating the agent's interaction interface. + +# MANDATORY EXECUTION RULES + +1. **MUST** load agent-menu-patterns.md before any conversation +2. **MUST** use menu patterns as structural templates +3. **MUST** keep final menu YAML under 100 lines +4. **MUST** include trigger, description, and handler/action for each command +5. **MUST NOT** add help or exit commands (auto-injected) +6. **MUST** document menu YAML in agent-plan before completion +7. **MUST** complete Menu [A][P][C] verification + +# EXECUTION PROTOCOLS + +## Load Menu Patterns + +Read agentMenuPatterns file to understand: +- Command structure requirements +- YAML formatting standards +- Handler/action patterns +- Best practices for menu design + +## Capability Discovery Conversation + +Guide collaborative conversation to: +1. Review capabilities from previous step +2. Identify which capabilities become commands +3. Group related capabilities +4. Define command scope and boundaries + +Ask targeted questions: +- "Which capabilities are primary commands vs secondary actions?" +- "Can related capabilities be grouped under single commands?" +- "What should each command accomplish?" +- "How should commands be triggered?" + +## Command Structure Development + +For each command, define: + +1. **Trigger** - User-facing command name + - Clear, intuitive, following naming conventions + - Examples: `/analyze`, `/create`, `/review` + +2. **Description** - What the command does + - Concise (one line preferred) + - Clear value proposition + - Examples: "Analyze code for issues", "Create new document" + +3. **Handler/Action** - How command executes + - Reference to specific capability or skill + - Include parameters if needed + - Follow pattern from agent-menu-patterns.md + +## Structure Best Practices + +- **Group related commands** logically +- **Prioritize frequently used** commands early +- **Use clear, action-oriented** trigger names +- **Keep descriptions** concise and valuable +- **Match handler names** to actual capabilities + +## Document Menu YAML + +Create structured menu YAML following format from agent-menu-patterns.md: + +```yaml +menu: + commands: + - trigger: "/command-name" + description: "Clear description of what command does" + handler: "specific_capability_or_skill" + parameters: + - name: "param_name" + description: "Parameter description" + required: true/false +``` + +## Menu [A][P][C] Verification + +**[A]ccuracy** +- All commands match defined capabilities +- Triggers are clear and intuitive +- Handlers reference actual capabilities + +**[P]attern Compliance** +- Follows agent-menu-patterns.md structure +- YAML formatting is correct +- No help/exit commands included + +**[C]ompleteness** +- All primary capabilities have commands +- Commands cover agent's core functions +- Menu is ready for next step + +# CONTEXT BOUNDARIES + +- **Focus on command structure**, not implementation details +- **Reference example menus** for patterns, not copying +- **Keep menu concise** - better fewer, clearer commands +- **User-facing perspective** - triggers should feel natural +- **Capability alignment** - every command maps to a capability + +# EXECUTION SEQUENCE + +1. Load agent-menu-patterns.md to understand structure +2. Review capabilities from agent-plan step 3 +3. Facilitate capability-to-command mapping conversation +4. Develop command structure for each capability +5. Define trigger, description, handler for each command +6. Verify no help/exit commands (auto-injected) +7. Document structured menu YAML to agent-plan +8. Complete Menu [A][P][C] verification +9. Confirm readiness for next step + +## 10. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- 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](#10-present-menu-options) + +### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [menu YAML documented in agent-plan and all commands have trigger/description/handler], will you then load and read fully `{nextStepFile}` to execute and begin activation planning. + +--- + +# SUCCESS METRICS + +✅ Menu YAML documented in agent-plan +✅ All commands have trigger, description, handler +✅ Menu follows agent-menu-patterns.md structure +✅ No help/exit commands included +✅ Menu [A][P][C] verification passed +✅ Ready for activation phase + +# FAILURE INDICATORS + +❌ Menu YAML missing from agent-plan +❌ Commands missing required elements (trigger/description/handler) +❌ Menu doesn't follow pattern structure +❌ Help/exit commands manually added +❌ Menu [A][P][C] verification failed +❌ Unclear command triggers or descriptions 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 deleted file mode 100644 index 950b542c..00000000 --- a/src/modules/bmb/workflows/create-agent/steps/step-05-name.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -name: 'step-05-name' -description: 'Name the agent based on discovered characteristics' - -# File References -nextStepFile: ./step-06-build.md -agentPlan: '{bmb_creations_output_folder}/agent-plan-{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 5: Agent Naming and Identity - -## STEP GOAL: - -Guide user to name the agent naturally based on its discovered purpose, personality, and capabilities while establishing a complete identity package. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are an identity architect who helps users discover the perfect name for their agent -- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring naming expertise, user brings their agent vision, together we create an authentic identity -- ✅ Maintain collaborative creative tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on naming agent based on discovered characteristics -- 🚫 FORBIDDEN to force generic or inappropriate names -- 💬 Approach: Let naming emerge naturally from agent characteristics -- 📋 Connect personality traits and capabilities to naming options - -## EXECUTION PROTOCOLS: - -- 🎯 Natural naming exploration based on agent characteristics -- 💾 Document complete identity package (name, title, icon, filename) -- 📖 Review discovered characteristics for naming inspiration -- 🚫 FORBIDDEN to suggest names without connecting to agent identity - -## CONTEXT BOUNDARIES: - -- Available context: Agent purpose, persona, and capabilities from previous steps -- Focus: Agent naming and complete identity package establishment -- Limits: No YAML generation yet, just identity development -- Dependencies: Complete understanding of agent characteristics from previous steps - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Naming Context Setup - -Present this to the user: - -"Now that we know who your agent is - its purpose, personality, and capabilities - let's give it the perfect name that captures its essence." - -**Review Agent Characteristics:** - -- Purpose: {{discovered_purpose}} -- Role: {{developed_role}} -- Communication style: {{selected_style}} -- Key capabilities: {{main_capabilities}} - -### 2. Naming Elements Exploration - -Guide user through each identity element: - -**Agent Name (Personal Identity):** -"What name feels right for this agent? Think about:" - -- Personality-based names (e.g., "Sarah", "Max", "Data Wizard") -- Domain-inspired names (e.g., "Clarity", "Nexus", "Catalyst") -- Functional names (e.g., "Builder", "Analyzer", "Orchestrator") - -**Agent Title (Professional Identity):** -"What professional title captures its role?" - -- Based on the role discovered earlier (already established) -- Examples: "Strategic Business Analyst", "Code Review Specialist", "Research Assistant" - -**Agent Icon (Visual Identity):** -"What emoji captures its personality and function?" - -- Should reflect both personality and purpose -- Examples: 🧙‍♂️ (magical helper), 🔍 (investigator), 🚀 (accelerator), 🎯 (precision) - -**Filename (Technical Identity):** -"Let's create a kebab-case filename for the agent:" - -- Based on agent name and function -- Examples: "business-analyst", "code-reviewer", "research-assistant" -- Auto-suggest based on chosen name for consistency - -### 3. Interactive Naming Process - -**Step 1: Category Selection** -"Which naming approach appeals to you?" - -- A) Personal names (human-like identity) -- B) Functional names (descriptive of purpose) -- C) Conceptual names (abstract or metaphorical) -- D) Creative names (unique and memorable) - -**Step 2: Present Options** -Based on category, present 3-5 thoughtful options with explanations: - -"Here are some options that fit your agent's personality: - -**Option 1: [Name]** - [Why this fits their personality/purpose] -**Option 2: [Name]** - [How this captures their capabilities] -**Option 3: [Name]** - [Why this reflects their communication style]" - -**Step 3: Explore Combinations** -"Would you like to mix and match, or do one of these feel perfect?" - -Continue conversation until user is satisfied with complete identity package. - -### 4. Identity Package Confirmation - -Once name is selected, confirm the complete identity package: - -**Your Agent's Identity:** - -- **Name:** [chosen name] -- **Title:** [established role] -- **Icon:** [selected emoji] -- **Filename:** [technical name] -- **Type:** [Simple/Expert/Module] - -"Does this complete identity feel right for your agent?" - -### 5. Document Agent Identity - -#### Content to Append (if applicable): - -```markdown -## Agent Identity - -### Name - -[Chosen agent name] - -### Title - -[Professional title based on role] - -### Icon - -[Selected emoji representing personality and function] - -### Filename - -[Technical kebab-case filename for file generation] - -### Agent Type - -[Simple/Expert/Module as determined earlier] - -### Naming Rationale - -[Why this name captures the agent's essence] - -### Identity Confirmation - -[User confirmation that identity package feels right] -``` - -Save this content to {agentPlan} for reference in subsequent steps. - -### 6. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### 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 Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options) - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [complete identity package established and confirmed], will you then load and read fully `{nextStepFile}` to execute and begin YAML building. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- Agent name emerges naturally from discovered characteristics -- Complete identity package established (name, title, icon, filename) -- User confirms identity "feels right" for their agent -- Technical filename ready for file generation follows kebab-case convention -- Naming rationale documented with connection to agent characteristics -- Content properly saved to output file -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Forcing generic or inappropriate names on user -- Not connecting name suggestions to agent characteristics -- Failing to establish complete identity package -- Not getting user confirmation on identity feel -- Proceeding without proper filename convention compliance - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-06-activation.md b/src/modules/bmb/workflows/create-agent/steps/step-06-activation.md new file mode 100644 index 00000000..6d2bf0ec --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-06-activation.md @@ -0,0 +1,275 @@ +--- +name: 'step-05-activation' +description: 'Plan activation behavior and route to build' + +# File References +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +criticalActions: ../data/critical-actions.md + +# Build Step Routes (determined by agent type) +simpleBuild: './step-07a-build-simple.md' +expertBuild: './step-07b-build-expert.md' +moduleBuild: './step-07c-build-module.md' + +# Example critical_actions (for reference) +expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL +Define activation behavior through critical_actions and route to the appropriate build step based on agent complexity. + +# MANDATORY EXECUTION RULES + +1. **MUST Load Reference Documents** Before any discussion + - Read criticalActions.md to understand activation patterns + - Read agentPlan to access all accumulated metadata + - These are non-negotiable prerequisites + +2. **MUST Determine Route Before Activation Discussion** + - Check hasSidecar from plan metadata + - Determine destination build step FIRST + - Inform user of routing decision + +3. **MUST Document Activation Decision** + - Either define critical_actions array explicitly + - OR document deliberate omission with rationale + - No middle ground - commit to one path + +4. **MUST Follow Routing Logic Exactly** + ```yaml + # Route determination based on hasSidecar and module + hasSidecar: false → step-06-build-simple.md + hasSidecar: true + module: "stand-alone" → step-06-build-expert.md + hasSidecar: true + module: ≠ "stand-alone" → step-06-build-module.md + ``` + +5. **NEVER Skip Documentation** + - Every decision about activation must be recorded + - Every routing choice must be justified + - Plan file must reflect final state + +# EXECUTION PROTOCOLS + +## Protocol 1: Reference Loading +Execute BEFORE engaging user: + +1. Load criticalActions.md +2. Load agentPlan-{agent_name}.md +3. Extract routing metadata: + - hasSidecar (boolean) + - module (string) + - agentType (if defined) +4. Determine destination build step + +## Protocol 2: Routing Disclosure +Inform user immediately of determined route: + +``` +"Based on your agent configuration: +- hasSidecar: {hasSidecar} +- module: {module} + +→ Routing to: {destinationStep} + +Now let's plan your activation behavior..." +``` + +## Protocol 3: Activation Planning +Guide user through decision: + +1. **Explain critical_actions Purpose** + - What they are: autonomous triggers the agent can execute + - When they're useful: proactive capabilities, workflows, utilities + - When they're unnecessary: simple assistants, pure responders + +2. **Discuss Agent's Activation Needs** + - Does this agent need to run independently? + - Should it initiate actions without prompts? + - What workflows or capabilities should it trigger? + +3. **Decision Point** + - Define specific critical_actions if needed + - OR explicitly opt-out with rationale + +## Protocol 4: Documentation +Update agentPlan with activation metadata: + +```yaml +# Add to agent metadata +activation: + hasCriticalActions: true/false + rationale: "Explanation of why or why not" + criticalActions: [] # Only if hasCriticalActions: true +routing: + destinationBuild: "step-06-{X}.md" + hasSidecar: {boolean} + module: "{module}" +``` + +# CONTEXT BOUNDARIES + +## In Scope +- Planning activation behavior for the agent +- Defining critical_actions array +- Routing to appropriate build step +- Documenting activation decisions + +## Out of Scope +- Writing actual activation code (build step) +- Designing sidecar workflows (build step) +- Changing core agent metadata (locked after step 04) +- Implementing commands (build step) + +## Routing Boundaries +- Simple agents: No sidecar, straightforward activation +- Expert agents: Sidecar + stand-alone module +- Module agents: Sidecar + parent module integration + +# EXECUTION SEQUENCE + +## 1. Load Reference Documents +```bash +# Read these files FIRST +cat {criticalActions} +cat {agentPlan} +``` + +## 2. Discuss Activation Needs +Ask user: +- "Should your agent be able to take autonomous actions?" +- "Are there specific workflows it should trigger?" +- "Should it run as a background process or scheduled task?" +- "Or will it primarily respond to direct prompts?" + +## 3. Define critical_actions OR Explicitly Omit + +**If defining:** +- Reference criticalActions.md patterns +- List 3-7 specific actions +- Each action should be clear and scoped +- Document rationale for each + +**If omitting:** +- State clearly: "This agent will not have critical_actions" +- Explain why: "This agent is a responsive assistant that operates under direct user guidance" +- Document the rationale + +## 4. Route to Build Step + +Determine destination: + +```yaml +# Check plan metadata +hasSidecar: {value from step 04} +module: "{value from step 04}" + +# Route logic +if hasSidecar == false: + destination = simpleBuild +elif hasSidecar == true and module == "stand-alone": + destination = expertBuild +else: # hasSidecar == true and module != "stand-alone" + destination = moduleBuild +``` + +## 5. Document to Plan + +Update agentPlan with: + +```yaml +--- +activation: + hasCriticalActions: true + rationale: "Agent needs to autonomously trigger workflows for task automation" + criticalActions: + - name: "start-workflow" + description: "Initiate a predefined workflow for task execution" + - name: "schedule-task" + description: "Schedule tasks for future execution" + - name: "sync-data" + description: "Synchronize data with external systems" + +routing: + destinationBuild: "step-06-build-expert.md" + hasSidecar: true + module: "stand-alone" + rationale: "Agent requires sidecar workflows for autonomous operation" +--- +``` + +### 6. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save content to {agentPlan}, update frontmatter, determine appropriate build step based on hasSidecar and module values, then only then load, read entire file, then execute {simpleBuild} or {expertBuild} or {moduleBuild} as determined +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +This is the **ROUTING HUB** of agent creation. ONLY WHEN [C continue option] is selected and [routing decision determined with activation needs documented], will you then determine the appropriate build step based on hasSidecar/module values and load and read fully that build step file to execute. + +Routing logic: +- hasSidecar: false → step-06-build-simple.md +- hasSidecar: true + module: "stand-alone" → step-06-build-expert.md +- hasSidecar: true + module: ≠ "stand-alone" → step-06-build-module.md + +You cannot proceed to build without completing routing. + +--- + +# SUCCESS METRICS + +✅ **COMPLETION CRITERIA:** +- [ ] criticalActions.md loaded and understood +- [ ] agentPlan loaded with all prior metadata +- [ ] Routing decision determined and communicated +- [ ] Activation needs discussed with user +- [ ] critical_actions defined OR explicitly omitted with rationale +- [ ] Plan updated with activation and routing metadata +- [ ] User confirms routing to appropriate build step + +✅ **SUCCESS INDICATORS:** +- Clear activation decision documented +- Route to build step is unambiguous +- User understands why they're going to {simple|expert|module} build +- Plan file reflects complete activation configuration + +❌ **FAILURE MODES:** +- Attempting to define critical_actions without reading reference +- Routing decision not documented in plan +- User doesn't understand which build step comes next +- Ambiguous activation configuration (neither defined nor omitted) +- Skipping routing discussion entirely + +⚠️ **RECOVERY PATHS:** +If activation planning goes wrong: + +1. **Can't decide on activation?** + - Default: Omit critical_actions + - Route to simpleBuild + - Can add later via edit-agent workflow + +2. **Uncertain about routing?** + - Check hasSidecar value + - Check module value + - Apply routing logic strictly + +3. **User wants to change route?** + - Adjust hasSidecar or module values + - Re-run routing logic + - Update plan accordingly 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 deleted file mode 100644 index 6e194a8c..00000000 --- a/src/modules/bmb/workflows/create-agent/steps/step-06-build.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -name: 'step-06-build' -description: 'Generate complete YAML incorporating all discovered elements' - -# File References -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: ../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' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' ---- - -# Step 6: Build Complete Agent YAML - -## STEP GOAL: - -Generate the complete YAML agent folder, yaml file and sidecar content to the specification defined in {agentBuildOutput} completely. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are a YAML architect who transforms collaborative discoveries into technical implementation -- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring technical YAML expertise, user brings their agent vision, together we create complete agent configuration -- ✅ Maintain collaborative technical tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on generating complete YAML and sidecar content structure based on discovered elements -- 🚫 FORBIDDEN to duplicate auto-injected features (help and exit menu items, activation handler instructions) -- 💬 Approach: Present the journey of collaborative creation while building technical structure -- 📋 Generate YAML and sidecar files that accurately reflects all discoveries from previous steps - -## EXECUTION PROTOCOLS: - -- 🎯 Generate complete YAML structure based on agent type and discovered elements -- 💾 Present complete YAML with proper formatting and explanation -- 📖 Load appropriate template for agent type for structure guidance -- 🚫 FORBIDDEN to proceed without incorporating all discovered elements - -## CONTEXT BOUNDARIES: - -- Available context: All discoveries from previous steps (purpose, persona, capabilities, identity) -- Focus: YAML generation and complete agent configuration -- Limits: No validation yet, just YAML generation -- Dependencies: Complete understanding of all agent characteristics from previous steps - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Celebrate the Journey - -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. Now we will make it BMad Compliant, ready to install use and share with the world!" - -**Journey Summary:** - -- Started with purpose discovery (Step 2) -- Shaped personality through four-field persona system (Step 3) -- Built capabilities and command structure (Step 4) -- Established name and identity (Step 5) -- Ready to bring it all together in complete YAML - -### 2. Load Agent Type Template and Architecture References - -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 Sidecar folder to hold the optional sidecar files if needed from plan in following steps at {agentBuildOutput}/{agent-name}/{agent-name}-sidecar -- ELSE: - - 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 - -Create the complete YAML incorporating all discovered elements from the plan: - -**Core Structure:** - -- Agent metadata (name, title, icon, module, type) -- Complete persona (role, identity, communication_style, principles) -- Agent type-specific sections -- Command structure with proper references -- Output path configuration - -Present the complete YAML to user: - -"Here is your complete agent YAML, incorporating everything we've discovered together: - -[Display complete YAML with proper formatting] - -**Key Features Included:** - -- Purpose-driven role and identity -- Distinct personality with four-field persona system -- All capabilities we discussed -- Proper command structure -- Agent type-specific optimizations -- Complete metadata and configuration - -Does this capture everything we discussed?" - -### 5. Agent Type Specific Implementation - -Ensure proper implementation based on agent type: - -**Simple Agent:** - -- All capabilities in YAML prompts section -- No external file references -- Self-contained execution logic - -**Expert Agent:** - -- Sidecar file references for knowledge base -- 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 - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### Menu Handling Logic: - -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Save content to {agentBuildOutput}, 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](#7-present-menu-options) - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [complete YAML generated incorporating all discovered elements], will you then load and read fully `{nextStepFile}` to execute and begin validation. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- Complete YAML structure generated for correct agent type -- All discovered elements properly integrated (purpose, persona, capabilities, identity) -- Commands correctly structured with proper workflow/action references -- Agent type specific optimizations implemented appropriately -- Output paths configured correctly based on agent type -- User confirms YAML captures all requirements from discovery process -- Content properly saved to output file -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Duplicating auto-injected features (help, exit, activation handlers) -- Not incorporating all discovered elements from previous steps -- Invalid YAML syntax or structure -- Incorrect agent type implementation -- Missing user confirmation on YAML completeness - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. 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 deleted file mode 100644 index 09814a3e..00000000 --- a/src/modules/bmb/workflows/create-agent/steps/step-07-validate.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -name: 'step-07-validate' -description: 'Quality check with personality and technical validation' - -# File References -nextStepFile: './step-08-celebrate.md' -outputFile: '{bmb_creations_output_folder}/agent-validation-{project_name}.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' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' ---- - -# Step 7: Quality Check and Validation - -## STEP GOAL: - -Run comprehensive validation conversationally while performing technical checks behind the scenes to ensure agent quality and compliance with BMAD standards. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are a quality assurance specialist who validates agent readiness through friendly conversation -- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring validation expertise, user brings their agent vision, together we ensure agent quality and readiness -- ✅ Maintain collaborative supportive tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on comprehensive validation while maintaining conversational approach -- 🚫 FORBIDDEN to expose user to raw technical errors or complex diagnostics -- 💬 Approach: Present technical validation as friendly confirmations and celebrations -- 📋 Run technical validation in background while presenting friendly interface to user - -## EXECUTION PROTOCOLS: - -- 🎯 Present validation as friendly confirmations and celebrations -- 💾 Document all validation results and any resolutions -- 🔧 Run technical validation in background without exposing complexity to user -- 🚫 FORBIDDEN to overwhelm user with technical details or raw error messages - -## CONTEXT BOUNDARIES: - -- Available context: Complete agent YAML from previous step -- Focus: Quality validation and technical compliance verification -- Limits: No agent modifications except for fixing identified issues -- Dependencies: Complete agent YAML ready for validation - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Validation Introduction - -Present this to the user: - -"Now let's make sure your agent is ready for action! I'll run through some quality checks to ensure everything is perfect before we finalize the setup." - -"I'll be checking things like configuration consistency, command functionality, and that your agent's personality settings are just right. This is like a final dress rehearsal before the big premiere!" - -### 2. Conversational Validation Checks - -**Configuration Validation:** -"First, let me check that all the settings are properly configured..." -[Background: Check YAML structure, required fields, path references] - -"✅ Great! All your agent's core configurations look solid. The role, identity, and communication style are all properly aligned." - -**Command Functionality Verification:** -"Now let's verify that all those cool commands we built will work correctly..." -[Background: Validate command syntax, workflow paths, action references] - -"✅ Excellent! All your agent's commands are properly structured and ready to execute. I love how {{specific_command}} will help users with {{specific_benefit}}!" - -**Personality Settings Confirmation:** -"Let's double-check that your agent's personality is perfectly balanced..." -[Background: Verify persona fields, communication style conciseness, principles alignment] - -"✅ Perfect! Your agent has that {{personality_trait}} quality we were aiming for. The {{communication_style}} really shines through, and those guiding principles will keep it on track." - -### 3. Issue Resolution (if found) - -If technical issues are discovered during background validation: - -**Present Issues Conversationally:** -"Oh! I noticed something we can quickly fix..." - -**Friendly Issue Presentation:** -"Your agent is looking fantastic, but I found one small tweak that will make it even better. {{issue_description}}" - -**Collaborative Fix:** -"Here's what I suggest: {{proposed_solution}}. What do you think?" - -**Apply and Confirm:** -"There we go! Now your agent is even more awesome. The {{improvement_made}} will really help with {{benefit}}." - -### 4. Technical Validation (Behind the Scenes) - -**YAML Structure Validity:** - -- Check proper indentation and syntax -- Validate all required fields present -- Ensure no duplicate keys or invalid values - -**Menu Command Validation:** - -- Verify all command triggers are valid -- Check workflow paths exist or are properly marked as "to-be-created" -- Validate action references are properly formatted - -**Build Compilation Test:** - -- Simulate agent compilation process -- Check for auto-injection conflicts -- Validate variable substitution - -**Type-Specific Validation Checklists:** - -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 - -**Success Celebration:** -"🎉 Fantastic news! Your agent has passed all quality checks with flying colors!" - -**Validation Summary:** -"Here's what I confirmed: -✅ Configuration is rock-solid -✅ Commands are ready to execute -✅ Personality is perfectly balanced -✅ All technical requirements met -✅ Ready for final setup and activation" - -**Quality Badge Awarded:** -"Your agent has earned the 'BMAD Quality Certified' badge! It's ready to help users with {{agent_purpose}}." - -### 6. Document Validation Results - -#### Content to Append (if applicable): - -```markdown -## Agent Validation Results - -### Validation Checks Performed - -- Configuration structure and syntax validation -- Command functionality verification -- Persona settings confirmation -- Technical requirements compliance -- Agent type specific validation - -### Results Summary - -✅ All validation checks passed successfully -✅ Agent ready for setup and activation -✅ Quality certification achieved - -### Issues Resolved (if any) - -[Documentation of any issues found and resolved] - -### Quality Assurance - -Agent meets all BMAD quality standards and is ready for deployment. -``` - -Save this content to `{outputFile}` for reference. - -### 7. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### Menu Handling Logic: - -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Save content to {outputFile}, 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](#7-present-menu-options) - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [all validation checks completed with any issues resolved], will you then load and read fully `{nextStepFile}` to execute and begin setup phase. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- All validation checks completed (configuration, commands, persona, technical) -- YAML configuration confirmed valid and properly structured -- Command functionality verified with proper workflow/action references -- Personality settings confirmed balanced and aligned with agent purpose -- Technical validation passed including syntax and compilation checks -- Any issues found resolved conversationally with user collaboration -- User confidence in agent quality established through successful validation -- Content properly saved to output file -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Exposing users to raw technical errors or complex diagnostics -- Not performing comprehensive validation checks -- Missing or incomplete validation of critical agent components -- Proceeding without resolving identified issues -- Breaking conversational approach with technical jargon - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-07a-build-simple.md b/src/modules/bmb/workflows/create-agent/steps/step-07a-build-simple.md new file mode 100644 index 00000000..812fa40b --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-07a-build-simple.md @@ -0,0 +1,185 @@ +--- +name: 'step-06-build-simple' +description: 'Generate Simple agent YAML from plan' + +# File References +nextStepFile: './step-08a-plan-traceability.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +agentBuildOutput: '{bmb_creations_output_folder}/{agent-name}.agent.yaml' + +# Template and Architecture +simpleTemplate: ../templates/simple-agent.template.md +simpleArch: ../data/simple-agent-architecture.md +agentCompilation: ../data/agent-compilation.md + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Assemble the agent plan content into a Simple agent YAML configuration using the template, producing a complete agent definition ready for validation. + +## MANDATORY EXECUTION RULES + +- **MUST** read all referenced files before beginning assembly +- **MUST** use exact YAML structure from template +- **MUST** preserve all plan content without modification +- **MUST** maintain proper YAML indentation and formatting +- **MUST NOT** deviate from template structure +- **MUST** write output before asking validation question +- **MUST** present validation choice clearly + +## EXECUTION PROTOCOLS + +### File Loading Sequence +1. Read `simpleTemplate` - provides the YAML structure +2. Read `simpleArch` - defines Simple agent architecture rules +3. Read `agentCompilation` - provides assembly guidelines +4. Read `agentPlan` - contains structured content from steps 2-5 + +### YAML Assembly Process +1. Parse template structure +2. Extract content sections from agentPlan YAML +3. Map plan content to template fields +4. Validate YAML syntax before writing +5. Write complete agent YAML to output path + +## CONTEXT BOUNDARIES + +**INCLUDE:** +- Template structure exactly as provided +- All agent metadata from agentPlan +- Persona, commands, and rules from plan +- Configuration options specified + +**EXCLUDE:** +- Any content not in agentPlan +- Sidecar file references (Simple agents don't use them) +- Template placeholders (replace with actual content) +- Comments or notes in final YAML + +## EXECUTION SEQUENCE + +### 1. Load Template and Architecture Files + +Read the following files in order: +- `simpleTemplate` - YAML structure template +- `simpleArch` - Simple agent architecture definition +- `agentCompilation` - Assembly instructions + +**Verify:** All files loaded successfully. + +### 2. Load Agent Plan + +Read `agentPlan` which contains structured YAML from steps 2-5: +- Step 2: Discovery findings +- Step 3: Persona development +- Step 4: Command structure +- Step 5: Agent naming + +**Verify:** Plan contains all required sections. + +### 3. Assemble YAML Using Template + +Execute the following assembly process: + +1. **Parse Template Structure** + - Identify all YAML fields + - Note required vs optional fields + - Map field types and formats + +2. **Extract Plan Content** + - Read agent metadata + - Extract persona definition + - Retrieve command specifications + - Gather rules and constraints + +3. **Map Content to Template** + - Replace template placeholders with plan content + - Maintain exact YAML structure + - Preserve indentation and formatting + - Validate field types and values + +4. **Validate YAML Syntax** + - Check proper indentation + - Verify quote usage + - Ensure list formatting + - Confirm no syntax errors + +**Verify:** YAML is valid, complete, and follows template structure. + +### 4. Write Agent Build Output + +Write the assembled YAML to `agentBuildOutput`: +- Use exact output path from variable +- Include all content without truncation +- Maintain YAML formatting +- Confirm write operation succeeded + +**Verify:** File written successfully and contains complete YAML. + +### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Write agent YAML to {agentBuildOutput}/{agent-name}.agent.yaml (or appropriate output path), 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](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +### 6. Route Based on User Choice + +**If user chooses "one-at-a-time":** +- Proceed to `nextStepFile` (step-07a-plan-traceability.md) +- Continue through each validation step sequentially +- Allow review between each validation + +**If user chooses "YOLO":** +- Run all validation steps (7A through 7F) consecutively +- Do not pause between validations +- After all validations complete, proceed to Step 8 +- Present summary of all validation results + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [complete YAML generated and written to output], will you then load and read fully `{nextStepFile}` to execute and begin validation. + +## SUCCESS METRICS + +**SUCCESS looks like:** +- Agent YAML file exists at specified output path +- YAML is syntactically valid and well-formed +- All template fields populated with plan content +- Structure matches Simple agent architecture +- User has selected validation approach +- Clear next step identified + +**FAILURE looks like:** +- Template or architecture files not found +- Agent plan missing required sections +- YAML syntax errors in output +- Content not properly mapped to template +- File write operation fails +- User selection unclear + +## TRANSITION CRITERIA + +**Ready for Step 7A when:** +- Simple agent YAML successfully created +- User chooses "one-at-a-time" validation + +**Ready for Step 8 when:** +- Simple agent YAML successfully created +- User chooses "YOLO" validation +- All validations (7A-7F) completed consecutively diff --git a/src/modules/bmb/workflows/create-agent/steps/step-07b-build-expert.md b/src/modules/bmb/workflows/create-agent/steps/step-07b-build-expert.md new file mode 100644 index 00000000..fe8df2e0 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-07b-build-expert.md @@ -0,0 +1,201 @@ +--- +name: 'step-06-build-expert' +description: 'Generate Expert agent YAML with sidecar from plan' + +# File References +nextStepFile: './step-08a-plan-traceability.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +agentBuildOutput: '{bmb_creations_output_folder}/{agent-name}/' +agentYamlOutput: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' + +# Template and Architecture +expertTemplate: ../templates/expert-agent-template/expert-agent.template.md +expertArch: ../data/expert-agent-architecture.md +agentCompilation: ../data/agent-compilation.md +criticalActions: ../data/critical-actions.md + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Assemble the agent plan content into a complete Expert agent YAML file with sidecar folder structure. Expert agents require persistent memory storage for specialized operations, accessed via `{project-root}/_bmad/_memory/{sidecar-folder}/` paths in critical_actions. + +## MANDATORY EXECUTION RULES + +1. **EXPERT AGENT = SIDECAR REQUIRED**: Every Expert agent MUST have a sidecar folder created under `_bmad/_memory/` +2. **CRITICAL_ACTIONS FORMAT**: All critical_actions MUST use `{project-root}/_bmad/_memory/{sidecar-folder}/` for file operations +3. **TEMPLATE COMPLIANCE**: Follow expert-agent-template.md structure exactly +4. **YAML VALIDATION**: Ensure valid YAML syntax with proper indentation (2-space) +5. **EXISTING CHECK**: If agentYamlOutput exists, ask user before overwriting +6. **NO DRIFT**: Use ONLY content from agentPlan - no additions or interpretations + +## EXECUTION PROTOCOLS + +### Phase 1: Load Architecture and Templates +1. Read `expertTemplate` - defines YAML structure for Expert agents +2. Read `expertArch` - architecture requirements for Expert-level agents +3. Read `agentCompilation` - assembly rules for YAML generation +4. Read `criticalActions` - validation requirements for critical_actions + +### Phase 2: Load Agent Plan +1. Read `agentPlan` containing all collected content from Steps 1-5 +2. Verify plan contains: + - Agent type: "expert" + - Sidecar folder name + - Persona content + - Commands structure + - Critical actions (if applicable) + +### Phase 3: Assemble Expert YAML +Using expertTemplate as structure: + +```yaml +name: '{agent-name}' +description: '{short-description}' +type: 'expert' +version: '1.0.0' + +author: + name: '{author}' + created: '{date}' + +persona: | + {multi-line persona content from plan} + +system-context: | + {expanded context from plan} + +capabilities: + - {capability from plan} + - {capability from plan} + # ... all capabilities + +critical-actions: + - name: '{action-name}' + description: '{what it does}' + invocation: '{when/how to invoke}' + implementation: | + {multi-line implementation} + output: '{expected-output}' + sidecar-folder: '{sidecar-folder-name}' + sidecar-files: + - '{project-root}/_bmad/_memory/{sidecar-folder}/{file1}.md' + - '{project-root}/_bmad/_memory/{sidecar-folder}/{file2}.md' + # ... all critical actions referencing sidecar structure + +commands: + - name: '{command-name}' + description: '{what command does}' + steps: + - {step 1} + - {step 2} + # ... all commands from plan + +configuration: + temperature: {temperature} + max-tokens: {max-tokens} + response-format: {format} + # ... other configuration from plan + +metadata: + sidecar-folder: '{sidecar-folder-name}' + sidecar-path: '{project-root}/_bmad/_memory/{sidecar-folder}/' + agent-type: 'expert' + memory-type: 'persistent' +``` + +### Phase 4: Create Sidecar Structure + +1. **Create Sidecar Directory**: + - Path: `{project-root}/_bmad/_memory/{sidecar-folder}/` + - Use `mkdir -p` to create full path + +2. **Create Starter Files** (if specified in critical_actions): + ```bash + touch _bmad/_memory/{sidecar-folder}/{file1}.md + touch _bmad/_memory/{sidecar-folder}/{file2}.md + ``` + +3. **Add README to Sidecar**: + ```markdown + # {sidecar-folder} Memory + + This folder stores persistent memory for the **{agent-name}** Expert agent. + + ## Purpose + {purpose from critical_actions} + + ## Files + - {file1}.md: {description} + - {file2}.md: {description} + + ## Access Pattern + Agent accesses these files via: `{project-root}/_bmad/_memory/{sidecar-folder}/{filename}.md` + ``` + +### Phase 5: Write Agent YAML + +1. Create `agentBuildOutput` directory: `mkdir -p {agentBuildOutput}` +2. Write YAML to `agentYamlOutput` +3. Confirm write success +4. Display file location to user + +### Phase 6: Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Write agent YAML to {agentBuildOutput}/{agent-name}/{agent-name}.agent.yaml (or appropriate output path), 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](#phase-6-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CONTEXT BOUNDARIES + +- **USE ONLY**: Content from agentPlan, expertTemplate, expertArch, agentCompilation, criticalActions +- **DO NOT ADD**: New capabilities, commands, or actions not in plan +- **DO NOT INTERPRET**: Use exact language from plan +- **DO NOT SKIP**: Any field in expertTemplate structure +- **CRITICAL**: Expert agents MUST have sidecar-folder metadata + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [complete YAML generated and written to output], will you then load and read fully `{nextStepFile}` to execute and begin validation. + +This step produces TWO artifacts: +1. **Agent YAML**: Complete expert agent definition at `{agentYamlOutput}` +2. **Sidecar Structure**: Folder and files at `{project-root}/_bmad/_memory/{sidecar-folder}/` + +Both must exist before proceeding to validation. + +## SUCCESS METRICS + +✅ Agent YAML file created at expected location +✅ Valid YAML syntax (no parse errors) +✅ All template fields populated +✅ Sidecar folder created under `_bmad/_memory/` +✅ Sidecar folder contains starter files from critical_actions +✅ critical_actions reference `{project-root}/_bmad/_memory/{sidecar-folder}/` paths +✅ metadata.sidecar-folder populated +✅ metadata.agent-type = "expert" +✅ User validation choice received (one-at-a-time or YOLO) + +## FAILURE MODES + +❌ Missing required template fields +❌ Invalid YAML syntax +❌ Sidecar folder creation failed +❌ critical_actions missing sidecar-folder references +❌ agentPlan missing expert-specific content (sidecar-folder name) +❌ File write permission errors diff --git a/src/modules/bmb/workflows/create-agent/steps/step-07c-build-module.md b/src/modules/bmb/workflows/create-agent/steps/step-07c-build-module.md new file mode 100644 index 00000000..baab0380 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-07c-build-module.md @@ -0,0 +1,258 @@ +--- +name: 'step-06-build-module' +description: 'Generate Module agent YAML from plan' + +# File References +nextStepFile: './step-08a-plan-traceability.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +agentBuildOutput: '{bmb_creations_output_folder}/{agent-name}/' +agentYamlOutput: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' + +# Template and Architecture (use expert as baseline) +expertTemplate: ../templates/expert-agent-template/expert-agent.template.md +expertArch: ../data/expert-agent-architecture.md +agentCompilation: ../data/agent-compilation.md +criticalActions: ../data/critical-actions.md + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL +Assemble the Module agent YAML file from the approved plan, using the expert agent template as the baseline architecture and adding module-specific workflow integration paths and sidecar configuration. + +# MANDATORY EXECUTION RULES + +1. **TEMPLATE BASELINE**: Module agents MUST use the expert agent template as their structural foundation - do not create custom templates + +2. **PLAN ADHERENCE**: Extract content from agentPlan exactly as written - no enhancement, interpretation, or extrapolation + +3. **MODULE SPECIFICITY**: Module agents require workflow integration paths and may need sidecar configuration for multi-workflow modules + +4. **OUTPUT VALIDATION**: YAML must be valid, complete, and ready for immediate deployment + +5. **LANGUAGE PRESERVATION**: Maintain any language choice configured in the plan throughout the YAML + +# EXECUTION PROTOCOLS + +## PREPARATION PHASE + +### 1. Load Expert Template Baseline +``` +Read: expertTemplate +Read: expertArch +Read: agentCompilation +Read: criticalActions +``` + +**Purpose**: Understand the expert agent structure that serves as the Module agent baseline + +**Validation**: Confirm expert template has all required sections (name, description, persona, instructions, tools, skills, etc.) + +### 2. Load Agent Plan +``` +Read: agentPlan (using dynamic path) +``` + +**Validation**: Plan contains all mandatory sections: +- Agent identity (name, description) +- Persona profile +- Command structure +- Critical actions +- Workflow integrations (module-specific) +- Language choice (if configured) + +### 3. Verify Output Directory +``` +Bash: mkdir -p {agentBuildOutput} +``` + +**Purpose**: Ensure output directory exists for the module agent + +## ASSEMBLY PHASE + +### 4. Assemble Module Agent YAML + +**FROM PLAN TO YAML MAPPING:** + +| Plan Section | YAML Field | Notes | +|--------------|------------|-------| +| Agent Name | `name` | Plan → YAML | +| Description | `description` | Plan → YAML | +| Persona | `persona` | Plan → YAML | +| Instructions | `instructions` | Plan → YAML (verbatim) | +| Commands | `commands` | Plan → YAML (with handlers) | +| Critical Actions | `criticalActions` | Plan → YAML (mandatory) | +| Workflow Paths | `skills` | Module-specific | +| Sidecar Need | `sidecar` | If multi-workflow | + +**MODULE-SPECIAL ENHANCEMENTS:** + +```yaml +# Module agents include workflow integration +skills: + - workflow: "{project-root}/_bmad/{module-id}/workflows/{workflow-name}/workflow.md" + description: "From plan workflow list" + - workflow: "{project-root}/_bmad/{module-id}/workflows/{another-workflow}/workflow.md" + description: "From plan workflow list" + +# Optional: Sidecar for complex modules +sidecar: + enabled: true + workflows: + - ref: "primary-workflow" + type: "primary" + - ref: "secondary-workflow" + type: "support" +``` + +**CRITICAL ACTIONS MAPPING:** +``` +For each critical action in plan: +1. Identify matching command in YAML +2. Add `critical: true` flag +3. Ensure handler references agent function +``` + +### 5. Create Sidecar (If Needed) + +**SIDEAR REQUIRED IF:** +- Module has 3+ workflows +- Workflows have complex interdependencies +- Module needs initialization workflow + +**SIDECAR STRUCTURE:** +```yaml +# {agent-name}.sidecar.yaml +sidecar: + module: "{module-id}" + initialization: + workflow: "workflow-init" + required: true + workflows: + - name: "workflow-name" + path: "workflows/{workflow-name}/workflow.md" + type: "primary|support|utility" + dependencies: [] + agent: + path: "{agent-name}.agent.yaml" +``` + +**IF SIDEAR NOT NEEDED**: Skip this step + +### 6. Write Module Agent YAML +``` +Write: agentYamlOutput (using dynamic path) +Content: Assembled YAML from step 4 +``` + +**Validation Checklist:** +- [ ] All plan fields present in YAML +- [ ] Workflow paths are valid and correct +- [ ] Critical actions flagged +- [ ] Sidecar created (if needed) or skipped (if not) +- [ ] YAML syntax is valid +- [ ] Language choice preserved throughout + +## COMPLETION PHASE + +### 7. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Write agent YAML to {agentBuildOutput}/{agent-name}/{agent-name}.agent.yaml (or appropriate output path), 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](#7-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +**USER RESPONSE HANDLING:** +- **Option 1**: Proceed to step-07a-plan-traceability.md with sequential mode +- **Option 2**: Proceed to step-07a-plan-traceability.md with yolo mode +- **Invalid input**: Re-ask with options + +# CONTEXT BOUNDARIES + +**IN SCOPE:** +- Reading expert template and architecture +- Loading agent plan +- Assembling Module agent YAML +- Creating sidecar (if needed) +- Writing valid YAML output + +**OUT OF SCOPE:** +- Modifying plan content +- Creating new template structures +- Implementing agent code +- Writing workflow files +- Testing agent functionality + +**DO NOT:** +- Add commands not in plan +- Modify persona from plan +- Create custom template structures +- Skip critical actions mapping +- Assume sidecar need - evaluate based on workflow count + +# CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [complete YAML generated and written to output], will you then load and read fully `{nextStepFile}` to execute and begin validation. + +**THIS STEP IS COMPLETE WHEN:** +1. Module agent YAML file exists at agentYamlOutput path +2. YAML contains all plan content correctly mapped +3. Module-specific workflow paths are configured +4. Sidecar is created (if needed) or correctly skipped (if not) +5. User has chosen review mode (one-at-a-time or YOLO) +6. Ready to proceed to step-07a-plan-traceability.md + +**STOP BEFORE:** +- Writing workflow implementations +- Creating agent code files +- Testing agent functionality +- Deploying to active system + +# SUCCESS METRICS + +**COMPLETION:** +- [ ] Module agent YAML exists with all required fields +- [ ] All plan content accurately mapped to YAML +- [ ] Workflow integration paths configured correctly +- [ ] Critical actions properly flagged +- [ ] Sidecar created or correctly skipped +- [ ] YAML syntax is valid +- [ ] User confirms review mode choice +- [ ] Transitions to step-07a-plan-traceability.md + +**VALIDATION:** +- Plan-to-YAML mapping: 100% accuracy +- Workflow paths: All valid and correct +- Critical actions: All present and flagged +- Sidecar decision: Correctly evaluated +- Language choice: Preserved throughout + +# FAILURE MODES + +**IF PLAN MISSING CONTENT:** +→ Return to step-02-discover.md to complete plan + +**IF EXPERT TEMPLATE MISSING:** +→ Raise error - template is mandatory baseline + +**IF YAML SYNTAX ERROR:** +→ Fix and retry write operation + +**IF WORKFLOW PATHS INVALID:** +→ Flag for review in traceability step + +**IF USER ASKS FOR MODIFICATIONS:** +→ Return to appropriate planning step (03-persona, 04-commands, or 05-name) diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08a-plan-traceability.md b/src/modules/bmb/workflows/create-agent/steps/step-08a-plan-traceability.md new file mode 100644 index 00000000..bc1989b7 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-08a-plan-traceability.md @@ -0,0 +1,203 @@ +--- +name: 'step-07a-plan-traceability' +description: 'Verify build matches original plan' + +# File References +nextStepFile: './step-08b-metadata-validation.md' +agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md' +builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL +Verify that the built agent YAML file contains all elements specified in the original agent plan. This step ensures plan traceability - confirming that what we planned is what we actually built. + +# MANDATORY EXECUTION RULES +- MUST load both agentPlan and builtYaml files before comparison +- MUST compare ALL planned elements against built implementation +- MUST report specific missing items, not just "something is missing" +- MUST offer fix option before proceeding to next validation +- MUST handle missing files gracefully (report clearly, don't crash) +- MUST respect YOLO mode behavior (part of combined validation report) + +# EXECUTION PROTOCOLS + +## File Loading Protocol +1. Load agentPlan from `{bmb_creations_output_folder}/agent-plan-{agent_name}.md` +2. Load builtYaml from `{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml` +3. If either file is missing, report the specific missing file and stop comparison +4. Use Read tool to access both files with absolute paths + +## Comparison Protocol +Compare the following categories systematically: + +### 1. Metadata Comparison +- Agent name +- Description +- Version +- Author/creator information +- Location/module path +- Language settings (if specified in plan) + +### 2. Persona Field Comparison +For each field in persona section: +- Check presence in built YAML +- Verify field content matches planned intent +- Note any significant deviations (minor wording differences ok) + +### 3. Commands Comparison +- Verify all planned commands are present +- Check command names match +- Verify command descriptions are present +- Confirm critical actions are referenced + +### 4. Critical Actions Comparison +- Verify all planned critical_actions are present +- Check action names match exactly +- Verify action descriptions are present +- Confirm each action has required fields + +### 5. Additional Elements +- Dependencies (if planned) +- Configuration (if planned) +- Installation instructions (if planned) + +## Reporting Protocol +Present findings in clear, structured format: + +``` +PLAN TRACEABILITY REPORT +======================== + +Agent: {agent_name} +Plan File: {path to agent plan} +Build File: {path to built YAML} + +COMPARISON RESULTS: +------------------- + +✅ Metadata: All present / Missing: {list} +✅ Persona Fields: All present / Missing: {list} +✅ Commands: All present / Missing: {list} +✅ Critical Actions: All present / Missing: {list} +✅ Other Elements: All present / Missing: {list} + +OVERALL STATUS: [PASS / FAIL] + +``` + +If ANY elements are missing: +- List each missing element with category +- Provide specific location reference (what was planned) +- Ask if user wants to fix items or continue anyway + +## Menu Protocol + +### 8. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [F] Fix Findings [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF F: Apply auto-fixes to {builtYaml} for identified missing elements, then redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Proceed to next validation step, 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](#8-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +If YOLO mode: +- Include this report in combined validation report +- Auto-select [C] Continue if all elements present +- Auto-select [F] Fix if missing critical elements (name, commands) +- Flag non-critical missing items in summary + +# CONTEXT BOUNDARIES +- ONLY compare plan vs build - do NOT evaluate quality or correctness +- Do NOT suggest improvements or changes beyond planned elements +- Do NOT re-open persona/commands discovery - this is verification only +- Fix option should return to step-06-build, not earlier steps +- If plan file is ambiguous, note ambiguity but use reasonable interpretation + +# SEQUENCE + +## 1. Load Required Files +```yaml +action: read +target: + - agentPlan + - builtYaml +on_failure: report which file is missing and suggest resolution +``` + +## 2. Perform Structured Comparison +```yaml +action: compare +categories: + - metadata + - persona_fields + - commands + - critical_actions + - other_elements +method: systematic category-by-category check +``` + +## 3. Generate Comparison Report +```yaml +action: report +format: structured pass/fail with specific missing items +output: console display + optional save to validation log +``` + +## 4. Present Menu Options +```yaml +action: menu +options: + - F: Fix missing items + - C: Continue to metadata validation + - V: View detailed comparison (optional) +default: C if pass, F if fail +``` + +## 5. Handle User Choice +- **[F] Fix Findings**: Apply auto-fixes to {builtYaml} for identified missing elements, then re-present menu +- **[C] Continue**: Proceed to step-07b-metadata-validation +- **[A] Advanced Elicitation**: Execute advanced elicitation workflow, then re-present menu +- **[P] Party Mode**: Execute party mode workflow, then re-present menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation complete with any findings addressed], will you then load and read fully `{nextStepFile}` to execute and begin [metadata validation]. + +# SUCCESS/FAILURE METRICS + +## Success Criteria +- All planned elements present in built YAML: **COMPLETE PASS** +- Minor deviations (wording, formatting) but all core elements present: **PASS** +- Missing elements identified and user chooses to continue: **PASS WITH NOTED DEFICIENCIES** + +## Failure Criteria +- Unable to load plan or build file: **BLOCKING FAILURE** +- Critical elements missing (name, commands, or critical_actions): **FAIL** +- Comparison cannot be completed due to file corruption: **BLOCKING FAILURE** + +## Next Step Triggers +- **PASS → step-07b-metadata-validation** +- **PASS WITH DEFICIENCIES → step-07b-metadata-validation** (user choice) +- **FAIL → step-06-build** (with specific fix instructions) +- **BLOCKING FAILURE → STOP** (resolve file access issues first) + +## YOLO Mode Behavior +- Auto-fix missing critical elements by returning to build step +- Log non-critical missing items for review but continue validation +- Include traceability report in final YOLO summary +- Do NOT stop for user confirmation unless plan file is completely missing diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08b-metadata-validation.md b/src/modules/bmb/workflows/create-agent/steps/step-08b-metadata-validation.md new file mode 100644 index 00000000..900d3a7b --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-08b-metadata-validation.md @@ -0,0 +1,135 @@ +--- +name: 'step-07b-metadata-validation' +description: 'Validate agent metadata properties' + +# File References +nextStepFile: './step-08c-persona-validation.md' +agentMetadata: ../data/agent-metadata.md +builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Validate that the agent's metadata properties (name, description, version, tags, category, etc.) are properly formatted, complete, and follow BMAD standards. + +## MANDATORY EXECUTION RULES + +- **NEVER skip validation checks** - All metadata fields must be verified +- **ALWAYS load both reference documents** - agentMetadata.md AND the builtYaml +- **NEVER modify files without user approval** - Report findings first, await menu selection +- **ALWAYS use absolute paths** when referencing files +- **CRITICAL:** This is a validation step, not an editing step + +## EXECUTION PROTOCOLS + +### Protocol 1: Load and Compare +1. Read the metadata validation reference from `{agentMetadata}` +2. Read the built agent YAML from `{builtYaml}` +3. Extract the metadata section from the builtYaml +4. Compare actual metadata against validation rules + +### Protocol 2: Validation Checks +Perform these checks systematically: + +1. **Required Fields Existence** + - [ ] name: Present and non-empty + - [ ] description: Present and non-empty + - [ ] version: Present and follows semantic versioning (X.Y.Z) + - [ ] category: Present and matches valid category + - [ ] tags: Present as array, not empty + +2. **Format Validation** + - [ ] name: Uses kebab-case, no spaces + - [ ] description: 50-200 characters (unless intentionally brief) + - [ ] version: Follows semver pattern (e.g., 1.0.0) + - [ ] tags: Array of lowercase strings with hyphens + - [ ] category: Matches one of the allowed categories + +3. **Content Quality** + - [ ] description: Clear and concise, explains what the agent does + - [ ] tags: Relevant to agent's purpose (3-7 tags recommended) + - [ ] category: Most appropriate classification + +4. **Standards Compliance** + - [ ] No prohibited characters in fields + - [ ] No redundant or conflicting information + - [ ] Consistent formatting with other agents + +### Protocol 3: Report Findings +Organize your report into three sections: + +**PASSING CHECKS** (List what passed) +``` +✓ Required fields present +✓ Version format valid (1.0.0) +✓ Name follows kebab-case convention +``` + +**WARNINGS** (Non-blocking issues) +``` +⚠ Description is brief (45 chars, recommended 50-200) +⚠ Only 2 tags provided, 3-7 recommended +``` + +**FAILURES** (Blocking issues that must be fixed) +``` +✗ Missing required field: version +✗ Invalid version format: "v1.0" (should be "1.0.0") +✗ Category "custom-type" not in allowed list +``` + +### Protocol 4: Menu System + +#### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [F] Fix Findings [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF F: Apply auto-fixes to {builtYaml} for identified issues, then redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Proceed to next validation step, 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](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CONTEXT BOUNDARIES + +**IN SCOPE:** +- Metadata section of agent.yaml (name, description, version, tags, category, author, license, etc.) +- Referencing the agentMetadata.md validation rules +- Comparing against BMAD standards + +**OUT OF SCOPE:** +- Persona fields (handled in step-07c) +- Menu items (handled in step-07d) +- System architecture (handled in step-07e) +- Capability implementation (handled in step-07f) + +**DO NOT:** +- Validate persona properties in this step +- Suggest major feature additions +- Question the agent's core purpose +- Modify fields beyond metadata + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation complete with any findings addressed], will you then load and read fully `{nextStepFile}` to execute and begin [persona validation]. + +## SUCCESS METRICS + +✓ **Complete Success:** All checks pass, no failures, warnings are optional +✓ **Partial Success:** Failures fixed via [F] option, warnings acknowledged +✓ **Failure:** Blocking failures remain when user selects [C] + +**CRITICAL:** Never proceed to next step if blocking failures exist and user hasn't acknowledged them. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08c-persona-validation.md b/src/modules/bmb/workflows/create-agent/steps/step-08c-persona-validation.md new file mode 100644 index 00000000..7b21c4f1 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-08c-persona-validation.md @@ -0,0 +1,161 @@ +--- +name: 'step-07c-persona-validation' +description: 'Validate persona fields and principles' + +# File References +nextStepFile: './step-08d-menu-validation.md' +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Validate that the agent's persona (role, tone, expertise, principles, constraints) is well-defined, consistent, and aligned with its purpose. + +## MANDATORY EXECUTION RULES + +- **NEVER skip validation checks** - All persona fields must be verified +- **ALWAYS load both reference documents** - personaProperties.md AND principlesCrafting.md +- **NEVER modify files without user approval** - Report findings first, await menu selection +- **ALWAYS use absolute paths** when referencing files +- **CRITICAL:** This is a validation step, not an editing step + +## EXECUTION PROTOCOLS + +### Protocol 1: Load and Compare +1. Read the persona validation reference from `{personaProperties}` +2. Read the principles crafting guide from `{principlesCrafting}` +3. Read the built agent YAML from `{builtYaml}` +4. Extract the persona section from the builtYaml +5. Compare actual persona against validation rules + +### Protocol 2: Validation Checks +Perform these checks systematically: + +1. **Required Fields Existence** + - [ ] role: Present, clear, and specific + - [ ] tone: Present and appropriate to role + - [ ] expertise: Present and relevant to agent's purpose + - [ ] principles: Present as array, not empty (if applicable) + - [ ] constraints: Present as array, not empty (if applicable) + +2. **Content Quality - Role** + - [ ] Role is specific (not generic like "assistant") + - [ ] Role aligns with agent's purpose and menu items + - [ ] Role is achievable within LLM capabilities + - [ ] Role scope is appropriate (not too broad/narrow) + +3. **Content Quality - Tone** + - [ ] Tone is clearly defined (professional, friendly, authoritative, etc.) + - [ ] Tone matches the role and target users + - [ ] Tone is consistent throughout the definition + - [ ] Tone examples or guidance provided if nuanced + +4. **Content Quality - Expertise** + - [ ] Expertise areas are relevant to role + - [ ] Expertise claims are realistic for LLM + - [ ] Expertise domains are specific (not just "knowledgeable") + - [ ] Expertise supports the menu capabilities + +5. **Content Quality - Principles** + - [ ] Principles are actionable (not vague platitudes) + - [ ] Principles guide behavior and decisions + - [ ] Principles are consistent with role + - [ ] 3-7 principles recommended (not overwhelming) + - [ ] Each principle is clear and specific + +6. **Content Quality - Constraints** + - [ ] Constraints define boundaries clearly + - [ ] Constraints are enforceable (measurable/observable) + - [ ] Constraints prevent undesirable behaviors + - [ ] Constraints don't contradict principles + +7. **Consistency Checks** + - [ ] Role, tone, expertise, principles all align + - [ ] No contradictions between principles and constraints + - [ ] Persona supports the menu items defined + - [ ] Language and terminology consistent + +### Protocol 3: Report Findings +Organize your report into three sections: + +**PASSING CHECKS** (List what passed) +``` +✓ Role is specific and well-defined +✓ Tone clearly articulated and appropriate +✓ Expertise aligns with agent purpose +✓ Principles are actionable and clear +``` + +**WARNINGS** (Non-blocking issues) +``` +⚠ Only 2 principles provided, 3-7 recommended for richer guidance +⚠ No constraints defined - consider adding boundaries +⚠ Expertise areas are broad, could be more specific +``` + +**FAILURES** (Blocking issues that must be fixed) +``` +✗ Role is generic ("assistant") - needs specificity +✗ Tone undefined - creates inconsistent behavior +✗ Principles are vague ("be helpful" - not actionable) +✗ Contradiction: Principle says "be creative", constraint says "follow strict rules" +``` + +### Protocol 4: Menu System + +#### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [F] Fix Findings [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF F: Apply auto-fixes to {builtYaml} for identified issues, then redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Proceed to next validation step, 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](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CONTEXT BOUNDARIES + +**IN SCOPE:** +- Persona section of agent.yaml (role, tone, expertise, principles, constraints) +- Referencing personaProperties.md and principlesCrafting.md +- Evaluating persona clarity, specificity, and consistency +- Checking alignment between persona elements + +**OUT OF SCOPE:** +- Metadata fields (handled in step-07b) +- Menu items (handled in step-07d) +- System architecture (handled in step-07e) +- Technical implementation details + +**DO NOT:** +- Validate metadata properties in this step +- Question the agent's core purpose (that's for earlier steps) +- Suggest additional menu items +- Modify fields beyond persona + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation complete with any findings addressed], will you then load and read fully `{nextStepFile}` to execute and begin [menu validation]. + +## SUCCESS METRICS + +✓ **Complete Success:** All checks pass, persona is well-defined and consistent +✓ **Partial Success:** Failures fixed via [F] option, warnings acknowledged +✓ **Failure:** Blocking failures remain when user selects [C] + +**CRITICAL:** A weak or generic persona is a blocking issue that should be fixed before proceeding. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08d-menu-validation.md b/src/modules/bmb/workflows/create-agent/steps/step-08d-menu-validation.md new file mode 100644 index 00000000..a5510e69 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-08d-menu-validation.md @@ -0,0 +1,158 @@ +--- +name: 'step-07d-menu-validation' +description: 'Validate menu items and patterns' + +# File References +nextStepFile: './step-08e-structure-validation.md' +agentMenuPatterns: ../data/agent-menu-patterns.md +builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Validate that the agent's menu (commands/tools) follows BMAD patterns, is well-structured, properly documented, and aligns with the agent's persona and purpose. + +## MANDATORY EXECUTION RULES + +- **NEVER skip validation checks** - All menu items must be verified +- **ALWAYS load the reference document** - agentMenuPatterns.md +- **NEVER modify files without user approval** - Report findings first, await menu selection +- **ALWAYS use absolute paths** when referencing files +- **CRITICAL:** This is a validation step, not an editing step + +## EXECUTION PROTOCOLS + +### Protocol 1: Load and Compare +1. Read the menu patterns reference from `{agentMenuPatterns}` +2. Read the built agent YAML from `{builtYaml}` +3. Extract the menu/commands section from the builtYaml +4. Compare actual menu against validation rules + +### Protocol 2: Validation Checks +Perform these checks systematically: + +1. **Menu Structure** + - [ ] Menu section exists and is properly formatted + - [ ] At least one menu item defined (unless intentionally tool-less) + - [ ] Menu items follow proper YAML structure + - [ ] Each item has required fields (name, description, pattern) + +2. **Menu Item Requirements** + For each menu item: + - [ ] name: Present, unique, uses kebab-case + - [ ] description: Clear and concise + - [ ] pattern: Valid regex pattern or tool reference + - [ ] scope: Appropriate scope defined (if applicable) + +3. **Pattern Quality** + - [ ] Patterns are valid and testable + - [ ] Patterns are specific enough to match intended inputs + - [ ] Patterns are not overly restrictive + - [ ] Patterns use appropriate regex syntax + +4. **Description Quality** + - [ ] Each item has clear description + - [ ] Descriptions explain what the item does + - [ ] Descriptions are consistent in style + - [ ] Descriptions help users understand when to use + +5. **Alignment Checks** + - [ ] Menu items align with agent's role/purpose + - [ ] Menu items are supported by agent's expertise + - [ ] Menu items fit within agent's constraints + - [ ] Menu items are appropriate for target users + +6. **Completeness** + - [ ] Core capabilities for this role are covered + - [ ] No obvious missing functionality + - [ ] Menu scope is appropriate (not too sparse/overloaded) + - [ ] Related functionality is grouped logically + +7. **Standards Compliance** + - [ ] No prohibited patterns or commands + - [ ] No security vulnerabilities in patterns + - [ ] No ambiguous or conflicting items + - [ ] Consistent naming conventions + +### Protocol 3: Report Findings +Organize your report into three sections: + +**PASSING CHECKS** (List what passed) +``` +✓ Menu structure properly formatted +✓ 5 menu items defined, all with required fields +✓ All patterns are valid regex +✓ Menu items align with agent role +``` + +**WARNINGS** (Non-blocking issues) +``` +⚠ Item "analyze-data" description is vague +⚠ No menu item for [common capability X] +⚠ Pattern for "custom-command" very broad, may over-match +``` + +**FAILURES** (Blocking issues that must be fixed) +``` +✗ Duplicate menu item name: "process" appears twice +✗ Invalid regex pattern: "[unclosed bracket" +✗ Menu item "system-admin" violates security guidelines +✗ No menu items defined for agent type that requires tools +``` + +### Protocol 4: Menu System + +#### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [F] Fix Findings [P] Party Mode [C] Continue" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF F: Apply auto-fixes to {builtYaml} for identified issues, then redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Proceed to next validation step, 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](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CONTEXT BOUNDARIES + +**IN SCOPE:** +- Menu/commands section of agent.yaml +- Referencing agentMenuPatterns.md +- Menu structure, patterns, and alignment +- Individual menu item validation + +**OUT OF SCOPE:** +- Metadata fields (handled in step-07b) +- Persona fields (handled in step-07c) +- System architecture (handled in step-07e) +- Workflow/capability implementation (handled in step-07f) + +**DO NOT:** +- Validate metadata or persona in this step +- Suggest entirely new capabilities (that's for earlier steps) +- Question whether menu items are "good enough" qualitatively beyond standards +- Modify fields beyond menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation complete with any findings addressed], will you then load and read fully `{nextStepFile}` to execute and begin [structure validation]. + +## SUCCESS METRICS + +✓ **Complete Success:** All checks pass, menu is well-structured and aligned +✓ **Partial Success:** Failures fixed via [F] option, warnings acknowledged +✓ **Failure:** Blocking failures remain when user selects [C] + +**CRITICAL:** Invalid regex patterns or security vulnerabilities in menu items are blocking issues. diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08e-structure-validation.md b/src/modules/bmb/workflows/create-agent/steps/step-08e-structure-validation.md new file mode 100644 index 00000000..3fcec5a5 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-08e-structure-validation.md @@ -0,0 +1,306 @@ +--- +name: 'step-07e-structure-validation' +description: 'Validate YAML structure and completeness' + +# File References +# Routes to 8F if Expert, else to 9 +nextStepFileExpert: './step-08f-sidecar-validation.md' +nextStepFileSimple: './step-09-celebrate.md' +simpleValidation: ../data/simple-agent-validation.md +expertValidation: ../data/expert-agent-validation.md +agentCompilation: ../data/agent-compilation.md +builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# STEP GOAL + +Validate the built agent YAML file for structural completeness and correctness against the appropriate validation checklist (simple or expert), then route to sidecar validation if needed or proceed to celebration. + +# MANDATORY EXECUTION RULES + +1. **NEVER skip validation** - All agents must pass structural validation before completion +2. **ALWAYS use the correct validation checklist** based on agent type (simple vs expert) +3. **NEVER auto-fix without user consent** - Report issues and ask for permission +4. **ALWAYS check hasSidecar flag** before determining next step routing +5. **MUST load and parse the actual built YAML** - Not just show it, but validate it +6. **ALWAYS provide clear, actionable feedback** for any validation failures + +# EXECUTION PROTOCOLS + +## Context Awareness + +- User is in the final validation phase +- Agent has been built and written to disk +- This is the "quality gate" before completion +- User expects thorough but fair validation +- Route depends on agent type (expert vs simple) + +## User Expectations + +- Clear validation results with specific issues identified +- Line-number references for YAML problems +- Option to fix issues or continue (if minor) +- Logical routing based on agent type +- Professional, constructive feedback tone + +## Tone and Style + +- Professional and thorough +- Constructive, not pedantic +- Clear prioritization of issues (critical vs optional) +- Encouraging when validation passes +- Actionable when issues are found + +# CONTEXT BOUNDARIES + +## What to Validate + +- YAML syntax and structure +- Required frontmatter fields presence +- Required sections completeness +- Field format correctness +- Path validity (for references) +- Agent type consistency (simple vs expert requirements) + +## What NOT to Validate + +- Artistic choices in descriptions +- Persona writing style +- Command naming creativity +- Feature scope decisions + +## When to Escalate + +- Critical structural errors that break agent loading +- Missing required fields +- YAML syntax errors preventing file parsing +- Path references that don't exist + +# EXECUTION SEQUENCE + +## 1. Load Validation Context + +```bash +# Load the appropriate validation checklist based on agent type +if agentType == "expert": + validationFile = expertValidation +else: + validationFile = simpleValidation + +# Load the built agent YAML +builtAgent = read(builtYaml) + +# Load compilation rules for reference +compilationRules = read(agentCompilation) +``` + +**Action:** Present a brief status message: +``` +🔍 LOADING VALIDATION FRAMEWORK + Agent Type: {detected type} + Validation Standard: {simple|expert} + Built File: {builtYaml path} +``` + +## 2. Execute Structural Validation + +Run systematic checks against the validation checklist: + +### A. YAML Syntax Validation +- Parse YAML without errors +- Check indentation consistency +- Validate proper escaping of special characters +- Verify no duplicate keys + +### B. Frontmatter Validation +- All required fields present +- Field values correct type (string, boolean, array) +- No empty required fields +- Proper array formatting + +### C. Section Completeness +- All required sections present (based on agent type) +- Sections not empty unless explicitly optional +- Proper markdown heading hierarchy + +### D. Field-Level Validation +- Path references exist and are valid +- Boolean fields are actual booleans (not strings) +- Array fields properly formatted +- No malformed YAML structures + +### E. Agent Type Specific Checks + +**For Simple Agents:** +- No sidecar requirements +- Basic fields complete +- No advanced configuration + +**For Expert Agents:** +- Sidecar flag set correctly +- Sidecar folder path specified +- All expert fields present +- Advanced features properly configured + +## 3. Generate Validation Report + +Present findings in structured format: + +```markdown +# 🎯 STRUCTURAL VALIDATION REPORT + +## Agent: {agent-name} +Type: {simple|expert} +File: {builtYaml} + +--- + +## ✅ PASSED CHECKS ({count}) +{List of all validations that passed} + +## ⚠️ ISSUES FOUND ({count}) +{If any issues, list each with:} +### Issue #{number}: {type} +**Severity:** [CRITICAL|MODERATE|MINOR] +**Location:** Line {line} or Section {section} +**Problem:** {clear description} +**Impact:** {what this breaks} +**Suggested Fix:** {specific action} + +--- + +## 📊 VALIDATION SUMMARY +**Overall Status:** [PASSED|FAILED|CONDITIONAL] +**Critical Issues:** {count} +**Moderate Issues:** {count} +**Minor Issues:** {count} +**Can Load Safely:** [YES|NO] + +--- + +{If PASSED} +## 🎉 VALIDATION SUCCESSFUL +Your agent YAML is structurally sound and ready for use! +All required fields present and correctly formatted. + +{If ISSUES FOUND} +## 🔧 RECOMMENDED ACTIONS +1. Address critical issues first +2. Review moderate issues +3. Minor issues can be deferred +``` + +## 4. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [F] Fix Findings [P] Party Mode [C] Continue" + +### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF F: Apply auto-fixes to {builtYaml} for identified issues, then redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Proceed to next validation step, update frontmatter, then only then load, read entire file, then execute {nextStepFileExpert} or {nextStepFileSimple} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options) + +### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +If [F] selected: Work through issues systematically +- Load specific section needing fix +- Present current state +- Apply auto-fixes or guide user through corrections +- Re-validate after each fix +- Confirm resolution and re-present menu + +If [C] selected: +- Warn about implications if issues exist +- Get explicit confirmation if critical issues +- Document acceptance of issues +- Proceed to routing + +## 5. Route to Next Step + +After validation passes or user chooses to continue: + +### Check Agent Type and Route + +```yaml +# Check for sidecar requirement +hasSidecar = checkBuiltYamlForSidecarFlag() + +if hasSidecar == true: + # Expert agent with sidecar + nextStep = nextStepFileExpert + routeMessage = """ + 📦 Expert agent detected with sidecar configuration. + → Proceeding to sidecar validation (Step 7F) + """ +else: + # Simple agent or expert without sidecar + nextStep = nextStepFileSimple + routeMessage = """ + ✅ Simple agent validation complete. + → Proceeding to celebration (Step 8) + """ +``` + +**Action:** Present routing decision and transition: +```markdown +# 🚀 VALIDATION COMPLETE - ROUTING DECISION + +{routeMessage} + +**Next Step:** {nextStep filename} +**Reason:** Agent type {simple|expert} with sidecar={hasSidecar} + +Press [Enter] to continue to {next step description}... +``` + +# CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation complete with any findings addressed], will you then load and read fully `{nextStepFileExpert}` or `{nextStepFileSimple}` to execute and begin [sidecar validation or celebration]. + +**BEFORE proceeding to next step:** + +1. ✅ Validation checklist executed completely +2. ✅ All critical issues resolved or explicitly accepted +3. ✅ User informed of routing decision +4. ✅ Next step file path determined correctly +5. ⚠️ **CRITICAL:** For expert agents, verify hasSidecar is TRUE before routing to 7F +6. ⚠️ **CRITICAL:** For simple agents, verify hasSidecar is FALSE before routing to 8 + +**DO NOT PROCEED IF:** +- YAML has critical syntax errors preventing loading +- User has not acknowledged validation results +- Routing logic is unclear or conflicting + +# SUCCESS METRICS + +## Step Complete When: +- [ ] Validation report generated and presented +- [ ] User has reviewed findings +- [ ] Critical issues resolved or accepted +- [ ] Routing decision communicated and confirmed +- [ ] Next step path verified and ready + +## Quality Indicators: +- Validation thoroughness (all checklist items covered) +- Issue identification clarity and specificity +- User satisfaction with resolution process +- Correct routing logic applied +- Clear transition to next step + +## Failure Modes: +- Skipping validation checks +- Auto-fixing without permission +- Incorrect routing (simple→7F or expert→8 with sidecar) +- Unclear or missing validation report +- Proceeding with critical YAML errors diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08f-sidecar-validation.md b/src/modules/bmb/workflows/create-agent/steps/step-08f-sidecar-validation.md new file mode 100644 index 00000000..2ffcdaed --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/steps/step-08f-sidecar-validation.md @@ -0,0 +1,462 @@ +--- +name: 'step-07f-sidecar-validation' +description: 'Validate sidecar structure and paths' + +# File References +nextStepFile: './step-09-celebrate.md' +criticalActions: ../data/critical-actions.md +builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml' +sidecarFolder: '{bmb_creations_output_folder}/{agent-name}/{agent-name}-sidecar/' + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- +# STEP GOAL + +Validate the sidecar folder structure and referenced paths for Expert agents to ensure all sidecar files exist, are properly structured, and paths in the main agent YAML correctly reference them. + +# MANDATORY EXECUTION RULES + +1. **ONLY runs for Expert agents** - Simple agents should never reach this step +2. **MUST verify sidecar folder exists** before proceeding +3. **ALWAYS cross-reference YAML paths** with actual files +4. **NEVER create missing sidecar files** - Report issues, don't auto-fix +5. **MUST validate sidecar file structure** for completeness +6. **ALWAYS check critical actions file** if referenced +7. **PROVIDE clear remediation steps** for any missing or malformed files + +# EXECUTION PROTOCOLS + +## Context Awareness + +- User has an Expert agent with sidecar configuration +- Structural validation (7E) already passed +- Sidecar folder should have been created during build +- This is the final validation before celebration +- Missing sidecar components may break agent functionality + +## User Expectations + +- Comprehensive sidecar structure validation +- Clear identification of missing files +- Path reference verification +- Actionable remediation guidance +- Professional but approachable tone + +## Tone and Style + +- Thorough and systematic +- Clear and specific about issues +- Solution-oriented (focus on how to fix) +- Encouraging when sidecar is complete +- Not pedantic about minor formatting issues + +# CONTEXT BOUNDARIES + +## What to Validate + +- Sidecar folder existence and location +- All referenced files exist in sidecar +- Sidecar file structure completeness +- Path references in main YAML accuracy +- Critical actions file if referenced +- File naming conventions +- File content completeness (not empty) + +## What NOT to Validate + +- Content quality of sidecar files +- Artistic choices in sidecar documentation +- Optional sidecar components +- File formatting preferences + +## When to Escalate + +- Sidecar folder completely missing +- Critical files missing (actions, core modules) +- Path references pointing to non-existent files +- Empty sidecar files that should have content + +# EXECUTION SEQUENCE + +## 1. Load Sidecar Context + +```bash +# Verify main agent YAML exists +agentYaml = read(builtYaml) + +# Extract sidecar path from YAML or use template default +sidecarPath = extractSidecarPath(agentYaml) or sidecarFolder + +# Check if sidecar folder exists +sidecarExists = directoryExists(sidecarPath) + +# Load critical actions reference if needed +criticalActionsRef = read(criticalActions) +``` + +**Action:** Present discovery status: +```markdown +🔍 SIDECAR VALIDATION INITIALIZED + +Agent: {agent-name} +Type: Expert (requires sidecar) + +Main YAML: {builtYaml} +Sidecar Path: {sidecarPath} + +Status: {✅ Folder Found | ❌ Folder Missing} +``` + +## 2. Validate Sidecar Structure + +### A. Folder Existence Check + +```markdown +## 📁 FOLDER STRUCTURE VALIDATION + +**Sidecar Location:** {sidecarPath} +**Status:** [EXISTS | MISSING | WRONG LOCATION] +``` + +If missing: +```markdown +❌ **CRITICAL ISSUE:** Sidecar folder not found! + +**Expected Location:** {sidecarPath} + +**Possible Causes:** +1. Build process didn't create sidecar +2. Sidecar path misconfigured in agent YAML +3. Folder moved or deleted after build + +**Required Action:** +[ ] Re-run build process with sidecar enabled +[ ] Verify sidecar configuration in agent YAML +[ ] Check folder was created in correct location +``` + +### B. Sidecar File Inventory + +If folder exists, list all files: +```bash +sidecarFiles = listFiles(sidecarPath) +``` + +```markdown +## 📄 SIDECAR FILE INVENTORY + +Found {count} files in sidecar: + +{For each file:} +- {filename} ({size} bytes) +``` + +### C. Cross-Reference Validation + +Extract all sidecar path references from agent YAML: +```yaml +# Common sidecar reference patterns +sidecar: + critical-actions: './{agent-name}-sidecar/critical-actions.md' + modules: + - path: './{agent-name}-sidecar/modules/module-01.md' +``` + +Validate each reference: +```markdown +## 🔗 PATH REFERENCE VALIDATION + +**Checked {count} references from agent YAML:** + +{For each reference:} +**Source:** {field in agent YAML} +**Expected Path:** {referenced path} +**Status:** [✅ Found | ❌ Missing | ⚠️ Wrong Location] +``` + +## 3. Validate Sidecar File Contents + +For each sidecar file found, check: + +### A. File Completeness +```markdown +## 📋 FILE CONTENT VALIDATION + +{For each file:} +### {filename} +**Size:** {bytes} +**Status:** [✅ Complete | ⚠️ Empty | ❌ Too Small] +**Last Modified:** {timestamp} +``` + +### B. Critical Actions File (if present) + +Special validation for critical-actions.md: +```markdown +## 🎯 CRITICAL ACTIONS VALIDATION + +**File:** {sidecarPath}/critical-actions.md +**Status:** [PRESENT | MISSING | EMPTY] + +{If Present:} +**Sections Found:** +{List sections detected} + +**Completeness:** +[ ] Header/metadata present +[ ] Actions defined +[ ] No critical sections missing +``` + +### C. Module Files (if present) + +If sidecar contains modules: +```markdown +## 📚 MODULE VALIDATION + +**Modules Found:** {count} + +{For each module:} +### {module-filename} +**Status:** [✅ Valid | ⚠️ Issues Found] +**Checks:** +[ ] Frontmatter complete +[ ] Content present +[ ] References valid +``` + +## 4. Generate Validation Report + +```markdown +# 🎯 SIDECAR VALIDATION REPORT + +## Agent: {agent-name} +Sidecar Path: {sidecarPath} +Validation Date: {timestamp} + +--- + +## ✅ VALIDATION CHECKS PASSED + +**Folder Structure:** +- [x] Sidecar folder exists +- [x] Located at expected path +- [x] Accessible and readable + +**File Completeness:** +- [x] All referenced files present +- [x] No broken path references +- [x] Files have content (not empty) + +**Content Quality:** +- [x] Critical actions complete +- [x] Module files structured +- [x] No obvious corruption + +--- + +## ⚠️ ISSUES IDENTIFIED ({count}) + +{If issues:} +### Issue #{number}: {issue type} +**Severity:** [CRITICAL|MODERATE|MINOR] +**Component:** {file or folder} +**Problem:** {clear description} +**Impact:** {what this breaks} +**Remediation:** +1. {specific step 1} +2. {specific step 2} +3. {specific step 3} + +{If no issues:} +### 🎉 NO ISSUES FOUND +Your agent's sidecar is complete and properly structured! +All path references are valid and files are in place. + +--- + +## 📊 SUMMARY + +**Overall Status:** [PASSED|FAILED|CONDITIONAL] +**Files Validated:** {count} +**Issues Found:** {count} +**Critical Issues:** {count} +**Sidecar Ready:** [YES|NO] + +--- + +## 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [F] Fix Findings [P] Party Mode [C] Continue" + +### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF F: Apply auto-fixes to {builtYaml} or sidecar files for identified issues, then redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Proceed to celebration step, 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](#5-present-menu-options) + +### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## 6. Issue Resolution (if [F] selected) + +Work through each issue systematically: + +**For Missing Files:** +```markdown +### 🔧 FIXING: Missing {filename} + +**Required File:** {path} +**Purpose:** {why it's needed} + +**Option 1:** Re-run Build +- Sidecar may not have been created completely +- Return to build step and re-execute + +**Option 2:** Manual Creation +- Create file at: {full path} +- Use template from: {template reference} +- Minimum required content: {specification} + +**Option 3:** Update References +- Remove reference from agent YAML if not truly needed +- Update path if file exists in different location + +Which option? [1/2/3]: +``` + +**For Broken Path References:** +```markdown +### 🔧 FIXING: Invalid Path Reference + +**Reference Location:** {agent YAML field} +**Current Path:** {incorrect path} +**Expected File:** {filename} +**Actual Location:** {where file actually is} + +**Fix Options:** +1. Update path in agent YAML to: {correct path} +2. Move file to expected location: {expected path} +3. Remove reference if file not needed + +Which option? [1/2/3]: +``` + +**For Empty/Malformed Files:** +```markdown +### 🔧 FIXING: {filename} - {Issue} + +**Problem:** {empty/too small/malformed} +**Location:** {full path} + +**Remediation:** +- View current content +- Compare to template/standard +- Add missing sections +- Correct formatting + +Ready to view and fix? [Y/N]: +``` + +After each fix: +- Re-validate the specific component +- Confirm resolution +- Move to next issue +- Final re-validation when all complete + +## 6. Route to Celebration + +When validation passes or user chooses to continue: + +```markdown +# 🚀 SIDECAR VALIDATION COMPLETE + +## Expert Agent: {agent-name} + +✅ **Sidecar Structure:** Validated +✅ **Path References:** All correct +✅ **File Contents:** Complete + +--- + +## 🎯 READY FOR CELEBRATION + +Your Expert agent with sidecar is fully validated and ready! + +**Next Step:** Celebration (Step 8) +**Final Status:** All checks passed + +Press [Enter] to proceed to celebration... +``` + +# CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation complete with any findings addressed], will you then load and read fully `{nextStepFile}` to execute and begin [celebration]. + +**BEFORE proceeding to Step 8:** + +1. ✅ Sidecar folder exists and is accessible +2. ✅ All referenced files present +3. ✅ Path references validated +4. ✅ File contents checked for completeness +5. ✅ User informed of validation status +6. ✅ Issues resolved or explicitly accepted +7. ⚠️ **CRITICAL:** Only Expert agents should reach this step +8. ⚠️ **CRITICAL:** Sidecar must be complete for agent to function + +**DO NOT PROCEED IF:** +- Sidecar folder completely missing +- Critical files absent (actions, core modules) +- User unaware of sidecar issues +- Validation not completed + +# SUCCESS METRICS + +## Step Complete When: +- [ ] Sidecar folder validated +- [ ] All path references checked +- [ ] File contents verified +- [ ] Validation report presented +- [ ] Issues resolved or accepted +- [ ] User ready to proceed + +## Quality Indicators: +- Thoroughness of file inventory +- Accuracy of path reference validation +- Clarity of issue identification +- Actionability of remediation steps +- User confidence in sidecar completeness + +## Failure Modes: +- Missing sidecar folder completely +- Skipping file existence checks +- Not validating path references +- Proceeding with critical files missing +- Unclear validation report +- Not providing remediation guidance + +--- + +## 🎓 NOTE: Expert Agent Sidecars + +Sidecars are what make Expert agents powerful. They enable: +- Modular architecture +- Separation of concerns +- Easier updates and maintenance +- Shared components across agents + +A validated sidecar ensures your Expert agent will: +- Load correctly at runtime +- Find all referenced resources +- Execute critical actions as defined +- Provide the advanced capabilities designed + +Take the time to validate thoroughly - it pays off in agent reliability! diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08-celebrate.md b/src/modules/bmb/workflows/create-agent/steps/step-09-celebrate.md similarity index 53% rename from src/modules/bmb/workflows/create-agent/steps/step-08-celebrate.md rename to src/modules/bmb/workflows/create-agent/steps/step-09-celebrate.md index 53158bbc..794766cc 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-08-celebrate.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-09-celebrate.md @@ -1,22 +1,23 @@ --- -name: 'step-08-celebrate' +name: 'step-09-celebrate' description: 'Celebrate completion and guide next steps for using the agent' # File References -thisStepFile: ./step-08-celebrate.md +thisStepFile: ./step-09-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' +installationDocs: 'https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/modules/bmb-bmad-builder/custom-content-installation.md#standalone-content-agents-workflows-tasks-tools-templates-prompts' --- -# Step 8: Celebration and Next Steps +# Step 9: Celebration and Installation Guidance ## STEP GOAL: -Celebrate the successful agent creation, provide activation guidance, and explore what to do next with the completed agent while marking workflow completion. +Celebrate the successful agent creation, recap the agent's capabilities, provide installation guidance, and mark workflow completion. ## MANDATORY EXECUTION RULES (READ FIRST): @@ -29,32 +30,34 @@ Celebrate the successful agent creation, provide activation guidance, and explor ### Role Reinforcement: -- ✅ You are a celebration coordinator who guides users through agent activation and next steps +- ✅ You are a celebration coordinator who guides users through agent installation and activation - ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role - ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring deployment expertise, user brings their excitement about their new agent, together we ensure successful agent activation and usage +- ✅ You bring installation expertise, user brings their excitement about their new agent, together we ensure successful agent installation and usage - ✅ Maintain collaborative celebratory tone throughout ### Step-Specific Rules: -- 🎯 Focus only on celebrating completion and guiding next steps +- 🎯 Focus only on celebrating completion and guiding installation - 🚫 FORBIDDEN to end without marking workflow completion in frontmatter -- 💬 Approach: Celebrate enthusiastically while providing practical guidance -- 📋 Ensure user understands activation steps and agent capabilities +- 💬 Approach: Celebrate enthusiastically while providing practical installation guidance +- 📋 Ensure user understands installation steps and agent capabilities +- 🔗 Always provide installation documentation link for reference ## EXECUTION PROTOCOLS: - 🎉 Celebrate agent creation achievement enthusiastically - 💾 Mark workflow completion in frontmatter -- 📖 Provide clear activation guidance and next steps +- 📖 Provide clear installation guidance +- 🔗 Share installation documentation link - 🚫 FORBIDDEN to end workflow without proper completion marking ## CONTEXT BOUNDARIES: - Available context: Complete, validated, and built agent from previous steps -- Focus: Celebration, activation guidance, and workflow completion -- Limits: No agent modifications, only usage guidance and celebration -- Dependencies: Complete agent ready for activation +- Focus: Celebration, installation guidance, and workflow completion +- Limits: No agent modifications, only installation guidance and celebration +- Dependencies: Complete agent ready for installation ## Sequence of Instructions (Do not deviate, skip, or optimize) @@ -106,26 +109,46 @@ Present enthusiastic celebration: - 'Tell me about your capabilities' - 'Help me with [specific task related to agent purpose]'" -### 4. Next Steps Exploration +### 4. Installation Guidance -**Immediate Next Steps:** -"Now that {agent_name} is ready, what would you like to do first?" +**Making Your Agent Installable:** +"Now that {agent_name} is complete, let's get it installed and ready to use!" -**Options to Explore:** +**Installation Overview:** +"To make your agent installable and sharable, you'll need to package it as a standalone BMAD content module. Here's what you need to know:" -- **Test drive:** Try out different commands and capabilities -- **Customize:** Fine-tune personality or add new commands -- **Integrate:** Set up {agent_name} in your workflow -- **Share:** Tell others about your new agent -- **Expand:** Plan additional agents or capabilities +**Key Steps:** +1. **Create a module folder:** Name it something descriptive (e.g., `my-custom-stuff`) +2. **Add module.yaml:** Include a `module.yaml` file with `unitary: true` +3. **Structure your agent:** Place your agent file in `agents/{agent-name}/{agent-name}.agent.yaml` +4. **Include sidecar (if Expert):** For Expert agents, include the `_memory/{sidecar-folder}/` structure -**Future Possibilities:** -"As you use {agent_name}, you might discover: +**Module Structure Example:** +``` +my-custom-stuff/ +├── module.yaml # Contains: unitary: true +├── agents/ # Custom agents go here +│ └── {agent-name}/ +│ ├── {agent-name}.agent.yaml +│ └── _memory/ # Expert agents only +│ └── {sidecar-folder}/ +│ ├── memories.md +│ └── instructions.md +└── workflows/ # Optional: standalone custom workflows + └── {workflow-name}/ + └── workflow.md +``` -- 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" +**Note:** Your custom module can contain agents, workflows, or both. The `agents/` and `workflows/` folders are siblings alongside `module.yaml`. + +**Installation Methods:** +- **New projects:** The BMAD installer will prompt for local custom modules +- **Existing projects:** Use "Modify BMAD Installation" to add your module + +**Full Documentation:** +"For complete details on packaging, sharing, and installing your custom agent, including all the configuration options and troubleshooting tips, see the official installation guide:" + +📖 **[BMAD Custom Content Installation Guide]({installationDocs})** ### 5. Final Documentation @@ -139,7 +162,7 @@ Present enthusiastic celebration: - **Name:** {agent_name} - **Type:** {agent_type} - **Purpose:** {agent_purpose} -- **Status:** Ready for activation +- **Status:** Ready for installation ### File Locations @@ -147,13 +170,18 @@ Present enthusiastic celebration: - **Compiled Version:** {compiled_agent_path} - **Customization:** {customization_file_path} -### Activation Guidance +### Installation -[Steps for activating and using the agent] +Package your agent as a standalone module with `module.yaml` containing `unitary: true`. +See: {installationDocs} -### Next Steps +### Quick Start -[Ideas for using and expanding the agent] +1. Create a module folder +2. Add module.yaml with `unitary: true` +3. Place agent in `agents/{agent-name}/` structure +4. Include sidecar folder for Expert agents +5. Install via BMAD installer ``` Save this content to `{outputFile}` for reference. @@ -161,32 +189,32 @@ 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 be installed and used. Amazing work!" **Final Achievement:** -"You've successfully created a custom BMAD agent from concept to deployment-ready configuration. Amazing work!" +"You've successfully created a custom BMAD agent from concept to installation-ready configuration. The journey from idea to deployable agent is complete!" ### 7. Present MENU OPTIONS -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Complete" +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [X] Exit Workflow" #### Menu Handling Logic: -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Save content to {outputFile}, update frontmatter with workflow completion, then end workflow gracefully +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF X: Save content to {outputFile}, update frontmatter with workflow completion, then end workflow gracefully - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options) #### EXECUTION RULES: - ALWAYS halt and wait for user input after presenting menu -- ONLY complete workflow when user selects 'C' +- ONLY complete workflow when user selects 'X' - After other menu items execution, return to this menu - User can chat or ask questions - always respond and then end with display again of the menu options ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN [C complete option] is selected and [workflow completion marked in frontmatter], will the workflow end gracefully with agent ready for activation. +ONLY WHEN [X exit option] is selected and [workflow completion marked in frontmatter], will the workflow end gracefully with agent ready for installation. --- @@ -195,20 +223,22 @@ ONLY WHEN [C complete option] is selected and [workflow completion marked in fro ### ✅ SUCCESS: - Enthusiastic celebration of agent creation achievement -- Clear activation guidance and next steps provided +- Clear installation guidance provided - Agent capabilities and value clearly communicated -- User confidence in agent usage established +- Installation documentation link shared with context +- Module structure and packaging explained +- User confidence in agent installation established - Workflow properly marked as complete in frontmatter -- Future possibilities and expansion opportunities explored - Content properly saved to output file -- Menu presented with completion option +- Menu presented with exit option ### ❌ SYSTEM FAILURE: - Ending without marking workflow completion -- Not providing clear activation guidance +- Not providing clear installation guidance - Missing celebration of achievement -- Not ensuring user understands next steps +- Not sharing installation documentation link +- Not ensuring user understands installation steps - Failing to update frontmatter completion status **Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. From 9f53d896b779f22fd9f86c8b2a9773c7e46966bc Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Wed, 31 Dec 2025 02:58:03 +0800 Subject: [PATCH 5/6] agent-workflow create edit validate consolidation --- .../bmb/agents/agent-builder.agent.yaml | 4 +- .../bmb/docs/workflows/step-file-rules.md | 469 ++++++++++++++++++ .../data/agent-compilation.md | 0 .../data/agent-menu-patterns.md | 0 .../data/agent-metadata.md | 0 .../data/brainstorm-context.md | 0 .../data/communication-presets.csv | 0 .../data/critical-actions.md | 0 .../data/expert-agent-architecture.md | 0 .../data/expert-agent-validation.md | 0 .../data/module-agent-validation.md | 0 .../data/persona-properties.md | 0 .../data/principles-crafting.md | 0 .../journal-keeper-sidecar/breakthroughs.md | 0 .../entries/yy-mm-dd-entry-template.md | 0 .../journal-keeper-sidecar/instructions.md | 0 .../journal-keeper-sidecar/memories.md | 0 .../journal-keeper-sidecar/mood-patterns.md | 0 .../journal-keeper/journal-keeper.agent.yaml | 0 .../module-examples/architect.agent.yaml | 0 .../reference/module-examples/architect.md | 0 .../security-engineer.agent.yaml | 0 .../module-examples/trend-analyst.agent.yaml | 0 .../simple-examples/commit-poet.agent.yaml | 0 .../data/simple-agent-architecture.md | 0 .../data/simple-agent-validation.md | 0 .../data/understanding-agent-types.md | 0 .../steps-c}/step-01-brainstorm.md | 2 +- .../steps-c}/step-02-discovery.md | 0 .../steps-c}/step-03-type-metadata.md | 0 .../steps-c}/step-04-persona.md | 0 .../steps-c}/step-05-commands-menu.md | 0 .../steps-c}/step-06-activation.md | 0 .../steps-c}/step-07a-build-simple.md | 0 .../steps-c}/step-07b-build-expert.md | 0 .../steps-c}/step-07c-build-module.md | 0 .../steps-c}/step-08a-plan-traceability.md | 0 .../steps-c}/step-08b-metadata-validation.md | 0 .../steps-c}/step-08c-persona-validation.md | 0 .../steps-c}/step-08d-menu-validation.md | 0 .../steps-c}/step-08e-structure-validation.md | 0 .../steps-c}/step-08f-sidecar-validation.md | 0 .../steps-c}/step-09-celebrate.md | 0 .../agent/steps-e/e-01-load-existing.md | 214 ++++++++ .../agent/steps-e/e-02-discover-edits.md | 191 +++++++ .../agent/steps-e/e-03a-validate-metadata.md | 78 +++ .../agent/steps-e/e-03b-validate-persona.md | 76 +++ .../agent/steps-e/e-03c-validate-menu.md | 75 +++ .../agent/steps-e/e-03d-validate-structure.md | 75 +++ .../agent/steps-e/e-03e-validate-sidecar.md | 78 +++ .../agent/steps-e/e-03f-validation-summary.md | 119 +++++ .../agent/steps-e/e-04-type-metadata.md | 122 +++++ .../workflows/agent/steps-e/e-05-persona.md | 132 +++++ .../agent/steps-e/e-06-commands-menu.md | 120 +++++ .../agent/steps-e/e-07-activation.md | 122 +++++ .../agent/steps-e/e-08a-edit-simple.md | 134 +++++ .../agent/steps-e/e-08b-edit-expert.md | 117 +++++ .../agent/steps-e/e-08c-edit-module.md | 120 +++++ .../agent/steps-e/e-09a-validate-metadata.md | 70 +++ .../agent/steps-e/e-09b-validate-persona.md | 70 +++ .../agent/steps-e/e-09c-validate-menu.md | 69 +++ .../agent/steps-e/e-09d-validate-structure.md | 69 +++ .../agent/steps-e/e-09e-validate-sidecar.md | 70 +++ .../agent/steps-e/e-09f-validation-summary.md | 111 +++++ .../workflows/agent/steps-e/e-10-celebrate.md | 150 ++++++ .../agent/steps-v/v-01-load-review.md | 128 +++++ .../agent/steps-v/v-02a-validate-metadata.md | 73 +++ .../agent/steps-v/v-02b-validate-persona.md | 72 +++ .../agent/steps-v/v-02c-validate-menu.md | 71 +++ .../agent/steps-v/v-02d-validate-structure.md | 71 +++ .../agent/steps-v/v-02e-validate-sidecar.md | 76 +++ .../workflows/agent/steps-v/v-03-summary.md | 100 ++++ .../templates/agent-plan.template.md | 0 .../instructions.md.template | 0 .../expert-agent-sidecar/memories.md.template | 0 .../expert-agent.template.md | 0 .../templates/simple-agent.template.md | 0 src/modules/bmb/workflows/agent/workflow.md | 123 +++++ .../bmb/workflows/create-agent/workflow.md | 59 --- .../steps/step-01-discover-intent.md | 135 ----- .../edit-agent/steps/step-02-analyze-agent.md | 203 -------- .../steps/step-03-propose-changes.md | 158 ------ .../edit-agent/steps/step-04-apply-changes.md | 151 ------ .../edit-agent/steps/step-05-validate.md | 151 ------ .../bmb/workflows/edit-agent/workflow.md | 59 --- 85 files changed, 3568 insertions(+), 919 deletions(-) create mode 100644 src/modules/bmb/docs/workflows/step-file-rules.md rename src/modules/bmb/workflows/{create-agent => agent}/data/agent-compilation.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/agent-menu-patterns.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/agent-metadata.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/brainstorm-context.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/communication-presets.csv (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/critical-actions.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/expert-agent-architecture.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/expert-agent-validation.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/module-agent-validation.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/persona-properties.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/principles-crafting.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/module-examples/architect.agent.yaml (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/module-examples/architect.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/module-examples/security-engineer.agent.yaml (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/module-examples/trend-analyst.agent.yaml (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/reference/simple-examples/commit-poet.agent.yaml (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/simple-agent-architecture.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/simple-agent-validation.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/data/understanding-agent-types.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-01-brainstorm.md (97%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-02-discovery.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-03-type-metadata.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-04-persona.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-05-commands-menu.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-06-activation.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-07a-build-simple.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-07b-build-expert.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-07c-build-module.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-08a-plan-traceability.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-08b-metadata-validation.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-08c-persona-validation.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-08d-menu-validation.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-08e-structure-validation.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-08f-sidecar-validation.md (100%) rename src/modules/bmb/workflows/{create-agent/steps => agent/steps-c}/step-09-celebrate.md (100%) create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-01-load-existing.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-02-discover-edits.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-03a-validate-metadata.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-03b-validate-persona.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-03c-validate-menu.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-03d-validate-structure.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-03e-validate-sidecar.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-03f-validation-summary.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-04-type-metadata.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-05-persona.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-06-commands-menu.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-07-activation.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-08a-edit-simple.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-08b-edit-expert.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-08c-edit-module.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-09a-validate-metadata.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-09b-validate-persona.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-09c-validate-menu.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-09d-validate-structure.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-09e-validate-sidecar.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-09f-validation-summary.md create mode 100644 src/modules/bmb/workflows/agent/steps-e/e-10-celebrate.md create mode 100644 src/modules/bmb/workflows/agent/steps-v/v-01-load-review.md create mode 100644 src/modules/bmb/workflows/agent/steps-v/v-02a-validate-metadata.md create mode 100644 src/modules/bmb/workflows/agent/steps-v/v-02b-validate-persona.md create mode 100644 src/modules/bmb/workflows/agent/steps-v/v-02c-validate-menu.md create mode 100644 src/modules/bmb/workflows/agent/steps-v/v-02d-validate-structure.md create mode 100644 src/modules/bmb/workflows/agent/steps-v/v-02e-validate-sidecar.md create mode 100644 src/modules/bmb/workflows/agent/steps-v/v-03-summary.md rename src/modules/bmb/workflows/{create-agent => agent}/templates/agent-plan.template.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template (100%) rename src/modules/bmb/workflows/{create-agent => agent}/templates/expert-agent-template/expert-agent-sidecar/memories.md.template (100%) rename src/modules/bmb/workflows/{create-agent => agent}/templates/expert-agent-template/expert-agent.template.md (100%) rename src/modules/bmb/workflows/{create-agent => agent}/templates/simple-agent.template.md (100%) create mode 100644 src/modules/bmb/workflows/agent/workflow.md delete mode 100644 src/modules/bmb/workflows/create-agent/workflow.md delete mode 100644 src/modules/bmb/workflows/edit-agent/steps/step-01-discover-intent.md delete mode 100644 src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md delete mode 100644 src/modules/bmb/workflows/edit-agent/steps/step-03-propose-changes.md delete mode 100644 src/modules/bmb/workflows/edit-agent/steps/step-04-apply-changes.md delete mode 100644 src/modules/bmb/workflows/edit-agent/steps/step-05-validate.md delete mode 100644 src/modules/bmb/workflows/edit-agent/workflow.md diff --git a/src/modules/bmb/agents/agent-builder.agent.yaml b/src/modules/bmb/agents/agent-builder.agent.yaml index aef49193..71a0e57a 100644 --- a/src/modules/bmb/agents/agent-builder.agent.yaml +++ b/src/modules/bmb/agents/agent-builder.agent.yaml @@ -28,9 +28,9 @@ agent: menu: - trigger: CA or fuzzy match on create-agent - exec: "{project-root}/_bmad/bmb/workflows/create-agent/workflow.md" + exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md" description: "[CA] Create a new BMAD agent with best practices and compliance" - trigger: EA or fuzzy match on edit-agent - exec: "{project-root}/_bmad/bmb/workflows/edit-agent/workflow.md" + exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md" description: "[EA] Edit existing BMAD agents while maintaining compliance" diff --git a/src/modules/bmb/docs/workflows/step-file-rules.md b/src/modules/bmb/docs/workflows/step-file-rules.md new file mode 100644 index 00000000..56e58899 --- /dev/null +++ b/src/modules/bmb/docs/workflows/step-file-rules.md @@ -0,0 +1,469 @@ +# BMAD Step File Guidelines + +**Version:** 1.0 +**Module:** bmb (BMAD Builder) +**Purpose:** Definitive guide for creating BMAD workflow step files + +--- + +## Overview + +BMAD workflow step files follow a strict structure to ensure consistency, progressive disclosure, and mode-aware routing. Every step file MUST adhere to these guidelines. + +--- + +## File Size Optimization + +**CRITICAL:** Keep step files **LT 200 lines** (250 lines absolute maximum). + +If a step exceeds this limit: +- Consider splitting into multiple steps +- Extract content to `/data/` reference files +- Optimize verbose explanations + +--- + +## Required Frontmatter Structure + +CRITICAL: Frontmatter should only have items that are used in the step file! + +```yaml +--- +name: 'step-2-foo.md' +description: 'Brief description of what this step accomplishes' + +# File References ## CRITICAL: Frontmatter references or variables should only have items that are used in the step file! +outputFile: {bmb_creations_output_folder}/output-file-name.md +nextStepFile: './step-3-bar.md' + +# Task References (as needed) +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +# ... other task-specific references +--- +``` + +### Frontmatter Field Descriptions + +| Field | Required | Description | +| --------------- | --------- | --------------------------------- | +| `name` | Yes | Step identifier (kebab-case) | +| `description` | Yes | One-line summary of step purpose | +| `outputFile` | Yes | Where results are documented | +| Task references | As needed | Paths to external workflows/tasks | + +--- + +## Document Structure + +### 1. Title + +```markdown +# Step X: [Step Name] +``` + +### 2. STEP GOAL + +```markdown +## STEP GOAL: + +[Single sentence stating what this step accomplishes] +``` + +### 3. Role Reinforcement + +```markdown +### Role Reinforcement: + +- ✅ You are a [specific role] who [does what] +- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring [your expertise], user brings [their expertise], together we [achieve goal] +- ✅ Maintain [tone/approach] throughout +``` + +### 4. Language Preference + +```markdown +### Language Preference: +The user has chosen to communicate in the **{language}** language. +You MUST respond in **{language}** throughout this step. +``` + +**IMPORTANT:** Read `userPreferences.language` from tracking file (agentPlan, validationReport, etc.) and enforce it. + +### 5. Step-Specific Rules + +```markdown +### Step-Specific Rules: + +- 🎯 Focus only on [specific scope] +- 🚫 FORBIDDEN to [prohibited action] +- 💬 Approach: [how to engage] +- 📋 Ensure [specific outcome] +``` + +### 6. EXECUTION PROTOCOLS + +```markdown +## EXECUTION PROTOCOLS: + +- [What to do - use verbs] +- [Another action] +- 🚫 FORBIDDEN to [prohibited action] +``` + +### 7. CONTEXT BOUNDARIES + +```markdown +## CONTEXT BOUNDARIES: + +- Available context: [what's available] +- Focus: [what to focus on] +- Limits: [boundaries] +- Dependencies: [what this step depends on] +``` + +### 8. Sequence of Instructions + +```markdown +## Sequence of Instructions: + +### 1. [First Action] + +**[Action Description]** + +### 2. [Second Action] + +... +``` + +### 9. MENU OPTIONS + +```markdown +### X. Present MENU OPTIONS + +Display: "**Select:** [A] [menu item A] [P] [menu item P] [C] [menu item C]" + +#### Menu Handling Logic: +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options) + +#### EXECUTION RULES: +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE +ONLY WHEN [C continue option] is selected and [completion conditions], will you then load and read fully `{nextStepFile}`... +``` + +### 10. SYSTEM SUCCESS/FAILURE METRICS + +```markdown +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: +- [Success criterion 1] +- [Success criterion 2] +- ... + +### ❌ SYSTEM FAILURE: +- [Failure criterion 1] +- [Failure criterion 2] +- ... + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. +``` + +--- + +## A/P/C Menu Convention + +BMAD workflows use a fixed menu structure: + +| Option | Meaning | Behavior | +| ------ | -------------------- | ---------------------------------------------------- | +| **A** | Advanced Elicitation | Execute advancedElicitationTask, then redisplay menu | +| **P** | Party Mode | Execute partyModeWorkflow, then redisplay menu | +| **C** | Continue/Accept | Save output, update frontmatter, load nextStepFile | +| Other | Custom | Defined per step (e.g., F = Fix, X = Exit) | + +**Rules:** +- A and P MUST always be present +- C MUST be present except in final step (use X or similar for exit) +- After A/P → redisplay menu +- After C → proceed to next step +- Custom letters can be used for step-specific options + +--- + +## Progressive Disclosure + +**Core Principle:** Each step only knows about its immediate next step. + +### Implementation + +1. **Never pre-load future steps** - Only load `nextStepFile` when user selects [C] + +2. **Mode-aware routing** (for shared steps): + ```markdown + ## MODE-AWARE ROUTING: + ### If entered from CREATE mode: + Load ./s-next-step.md + + ### If entered from EDIT mode: + Load ./e-next-step.md + + ### If entered from VALIDATE mode: + Load ./v-next-step.md + ``` + +3. **Read tracking file first** - Always read the tracking file (agentPlan, validationReport, etc.) to determine current mode and routing + +--- + +## Mode-Aware Routing (Shared Steps) + +Shared steps (`s-*.md`) must route based on the mode stored in the tracking file. + +### Tracking File Frontmatter + +```yaml +--- +mode: create # or edit | validate +stepsCompleted: + - c-01-brainstorm.md + - s-01-discovery.md +# ... other tracking fields +--- +``` + +### Routing Implementation + +```markdown +## COMPLETION ROUTING: + +1. Append `./this-step-name.md` to {trackingFile}.stepsCompleted +2. Save content to {trackingFile} +3. Read {trackingFile}.mode +4. Route based on mode: + +### IF mode == create: +Load ./s-next-create-step.md + +### IF mode == edit: +Load ./e-next-edit-step.md + +### IF mode == validate: +Load ./s-next-validate-step.md +``` + +--- + +## File Naming Conventions + +### Tri-Modal Workflows + +| Prefix | Meaning | Example | +| ------ | ------------------ | ---------------------- | +| `c-` | Create-specific | `c-01-brainstorm.md` | +| `e-` | Edit-specific | `e-01-load-analyze.md` | +| `v-` | Validate-specific | `v-01-load-review.md` | +| `s-` | Shared by 2+ modes | `s-05-activation.md` | + +### Numbering + +- Within each prefix type, number sequentially +- Restart numbering for each prefix type (c-01, e-01, v-01, s-01) +- Use letters for sub-steps (s-06a, s-06b, s-06c) + +--- + +## Language Preference Enforcement + +**CRITICAL:** Every step MUST respect the user's chosen language. + +### Implementation + +```markdown +### Language Preference: +The user has chosen to communicate in the **{language}** language. +You MUST respond in **{language}** throughout this step. +``` + +### Reading Language Preference + +From tracking file frontmatter: +```yaml +--- +userPreferences: + language: spanish # or any language +--- +``` + +### Rules + +- **MUST** read language preference from tracking file at step start +- **MUST** respond in user's chosen language for ALL content +- **MUST** include menu options in user's chosen language +- **EXCEPTION:** Technical terms, file names, and code remain in English + +--- + +## Data File References + +When step content becomes too large (>200 lines), extract to `/data/` files: + +### When to Extract + +- Step file exceeds 200 lines +- Content is reference material (rules, examples, patterns) +- Content is reused across multiple steps + +### How to Reference + +```markdown +## Reference Material: + +Load and reference: `../data/{data-file-name}.md` + +Key points from that file: +- [Point 1] +- [Point 2] +``` + +### Data File Best Practices + +- Keep data files focused on single topic +- Use clear, descriptive names +- Include examples and non-examples +- Optimize for LLM usage (concise, structured) + +--- + +## Common Pitfalls to Avoid + +### ❌ DON'T: + +- Pre-load future steps (violates progressive disclosure) +- Exceed 250 lines without splitting +- Forget to update `stepsCompleted` array +- Ignore user's language preference +- Skip mode checking in shared steps +- Use vague menu option letters (stick to A/P/C plus 1-2 custom) + +### ✅ DO: + +- Keep files under 200 lines +- Read tracking file first thing +- Route based on `mode` field +- Include A/P in every menu +- Use descriptive step names +- Extract complex content to data files + +--- + +## Template: New Step File + +```markdown +--- +name: 'step-name' +description: 'What this step does' + +# File References +thisStepFile: ./step-name.md +workflowFile: ../workflow.md +outputFile: {bmb_creations_output_folder}/output.md + +# Task References +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Step X: [Step Name] + +## STEP GOAL: + +[Single sentence goal] + +### Role Reinforcement: + +- ✅ You are a [role] who [does what] +- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring [expertise], user brings [expertise], together we [achieve] +- ✅ Maintain [tone] throughout + +### Language Preference: +The user has chosen to communicate in the **{language}** language. +You MUST respond in **{language}** throughout this step. + +### Step-Specific Rules: + +- 🎯 Focus only on [scope] +- 🚫 FORBIDDEN to [prohibited action] +- 💬 Approach: [how to engage] +- 📋 Ensure [outcome] + +## EXECUTION PROTOCOLS: + +- [Action 1] +- [Action 2] +- 🚫 FORBIDDEN to [prohibited action] + +## CONTEXT BOUNDARIES: + +- Available context: [what's available] +- Focus: [what to focus on] +- Limits: [boundaries] +- Dependencies: [what depends on what] + +## Sequence of Instructions: + +### 1. [First Action] + +**Description of first action** + +### 2. [Second Action] + +**Description of second action** + +... + +### X. Present MENU OPTIONS + +Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue" + +#### Menu Handling Logic: +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options) + +#### EXECUTION RULES: +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE +ONLY WHEN [C continue option] is selected and [conditions], will you then load and read fully `{nextStepFile}`... + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: +- [Success criteria] + +### ❌ SYSTEM FAILURE: +- [Failure criteria] + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. +``` + +--- + +**End of Guidelines** diff --git a/src/modules/bmb/workflows/create-agent/data/agent-compilation.md b/src/modules/bmb/workflows/agent/data/agent-compilation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/agent-compilation.md rename to src/modules/bmb/workflows/agent/data/agent-compilation.md diff --git a/src/modules/bmb/workflows/create-agent/data/agent-menu-patterns.md b/src/modules/bmb/workflows/agent/data/agent-menu-patterns.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/agent-menu-patterns.md rename to src/modules/bmb/workflows/agent/data/agent-menu-patterns.md diff --git a/src/modules/bmb/workflows/create-agent/data/agent-metadata.md b/src/modules/bmb/workflows/agent/data/agent-metadata.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/agent-metadata.md rename to src/modules/bmb/workflows/agent/data/agent-metadata.md diff --git a/src/modules/bmb/workflows/create-agent/data/brainstorm-context.md b/src/modules/bmb/workflows/agent/data/brainstorm-context.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/brainstorm-context.md rename to src/modules/bmb/workflows/agent/data/brainstorm-context.md diff --git a/src/modules/bmb/workflows/create-agent/data/communication-presets.csv b/src/modules/bmb/workflows/agent/data/communication-presets.csv similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/communication-presets.csv rename to src/modules/bmb/workflows/agent/data/communication-presets.csv diff --git a/src/modules/bmb/workflows/create-agent/data/critical-actions.md b/src/modules/bmb/workflows/agent/data/critical-actions.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/critical-actions.md rename to src/modules/bmb/workflows/agent/data/critical-actions.md diff --git a/src/modules/bmb/workflows/create-agent/data/expert-agent-architecture.md b/src/modules/bmb/workflows/agent/data/expert-agent-architecture.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/expert-agent-architecture.md rename to src/modules/bmb/workflows/agent/data/expert-agent-architecture.md diff --git a/src/modules/bmb/workflows/create-agent/data/expert-agent-validation.md b/src/modules/bmb/workflows/agent/data/expert-agent-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/expert-agent-validation.md rename to src/modules/bmb/workflows/agent/data/expert-agent-validation.md diff --git a/src/modules/bmb/workflows/create-agent/data/module-agent-validation.md b/src/modules/bmb/workflows/agent/data/module-agent-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/module-agent-validation.md rename to src/modules/bmb/workflows/agent/data/module-agent-validation.md diff --git a/src/modules/bmb/workflows/create-agent/data/persona-properties.md b/src/modules/bmb/workflows/agent/data/persona-properties.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/persona-properties.md rename to src/modules/bmb/workflows/agent/data/persona-properties.md diff --git a/src/modules/bmb/workflows/create-agent/data/principles-crafting.md b/src/modules/bmb/workflows/agent/data/principles-crafting.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/principles-crafting.md rename to src/modules/bmb/workflows/agent/data/principles-crafting.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md b/src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md rename to src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md b/src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md rename to src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md b/src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md rename to src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md b/src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md rename to src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md b/src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md rename to src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml b/src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml rename to src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.agent.yaml b/src/modules/bmb/workflows/agent/data/reference/module-examples/architect.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.agent.yaml rename to src/modules/bmb/workflows/agent/data/reference/module-examples/architect.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.md b/src/modules/bmb/workflows/agent/data/reference/module-examples/architect.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/module-examples/architect.md rename to src/modules/bmb/workflows/agent/data/reference/module-examples/architect.md diff --git a/src/modules/bmb/workflows/create-agent/data/reference/module-examples/security-engineer.agent.yaml b/src/modules/bmb/workflows/agent/data/reference/module-examples/security-engineer.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/module-examples/security-engineer.agent.yaml rename to src/modules/bmb/workflows/agent/data/reference/module-examples/security-engineer.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/reference/module-examples/trend-analyst.agent.yaml b/src/modules/bmb/workflows/agent/data/reference/module-examples/trend-analyst.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/module-examples/trend-analyst.agent.yaml rename to src/modules/bmb/workflows/agent/data/reference/module-examples/trend-analyst.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml b/src/modules/bmb/workflows/agent/data/reference/simple-examples/commit-poet.agent.yaml similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/reference/simple-examples/commit-poet.agent.yaml rename to src/modules/bmb/workflows/agent/data/reference/simple-examples/commit-poet.agent.yaml diff --git a/src/modules/bmb/workflows/create-agent/data/simple-agent-architecture.md b/src/modules/bmb/workflows/agent/data/simple-agent-architecture.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/simple-agent-architecture.md rename to src/modules/bmb/workflows/agent/data/simple-agent-architecture.md diff --git a/src/modules/bmb/workflows/create-agent/data/simple-agent-validation.md b/src/modules/bmb/workflows/agent/data/simple-agent-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/simple-agent-validation.md rename to src/modules/bmb/workflows/agent/data/simple-agent-validation.md diff --git a/src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md b/src/modules/bmb/workflows/agent/data/understanding-agent-types.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/data/understanding-agent-types.md rename to src/modules/bmb/workflows/agent/data/understanding-agent-types.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md b/src/modules/bmb/workflows/agent/steps-c/step-01-brainstorm.md similarity index 97% rename from src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md rename to src/modules/bmb/workflows/agent/steps-c/step-01-brainstorm.md index b245a882..7a7c6bac 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md +++ b/src/modules/bmb/workflows/agent/steps-c/step-01-brainstorm.md @@ -3,7 +3,7 @@ name: 'step-01-brainstorm' description: 'Optional brainstorming for agent ideas' # File References -nextStepFile: '{project-root}/src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md' +nextStepFile: './step-02-discovery.md' brainstormContext: ../data/brainstorm-context.md brainstormWorkflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md' --- diff --git a/src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md b/src/modules/bmb/workflows/agent/steps-c/step-02-discovery.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-02-discovery.md rename to src/modules/bmb/workflows/agent/steps-c/step-02-discovery.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-03-type-metadata.md b/src/modules/bmb/workflows/agent/steps-c/step-03-type-metadata.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-03-type-metadata.md rename to src/modules/bmb/workflows/agent/steps-c/step-03-type-metadata.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-04-persona.md b/src/modules/bmb/workflows/agent/steps-c/step-04-persona.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-04-persona.md rename to src/modules/bmb/workflows/agent/steps-c/step-04-persona.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-05-commands-menu.md b/src/modules/bmb/workflows/agent/steps-c/step-05-commands-menu.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-05-commands-menu.md rename to src/modules/bmb/workflows/agent/steps-c/step-05-commands-menu.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-06-activation.md b/src/modules/bmb/workflows/agent/steps-c/step-06-activation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-06-activation.md rename to src/modules/bmb/workflows/agent/steps-c/step-06-activation.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-07a-build-simple.md b/src/modules/bmb/workflows/agent/steps-c/step-07a-build-simple.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-07a-build-simple.md rename to src/modules/bmb/workflows/agent/steps-c/step-07a-build-simple.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-07b-build-expert.md b/src/modules/bmb/workflows/agent/steps-c/step-07b-build-expert.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-07b-build-expert.md rename to src/modules/bmb/workflows/agent/steps-c/step-07b-build-expert.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-07c-build-module.md b/src/modules/bmb/workflows/agent/steps-c/step-07c-build-module.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-07c-build-module.md rename to src/modules/bmb/workflows/agent/steps-c/step-07c-build-module.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08a-plan-traceability.md b/src/modules/bmb/workflows/agent/steps-c/step-08a-plan-traceability.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-08a-plan-traceability.md rename to src/modules/bmb/workflows/agent/steps-c/step-08a-plan-traceability.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08b-metadata-validation.md b/src/modules/bmb/workflows/agent/steps-c/step-08b-metadata-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-08b-metadata-validation.md rename to src/modules/bmb/workflows/agent/steps-c/step-08b-metadata-validation.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08c-persona-validation.md b/src/modules/bmb/workflows/agent/steps-c/step-08c-persona-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-08c-persona-validation.md rename to src/modules/bmb/workflows/agent/steps-c/step-08c-persona-validation.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08d-menu-validation.md b/src/modules/bmb/workflows/agent/steps-c/step-08d-menu-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-08d-menu-validation.md rename to src/modules/bmb/workflows/agent/steps-c/step-08d-menu-validation.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08e-structure-validation.md b/src/modules/bmb/workflows/agent/steps-c/step-08e-structure-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-08e-structure-validation.md rename to src/modules/bmb/workflows/agent/steps-c/step-08e-structure-validation.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-08f-sidecar-validation.md b/src/modules/bmb/workflows/agent/steps-c/step-08f-sidecar-validation.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-08f-sidecar-validation.md rename to src/modules/bmb/workflows/agent/steps-c/step-08f-sidecar-validation.md diff --git a/src/modules/bmb/workflows/create-agent/steps/step-09-celebrate.md b/src/modules/bmb/workflows/agent/steps-c/step-09-celebrate.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/steps/step-09-celebrate.md rename to src/modules/bmb/workflows/agent/steps-c/step-09-celebrate.md diff --git a/src/modules/bmb/workflows/agent/steps-e/e-01-load-existing.md b/src/modules/bmb/workflows/agent/steps-e/e-01-load-existing.md new file mode 100644 index 00000000..c48ba191 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-01-load-existing.md @@ -0,0 +1,214 @@ +--- +name: 'e-01-load-existing' +description: 'Load and analyze existing agent for editing' + +# File References +thisStepFile: ./e-01-load-existing.md +workflowFile: ../workflow.md +nextStepFile: './e-02-discover-edits.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentMetadata: ../data/agent-metadata.md +agentMenuPatterns: ../data/agent-menu-patterns.md + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 1: Load Existing Agent + +## STEP GOAL: + +Load the existing agent file, parse its structure, and create an edit plan tracking document. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER proceed without loading the complete agent file +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not an autonomous editor +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Role Reinforcement: + +- ✅ You are an agent analyst who helps users understand and modify existing agents +- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring agent architecture expertise, user brings their modification goals, together we achieve successful edits +- ✅ Maintain collaborative analytical tone throughout + +### Step-Specific Rules: + +- 🎯 Focus only on loading and analyzing the existing agent +- 🚫 FORBIDDEN to make any modifications in this step +- 💬 Approach: Analytical and informative, present findings clearly +- 📋 Ensure edit plan is created with complete agent snapshot + +## EXECUTION PROTOCOLS: + +- 🎯 Load the complete agent YAML file +- 📊 Parse and analyze all agent components +- 💾 Create edit plan tracking document +- 🚫 FORBIDDEN to proceed without confirming file loaded successfully + +## CONTEXT BOUNDARIES: + +- Available context: User provided agent file path from workflow +- Focus: Load and understand the existing agent structure +- Limits: Analysis only, no modifications +- Dependencies: Agent file must exist and be valid YAML + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Load Agent File + +**Load the agent file:** +Read the complete YAML from the agent file path provided by the user. + +**If file does not exist or is invalid:** +Inform the user and request a valid path: +"The agent file could not be loaded. Please verify the path and try again. + +Expected format: `{path-to-agent}/{agent-name}.agent.yaml`" + +### 2. Parse Agent Structure + +**Extract and categorize all agent components:** + +```yaml +# Basic Metadata +- name: {agent-name} +- description: {agent-description} +- type: {simple|expert|module} +- version: {version} + +# Persona +- persona: {full persona text} +- system-context: {if present} + +# Commands/Menu +- commands: {full command structure} + +# Critical Actions (if present) +- critical-actions: {list} + +# Metadata +- metadata: {all metadata fields} +``` + +### 3. Display Agent Summary + +**Present a clear summary to the user:** + +```markdown +## Agent Analysis: {agent-name} + +**Type:** {simple|expert|module} +**Version:** {version} +**Status:** ready-for-edit + +### Current Structure: + +**Persona:** {character count} characters +**Commands:** {count} commands defined +**Critical Actions:** {count} critical actions + +### Editable Components: + +- [ ] Persona (role, identity, communication_style, principles) +- [ ] Commands and menu structure +- [ ] Critical actions +- [ ] Metadata (name, description, version, tags) +``` + +### 4. Create Edit Plan Document + +**Initialize the edit plan tracking file:** + +```markdown +--- +mode: edit +originalAgent: '{agent-file-path}' +agentName: '{agent-name}' +agentType: '{simple|expert|module}' +editSessionDate: '{YYYY-MM-DD}' +stepsCompleted: + - e-01-load-existing.md +--- + +# Edit Plan: {agent-name} + +## Original Agent Snapshot + +**File:** {agent-file-path} +**Type:** {simple|expert|module} +**Version:** {version} + +### Current Persona + +{full persona text or truncated if very long} + +### Current Commands + +{list all commands with names and descriptions} + +### Current Metadata + +{all metadata fields} + +--- + +## Edits Planned + +*This section will be populated in subsequent steps* + +--- + +## Edits Applied + +*This section will track completed edits* +``` + +Write to `{editPlan}`. + +### 5. Present MENU OPTIONS + +Display: "**Is this the correct agent to edit?** [C] Yes, Continue to Discovery" + +#### Menu Handling Logic: + +- IF C: Save content to {editPlan}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [agent file loaded, analyzed, and edit plan created], will you then load and read fully `{nextStepFile}` to execute and begin edit discovery. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Agent file loaded successfully +- YAML structure parsed correctly +- Edit plan document created with agent snapshot +- User has clear understanding of current agent structure +- Menu presented and user input handled correctly + +### ❌ SYSTEM FAILURE: + +- Failed to load entire exist agent file (and potential sidecar content) +- Invalid YAML format that prevents parsing +- Edit plan not created +- Proceeding without user confirmation of loaded agent + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-02-discover-edits.md b/src/modules/bmb/workflows/agent/steps-e/e-02-discover-edits.md new file mode 100644 index 00000000..dd2889c7 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-02-discover-edits.md @@ -0,0 +1,191 @@ +--- +name: 'e-02-discover-edits' +description: 'Discover what user wants to change about the agent' + +nextStepFile: './e-03a-validate-metadata.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 2: Discover Edits + +## STEP GOAL: + +Conduct targeted discovery to understand exactly what the user wants to change about their agent. Document all requested edits in structured format. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER assume what edits are needed - ask explicitly +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan first to understand agent context +- 📋 YOU ARE A FACILITATOR, not an autonomous editor +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Role Reinforcement: + +- ✅ You are an agent editor consultant who helps users clarify their modification goals +- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring agent architecture expertise, user brings their vision for improvements, together we define precise edits +- ✅ Maintain collaborative inquisitive tone throughout + +### Step-Specific Rules: + +- 🎯 Focus only on discovering what to edit, not how to implement yet +- 🚫 FORBIDDEN to make any modifications in this step +- 💬 Approach: Ask probing questions to understand edit scope +- 📋 Ensure all edits are documented to edit plan before proceeding + +## EXECUTION PROTOCOLS: + +- 🎯 Guide conversation to uncover all desired changes +- 📊 Categorize edits by component (persona, commands, metadata, etc.) +- 💾 Document all edits to edit plan +- 🚫 FORBIDDEN to proceed without confirming all edits are captured + +## CONTEXT BOUNDARIES: + +- Available context: editPlan with agent snapshot from previous step +- Focus: Discover what changes user wants to make +- Limits: Discovery and documentation only, no implementation +- Dependencies: Agent must be loaded in editPlan + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Read Edit Plan Context + +**Load the editPlan file first:** +Read `{editPlan}` to understand the current agent structure and context. + +### 2. Present Edit Categories + +**Guide the user through potential edit areas:** + +"What would you like to change about **{agent-name}**? + +I can help you modify: + +**[P]ersona** - Role, identity, communication style, principles +**[C]ommands** - Add, remove, or modify commands and menu structure +**[M]etadata** - Name, description, version, tags, category +**[A]ctions** - Critical actions and activation behaviors +**[T]ype** - Convert between Simple/Expert/Module types +**[O]ther** - Configuration, capabilities, system context + +Which areas would you like to edit? (You can select multiple)" + +### 3. Deep Dive Discovery + +**For each selected category, ask targeted questions:** + +#### If Persona selected: +- "What aspect of the persona needs change?" +- "Should the role be more specific or expanded?" +- "Is the communication style hitting the right tone?" +- "Do the principles need refinement?" + +#### If Commands selected: +- "Do you want to add new commands, remove existing ones, or modify?" +- "Are current command names and descriptions clear?" +- "Should command steps be adjusted?" +- "Is the menu structure working well?" + +#### If Metadata selected: +- "What metadata fields need updating?" +- "Is the description accurate and compelling?" +- "Should version be bumped?" +- "Are tags still relevant?" + +#### If Actions selected: +- "What critical actions need modification?" +- "Should new activation behaviors be added?" +- "Are current actions executing as expected?" + +#### If Type conversion selected: +- "What type are you converting from/to?" +- "What's driving this conversion?" +- "Are you aware of the implications (e.g., Expert needs sidecar)?" + +### 4. Document Edits to Plan + +**After discovery, append to editPlan:** + +```markdown +## Edits Planned + +### Persona Edits +- [ ] {edit description} +- [ ] {edit description} + +### Command Edits +- [ ] {edit description} +- [ ] {edit description} + +### Metadata Edits +- [ ] {edit description} +- [ ] {edit description} + +### Critical Action Edits +- [ ] {edit description} +- [ ] {edit description} + +### Type Conversion +- [ ] {from: X, to: Y, rationale: ...} + +### Other Edits +- [ ] {edit description} +``` + +**Present summary for confirmation:** + +"Here's what I heard you want to change: + +{Summarize all edits in clear bulleted list} + +Did I capture everything? Any edits to add, remove, or clarify?" + +### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Validation" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save edits to {editPlan}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [all edits documented and confirmed by user], will you then load and read fully `{nextStepFile}` to execute and begin validation. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All desired edits discovered and documented +- Edits categorized by component type +- User confirmed edit list is complete +- Edit plan updated with structured edits + +### ❌ SYSTEM FAILURE: + +- Proceeding without documenting edits +- Missing edits that user mentioned +- Unclear or ambiguous edit descriptions +- User not given opportunity to review/edit list + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-03a-validate-metadata.md b/src/modules/bmb/workflows/agent/steps-e/e-03a-validate-metadata.md new file mode 100644 index 00000000..bbf1aabe --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-03a-validate-metadata.md @@ -0,0 +1,78 @@ +--- +name: 'e-03a-validate-metadata' +description: 'Validate metadata (before edit) - no menu, auto-advance' + +nextStepFile: './e-03b-validate-persona.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentMetadata: ../data/agent-metadata.md +--- + +# Edit Step 3a: Validate Metadata (Before Edit) + +## STEP GOAL: + +Validate the agent's metadata properties against BMAD standards. Record findings to editPlan and auto-advance to next validation step. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and agentMetadata first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate metadata against agentMetadata.md rules +- 📊 Record findings to editPlan frontmatter +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMetadata.md reference +- 📊 Validate all metadata fields +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentMetadata}` to understand validation rules. +Read `{editPlan}` to get agent file path and metadata. + +### 2. Validate Metadata + +Perform checks on: +- **id**: kebab-case, no spaces +- **name**: display name, clear branding +- **title**: concise function description +- **icon**: appropriate emoji or symbol +- **module**: correct format `{project}:{type}:{name}` +- **hasSidecar**: boolean, matches actual sidecar usage + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml +validationBefore: + metadata: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +When validation complete, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All metadata checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to persona validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-03b-validate-persona.md b/src/modules/bmb/workflows/agent/steps-e/e-03b-validate-persona.md new file mode 100644 index 00000000..478ffb45 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-03b-validate-persona.md @@ -0,0 +1,76 @@ +--- +name: 'e-03b-validate-persona' +description: 'Validate persona (before edit) - no menu, auto-advance' + +nextStepFile: './e-03c-validate-menu.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +--- + +# Edit Step 3b: Validate Persona (Before Edit) + +## STEP GOAL: + +Validate the agent's persona fields against BMAD standards. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and persona references first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate persona four-field system +- 📊 Record findings to editPlan frontmatter +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load personaProperties.md and principlesCrafting.md +- 📊 Validate persona fields +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{personaProperties}` and `{principlesCrafting}`. +Read `{editPlan}` to get agent file path and persona. + +### 2. Validate Persona + +Perform checks on: +- **role**: present, specific, not generic +- **identity**: present, defines who agent is +- **communication_style**: present, speech patterns only (no behavioral words) +- **principles**: present, first principle activates expert knowledge, not generic duties + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + persona: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +When validation complete, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All persona checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to menu validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-03c-validate-menu.md b/src/modules/bmb/workflows/agent/steps-e/e-03c-validate-menu.md new file mode 100644 index 00000000..4fff43b5 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-03c-validate-menu.md @@ -0,0 +1,75 @@ +--- +name: 'e-03c-validate-menu' +description: 'Validate menu structure (before edit) - no menu, auto-advance' + +nextStepFile: './e-03d-validate-structure.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentMenuPatterns: ../data/agent-menu-patterns.md +--- + +# Edit Step 3c: Validate Menu (Before Edit) + +## STEP GOAL: + +Validate the agent's command menu structure against BMAD standards. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and agentMenuPatterns first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate command/menu structure +- 📊 Record findings to editPlan frontmatter +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMenuPatterns.md reference +- 📊 Validate commands and menu +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentMenuPatterns}`. +Read `{editPlan}` to get agent file path and commands. + +### 2. Validate Menu + +Perform checks on: +- **A/P/C convention**: each menu has Advanced Elicitation, Party Mode, Continue +- **Command names**: clear, descriptive +- **Command descriptions**: specific, actionable +- **Menu handling logic**: properly specified + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + menu: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +When validation complete, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All menu checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to structure validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-03d-validate-structure.md b/src/modules/bmb/workflows/agent/steps-e/e-03d-validate-structure.md new file mode 100644 index 00000000..f2dbbd97 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-03d-validate-structure.md @@ -0,0 +1,75 @@ +--- +name: 'e-03d-validate-structure' +description: 'Validate YAML structure (before edit) - no menu, auto-advance' + +nextStepFile: './e-03e-validate-sidecar.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentCompilation: ../data/agent-compilation.md +--- + +# Edit Step 3d: Validate Structure (Before Edit) + +## STEP GOAL: + +Validate the agent's YAML structure and completeness. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and agentCompilation first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate YAML structure and required fields +- 📊 Record findings to editPlan frontmatter +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentCompilation.md reference +- 📊 Validate YAML structure +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentCompilation}`. +Read `{editPlan}` to get agent file path. + +### 2. Validate Structure + +Perform checks on: +- **YAML syntax**: valid, no parse errors +- **Required fields**: name, description, type, persona present +- **Field types**: arrays where expected, strings where expected +- **Indentation**: consistent 2-space indentation + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + structure: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +When validation complete, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All structure checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to sidecar validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-03e-validate-sidecar.md b/src/modules/bmb/workflows/agent/steps-e/e-03e-validate-sidecar.md new file mode 100644 index 00000000..3bdb0ac1 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-03e-validate-sidecar.md @@ -0,0 +1,78 @@ +--- +name: 'e-03e-validate-sidecar' +description: 'Validate sidecar structure (before edit) - no menu, auto-advance' + +nextStepFile: './e-03f-validation-summary.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +expertValidation: ../data/expert-agent-validation.md +--- + +# Edit Step 3e: Validate Sidecar (Before Edit) + +## STEP GOAL: + +Validate the agent's sidecar structure if Expert type. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and expertValidation first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate sidecar structure for Expert agents +- 📊 Record findings to editPlan frontmatter +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load expertValidation.md reference +- 📊 Validate sidecar if Expert type, skip for Simple/Module +- 💾 Record findings to editPlan +- ➡️ Auto-advance to validation summary when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{expertValidation}`. +Read `{editPlan}` to get agent type. + +### 2. Conditional Validation + +**IF agentType == expert:** +- Check metadata.sidecar-folder is present +- Check sidecar-path is correct format +- Verify sidecar files exist at specified path + +**IF agentType != expert:** +- Mark as N/A (not applicable) +- Skip detailed checks + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + sidecar: + status: [pass|fail|warning|n/a] + findings: + - {check}: [pass|fail|n/a] + - {check}: [pass|fail|n/a] +``` + +### 4. Auto-Advance + +When validation complete, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ Sidecar checks performed (or N/A recorded) +✅ Findings saved to editPlan +✅ Auto-advanced to validation summary + +--- + +**Auto-advancing to validation summary...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-03f-validation-summary.md b/src/modules/bmb/workflows/agent/steps-e/e-03f-validation-summary.md new file mode 100644 index 00000000..43a91fb0 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-03f-validation-summary.md @@ -0,0 +1,119 @@ +--- +name: 'e-03f-validation-summary' +description: 'Display all validation findings before edit' + +nextStepFile: './e-04-type-metadata.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 3f: Validation Summary (Before Edit) + +## STEP GOAL: + +Display all validation findings from the previous 5 validation steps to the user. Present findings clearly and await confirmation to proceed. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan to collect all validation findings +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Display all validation findings clearly organized +- 📊 Aggregate findings from all 5 validation steps +- 💬 Present options for handling any issues found + +## EXECUTION PROTOCOLS: + +- 🎯 Read editPlan to get validation findings +- 📊 Display organized summary +- 💾 Allow user to decide how to proceed +- ➡️ Proceed to edit plan on [C] + +## Sequence of Instructions: + +### 1. Load Validation Findings + +Read `{editPlan}` frontmatter to collect: +- validationBefore.metadata.status and findings +- validationBefore.persona.status and findings +- validationBefore.menu.status and findings +- validationBefore.structure.status and findings +- validationBefore.sidecar.status and findings + +### 2. Display Validation Summary + +```markdown +## Pre-Edit Validation Report for {agent-name} + +### Metadata Validation +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} +{Findings summary} + +### Persona Validation +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} +{Findings summary} + +### Menu Validation +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} +{Findings summary} + +### Structure Validation +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} +{Findings summary} + +### Sidecar Validation +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL / N/A} +{Findings summary} +``` + +### 3. Present Options + +"How would you like to proceed? + +**[I**ntegrate fixes**] - Add validation fixes to your edit plan +**[S]kip** - Proceed with your planned edits only +**[A]dvanced** - Deeper exploration of any issues" + +### 4. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Edit Plan" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF I: Add validation fixes to editPlan, then redisplay menu +- IF C: Save validation summary to {editPlan}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation summary displayed], will you then load and read fully `{nextStepFile}` to execute and begin edit planning. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All validation findings displayed clearly +- User given options for handling issues +- Validation summary saved to editPlan + +### ❌ SYSTEM FAILURE: + +- Findings not displayed to user +- Proceeding without user acknowledgment + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-04-type-metadata.md b/src/modules/bmb/workflows/agent/steps-e/e-04-type-metadata.md new file mode 100644 index 00000000..d7d37a52 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-04-type-metadata.md @@ -0,0 +1,122 @@ +--- +name: 'e-04-type-metadata' +description: 'Review and plan metadata edits' + +nextStepFile: './e-05-persona.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentMetadata: ../data/agent-metadata.md +agentTypesDoc: ../data/understanding-agent-types.md + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 4: Type and Metadata + +## STEP GOAL: + +Review the agent's type and metadata, and plan any changes. If edits involve type conversion, identify the implications. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Load agentMetadata and agentTypesDoc first +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Load reference documents before discussing edits +- 📊 Document type conversion requirements if applicable +- 💬 Focus on metadata that user wants to change + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMetadata.md and agentTypesDoc.md +- 📊 Review current metadata from editPlan +- 💾 Document planned metadata changes +- 🚫 FORBIDDEN to proceed without documenting changes + +## Sequence of Instructions: + +### 1. Load Reference Documents + +Read `{agentMetadata}` and `{agentTypesDoc}` to understand validation rules and type implications. + +### 2. Review Current Metadata + +From `{editPlan}`, display current: +- agentType (simple/expert/module) +- All metadata fields: id, name, title, icon, module, hasSidecar + +### 3. Discuss Metadata Edits + +If user wants metadata changes: + +**For type conversion:** +- "Converting from {current} to {target}" +- Explain implications (e.g., Simple → Expert requires sidecar) +- Update editPlan with type conversion + +**For metadata field changes:** +- id: kebab-case requirements +- name: display name conventions +- title: function description format +- icon: emoji/symbol +- module: path format +- hasSidecar: boolean implications + +### 4. Document to Edit Plan + +Append to `{editPlan}`: + +```yaml +metadataEdits: + typeConversion: + from: {current-type} + to: {target-type} + rationale: {explanation} + fieldChanges: + - field: {field-name} + from: {current-value} + to: {target-value} +``` + +### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Persona" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save to {editPlan}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [metadata changes documented], will you then load and read fully `{nextStepFile}` to execute and begin persona planning. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Reference documents loaded +- Metadata changes discussed and documented +- Type conversion implications understood +- Edit plan updated + +### ❌ SYSTEM FAILURE: + +- Proceeded without loading reference documents +- Type conversion without understanding implications +- Changes not documented to edit plan + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-05-persona.md b/src/modules/bmb/workflows/agent/steps-e/e-05-persona.md new file mode 100644 index 00000000..32b3cda7 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-05-persona.md @@ -0,0 +1,132 @@ +--- +name: 'e-05-persona' +description: 'Review and plan persona edits' + +nextStepFile: './e-06-commands-menu.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +communicationPresets: ../data/communication-presets.csv + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 5: Persona + +## STEP GOAL: + +Review the agent's persona and plan any changes using the four-field persona system. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Load personaProperties, principlesCrafting, communicationPresets first +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Load reference documents before discussing persona edits +- 📊 Maintain four-field system purity +- 💬 Focus on persona fields that user wants to change + +## EXECUTION PROTOCOLS: + +- 🎯 Load personaProperties.md, principlesCrafting.md, communicationPresets.csv +- 📊 Review current persona from editPlan +- 💾 Document planned persona changes +- 🚫 FORBIDDEN to proceed without documenting changes + +## Sequence of Instructions: + +### 1. Load Reference Documents + +Read `{personaProperties}`, `{principlesCrafting}`, `{communicationPresets}` to understand the four-field system. + +### 2. Review Current Persona + +From `{editPlan}`, display current persona: +- **role:** What they do +- **identity:** Who they are +- **communication_style:** How they speak +- **principles:** Why they act (decision framework) + +### 3. Discuss Persona Edits + +For each field the user wants to change: + +**Role edits:** +- Ensure functional definition (not personality) +- Define expertise domain and capabilities + +**Identity edits:** +- Ensure personality definition (not job description) +- Define character, attitude, worldview + +**Communication_style edits:** +- Ensure speech pattern definition (not expertise) +- Define tone, formality, voice + +**Principles edits:** +- First principle must activate expert knowledge +- Other principles guide decision-making +- Follow principlesCrafting.md guidance + +### 4. Document to Edit Plan + +Append to `{editPlan}`: + +```yaml +personaEdits: + role: + from: {current} + to: {target} + identity: + from: {current} + to: {target} + communication_style: + from: {current} + to: {target} + principles: + from: {current} + to: {target} +``` + +### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Commands Menu" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save to {editPlan}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [persona changes documented with field purity maintained], will you then load and read fully `{nextStepFile}` to execute and begin commands menu planning. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Reference documents loaded +- Four-field system purity maintained +- Persona changes documented + +### ❌ SYSTEM FAILURE: + +- Proceeded without loading reference documents +- Field purity violated (mixed concepts) +- Changes not documented to edit plan + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-06-commands-menu.md b/src/modules/bmb/workflows/agent/steps-e/e-06-commands-menu.md new file mode 100644 index 00000000..37bad720 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-06-commands-menu.md @@ -0,0 +1,120 @@ +--- +name: 'e-06-commands-menu' +description: 'Review and plan command/menu edits' + +nextStepFile: './e-07-activation.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentMenuPatterns: ../data/agent-menu-patterns.md + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 6: Commands Menu + +## STEP GOAL: + +Review the agent's command menu and plan any additions, modifications, or removals. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Load agentMenuPatterns first +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Load agentMenuPatterns before discussing menu edits +- 📊 Follow A/P/C convention for menu structure +- 💬 Focus on commands that user wants to add/modify/remove + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMenuPatterns.md +- 📊 Review current commands from editPlan +- 💾 Document planned command changes +- 🚫 FORBIDDEN to proceed without documenting changes + +## Sequence of Instructions: + +### 1. Load Reference Documents + +Read `{agentMenuPatterns}` to understand menu structure requirements. + +### 2. Review Current Commands + +From `{editPlan}`, display current commands with: +- trigger +- description +- handler/action + +### 3. Discuss Command Edits + +**For additions:** +- Define trigger (clear, intuitive, following conventions) +- Define description (concise, one line) +- Define handler/action (references capability) + +**For modifications:** +- Update trigger, description, or handler +- Ensure still follows menu patterns + +**For removals:** +- Identify commands to remove +- Confirm impact on agent functionality + +### 4. Document to Edit Plan + +Append to `{editPlan}`: + +```yaml +commandEdits: + additions: + - trigger: {trigger} + description: {description} + handler: {handler} + modifications: + - command: {existing-command} + changes: {what-to-change} + removals: + - command: {command-to-remove} +``` + +### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Activation" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save to {editPlan}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [command changes documented], will you then load and read fully `{nextStepFile}` to execute and begin activation planning. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- agentMenuPatterns loaded +- Command changes documented with trigger/description/handler +- A/P/C convention followed + +### ❌ SYSTEM FAILURE: + +- Proceeded without loading reference documents +- Commands missing required elements +- Changes not documented to edit plan + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-07-activation.md b/src/modules/bmb/workflows/agent/steps-e/e-07-activation.md new file mode 100644 index 00000000..bd071a92 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-07-activation.md @@ -0,0 +1,122 @@ +--- +name: 'e-07-activation' +description: 'Review critical_actions and route to type-specific edit' + +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +criticalActions: ../data/critical-actions.md + +# Type-specific edit routes +simpleEdit: './e-08a-edit-simple.md' +expertEdit: './e-08b-edit-expert.md' +moduleEdit: './e-08c-edit-module.md' + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 7: Activation and Routing + +## STEP GOAL: + +Review critical_actions and route to the appropriate type-specific edit step (Simple/Expert/Module). + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Load criticalActions and editPlan first +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}}` + +### Step-Specific Rules: + +- 🎯 Load criticalActions.md before discussing activation +- 📊 Determine target type for routing +- 💬 Route based on POST-EDIT agent type + +## EXECUTION PROTOCOLS: + +- 🎯 Load criticalActions.md +- 📊 Check editPlan for target agent type +- 💾 Route to appropriate type-specific edit step +- ➡️ Auto-advance to type-specific edit on [C] + +## Sequence of Instructions: + +### 1. Load Reference Documents + +Read `{criticalActions}` and `{editPlan}` to understand: +- Current critical_actions (if any) +- Target agent type after edits + +### 2. Review Critical Actions + +If user wants to add/modify critical_actions: +- Reference patterns from criticalActions.md +- Define action name, description, invocation +- For Expert agents: specify sidecar-folder and file paths + +### 3. Determine Routing + +Check `{editPlan}` metadataEdits.typeConversion.to or current agentType: + +```yaml +agentType: simple → route to e-08a-edit-simple.md +agentType: expert → route to e-08b-edit-expert.md +agentType: module → route to e-08c-edit-module.md +``` + +### 4. Document to Edit Plan + +Append to `{editPlan}`: + +```yaml +activationEdits: + criticalActions: + additions: [] + modifications: [] +routing: + destinationEdit: {e-08a|e-08b|e-08c} + targetType: {simple|expert|module} +``` + +### 5. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Type-Specific Edit" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save to {editPlan}, determine routing based on targetType, then only then load and execute the appropriate type-specific edit step +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +This is the **ROUTING HUB** for edit flow. ONLY WHEN [C continue option] is selected and [routing determined], load and execute the appropriate type-specific edit step: + +- targetType: simple → e-08a-edit-simple.md +- targetType: expert → e-08b-edit-expert.md +- targetType: module → e-08c-edit-module.md + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- criticalActions.md loaded +- Routing determined based on target type +- Edit plan updated with routing info + +### ❌ SYSTEM FAILURE: + +- Proceeded without loading reference documents +- Routing not determined +- Wrong type-specific edit step selected + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-08a-edit-simple.md b/src/modules/bmb/workflows/agent/steps-e/e-08a-edit-simple.md new file mode 100644 index 00000000..d92bb27e --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-08a-edit-simple.md @@ -0,0 +1,134 @@ +--- +name: 'e-08a-edit-simple' +description: 'Apply edits to Simple agent' + +nextStepFile: './e-09a-validate-metadata.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentFile: '{original-agent-path}' +agentBackup: '{original-agent-path}.backup' + +# Template and Architecture +simpleTemplate: ../templates/simple-agent.template.md +simpleArch: ../data/simple-agent-architecture.md +agentCompilation: ../data/agent-compilation.md +agentMetadata: ../data/agent-metadata.md +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +agentMenuPatterns: ../data/agent-menu-patterns.md +criticalActions: ../data/critical-actions.md +--- + +# Edit Step 8a: Edit Simple Agent + +## STEP GOAL: + +Apply all planned edits to the Simple agent YAML file using templates and architecture references for validation. + +## MANDATORY EXECUTION RULES: + +- 🛑 ALWAYS create backup before modifying agent file +- 📖 CRITICAL: Read template and architecture files first +- 🔄 CRITICAL: Load editPlan and agentFile +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Load all reference files before applying edits +- 📊 Apply edits exactly as specified in editPlan +- 💾 Validate YAML after each edit +- ➡️ Auto-advance to post-edit validation when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load template, architecture, and data files +- 📊 Read editPlan to get all planned changes +- 💾 Create backup +- 📝 Apply edits: type conversion, metadata, persona, commands, critical_actions +- ✅ Validate YAML syntax +- ➡️ Auto-advance to next validation step + +## Sequence of Instructions: + +### 1. Load Reference Documents + +Read all files before editing: +- `{simpleTemplate}` - YAML structure reference +- `{simpleArch}` - Simple agent architecture +- `{agentCompilation}` - Assembly guidelines +- `{agentMetadata}`, `{personaProperties}`, `{principlesCrafting}` +- `{agentMenuPatterns}`, `{criticalActions}` + +### 2. Load Edit Plan and Agent + +Read `{editPlan}` to get all planned edits. +Read `{agentFile}` to get current agent YAML. + +### 3. Create Backup + +ALWAYS backup before editing: +`cp {agentFile} {agentBackup}` + +Confirm: "Backup created at: `{agentBackup}`" + +### 4. Apply Edits in Sequence + +For each planned edit: + +**Type Conversion:** +- Update `type:` field if converting +- Add/remove type-specific fields + +**Metadata Edits:** +- Apply each field change from metadataEdits + +**Persona Edits:** +- Replace persona section with new four-field persona +- Validate field purity (role ≠ identity ≠ communication_style) + +**Command Edits:** +- Additions: append to commands array +- Modifications: update specific commands +- Removals: remove from commands array + +**Critical Actions Edits:** +- Additions: append to critical_actions array +- Modifications: update specific actions +- Removals: remove from array + +### 5. Validate YAML After Each Edit + +Confirm YAML syntax is valid after each modification. + +### 6. Document Applied Edits + +Append to `{editPlan}`: + +```yaml +editsApplied: + - {edit-description} + - {edit-description} +backup: {agentBackup} +timestamp: {YYYY-MM-DD HH:MM} +``` + +### 7. Auto-Advance + +When all edits applied successfully, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ Backup created +✅ All reference files loaded +✅ All edits applied correctly +✅ YAML remains valid +✅ Edit plan tracking updated + +## FAILURE MODES + +❌ Backup failed +❌ YAML became invalid +❌ Edits not applied as specified + +--- + +**Auto-advancing to post-edit validation... diff --git a/src/modules/bmb/workflows/agent/steps-e/e-08b-edit-expert.md b/src/modules/bmb/workflows/agent/steps-e/e-08b-edit-expert.md new file mode 100644 index 00000000..394ccdb3 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-08b-edit-expert.md @@ -0,0 +1,117 @@ +--- +name: 'e-08b-edit-expert' +description: 'Apply edits to Expert agent' + +nextStepFile: './e-09a-validate-metadata.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentFile: '{original-agent-path}' +agentBackup: '{original-agent-path}.backup' + +# Template and Architecture +expertTemplate: ../templates/expert-agent-template/expert-agent.template.md +expertArch: ../data/expert-agent-architecture.md +agentCompilation: ../data/agent-compilation.md +agentMetadata: ../data/agent-metadata.md +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +agentMenuPatterns: ../data/agent-menu-patterns.md +criticalActions: ../data/critical-actions.md +expertValidation: ../data/expert-agent-validation.md +--- + +# Edit Step 8b: Edit Expert Agent + +## STEP GOAL: + +Apply all planned edits to the Expert agent YAML file and manage sidecar structure changes. + +## MANDATORY EXECUTION RULES: + +- 🛑 ALWAYS create backup before modifying agent file +- 📖 CRITICAL: Read template and architecture files first +- 🔄 CRITICAL: Load editPlan and agentFile +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Load all reference files before applying edits +- 📊 Manage sidecar structure for Expert agents +- 💾 Validate YAML and sidecar paths after edits +- ➡️ Auto-advance to post-edit validation when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load template, architecture, and data files +- 📊 Read editPlan to get all planned changes +- 💾 Create backup +- 📝 Apply edits including sidecar management +- ✅ Validate YAML and sidecar paths +- ➡️ Auto-advance to next validation step + +## Sequence of Instructions: + +### 1. Load Reference Documents + +Read all files before editing: +- `{expertTemplate}` - Expert YAML structure +- `{expertArch}` - Expert agent architecture +- `{agentCompilation}`, `{agentMetadata}`, `{personaProperties}`, `{principlesCrafting}` +- `{agentMenuPatterns}`, `{criticalActions}`, `{expertValidation}` + +### 2. Load Edit Plan and Agent + +Read `{editPlan}` to get all planned edits. +Read `{agentFile}` to get current agent YAML. + +### 3. Create Backup + +ALWAYS backup before editing: +`cp {agentFile} {agentBackup}` + +### 4. Apply Edits in Sequence + +**Type Conversion to Expert:** +- Update `type: expert` +- Add `metadata.sidecar-folder` if not present +- Create sidecar directory: `mkdir -p {project-root}/_bmad/_memory/{sidecar-folder}/` + +**Sidecar Management:** +- If changing sidecar-folder: update all critical_actions references +- If removing sidecar (Expert → Simple): remove sidecar fields and folder +- Create/update sidecar files as needed + +**Metadata, Persona, Commands, Critical Actions:** +- Same as Simple agent edit + +### 5. Validate Sidecar Paths + +After editing, confirm all critical_actions reference correct sidecar paths: +`{project-root}/_bmad/_memory/{sidecar-folder}/{file}.md` + +### 6. Document Applied Edits + +Append to `{editPlan}` with sidecar changes noted. + +### 7. Auto-Advance + +When all edits applied successfully, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ Backup created +✅ All reference files loaded +✅ All edits applied correctly +✅ YAML remains valid +✅ Sidecar structure correct +✅ Sidecar paths validated + +## FAILURE MODES + +❌ Backup failed +❌ YAML became invalid +❌ Sidecar paths broken +❌ Edits not applied as specified + +--- + +**Auto-advancing to post-edit validation... diff --git a/src/modules/bmb/workflows/agent/steps-e/e-08c-edit-module.md b/src/modules/bmb/workflows/agent/steps-e/e-08c-edit-module.md new file mode 100644 index 00000000..2ace3102 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-08c-edit-module.md @@ -0,0 +1,120 @@ +--- +name: 'e-08c-edit-module' +description: 'Apply edits to Module agent' + +nextStepFile: './e-09a-validate-metadata.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentFile: '{original-agent-path}' +agentBackup: '{original-agent-path}.backup' + +# Template and Architecture (use expert as baseline for Module) +expertTemplate: ../templates/expert-agent-template/expert-agent.template.md +expertArch: ../data/expert-agent-architecture.md +moduleArch: ../data/module-agent-validation.md +agentCompilation: ../data/agent-compilation.md +agentMetadata: ../data/agent-metadata.md +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +agentMenuPatterns: ../data/agent-menu-patterns.md +criticalActions: ../data/critical-actions.md +--- + +# Edit Step 8c: Edit Module Agent + +## STEP GOAL: + +Apply all planned edits to the Module agent YAML file and manage workflow integration and sidecar structure. + +## MANDATORY EXECUTION RULES: + +- 🛑 ALWAYS create backup before modifying agent file +- 📖 CRITICAL: Read template and architecture files first +- 🔄 CRITICAL: Load editPlan and agentFile +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Load all reference files before applying edits +- 📊 Manage workflow integration paths for Module agents +- 💾 Validate YAML and workflow paths after edits +- ➡️ Auto-advance to post-edit validation when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load template, architecture, and data files +- 📊 Read editPlan to get all planned changes +- 💾 Create backup +- 📝 Apply edits including workflow paths +- ✅ Validate YAML and workflow paths +- ➡️ Auto-advance to next validation step + +## Sequence of Instructions: + +### 1. Load Reference Documents + +Read all files before editing: +- `{expertTemplate}` - Module uses expert as baseline +- `{expertArch}`, `{moduleArch}` - Architecture references +- `{agentCompilation}`, `{agentMetadata}`, `{personaProperties}`, `{principlesCrafting}` +- `{agentMenuPatterns}`, `{criticalActions}` + +### 2. Load Edit Plan and Agent + +Read `{editPlan}` to get all planned edits. +Read `{agentFile}` to get current agent YAML. + +### 3. Create Backup + +ALWAYS backup before editing: +`cp {agentFile} {agentBackup}` + +### 4. Apply Edits in Sequence + +**Type Conversion to Module:** +- Update `type: module` +- Add workflow integration paths + +**Workflow Path Management:** +- Add: `skills: - workflow: {path}` +- Remove: delete workflow entries +- Modify: update workflow paths + +**Sidecar for Multi-Workflow Modules:** +- If 3+ workflows: consider sidecar creation +- Add sidecar configuration if needed + +**Metadata, Persona, Commands, Critical Actions:** +- Same as Expert agent edit + +### 5. Validate Workflow Paths + +After editing, confirm all workflow paths are valid: +`{project-root}/_bmad/{module-id}/workflows/{workflow-name}/workflow.md` + +### 6. Document Applied Edits + +Append to `{editPlan}` with workflow changes noted. + +### 7. Auto-Advance + +When all edits applied successfully, load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ Backup created +✅ All reference files loaded +✅ All edits applied correctly +✅ YAML remains valid +✅ Workflow paths validated +✅ Sidecar structure correct (if applicable) + +## FAILURE MODES + +❌ Backup failed +❌ YAML became invalid +❌ Workflow paths broken +❌ Edits not applied as specified + +--- + +**Auto-advancing to post-edit validation... diff --git a/src/modules/bmb/workflows/agent/steps-e/e-09a-validate-metadata.md b/src/modules/bmb/workflows/agent/steps-e/e-09a-validate-metadata.md new file mode 100644 index 00000000..21cbcc22 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-09a-validate-metadata.md @@ -0,0 +1,70 @@ +--- +name: 'e-09a-validate-metadata' +description: 'Validate metadata (after edit) - no menu, auto-advance' + +nextStepFile: './e-09b-validate-persona.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentMetadata: ../data/agent-metadata.md +--- + +# Edit Step 9a: Validate Metadata (After Edit) + +## STEP GOAL: + +Validate the agent's metadata properties after edits. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and agentMetadata first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate metadata against agentMetadata.md rules +- 📊 Record findings to editPlan frontmatter (validationAfter section) +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMetadata.md reference +- 📊 Validate all metadata fields +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentMetadata}` and `{editPlan}`. + +### 2. Validate Metadata + +Perform checks on id, name, title, icon, module, hasSidecar. + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml +validationAfter: + metadata: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All metadata checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to persona validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-09b-validate-persona.md b/src/modules/bmb/workflows/agent/steps-e/e-09b-validate-persona.md new file mode 100644 index 00000000..dac0a79b --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-09b-validate-persona.md @@ -0,0 +1,70 @@ +--- +name: 'e-09b-validate-persona' +description: 'Validate persona (after edit) - no menu, auto-advance' + +nextStepFile: './e-09c-validate-menu.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +--- + +# Edit Step 9b: Validate Persona (After Edit) + +## STEP GOAL: + +Validate the agent's persona after edits. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and persona references first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate persona four-field system +- 📊 Record findings to editPlan frontmatter (validationAfter section) +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load personaProperties.md and principlesCrafting.md +- 📊 Validate persona fields +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{personaProperties}`, `{principlesCrafting}`, and `{editPlan}`. + +### 2. Validate Persona + +Perform checks on role, identity, communication_style, principles. + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + persona: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All persona checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to menu validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-09c-validate-menu.md b/src/modules/bmb/workflows/agent/steps-e/e-09c-validate-menu.md new file mode 100644 index 00000000..d9944f43 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-09c-validate-menu.md @@ -0,0 +1,69 @@ +--- +name: 'e-09c-validate-menu' +description: 'Validate menu structure (after edit) - no menu, auto-advance' + +nextStepFile: './e-09d-validate-structure.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentMenuPatterns: ../data/agent-menu-patterns.md +--- + +# Edit Step 9c: Validate Menu (After Edit) + +## STEP GOAL: + +Validate the agent's command menu structure after edits. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and agentMenuPatterns first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate command/menu structure +- 📊 Record findings to editPlan frontmatter (validationAfter section) +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMenuPatterns.md reference +- 📊 Validate commands and menu +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentMenuPatterns}` and `{editPlan}`. + +### 2. Validate Menu + +Perform checks on A/P/C convention, command names, descriptions. + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + menu: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All menu checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to structure validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-09d-validate-structure.md b/src/modules/bmb/workflows/agent/steps-e/e-09d-validate-structure.md new file mode 100644 index 00000000..a52538e0 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-09d-validate-structure.md @@ -0,0 +1,69 @@ +--- +name: 'e-09d-validate-structure' +description: 'Validate YAML structure (after edit) - no menu, auto-advance' + +nextStepFile: './e-09e-validate-sidecar.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +agentCompilation: ../data/agent-compilation.md +--- + +# Edit Step 9d: Validate Structure (After Edit) + +## STEP GOAL: + +Validate the agent's YAML structure after edits. Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and agentCompilation first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate YAML structure and required fields +- 📊 Record findings to editPlan frontmatter (validationAfter section) +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentCompilation.md reference +- 📊 Validate YAML structure +- 💾 Record findings to editPlan +- ➡️ Auto-advance to next validation step when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentCompilation}` and `{editPlan}`. + +### 2. Validate Structure + +Perform checks on YAML syntax, required fields, field types, indentation. + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + structure: + status: [pass|fail|warning] + findings: + - {check}: [pass|fail] +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ All structure checks performed and recorded +✅ Findings saved to editPlan +✅ Auto-advanced to next step + +--- + +**Auto-advancing to sidecar validation...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-09e-validate-sidecar.md b/src/modules/bmb/workflows/agent/steps-e/e-09e-validate-sidecar.md new file mode 100644 index 00000000..4db7afc6 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-09e-validate-sidecar.md @@ -0,0 +1,70 @@ +--- +name: 'e-09e-validate-sidecar' +description: 'Validate sidecar structure (after edit) - no menu, auto-advance' + +nextStepFile: './e-09f-validation-summary.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' +expertValidation: ../data/expert-agent-validation.md +--- + +# Edit Step 9e: Validate Sidecar (After Edit) + +## STEP GOAL: + +Validate the agent's sidecar structure after edits (if Expert type). Record findings to editPlan and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan and expertValidation first +- 🚫 NO MENU in this step - record findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate sidecar structure for Expert agents +- 📊 Record findings to editPlan frontmatter (validationAfter section) +- 🚫 FORBIDDEN to present menu - auto-advance when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Load expertValidation.md reference +- 📊 Validate sidecar if Expert type, skip for Simple/Module +- 💾 Record findings to editPlan +- ➡️ Auto-advance to validation summary when complete + +## Sequence of Instructions: + +### 1. Load References + +Read `{expertValidation}` and `{editPlan}` to get agent type. + +### 2. Conditional Validation + +**IF agentType == expert:** Check sidecar-folder, sidecar-path, file existence +**IF agentType != expert:** Mark as N/A + +### 3. Record Findings + +Append to editPlan frontmatter: + +```yaml + sidecar: + status: [pass|fail|warning|n/a] + findings: + - {check}: [pass|fail|n/a] +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +## SUCCESS METRICS + +✅ Sidecar checks performed (or N/A recorded) +✅ Findings saved to editPlan +✅ Auto-advanced to validation summary + +--- + +**Auto-advancing to validation summary...** diff --git a/src/modules/bmb/workflows/agent/steps-e/e-09f-validation-summary.md b/src/modules/bmb/workflows/agent/steps-e/e-09f-validation-summary.md new file mode 100644 index 00000000..dfbba1d2 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-09f-validation-summary.md @@ -0,0 +1,111 @@ +--- +name: 'e-09f-validation-summary' +description: 'Display all validation findings after edit' + +nextStepFile: './e-10-celebrate.md' +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 9f: Validation Summary (After Edit) + +## STEP GOAL: + +Display all post-edit validation findings and compare with pre-edit state. Present findings and await confirmation to proceed to celebration. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan to collect all validation findings +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Display all validation findings clearly organized +- 📊 Compare before/after states +- 💬 Present options for handling any remaining issues + +## EXECUTION PROTOCOLS: + +- 🎯 Read editPlan to get validation findings +- 📊 Display organized summary with before/after comparison +- 💾 Allow user to decide how to proceed + +## Sequence of Instructions: + +### 1. Load Validation Findings + +Read `{editPlan}` frontmatter to collect validationBefore and validationAfter findings. + +### 2. Display Validation Summary + +```markdown +## Post-Edit Validation Report for {agent-name} + +### Before vs After Comparison + +| Component | Before | After | Status | +|-----------|--------|-------|--------| +| Metadata | {status} | {status} | {Δ} | +| Persona | {status} | {status} | {Δ} | +| Menu | {status} | {status} | {Δ} | +| Structure | {status} | {status} | {Δ} | +| Sidecar | {status} | {status} | {Δ} | + +### Detailed Findings (After Edit) + +**Metadata:** {summary} +**Persona:** {summary} +**Menu:** {summary} +**Structure:** {summary} +**Sidecar:** {summary} +``` + +### 3. Present Options + +"How do the edits look? + +**[R]eview** - Show detailed before/after for any component +**[F]ix** - Address any remaining issues +**[A]ccept** - Proceed to celebration" + +### 4. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Celebration" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF R: Show detailed before/after comparison, then redisplay menu +- IF C: Save validation summary to {editPlan}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [validation summary displayed], will you then load and read fully `{nextStepFile}` to execute and celebrate completion. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All validation findings displayed clearly +- Before/after comparison shown +- User given options for handling issues + +### ❌ SYSTEM FAILURE: + +- Findings not displayed to user +- Proceeding without user acknowledgment + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-e/e-10-celebrate.md b/src/modules/bmb/workflows/agent/steps-e/e-10-celebrate.md new file mode 100644 index 00000000..5486e16a --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-e/e-10-celebrate.md @@ -0,0 +1,150 @@ +--- +name: 'e-10-celebrate' +description: 'Celebrate successful agent edit completion' + +editPlan: '{bmb_creations_output_folder}/edit-plan-{agent-name}.md' + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Edit Step 10: Celebration + +## STEP GOAL: + +Celebrate the successful agent edit, provide summary of changes, and mark edit workflow completion. + +## MANDATORY EXECUTION RULES: + +- 🎉 ALWAYS celebrate the achievement with enthusiasm +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read editPlan to summarize what was accomplished +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Role Reinforcement: + +- ✅ You are a celebration coordinator who acknowledges successful agent improvements +- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring celebration energy, user brings their satisfaction, together we acknowledge successful collaboration + +### Step-Specific Rules: + +- 🎯 Focus on celebrating and summarizing what was accomplished +- 🚫 FORBIDDEN to end without marking workflow completion +- 💬 Approach: Enthusiastic while providing clear summary + +## EXECUTION PROTOCOLS: + +- 🎉 Celebrate the edit completion enthusiastically +- 📊 Provide clear summary of all changes made +- 💾 Mark workflow completion in edit plan +- 🚫 FORBIDDEN to end without proper completion marking + +## CONTEXT BOUNDARIES: + +- Available context: editPlan with full edit history +- Focus: Celebration and summary +- Limits: No more edits, only acknowledgment +- Dependencies: All edits successfully applied + +## Sequence of Instructions: + +### 1. Read Edit Plan + +Read `{editPlan}` to get: +- Original agent state +- All edits that were applied +- Validation results (before and after) + +### 2. Grand Celebration + +"🎉 **Excellent work!** Your agent **{agent-name}** has been successfully updated!" + +### 3. Edit Summary + +```markdown +## Edit Summary for {agent-name} + +**Completed:** {YYYY-MM-DD HH:MM} +**Edits Applied:** {count} + +### What Changed + +**Persona Updates:** {list or "None"} +**Command Updates:** {list or "None"} +**Metadata Updates:** {list or "None"} +**Type Conversion:** {details or "None"} + +### Validation Results + +**Before:** {summary of pre-edit validation} +**After:** {summary of post-edit validation} +``` + +### 4. Verification Guidance + +"**Quick Test:** +- Load the agent and check it initializes correctly +- Run through a few commands to verify behavior + +**File Locations:** +- **Agent File:** `{agentFile}` +- **Backup:** `{agentFile}.backup`" + +### 5. Document Completion + +Append to editPlan: + +```markdown +## Edit Session Complete ✅ + +**Completed:** {YYYY-MM-DD HH:MM} +**Status:** Success + +### Final State +- Agent file updated successfully +- All edits applied +- Backup preserved +``` + +### 6. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [X] Exit Workflow" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF X: Save completion status to {editPlan} and end workflow gracefully +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY complete workflow when user selects 'X' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [X exit option] is selected and [completion documented], will the workflow end gracefully with agent edit complete. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Enthusiastic celebration of edit completion +- Clear summary of all changes provided +- Before/after validation comparison shown +- Verification guidance provided +- Workflow completion marked in edit plan + +### ❌ SYSTEM FAILURE: + +- Ending without marking workflow completion +- Not providing clear summary of changes +- Missing celebration of achievement + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-v/v-01-load-review.md b/src/modules/bmb/workflows/agent/steps-v/v-01-load-review.md new file mode 100644 index 00000000..0e6a6df8 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-v/v-01-load-review.md @@ -0,0 +1,128 @@ +--- +name: 'v-01-load-review' +description: 'Load agent and initialize validation report' + +nextStepFile: './v-02a-validate-metadata.md' +validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md' +agentMetadata: ../data/agent-metadata.md + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Validate Step 1: Load Agent for Review + +## STEP GOAL: + +Load the existing agent file and initialize a validation report to track all findings. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Load the complete agent file +- 📊 Create validation report tracking document +- 🚫 FORBIDDEN to proceed without user confirming correct agent + +## EXECUTION PROTOCOLS: + +- 🎯 Load the complete agent YAML file +- 📊 Parse and display agent summary +- 💾 Create validation report document +- 🚫 FORBIDDEN to proceed without user confirmation + +## Sequence of Instructions: + +### 1. Load Agent File + +Read the complete YAML from the agent file path provided by the user. + +### 2. Display Agent Summary + +```markdown +## Agent to Validate: {agent-name} + +**Type:** {simple|expert|module} +**Version:** {version} +**File:** {agent-file-path} + +### Current Structure: + +**Persona:** {character count} characters +**Commands:** {count} commands +**Critical Actions:** {count} actions +``` + +### 3. Create Validation Report + +Initialize the validation report: + +```markdown +--- +agentName: '{agent-name}' +agentType: '{simple|expert|module}' +agentFile: '{agent-file-path}' +validationDate: '{YYYY-MM-DD}' +stepsCompleted: + - v-01-load-review.md +--- + +# Validation Report: {agent-name} + +## Agent Overview + +**Name:** {agent-name} +**Type:** {simple|expert|module} +**Version:** {version} +**File:** {agent-file-path} + +--- + +## Validation Findings + +*This section will be populated by validation steps* +``` + +Write to `{validationReport}`. + +### 4. Present MENU OPTIONS + +Display: "**Is this the correct agent to validate?** [A] Advanced Elicitation [P] Party Mode [C] Yes, Begin Validation" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Save to {validationReport}, then only then load, read entire file, then execute {nextStepFile} +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [agent loaded and report created], will you then load and read fully `{nextStepFile}` to execute and begin validation. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Agent file loaded successfully +- Validation report created +- User confirmed correct agent + +### ❌ SYSTEM FAILURE: + +- Failed to load agent file +- Report not created +- Proceeded without user confirmation + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/agent/steps-v/v-02a-validate-metadata.md b/src/modules/bmb/workflows/agent/steps-v/v-02a-validate-metadata.md new file mode 100644 index 00000000..e0828072 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-v/v-02a-validate-metadata.md @@ -0,0 +1,73 @@ +--- +name: 'v-02a-validate-metadata' +description: 'Validate metadata and append to report' + +nextStepFile: './v-02b-validate-persona.md' +validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md' +agentMetadata: ../data/agent-metadata.md +--- + +# Validate Step 2a: Validate Metadata + +## STEP GOAL: + +Validate the agent's metadata properties against BMAD standards. Append findings to validation report and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read validationReport and agentMetadata first +- 🚫 NO MENU - append findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate metadata against agentMetadata.md rules +- 📊 Append findings to validation report +- 🚫 FORBIDDEN to present menu + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMetadata.md reference +- 📊 Validate all metadata fields +- 💾 Append findings to validation report +- ➡️ Auto-advance to next validation step + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentMetadata}` and `{validationReport}`. + +### 2. Validate Metadata + +Perform checks on: id, name, title, icon, module, hasSidecar. + +### 3. Append Findings to Report + +Append to `{validationReport}`: + +```markdown +### Metadata Validation + +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} + +**Checks:** +- [ ] id: kebab-case, no spaces +- [ ] name: clear display name +- [ ] title: concise function description +- [ ] icon: appropriate emoji/symbol +- [ ] module: correct format `{project}:{type}:{name}` +- [ ] hasSidecar: matches actual usage + +**Findings:** +{Detailed findings} +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +--- + +**Validating persona...** diff --git a/src/modules/bmb/workflows/agent/steps-v/v-02b-validate-persona.md b/src/modules/bmb/workflows/agent/steps-v/v-02b-validate-persona.md new file mode 100644 index 00000000..7876a7e0 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-v/v-02b-validate-persona.md @@ -0,0 +1,72 @@ +--- +name: 'v-02b-validate-persona' +description: 'Validate persona and append to report' + +nextStepFile: './v-02c-validate-menu.md' +validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md' +personaProperties: ../data/persona-properties.md +principlesCrafting: ../data/principles-crafting.md +--- + +# Validate Step 2b: Validate Persona + +## STEP GOAL: + +Validate the agent's persona against BMAD standards. Append findings to validation report and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read validationReport and persona references first +- 🚫 NO MENU - append findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate persona four-field system +- 📊 Append findings to validation report +- 🚫 FORBIDDEN to present menu + +## EXECUTION PROTOCOLS: + +- 🎯 Load personaProperties.md and principlesCrafting.md +- 📊 Validate persona fields +- 💾 Append findings to validation report +- ➡️ Auto-advance to next validation step + +## Sequence of Instructions: + +### 1. Load References + +Read `{personaProperties}`, `{principlesCrafting}`, and `{validationReport}`. + +### 2. Validate Persona + +Perform checks on: role, identity, communication_style, principles. + +### 3. Append Findings to Report + +Append to `{validationReport}`: + +```markdown +### Persona Validation + +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} + +**Checks:** +- [ ] role: specific, not generic +- [ ] identity: defines who agent is +- [ ] communication_style: speech patterns only +- [ ] principles: first principle activates expert knowledge + +**Findings:** +{Detailed findings} +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +--- + +**Validating menu structure...** diff --git a/src/modules/bmb/workflows/agent/steps-v/v-02c-validate-menu.md b/src/modules/bmb/workflows/agent/steps-v/v-02c-validate-menu.md new file mode 100644 index 00000000..0faf4913 --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-v/v-02c-validate-menu.md @@ -0,0 +1,71 @@ +--- +name: 'v-02c-validate-menu' +description: 'Validate menu structure and append to report' + +nextStepFile: './v-02d-validate-structure.md' +validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md' +agentMenuPatterns: ../data/agent-menu-patterns.md +--- + +# Validate Step 2c: Validate Menu + +## STEP GOAL: + +Validate the agent's command menu structure against BMAD standards. Append findings to validation report and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read validationReport and agentMenuPatterns first +- 🚫 NO MENU - append findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate command/menu structure +- 📊 Append findings to validation report +- 🚫 FORBIDDEN to present menu + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentMenuPatterns.md reference +- 📊 Validate commands and menu +- 💾 Append findings to validation report +- ➡️ Auto-advance to next validation step + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentMenuPatterns}` and `{validationReport}`. + +### 2. Validate Menu + +Perform checks on: A/P/C convention, command names, descriptions. + +### 3. Append Findings to Report + +Append to `{validationReport}`: + +```markdown +### Menu Validation + +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} + +**Checks:** +- [ ] A/P/C convention followed +- [ ] Command names clear and descriptive +- [ ] Command descriptions specific and actionable +- [ ] Menu handling logic properly specified + +**Findings:** +{Detailed findings} +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +--- + +**Validating YAML structure...** diff --git a/src/modules/bmb/workflows/agent/steps-v/v-02d-validate-structure.md b/src/modules/bmb/workflows/agent/steps-v/v-02d-validate-structure.md new file mode 100644 index 00000000..1c1b0b4f --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-v/v-02d-validate-structure.md @@ -0,0 +1,71 @@ +--- +name: 'v-02d-validate-structure' +description: 'Validate YAML structure and append to report' + +nextStepFile: './v-02e-validate-sidecar.md' +validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md' +agentCompilation: ../data/agent-compilation.md +--- + +# Validate Step 2d: Validate Structure + +## STEP GOAL: + +Validate the agent's YAML structure and completeness. Append findings to validation report and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read validationReport and agentCompilation first +- 🚫 NO MENU - append findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate YAML structure and required fields +- 📊 Append findings to validation report +- 🚫 FORBIDDEN to present menu + +## EXECUTION PROTOCOLS: + +- 🎯 Load agentCompilation.md reference +- 📊 Validate YAML structure +- 💾 Append findings to validation report +- ➡️ Auto-advance to next validation step + +## Sequence of Instructions: + +### 1. Load References + +Read `{agentCompilation}` and `{validationReport}`. + +### 2. Validate Structure + +Perform checks on: YAML syntax, required fields, field types, indentation. + +### 3. Append Findings to Report + +Append to `{validationReport}`: + +```markdown +### Structure Validation + +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL} + +**Checks:** +- [ ] Valid YAML syntax +- [ ] Required fields present (name, description, type, persona) +- [ ] Field types correct (arrays, strings) +- [ ] Consistent 2-space indentation + +**Findings:** +{Detailed findings} +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +--- + +**Validating sidecar structure...** diff --git a/src/modules/bmb/workflows/agent/steps-v/v-02e-validate-sidecar.md b/src/modules/bmb/workflows/agent/steps-v/v-02e-validate-sidecar.md new file mode 100644 index 00000000..2b70d1cb --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-v/v-02e-validate-sidecar.md @@ -0,0 +1,76 @@ +--- +name: 'v-02e-validate-sidecar' +description: 'Validate sidecar structure and append to report' + +nextStepFile: './v-03-summary.md' +validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md' +expertValidation: ../data/expert-agent-validation.md +--- + +# Validate Step 2e: Validate Sidecar + +## STEP GOAL: + +Validate the agent's sidecar structure (if Expert type). Append findings to validation report and auto-advance. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read validationReport and expertValidation first +- 🚫 NO MENU - append findings and auto-advance +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Validate sidecar structure for Expert agents +- 📊 Append findings to validation report +- 🚫 FORBIDDEN to present menu + +## EXECUTION PROTOCOLS: + +- 🎯 Load expertValidation.md reference +- 📊 Validate sidecar if Expert type, skip for Simple/Module +- 💾 Append findings to validation report +- ➡️ Auto-advance to summary step + +## Sequence of Instructions: + +### 1. Load References + +Read `{expertValidation}` and `{validationReport}` to get agent type. + +### 2. Conditional Validation + +**IF agentType == expert:** +- Check metadata.sidecar-folder present +- Check sidecar-path correct format +- Verify sidecar files exist + +**IF agentType != expert:** +- Mark as N/A + +### 3. Append Findings to Report + +Append to `{validationReport}`: + +```markdown +### Sidecar Validation + +**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL / N/A} + +**Checks:** +- [ ] metadata.sidecar-folder present (Expert only) +- [ ] sidecar-path format correct +- [ ] Sidecar files exist at specified path + +**Findings:** +{Detailed findings or "N/A - Not an Expert agent"} +``` + +### 4. Auto-Advance + +Load and execute `{nextStepFile}` immediately. + +--- + +**Compiling validation summary...** diff --git a/src/modules/bmb/workflows/agent/steps-v/v-03-summary.md b/src/modules/bmb/workflows/agent/steps-v/v-03-summary.md new file mode 100644 index 00000000..21a435fa --- /dev/null +++ b/src/modules/bmb/workflows/agent/steps-v/v-03-summary.md @@ -0,0 +1,100 @@ +--- +name: 'v-03-summary' +description: 'Display complete validation report and offer next steps' + +validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md' + +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +--- + +# Validate Step 3: Validation Summary + +## STEP GOAL: + +Display the complete validation report to the user and offer options for fixing issues or improving the agent. + +## MANDATORY EXECUTION RULES: + +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: Read validationReport to display findings +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Step-Specific Rules: + +- 🎯 Display complete validation report clearly +- 📊 Offer options for fixing issues +- 💬 Present next step choices + +## EXECUTION PROTOCOLS: + +- 🎯 Read validation report to collect all findings +- 📊 Display organized summary +- 💾 Allow user to decide next steps + +## Sequence of Instructions: + +### 1. Load Validation Report + +Read `{validationReport}` to collect all validation findings. + +### 2. Display Complete Report + +```markdown +## Validation Complete: {agent-name} + +### Overall Status + +{Summary table: Metadata | Persona | Menu | Structure | Sidecar} + +### Detailed Findings + +{Display all sections from the validation report} +``` + +### 3. Present Next Steps + +"What would you like to do? + +**[E]dit Agent** - Launch edit workflow to fix issues or make improvements +**[S]ave Report** - Save this validation report and exit +**[R]etry** - Run validation again (if you've made external changes)" + +### 4. Present MENU OPTIONS + +Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [E] Edit Agent [S] Save & Exit [R] Retry Validation" + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu +- IF E: Inform user they can launch edit workflow with the same agent file, then redisplay menu +- IF S: Save final report to {validationReport} and end workflow +- IF R: Restart validation from step v-01 +- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options) + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- User can chat or ask questions - always respond and then end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +The validation workflow is complete when user selects [S] to save the report, or [E] to proceed to edit workflow. + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Complete validation report displayed +- All findings clearly organized +- User offered clear next steps + +### ❌ SYSTEM FAILURE: + +- Findings not displayed to user +- No clear next steps offered + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/create-agent/templates/agent-plan.template.md b/src/modules/bmb/workflows/agent/templates/agent-plan.template.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/templates/agent-plan.template.md rename to src/modules/bmb/workflows/agent/templates/agent-plan.template.md diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template b/src/modules/bmb/workflows/agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template similarity index 100% rename from src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template rename to src/modules/bmb/workflows/agent/templates/expert-agent-template/expert-agent-sidecar/instructions.md.template diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template b/src/modules/bmb/workflows/agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template similarity index 100% rename from src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template rename to src/modules/bmb/workflows/agent/templates/expert-agent-template/expert-agent-sidecar/memories.md.template diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent.template.md b/src/modules/bmb/workflows/agent/templates/expert-agent-template/expert-agent.template.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/templates/expert-agent-template/expert-agent.template.md rename to src/modules/bmb/workflows/agent/templates/expert-agent-template/expert-agent.template.md diff --git a/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md b/src/modules/bmb/workflows/agent/templates/simple-agent.template.md similarity index 100% rename from src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md rename to src/modules/bmb/workflows/agent/templates/simple-agent.template.md diff --git a/src/modules/bmb/workflows/agent/workflow.md b/src/modules/bmb/workflows/agent/workflow.md new file mode 100644 index 00000000..7348562d --- /dev/null +++ b/src/modules/bmb/workflows/agent/workflow.md @@ -0,0 +1,123 @@ +--- +name: agent +description: Tri-modal workflow for creating, editing, and validating BMAD Core compliant agents +web_bundle: true +--- + +# Agent Workflow + +**Goal:** Collaboratively create, edit, or validate BMAD Core compliant agents through guided discovery and systematic execution. + +**Your Role:** In addition to your name, communication_style, and persona, you are also an expert agent architect specializing in BMAD Core agent lifecycle management. You guide users through creating new agents, editing existing ones, or validating agent configurations. + +--- + +## WORKFLOW ARCHITECTURE + +This uses **step-file architecture** for disciplined execution: + +### Core Principles + +- **Micro-file Design**: Each step is a self-contained instruction file +- **Just-In-Time Loading**: Only the current step file is in memory +- **Sequential Enforcement**: Steps completed in order, conditional based on mode +- **State Tracking**: Document progress in tracking files (agentPlan, editPlan, validationReport) +- **Mode-Aware Routing**: Separate step flows for Create/Edit/Validate + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute numbered sections in order +3. **WAIT FOR INPUT**: Halt at menus and wait for user selection +4. **CHECK CONTINUATION**: Only proceed when user selects appropriate option +5. **SAVE STATE**: Update progress before loading next step +6. **LOAD NEXT**: When directed, load and execute the next step file + +### Critical Rules + +- 🛑 **NEVER** load multiple step files simultaneously +- 📖 **ALWAYS** read entire step file before execution +- 🚫 **NEVER** skip steps unless explicitly optional +- 💾 **ALWAYS** save progress and outputs +- 🎯 **ALWAYS** follow exact instructions in step files +- ⏸️ **ALWAYS** halt at menus and wait for input +- 📋 **NEVER** pre-load future steps + +--- + +## MODE OVERVIEW + +This workflow supports three modes: + +| Mode | Purpose | Entry Point | Output | +|------|---------|-------------|--------| +| **Create** | Build new agent from scratch | `steps-c/step-01-brainstorm.md` | New `.agent.yaml` file | +| **Edit** | Modify existing agent | `steps-e/e-01-load-existing.md` | Updated `.agent.yaml` file | +| **Validate** | Review existing agent | `steps-v/v-01-load-review.md` | Validation report | + +--- + +## INITIALIZATION SEQUENCE + +### 1. Configuration Loading + +Load and read full config from `{project-root}/_bmad/bmb/config.yaml`: + +- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder` +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### 2. Mode Determination + +**Check if mode was specified in the command invocation:** + +- If user invoked with "create agent" or "new agent" → Set mode to **create** +- If user invoked with "edit agent" or "modify agent" → Set mode to **edit** +- If user invoked with "validate agent" or "review agent" → Set mode to **validate** + +**If mode is unclear from command, ask user:** + +"Welcome to the BMAD Agent Workflow! What would you like to do? + +**[C]reate** - Build a new agent from scratch +**[E]dit** - Modify an existing agent +**[V]alidate** - Review an existing agent and generate report + +Please select: [C]reate / [E]dit / [V]alidate" + +### 3. Route to First Step + +**IF mode == create:** +Load, read completely, then execute `steps-c/step-01-brainstorm.md` + +**IF mode == edit:** +Prompt for agent file path: "Which agent would you like to edit? Please provide the path to the `.agent.yaml` file." +Then load, read completely, and execute `steps-e/e-01-load-existing.md` + +**IF mode == validate:** +Prompt for agent file path: "Which agent would you like to validate? Please provide the path to the `.agent.yaml` file." +Then load, read completely, and execute `steps-v/v-01-load-review.md` + +--- + +## MODE-SPECIFIC NOTES + +### Create Mode +- Starts with optional brainstorming +- Progresses through discovery, metadata, persona, commands, activation +- Builds agent based on type (Simple/Expert/Module) +- Validates built agent +- Celebrates completion with installation guidance + +### Edit Mode +- Loads existing agent first +- Discovers what user wants to change +- Validates current agent before editing +- Creates structured edit plan +- Applies changes with validation +- Celebrates successful edit + +### Validate Mode +- Loads existing agent +- Runs systematic validation (metadata, persona, menu, structure, sidecar) +- Generates comprehensive validation report +- Offers option to apply fixes if user desires diff --git a/src/modules/bmb/workflows/create-agent/workflow.md b/src/modules/bmb/workflows/create-agent/workflow.md deleted file mode 100644 index d871fd3b..00000000 --- a/src/modules/bmb/workflows/create-agent/workflow.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: create-agent -description: Interactive workflow to build BMAD Core compliant agents with optional brainstorming, persona development, and command structure -web_bundle: true ---- - -# Create Agent Workflow - -**Goal:** Collaboratively build BMAD Core compliant agents through guided discovery, preserving all functionality from the legacy workflow while enabling step-specific loading. - -**Your Role:** In addition to your name, communication_style, and persona, you are also an expert agent architect and builder specializing in BMAD Core agent creation. You guide users through discovering their agent's purpose, shaping its personality, building its capabilities, and generating complete YAML configuration with all necessary supporting files. - ---- - -## WORKFLOW ARCHITECTURE - -This uses **step-file architecture** for disciplined execution: - -### Core Principles - -- **Micro-file Design**: Each step is a self contained instruction file -- **Just-In-Time Loading**: Only the current step file is in memory -- **Sequential Enforcement**: Steps completed in order, conditional based on agent type -- **State Tracking**: Document progress in agent output files -- **Agent-Type Optimization**: Load only relevant steps for Simple/Expert/Module agents - -### Step Processing Rules - -1. **READ COMPLETELY**: Always read the entire step file before taking any action -2. **FOLLOW SEQUENCE**: Execute numbered sections in order -3. **WAIT FOR INPUT**: Halt at menus and wait for user selection -4. **CHECK CONTINUATION**: Only proceed when user selects 'C' (Continue) -5. **SAVE STATE**: Update progress before loading next step -6. **LOAD NEXT**: When directed, load and execute the next step file - -### Critical Rules - -- 🛑 **NEVER** load multiple step files simultaneously -- 📖 **ALWAYS** read entire step file before execution -- 🚫 **NEVER** skip steps unless explicitly optional -- 💾 **ALWAYS** save progress and outputs -- 🎯 **ALWAYS** follow exact instructions in step files -- ⏸️ **ALWAYS** halt at menus and wait for input -- 📋 **NEVER** pre-load future steps - ---- - -## INITIALIZATION SEQUENCE - -### 1. Configuration Loading - -Load and read full config from `{project-root}/_bmad/bmb/config.yaml`: - -- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder` -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### 2. First Step EXECUTION - -Load, read completely, then execute `steps/step-01-brainstorm.md` to begin the workflow. diff --git a/src/modules/bmb/workflows/edit-agent/steps/step-01-discover-intent.md b/src/modules/bmb/workflows/edit-agent/steps/step-01-discover-intent.md deleted file mode 100644 index 39c57e2e..00000000 --- a/src/modules/bmb/workflows/edit-agent/steps/step-01-discover-intent.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -name: 'step-01-discover-intent' -description: 'Get agent path and user editing goals' - -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/edit-agent' - -# File References -thisStepFile: '{workflow_path}/steps/step-01-discover-intent.md' -nextStepFile: '{workflow_path}/steps/step-02-analyze-agent.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: Discover Edit Intent - -## STEP GOAL: - -Get the agent path to edit and understand what the user wants to accomplish before proceeding to targeted analysis. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are an agent editor who helps users improve their BMAD agents -- ✅ If you already have a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring agent architecture expertise, user brings their agent and goals, together we improve the agent -- ✅ Maintain collaborative guiding tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on getting agent path and understanding user goals -- 🚫 FORBIDDEN to load any documentation or analyze the agent yet -- 💬 Approach: Direct questions to understand what needs fixing -- 🚫 FORBIDDEN to make suggestions or propose solutions - -## EXECUTION PROTOCOLS: - -- 🎯 Ask clear questions to get agent path and user goals -- 💾 Store path and goals for next step -- 📖 Do NOT load any references in this step -- 🚫 FORBIDDEN to analyze agent content yet - -## CONTEXT BOUNDARIES: - -- Available context: User wants to edit an existing agent -- Focus: Get path and understand goals ONLY -- Limits: No analysis, no documentation loading, no suggestions -- Dependencies: User must provide agent path - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Get Agent Path - -Ask the user: -"What agent do you want to edit? Please provide the path to: - -- A .agent.yaml file (Simple agent) -- A folder containing .agent.yaml (Expert agent with sidecar files)" - -Wait for user response with the path. - -### 2. Understand Editing Goals - -Ask clear questions to understand what they want to accomplish: -"What do you want to change about this agent?" - -Listen for specific goals such as: - -- Fix broken functionality -- Update personality/communication style -- Add or remove commands -- Fix references or paths -- Reorganize sidecar files (Expert agents) -- Update for new standards - -Continue asking clarifying questions until goals are clear. - -### 3. Confirm Understanding - -Summarize back to user: -"So you want to edit the agent at {{agent_path}} to {{user_goals}}. Is that correct?" - -### 4. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### Menu Handling Logic: - -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Load, read entire file, then execute {nextStepFile} -- IF Any other comments or queries: help user respond then redisplay menu options - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [agent path and goals obtained], will you then load and read fully `{nextStepFile}` to execute and begin agent analysis. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- Agent path clearly obtained and validated -- User editing goals understood completely -- User confirms understanding is correct -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Proceeding without agent path -- Making suggestions or analyzing agent -- Loading documentation in this step -- Not confirming user goals clearly - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md b/src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md deleted file mode 100644 index ae23b183..00000000 --- a/src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -name: 'step-02-analyze-agent' -description: 'Load agent and relevant documentation for analysis' - -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/edit-agent' - -# File References -thisStepFile: '{workflow_path}/steps/step-02-analyze-agent.md' -nextStepFile: '{workflow_path}/steps/step-03-propose-changes.md' - -# Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' - -# Documentation References (load JIT based on user goals) -understanding_agent_types: '{project-root}/_bmad/bmb/docs/agents/understanding-agent-types.md' -agent_compilation: '{project-root}/_bmad/bmb/docs/agents/agent-compilation.md' -simple_architecture: '{project-root}/_bmad/bmb/docs/agents/simple-agent-architecture.md' -expert_architecture: '{project-root}/_bmad/bmb/docs/agents/expert-agent-architecture.md' -module_architecture: '{project-root}/_bmad/bmb/docs/agents/module-agent-architecture.md' -menu_patterns: '{project-root}/_bmad/bmb/docs/agents/agent-menu-patterns.md' -communication_presets: '{project-root}/_bmad/bmb/workflows/create-agent/data/communication-presets.csv' -reference_simple_agent: '{project-root}/_bmad/bmb/reference/agents/simple-examples/commit-poet.agent.yaml' -reference_expert_agent: '{project-root}/_bmad/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml' -validation: '{project-root}/_bmad/bmb/workflows/create-agent/data/agent-validation-checklist.md' ---- - -# Step 2: Analyze Agent - -## STEP GOAL: - -Load the agent and relevant documentation, then analyze with focus on the user's stated goals to identify specific issues that need fixing. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are an agent editor with deep knowledge of BMAD agent architecture -- ✅ If you already have a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring agent architecture expertise, user brings their agent and goals, together we identify specific improvements -- ✅ Maintain analytical yet supportive tone throughout - -### Step-Specific Rules: - -- 🎯 Focus analysis ONLY on user's stated goals from step 1 -- 🚫 FORBIDDEN to load documentation not relevant to user goals -- 💬 Approach: Load documentation JIT when needed for specific analysis -- 🚫 FORBIDDEN to propose solutions yet (analysis only) - -## EXECUTION PROTOCOLS: - -- 🎯 Load agent file from path provided in step 1 -- 💾 Load documentation JIT based on user goals -- 📖 Always "Load and read fully" when accessing documentation -- 🚫 FORBIDDEN to make changes in this step (analysis only) - -## CONTEXT BOUNDARIES: - -- Available context: Agent path and user goals from step 1 -- Focus: Analyze agent in context of user goals -- Limits: Only load documentation relevant to stated goals -- Dependencies: Must have agent path and clear user goals - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Load Agent File - -Load the agent file from the path provided in step 1: - -**If path is to a .agent.yaml file (Simple Agent):** - -- Load and read the entire YAML file -- Note: Simple agent, all content in one file - -**If path is to a folder (Expert Agent with sidecar files):** - -- Load and read the .agent.yaml file from inside the folder -- Inventory all sidecar files in the folder: - - Templates (`_.md`, `_.txt`) - - Documentation files - - Knowledge base files (`_.csv`, `_.json`, `*.yaml`) - - Any other resources referenced by the agent -- Note: Expert agent with sidecar structure - -Present what was loaded: - -- "Loaded [agent-name].agent.yaml" -- If Expert: "Plus X sidecar files: [list them]" - -### 2. Load Relevant Documentation Based on User Goals - -**CRITICAL: Load documentation JIT based ONLY on user's stated goals:** - -**If user mentioned persona/communication issues:** - -- Load and read fully: `{agent_compilation}` - understand how LLM interprets persona fields -- Load and read fully: `{communication_presets}` - reference for pure communication styles - -**If user mentioned functional/broken reference issues:** - -- Load and read fully: `{menu_patterns}` - proper menu structure -- Load and read fully: `{agent_compilation}` - compilation requirements - -**If user mentioned sidecar/structure issues (Expert agents):** - -- Load and read fully: `{expert_architecture}` - sidecar best practices - -**If user mentioned agent type confusion:** - -- Load and read fully: `{understanding_agent_types}` -- Load and read fully appropriate architecture guide based on agent type - -### 3. Focused Analysis Based on User Goals - -Analyze only what's relevant to user goals: - -**For persona/communication issues:** - -- Check communication_style field for mixed behaviors/identity/principles -- Look for red flag words that indicate improper mixing: - - "ensures", "makes sure", "always", "never" → Behaviors (belongs in principles) - - "experienced", "expert who", "senior", "seasoned" → Identity descriptors (belongs in role/identity) - - "believes in", "focused on", "committed to" → Philosophy (belongs in principles) -- Compare current communication_style against examples in `{communication_presets}` - -**For functional issues:** - -- Verify all workflow references exist and are valid -- Check menu handler patterns against `{menu_patterns}` -- Validate YAML syntax and structure - -**For sidecar issues:** - -- Map each menu item reference to actual sidecar files -- Identify orphaned files (not referenced in YAML) -- Check if all referenced files actually exist - -### 4. Report Findings - -Present focused analysis findings: -"Based on your goal to {{user_goal}}, I found the following issues:" - -For each issue found: - -- Describe the specific problem -- Show the relevant section of the agent -- Reference the loaded documentation that explains the standard -- Explain why this is an issue - -### 5. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### Menu Handling Logic: - -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Load, read entire file, then execute {nextStepFile} -- IF Any other comments or queries: help user respond then redisplay menu options - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [analysis complete with specific issues identified], will you then load and read fully `{nextStepFile}` to execute and begin proposing specific changes. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- Agent file loaded completely with proper type detection -- Relevant documentation loaded JIT based on user goals -- Analysis focused only on user's stated issues -- Specific problems identified with documentation references -- User understands what needs fixing and why -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Loading documentation not relevant to user goals -- Proposing solutions instead of analyzing -- Missing critical issues related to user goals -- Not following "load and read fully" instruction -- Making changes to agent files - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/edit-agent/steps/step-03-propose-changes.md b/src/modules/bmb/workflows/edit-agent/steps/step-03-propose-changes.md deleted file mode 100644 index 32342ebf..00000000 --- a/src/modules/bmb/workflows/edit-agent/steps/step-03-propose-changes.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -name: 'step-03-propose-changes' -description: 'Propose specific changes and get approval' - -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/edit-agent' - -# File References -thisStepFile: '{workflow_path}/steps/step-03-propose-changes.md' -nextStepFile: '{workflow_path}/steps/step-04-apply-changes.md' -agentFile: '{{agent_path}}' - -# Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' - -# Documentation References (load JIT if needed) -communication_presets: '{project-root}/_bmad/bmb/workflows/create-agent/data/communication-presets.csv' -agent_compilation: '{project-root}/_bmad/bmb/docs/agents/agent-compilation.md' ---- - -# Step 3: Propose Changes - -## STEP GOAL: - -Propose specific, targeted changes based on analysis and get user approval before applying them to the agent. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are an agent editor who helps users improve their BMAD agents through targeted changes -- ✅ If you already have a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring agent architecture expertise, user brings their agent and goals, together we improve the agent -- ✅ Maintain collaborative guiding tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on proposing changes based on analysis from step 2 -- 🚫 FORBIDDEN to apply changes without explicit user approval -- 💬 Approach: Present one change at a time with clear before/after comparison -- 📋 Load references JIT when explaining rationale or providing examples - -## EXECUTION PROTOCOLS: - -- 🎯 Propose one change at a time with clear before/after comparison -- 💾 Track approved changes for application in next step -- 📖 Load references JIT if needed for examples or best practices -- 🚫 FORBIDDEN to apply changes without explicit user approval - -## CONTEXT BOUNDARIES: - -- Available context: Analysis results from step 2, agent path, and user goals from step 1 -- Focus: Propose specific changes based on analysis, not apply them -- Limits: Only propose changes, do not modify any files yet -- Dependencies: Must have completed step 2 analysis results - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Present First Change - -Based on analysis from step 2, propose the most important change first: - -"I recommend fixing {{issue}} because {{reason}}. - -**Current:** - -```yaml -{ { current_code } } -``` - -**Proposed:** - -```yaml -{ { proposed_code } } -``` - -This will help with {{benefit}}." - -### 2. Explain Rationale - -- Why this change matters for the agent's functionality -- How it aligns with BMAD agent best practices -- Reference loaded documentation if helpful for explaining - -### 3. Load References if Needed - -**Load references JIT when explaining:** - -- If proposing persona changes: Load and read `{communication_presets}` for examples -- If proposing structural changes: Load and read `{agent_compilation}` for requirements - -### 4. Get User Approval - -"Does this change look good? Should I apply it?" -Wait for explicit user approval before proceeding. - -### 5. Repeat for Each Issue - -Go through each identified issue from step 2 analysis one by one: - -- Present change with before/after -- Explain rationale with loaded references if needed -- Get explicit user approval for each change -- Track which changes are approved vs rejected - -### 6. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### Menu Handling Logic: - -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Save approved changes list to context, 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: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [all proposed changes reviewed and user approvals obtained], will you then load and read fully `{nextStepFile}` to execute and begin applying approved changes. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- All proposed changes clearly presented with before/after comparison -- Rationale explained with references to best practices -- User approval obtained for each proposed change -- Approved changes tracked for application in next step -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Applying changes without explicit user approval -- Not presenting clear before/after comparisons -- Skipping explanation of rationale or references -- Proceeding without tracking which changes were approved -- Loading references when not needed for current proposal - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/edit-agent/steps/step-04-apply-changes.md b/src/modules/bmb/workflows/edit-agent/steps/step-04-apply-changes.md deleted file mode 100644 index bc1679e4..00000000 --- a/src/modules/bmb/workflows/edit-agent/steps/step-04-apply-changes.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: 'step-04-apply-changes' -description: 'Apply approved changes to the agent' - -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/edit-agent' - -# File References -thisStepFile: '{workflow_path}/steps/step-04-apply-changes.md' -agentFile: '{{agent_path}}' -nextStepFile: '{workflow_path}/steps/step-05-validate.md' - -# Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' ---- - -# Step 4: Apply Changes - -## STEP GOAL: - -Apply all user-approved changes to the agent files directly using the Edit tool. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are an agent editor who helps users improve their BMAD agents through precise modifications -- ✅ If you already have a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring agent architecture expertise, user brings their agent and goals, together we improve the agent -- ✅ Maintain collaborative guiding tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on applying changes that were explicitly approved in step 3 -- 🚫 FORBIDDEN to make any changes that were not approved by the user -- 💬 Approach: Apply changes one by one with confirmation after each -- 📋 Use Edit tool to make precise modifications to agent files - -## EXECUTION PROTOCOLS: - -- 🎯 Apply only changes that were explicitly approved in step 3 -- 💾 Show confirmation after each change is applied -- 📖 Edit files directly using Edit tool with precise modifications -- 🚫 FORBIDDEN to make unapproved changes or extra modifications - -## CONTEXT BOUNDARIES: - -- Available context: Approved changes list from step 3, agent path from step 1 -- Focus: Apply ONLY the approved changes, nothing more -- Limits: Do not make any modifications beyond what was explicitly approved -- Dependencies: Must have approved changes list from step 3 - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Load Agent File - -Read the complete agent file to understand current state before making changes. - -### 2. Apply First Approved Change - -For each change approved in step 3, apply it systematically: - -**For YAML changes in main agent file:** - -- Use Edit tool to modify the agent YAML file at `{agentFile}` -- Make the exact approved modification -- Confirm the change was applied correctly - -**For sidecar file changes (Expert agents):** - -- Use Edit tool to modify the specific sidecar file -- Make the exact approved modification -- Confirm the change was applied correctly - -### 3. Confirm Each Change Applied - -After each change is applied: -"Applied change: {{description}} - -- Updated section matches approved change ✓ -- File saved successfully ✓" - -### 4. Continue Until All Changes Applied - -Repeat step 2-3 for each approved change until complete: - -- Apply change using Edit tool -- Confirm it matches what was approved -- Move to next approved change - -### 5. Verify All Changes Complete - -"Summary of changes applied: - -- {{number}} changes applied successfully -- All modifications match user approvals from step 3 -- Agent files updated and saved" - -### 6. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue" - -#### Menu Handling Logic: - -- IF A: Execute {advancedElicitationTask} -- IF P: Execute {partyModeWorkflow} -- IF C: Save completion status to context, 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: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After other menu items execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C continue option] is selected and [all approved changes from step 3 have been applied to agent files], will you then load and read fully `{nextStepFile}` to execute and begin validation of applied changes. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- All approved changes from step 3 applied using Edit tool -- Each modification matches exactly what was approved by user -- Agent files updated and saved correctly -- Confirmation provided for each applied change -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Making changes that were not approved in step 3 -- Using tools other than Edit tool for file modifications -- Not confirming each change was applied correctly -- Making extra modifications beyond approved changes -- Skipping confirmation steps or verification - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/edit-agent/steps/step-05-validate.md b/src/modules/bmb/workflows/edit-agent/steps/step-05-validate.md deleted file mode 100644 index aac9e749..00000000 --- a/src/modules/bmb/workflows/edit-agent/steps/step-05-validate.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: 'step-05-validate' -description: 'Validate that changes work correctly' - -# Path Definitions -workflow_path: '{project-root}/bmb/workflows/create-agent/edit-agent' - -# File References -thisStepFile: '{workflow_path}/steps/step-05-validate.md' -agentFile: '{{agent_path}}' - -# Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' - -# Documentation References (load JIT) -validation: '{project-root}/_bmad/bmb/workflows/create-agent/data/agent-validation-checklist.md' -agent_compilation: '{project-root}/_bmad/bmb/docs/agents/agent-compilation.md' ---- - -# Step 5: Validate Changes - -## STEP GOAL: - -Validate that the applied changes work correctly and the edited agent follows BMAD best practices and standards. - -## MANDATORY EXECUTION RULES (READ FIRST): - -### Universal Rules: - -- 🛑 NEVER generate content without user input -- 📖 CRITICAL: Read the complete step file before taking any action -- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read -- 📋 YOU ARE A FACILITATOR, not a content generator -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### Role Reinforcement: - -- ✅ You are an agent editor who helps users ensure their edited BMAD agents meet quality standards -- ✅ If you already have a name, communication_style and identity, continue to use those while playing this new role -- ✅ We engage in collaborative dialogue, not command-response -- ✅ You bring agent architecture expertise, user brings their agent and goals, together we ensure quality -- ✅ Maintain collaborative guiding tone throughout - -### Step-Specific Rules: - -- 🎯 Focus only on validating changes that were applied in step 4 -- 🚫 FORBIDDEN to make additional changes during validation -- 💬 Approach: Systematic validation using standard checklist -- 📋 Load validation references JIT when needed for specific checks - -## EXECUTION PROTOCOLS: - -- 🎯 Validate only the changes that were applied in step 4 -- 💾 Report validation results clearly and systematically -- 📖 Load validation checklist and standards JIT as needed -- 🚫 FORBIDDEN to make additional modifications during validation - -## CONTEXT BOUNDARIES: - -- Available context: Applied changes from step 4, agent path from step 1, original goals from step 1 -- Focus: Validate that applied changes work and meet standards -- Limits: Do not modify anything, only validate and report -- Dependencies: Must have completed step 4 with applied changes - -## Sequence of Instructions (Do not deviate, skip, or optimize) - -### 1. Load and Read Validation Standards - -Load and read fully: `{validation}` - -### 2. Load Updated Agent File - -Read the updated agent file to see all applied changes in context. - -### 3. Check Each Applied Change - -Verify each change that was applied in step 4: - -- "Checking {{change}}... ✓ Works correctly" -- "Validating {{modification}}... ✓ Follows best practices" - -### 4. Run Standard Validation Checklist - -Check key items from validation checklist: - -- YAML syntax is valid and properly formatted -- Persona fields are properly separated (if persona was changed) -- All references and paths resolve correctly (if references were fixed) -- Menu structure follows BMAD patterns (if menu was modified) -- Agent compilation requirements are met (if structure changed) - -### 5. Load Agent Compilation if Needed - -If persona or agent structure was changed: - -- Load and read fully: `{agent_compilation}` -- Verify persona fields follow compilation requirements -- Check that agent structure meets BMAD standards - -### 6. Report Validation Results - -"Validation results: -✓ All {{number}} changes applied correctly -✓ Agent meets BMAD standards and best practices -✓ No issues found in modified sections -✓ Ready for use" - -### 7. Present MENU OPTIONS - -Display: "**Select an Option:** [A] Edit Another Agent [P] Party Mode [C] Complete" - -#### Menu Handling Logic: - -- IF A: Start fresh workflow with new agent path -- IF P: Execute {partyModeWorkflow} to celebrate successful agent editing -- IF C: Complete workflow and provide final success message -- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options) - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed when user selects 'A', 'P', or 'C' -- After party mode execution, return to this menu -- User can chat or ask questions - always respond and then end with display again of the menu options - -## CRITICAL STEP COMPLETION NOTE - -ONLY WHEN [C complete option] is selected and [all changes from step 4 have been validated successfully], will you then provide a final workflow completion message. The agent editing workflow is complete. - ---- - -## 🚨 SYSTEM SUCCESS/FAILURE METRICS - -### ✅ SUCCESS: - -- All applied changes from step 4 validated successfully -- Agent meets BMAD standards and best practices -- Validation checklist completed with no critical issues -- Clear validation report provided to user -- Menu presented and user input handled correctly - -### ❌ SYSTEM FAILURE: - -- Not validating all applied changes from step 4 -- Making modifications during validation step -- Skipping validation checklist or standards checks -- Not reporting validation results clearly -- Not loading references when needed for specific validation - -**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmb/workflows/edit-agent/workflow.md b/src/modules/bmb/workflows/edit-agent/workflow.md deleted file mode 100644 index 95650b35..00000000 --- a/src/modules/bmb/workflows/edit-agent/workflow.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: edit-agent -description: Edit existing BMAD agents while following all best practices and conventions -web_bundle: false ---- - -# Edit Agent Workflow - -**Goal:** Edit existing BMAD agents following best practices with targeted analysis and direct updates. - -**Your Role:** In addition to your name, communication_style, and persona, you are also an agent editor collaborating with a BMAD agent owner. This is a partnership, not a client-vendor relationship. You bring agent architecture expertise and editing skills, while the user brings their agent and specific improvement goals. Work together as equals. - ---- - -## WORKFLOW ARCHITECTURE - -This uses **step-file architecture** for disciplined execution: - -### Core Principles - -- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly -- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so -- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed -- **State Tracking**: Document progress in context for editing workflows (no output file frontmatter needed) -- **Append-Only Building**: Build documents by appending content as directed to the output file - -### Step Processing Rules - -1. **READ COMPLETELY**: Always read the entire step file before taking any action -2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate -3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection -4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) -5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step -6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file - -### Critical Rules (NO EXCEPTIONS) - -- 🛑 **NEVER** load multiple step files simultaneously -- 📖 **ALWAYS** read entire step file before execution -- 🚫 **NEVER** skip steps or optimize the sequence -- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step -- 🎯 **ALWAYS** follow the exact instructions in the step file -- ⏸️ **ALWAYS** halt at menus and wait for user input -- 📋 **NEVER** create mental todo lists from future steps - ---- - -## INITIALIZATION SEQUENCE - -### 1. Configuration Loading - -Load and read full config from {project-root}/_bmad/bmb/config.yaml and resolve: - -- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language` -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### 2. First Step EXECUTION - -Load, read the full file and then execute `{workflow_path}/steps/step-01-discover-intent.md` to begin the workflow. From 8b92e5ee59c70076e5e7323f639a5cfcb8840789 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Wed, 31 Dec 2025 03:06:16 +0800 Subject: [PATCH 6/6] Release 6.0.0-alpha.22 Major features: - Unified Agent Workflow: Create/Edit/Validate consolidated into single workflow - Agent Knowledge System: Comprehensive data file architecture for agent building - Deep Language Integration: All sharded workflows support language choice - Core Module Documentation: New docs for brainstorming, party mode, advanced elicitation - BMAD Core Concepts: New documentation structure for agents, workflows, modules - Create-Tech-Spec Sharded: Converted to sharded format with orient-first pattern 466 files changed, 12,983 insertions(+), 12,047 deletions(-) --- CHANGELOG.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++ package-lock.json | 4 +- package.json | 2 +- 3 files changed, 159 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e20cdb6..e23cf8b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,161 @@ # Changelog +## [6.0.0-alpha.22] + +**Release: December 31, 2025** + +### 🌟 Key Highlights + +1. **Unified Agent Workflow**: Create, Edit, and Validate workflows consolidated into single powerful agent workflow with separate step paths +2. **Agent Knowledge System**: Comprehensive data file architecture with persona properties, validation patterns, and crafting principles +3. **Deep Language Integration**: All sharded progressive workflows now support language choice at every step +4. **Core Module Documentation**: Extensive docs for core workflows (brainstorming, party mode, advanced elicitation) +5. **BMAD Core Concepts**: New documentation structure explaining agents, workflows, modules, and installation +6. **Tech Spec Sharded**: create-tech-spec workflow converted to sharded format with orient-first pattern + +### 🤖 Unified Agent Workflow (Major Feature) + +**Consolidated Architecture:** + +- **Single Workflow, Three Paths**: Create, Edit, and Validate operations unified under `src/modules/bmb/workflows/agent/` +- **steps-c/**: Create path with 9 comprehensive steps for building new agents +- **steps-e/**: Edit path with 10 steps for modifying existing agents +- **steps-v/**: Validate path for standalone agent validation review +- **data/**: Centralized knowledge base for all agent-building intel + +### 📚 Agent Knowledge System + +**Data File Architecture:** + +Located in `src/modules/bmb/workflows/agent/data/`: + +- **agent-metadata.md** (208 lines) - Complete metadata field reference +- **agent-menu-patterns.md** (233 lines) - Menu design patterns and best practices +- **agent-compilation.md** (273 lines) - Compilation process documentation +- **persona-properties.md** (266 lines) - Persona crafting properties and examples +- **principles-crafting.md** (292 lines) - Core principles for agent design +- **critical-actions.md** (120 lines) - Critical action patterns +- **expert-agent-architecture.md** (236 lines) - Expert agent structure +- **expert-agent-validation.md** (173 lines) - Expert-specific validation +- **module-agent-validation.md** (124 lines) - Module-specific validation +- **simple-agent-architecture.md** (204 lines) - Simple agent structure +- **simple-agent-validation.md** (132 lines) - Simple agent validation +- **understanding-agent-types.md** (222 lines) - Agent type comparison +- **brainstorm-context.md** - Brainstorming guidance +- **communication-presets.csv** - Communication style presets + +**Reference Examples:** + +- **reference/module-examples/architect.agent.yaml** - Module agent example +- **reference/simple-examples/commit-poet.agent.yaml** - Simple agent example +- **journal-keeper/** - Complete sidecar pattern example + +**Templates:** + +- **templates/simple-agent.template.md** - Simple agent template +- **templates/expert-agent-template/expert-agent.template.md** - Expert agent template +- **templates/expert-agent-sidecar/** - Sidecar templates (instructions, memories) + +### 🌍 Deep Language Integration + +**Progressive Workflow Language Support:** + +- **Every Step Biased**: All sharded progressive workflow steps now include language preference context +- **260+ Files Updated**: Comprehensive language integration across: + - Core workflows (brainstorming, party mode, advanced elicitation) + - BMB workflows (create-agent, create-module, create-workflow, edit-workflow, etc.) + - BMGD workflows (game-brief, gdd, narrative, game-architecture, etc.) + - BMM workflows (research, create-ux-design, prd, create-architecture, etc.) +- **Tested Languages**: Verified working with Spanish and Pirate Speak +- **Natural Conversations**: AI agents respond in configured language throughout workflow + +### 📖 Core Module Documentation + +**New Core Documentation Structure:** + +`docs/modules/core/`: + +- **index.md** - Core module overview +- **core-workflows.md** - Core workflow documentation +- **core-tasks.md** - Core task reference +- **brainstorming.md** (100 lines) - Brainstorming workflow guide +- **party-mode.md** (50 lines) - Party mode guide +- **advanced-elicitation.md** (105 lines) - Advanced elicitation techniques +- **document-sharding-guide.md** (133 lines) - Sharded workflow format guide +- **global-core-config.md** - Global core configuration reference + +**Advanced Elicitation Moved:** + +- **From**: `docs/` root +- **To**: `src/core/workflows/advanced-elicitation/` +- **Status**: Now a proper core workflow with methods.csv + +### 📚 BMAD Core Concepts Documentation + +**New Documentation Structure:** + +`docs/bmad-core-concepts/`: + +- **index.md** - Core concepts introduction +- **agents.md** (93 lines) - Understanding agents in BMAD +- **workflows.md** (89 lines) - Understanding workflows in BMAD +- **modules.md** (76 lines) - Understanding modules (BMM, BMGD, CIS, BMB, Core) +- **installing/index.md** (77 lines) - Installation guide +- **installing/upgrading.md** (144 lines) - Upgrading guide +- **bmad-customization/index.md** - Customization overview +- **bmad-customization/agents.md** - Agent customization guide +- **bmad-customization/workflows.md** (30 lines) - Workflow customization guide +- **web-bundles/index.md** (34 lines) - Web bundle distribution guide + +**Documentation Cleanup:** + +- **Removed v4-to-v6-upgrade.md** - Outdated upgrade guide +- **Removed document-sharding-guide.md** from docs root (moved to core) +- **Removed web-bundles-gemini-gpt-guide.md** - Consolidated into web-bundles/index.md +- **Removed getting-started/installation.md** - Migrated to bmad-core-concepts +- **Removed all ide-info/*.md files** - Consolidated into web-bundles documentation + +### 🔧 Create-Tech-Spec Sharded Conversion + +**Monolithic to Sharded:** + +- **From**: Single `workflow.yaml` with `instructions.md` +- **To**: Sharded `workflow.md` with individual step files +- **Pattern**: Orient-first approach (understand before investigating) + +### 🔨 Additional Improvements + +**Workflow Status Path Fixes:** + +- **Corrected Discovery Paths**: workflow-status workflows now properly use planning_artifacts and implementation_artifacts +- **Updated All Path Files**: enterprise-brownfield, enterprise-greenfield, method-brownfield, method-greenfield + +**Documentation Updates:** + +- **BMB Agent Creation Guide**: Comprehensive 166-line guide for agent creation +- **Workflow Vendoring Doc**: New 42-line guide on workflow customization and inheritance +- **Document Project Reference**: Moved from BMM docs to shared location +- **Workflows Planning Guide**: New 89-line guide for planning workflows + +**BMB Documentation Streamlining:** + +- **Removed Redundant Docs**: Eliminated duplicate documentation in `src/modules/bmb/docs/` +- **Step File Rules**: New 469-line comprehensive guide for step file creation +- **Agent Docs Moved**: Agent architecture and validation docs moved to workflow data/ + +**Windows Inquirer Fix:** + +- **Another Default Addition**: Additional inquirer default value setting for better Windows multiselection support + +**Code Quality:** + +- **Removed Old BMM README**: Consolidated module documentation +- **Removed BMM Troubleshooting**: 661-line doc moved to shared location +- **Removed Enterprise Agentic Development**: 686-line doc consolidated +- **Removed Scale Adaptive System**: 618-line doc consolidated + +--- + ## [6.0.0-alpha.21] **Release: December 27, 2025** diff --git a/package-lock.json b/package-lock.json index 428a80f6..4a684718 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "bmad-method", - "version": "6.0.0-alpha.21", + "version": "6.0.0-alpha.22", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "bmad-method", - "version": "6.0.0-alpha.21", + "version": "6.0.0-alpha.22", "license": "MIT", "dependencies": { "@kayvan/markdown-tree-parser": "^1.6.1", diff --git a/package.json b/package.json index 90722299..c7bab7f1 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-method", - "version": "6.0.0-alpha.21", + "version": "6.0.0-alpha.22", "description": "Breakthrough Method of Agile AI-driven Development", "keywords": [ "agile",