@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.3

package/src/bmb/workflows/agent/data/understanding-agent-types.md

@@ -1,126 +1,126 @@
-# Understanding Agent Types
-
-> **LLM Instructions:** Load example files when helping users:
-> - Without sidecar: `{workflow_path}/data/reference/without-sidecar/commit-poet.agent.yaml`
-> - With sidecar: `{workflow_path}/data/reference/with-sidecar/journal-keeper/`
-
----
-
-## Decision Tree
-
-```
-Multiple personas/roles OR multi-user OR mixed data scope?
-├── YES → Use BMAD Module Builder
-└── NO → Single Agent
-    └── Need memory across sessions?
-        ├── YES → hasSidecar: true
-        └── NO → hasSidecar: false
-```
-
-**Key:** All agents have equal capability. Difference is memory/state management only.
-
----
-
-## Without Sidecar (`hasSidecar: false`)
-
-**Single file, stateless, ~250 lines max**
-
-```
-agent-name.agent.yaml
-├── metadata.hasSidecar: false
-├── persona
-├── prompts (inline)
-└── menu (triggers → #prompt-id or inline)
-```
-
-| When to Use | Examples |
-|-------------|----------|
-| Single-purpose utility | Commit Poet |
-| Each session independent | Snarky Weather Bot |
-| All knowledge fits in YAML | Pun-making Barista |
-| Menu handlers 1-2 lines | Motivational Gym Bro |
-| Persona-driven (fun/character) | Sassy Fortune Teller |
-
-**Optional critical_actions:** Allowed for activation behaviors (quotes, data fetches). Must NOT reference sidecar files.
-
----
-
-## With Sidecar (`hasSidecar: true`)
-
-**Persistent memory, knowledge, workflows**
-
-```
-agent-name.agent.yaml
-└── agent-name-sidecar/
-    ├── memories.md           # User profile, session history
-    ├── instructions.md       # Protocols, boundaries
-    ├── [custom-files].md     # Tracking, goals, etc.
-    ├── workflows/            # Large workflows on-demand
-    └── knowledge/            # Domain reference
-```
-
-| When to Use | Examples |
-|-------------|----------|
-| Remember across sessions | Journal companion |
-| User preferences/settings | Novel writing buddy |
-| Personal knowledge base | Job augmentation agent |
-| Learning/evolving over time | Therapy/health tracking |
-| Domain-specific + restricted access | Fitness coach with PRs |
-| Complex multi-step workflows | Language tutor |
-
-**Required critical_actions:**
-```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}/"
-```
-
----
-
-## Comparison
-
-| Aspect | Without Sidecar | With Sidecar |
-|--------|----------------|--------------|
-| Structure | Single YAML | YAML + sidecar/ |
-| Persistent memory | No | Yes |
-| critical_actions | Optional | MANDATORY |
-| Workflows | Inline prompts | Sidecar files |
-| File access | Project/output | Restricted to sidecar |
-| Session state | Stateless | Remembers |
-| Best for | Focused skills | Long-term relationships |
-
----
-
-## Selection Checklist
-
-**Without sidecar:**
-- [ ] One clear purpose, related skills
-- [ ] No cross-session memory needed
-- [ ] Fits in ~250 lines
-- [ ] Independent interactions
-- [ ] Persona-driven value
-
-**With sidecar:**
-- [ ] Memory across sessions
-- [ ] Personal knowledge base
-- [ ] Domain-specific expertise
-- [ ] Restricted file access
-- [ ] Progress tracking/history
-- [ ] Complex workflows
-
-**Escalate to Module Builder if:**
-- [ ] Multiple distinct personas needed
-- [ ] Many specialized workflows
-- [ ] Multiple users with mixed data scope
-- [ ] Shared resources across agents
-
----
-
-## Quick Tips
-
-- Unsure? Ask about **memory needs first**
-- Multiple personas → Module Builder, not one giant agent
-- Ask: memory needs, user count, data scope, integration plans
-- Personality agents → usually without sidecar
-- Relationship/coaching agents → usually with sidecar
+# Understanding Agent Types
+
+> **LLM Instructions:** Load example files when helping users:
+> - Without sidecar: `{workflow_path}/data/reference/without-sidecar/commit-poet.agent.yaml`
+> - With sidecar: `{workflow_path}/data/reference/with-sidecar/journal-keeper/`
+
+---
+
+## Decision Tree
+
+```
+Multiple personas/roles OR multi-user OR mixed data scope?
+├── YES → Use BMAD Module Builder
+└── NO → Single Agent
+    └── Need memory across sessions?
+        ├── YES → hasSidecar: true
+        └── NO → hasSidecar: false
+```
+
+**Key:** All agents have equal capability. Difference is memory/state management only.
+
+---
+
+## Without Sidecar (`hasSidecar: false`)
+
+**Single file, stateless, ~250 lines max**
+
+```
+agent-name.agent.yaml
+├── metadata.hasSidecar: false
+├── persona
+├── prompts (inline)
+└── menu (triggers → #prompt-id or inline)
+```
+
+| When to Use | Examples |
+|-------------|----------|
+| Single-purpose utility | Commit Poet |
+| Each session independent | Snarky Weather Bot |
+| All knowledge fits in YAML | Pun-making Barista |
+| Menu handlers 1-2 lines | Motivational Gym Bro |
+| Persona-driven (fun/character) | Sassy Fortune Teller |
+
+**Optional critical_actions:** Allowed for activation behaviors (quotes, data fetches). Must NOT reference sidecar files.
+
+---
+
+## With Sidecar (`hasSidecar: true`)
+
+**Persistent memory, knowledge, workflows**
+
+```
+agent-name.agent.yaml
+└── agent-name-sidecar/
+    ├── memories.md           # User profile, session history
+    ├── instructions.md       # Protocols, boundaries
+    ├── [custom-files].md     # Tracking, goals, etc.
+    ├── workflows/            # Large workflows on-demand
+    └── knowledge/            # Domain reference
+```
+
+| When to Use | Examples |
+|-------------|----------|
+| Remember across sessions | Journal companion |
+| User preferences/settings | Novel writing buddy |
+| Personal knowledge base | Job augmentation agent |
+| Learning/evolving over time | Therapy/health tracking |
+| Domain-specific + restricted access | Fitness coach with PRs |
+| Complex multi-step workflows | Language tutor |
+
+**Required critical_actions:**
+```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}/"
+```
+
+---
+
+## Comparison
+
+| Aspect | Without Sidecar | With Sidecar |
+|--------|----------------|--------------|
+| Structure | Single YAML | YAML + sidecar/ |
+| Persistent memory | No | Yes |
+| critical_actions | Optional | MANDATORY |
+| Workflows | Inline prompts | Sidecar files |
+| File access | Project/output | Restricted to sidecar |
+| Session state | Stateless | Remembers |
+| Best for | Focused skills | Long-term relationships |
+
+---
+
+## Selection Checklist
+
+**Without sidecar:**
+- [ ] One clear purpose, related skills
+- [ ] No cross-session memory needed
+- [ ] Fits in ~250 lines
+- [ ] Independent interactions
+- [ ] Persona-driven value
+
+**With sidecar:**
+- [ ] Memory across sessions
+- [ ] Personal knowledge base
+- [ ] Domain-specific expertise
+- [ ] Restricted file access
+- [ ] Progress tracking/history
+- [ ] Complex workflows
+
+**Escalate to Module Builder if:**
+- [ ] Multiple distinct personas needed
+- [ ] Many specialized workflows
+- [ ] Multiple users with mixed data scope
+- [ ] Shared resources across agents
+
+---
+
+## Quick Tips
+
+- Unsure? Ask about **memory needs first**
+- Multiple personas → Module Builder, not one giant agent
+- Ask: memory needs, user count, data scope, integration plans
+- Personality agents → usually without sidecar
+- Relationship/coaching agents → usually with sidecar

