create-byan-agent 2.1.1 → 2.2.2

package/install/templates/_byan/bmb/workflows/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: _byan/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: |
+        <instructions>What this does</instructions>
+        <process>1. Step one 2. Step two</process>
+
+    - 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 | `_byan/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: |
+      <instructions>What this does</instructions>
+      <process>1. Step 2. Step</process>
+
+menu:
+  - trigger: WC or fuzzy match on write
+    action: "#write-commit"
+```
+
+**Tips:** Use semantic XML tags (`<instructions>`, `<process>`, `<example>`), 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** (`<instructions>`, `<process>`, `<example>`)
+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

package/install/templates/_byan/bmb/workflows/agent/data/simple-agent-validation.md

@@ -0,0 +1,133 @@
+# 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`, `hasSidecar`
+- [ ] `agent.metadata.hasSidecar` is `false` (Simple agents don't have sidecars)
+- [ ] `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: `<instructions>`, `<process>`, 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'`

package/install/templates/_byan/bmb/workflows/agent/data/understanding-agent-types.md

@@ -0,0 +1,222 @@
+# Understanding Agent Types: Simple VS Expert VS Module
+
+> **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`
+
+---
+
+## 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 in one file. No external dependencies. No memory.**
+
+```
+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
+
+**Sidecar folder with persistent memory, workflows, knowledge files.**
+
+```
+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
+```
+
+**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
+
+**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
+
+**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
+
+Two distinct purposes:
+
+#### 1. Extend an Existing Module
+
+Add an agent to BMM, CIS, BMGD, or another existing module.
+
+**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
+
+**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
+
+**Reference:** `./data/reference/module-examples/security-engineer.agent.yaml`
+
+#### 2. Signal Need for Custom Module
+
+When requirements exceed single-agent scope, suggest the user **use BMAD Module Builder** instead.
+
+**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..."
+
+**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
+
+**→ Use BMAD Module Builder workflow to create the module, then create individual agents within it.**
+
+---
+
+## Side-by-Side Comparison
+
+| 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           |
+
+**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.
+
+---
+
+## Selection Checklist
+
+**Choose Simple if:**
+- [ ] One clear purpose
+- [ ] No need to remember past sessions
+- [ ] All logic fits in ~250 lines
+- [ ] Each interaction is independent
+
+**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
+
+**Then, for EITHER Simple or Expert:**
+- [ ] Extending existing module (BMM/CIS/BMGD/etc.) → Make it a Module Agent
+- [ ] Independent operation → Keep it Standalone
+
+**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
+
+---
+
+## Tips for the LLM Facilitator
+
+- 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
+
+---
+
+## 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.

package/install/templates/_byan/bmb/workflows/agent/steps-c/step-01-brainstorm.md

@@ -0,0 +1,128 @@
+---
+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}/_byan/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 [C] Continue to Discovery?"
+
+#### Menu Handling Logic:
+
+- 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.