create-byan-agent 2.18.0 → 2.19.0

package/install/templates/_byan/workflow/simple/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/agent/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/workflow/simple/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/workflow/simple/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.

package/install/templates/_byan/workflow/simple/agent/steps-c/step-02-discovery.md

@@ -0,0 +1,170 @@
+---
+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}/_byan/workflow/simple/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_byan/workflow/simple/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
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+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