package/src/bmb/workflows/agent/steps-c/step-01-brainstorm.md

@@ -1,129 +1,129 @@
----
-name: 'step-01-brainstorm'
-description: 'Optional brainstorming for agent ideas'
-
-# File References
-nextStepFile: './step-02-discovery.md'
-brainstormContext: ../data/brainstorm-context.md
-brainstormWorkflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
----
-
-# Step 1: Optional Brainstorming
-
-## STEP GOAL:
-
-Optional creative exploration to generate agent ideas through structured brainstorming before proceeding to agent discovery and development.
-
-## 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 creative facilitator who helps users explore agent possibilities
-- ✅ 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 creative brainstorming expertise, user brings their goals and domain knowledge, together we explore innovative agent concepts
-- ✅ Maintain collaborative inspiring tone throughout
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Present brainstorming as optional first step with clear benefits
-- 💾 Preserve brainstorming output for reference in subsequent steps
-- 📖 Use brainstorming workflow when user chooses to participate
-- 🚫 FORBIDDEN to proceed without clear user choice
-
-## CONTEXT BOUNDARIES:
-
-- Available context: User is starting agent creation workflow
-- Focus: Offer optional creative exploration before formal discovery
-- Limits: No mandatory brainstorming, no pressure tactics
-- Dependencies: User choice to participate or skip brainstorming
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
-### 1. Present Brainstorming Opportunity
-
-Present this to the user:
-
-"Would you like to brainstorm agent ideas first? This can help spark creativity and explore possibilities you might not have considered yet.
-
-**Benefits of brainstorming:**
-
-- Generate multiple agent concepts quickly
-- Explore different use cases and approaches
-- Discover unique combinations of capabilities
-- Get inspired by creative prompts
-
-**Skip if you already have a clear agent concept in mind!**
-
-This step is completely optional - you can move directly to agent discovery if you already know what you want to build.
-
-Would you like to brainstorm? [y/n]"
-
-Wait for clear user response (yes/no or y/n).
-
-### 2. Handle User Choice
-
-**If user answers yes:**
-
-- 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
-
-**If user answers no:**
-
-- Acknowledge their choice respectfully
-- Proceed directly to menu options
-
-### 3. Present MENU OPTIONS
-
-Display: "Are you ready to [AR] Adversarial Review [C] Continue to Discovery?"
-
-#### Menu Handling Logic:
-
-- IF AR: Execute {project-root}/_bmad/core/tasks/review-adversarial-general.xml — pass the current editPlan (or plan document in context) as the content to review; display findings with recommendations; then redisplay this menu
-- IF C: Load, read entire file, then execute {nextStepFile}
-
-#### 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 [user choice regarding brainstorming handled], will you then load and read fully `{nextStepFile}` to execute and begin agent discovery.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- User understands brainstorming is optional
-- User choice (yes/no) clearly obtained and respected
-- Brainstorming workflow executes correctly when chosen
-- Brainstorming output preserved when generated
-- Menu presented and user input handled correctly
-- Smooth transition to agent discovery phase
-
-### ❌ SYSTEM FAILURE:
-
-- Making brainstorming mandatory or pressuring user
-- Proceeding without clear user choice on brainstorming
-- Not preserving brainstorming output when generated
-- Failing to execute brainstorming workflow when chosen
-- Not respecting user's choice to skip brainstorming
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+---
+name: 'step-01-brainstorm'
+description: 'Optional brainstorming for agent ideas'
+
+# File References
+nextStepFile: './step-02-discovery.md'
+brainstormContext: ../data/brainstorm-context.md
+brainstormWorkflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
+---
+
+# Step 1: Optional Brainstorming
+
+## STEP GOAL:
+
+Optional creative exploration to generate agent ideas through structured brainstorming before proceeding to agent discovery and development.
+
+## 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 creative facilitator who helps users explore agent possibilities
+- ✅ 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 creative brainstorming expertise, user brings their goals and domain knowledge, together we explore innovative agent concepts
+- ✅ Maintain collaborative inspiring tone throughout
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Present brainstorming as optional first step with clear benefits
+- 💾 Preserve brainstorming output for reference in subsequent steps
+- 📖 Use brainstorming workflow when user chooses to participate
+- 🚫 FORBIDDEN to proceed without clear user choice
+
+## CONTEXT BOUNDARIES:
+
+- Available context: User is starting agent creation workflow
+- Focus: Offer optional creative exploration before formal discovery
+- Limits: No mandatory brainstorming, no pressure tactics
+- Dependencies: User choice to participate or skip brainstorming
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Present Brainstorming Opportunity
+
+Present this to the user:
+
+"Would you like to brainstorm agent ideas first? This can help spark creativity and explore possibilities you might not have considered yet.
+
+**Benefits of brainstorming:**
+
+- Generate multiple agent concepts quickly
+- Explore different use cases and approaches
+- Discover unique combinations of capabilities
+- Get inspired by creative prompts
+
+**Skip if you already have a clear agent concept in mind!**
+
+This step is completely optional - you can move directly to agent discovery if you already know what you want to build.
+
+Would you like to brainstorm? [y/n]"
+
+Wait for clear user response (yes/no or y/n).
+
+### 2. Handle User Choice
+
+**If user answers yes:**
+
+- 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
+
+**If user answers no:**
+
+- Acknowledge their choice respectfully
+- Proceed directly to menu options
+
+### 3. Present MENU OPTIONS
+
+Display: "Are you ready to [AR] Adversarial Review [C] Continue to Discovery?"
+
+#### Menu Handling Logic:
+
+- IF AR: Execute {project-root}/_bmad/core/tasks/review-adversarial-general.xml — pass the current editPlan (or plan document in context) as the content to review; display findings with recommendations; then redisplay this menu
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### 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 [user choice regarding brainstorming handled], will you then load and read fully `{nextStepFile}` to execute and begin agent discovery.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- User understands brainstorming is optional
+- User choice (yes/no) clearly obtained and respected
+- Brainstorming workflow executes correctly when chosen
+- Brainstorming output preserved when generated
+- Menu presented and user input handled correctly
+- Smooth transition to agent discovery phase
+
+### ❌ SYSTEM FAILURE:
+
+- Making brainstorming mandatory or pressuring user
+- Proceeding without clear user choice on brainstorming
+- Not preserving brainstorming output when generated
+- Failing to execute brainstorming workflow when chosen
+- Not respecting user's choice to skip brainstorming
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.