create-byan-agent 2.18.0 → 2.19.0

package/install/templates/_byan/workflow/simple/advanced-elicitation/workflow.xml

@@ -0,0 +1,117 @@
+<task id="_byan/workflow/simple/advanced-elicitation/workflow.xml" name="Advanced Elicitation" standalone="true"
+  methods="{project-root}/_byan/workflow/simple/advanced-elicitation/methods.csv"
+  agent-party="{project-root}/_byan/_config/agent-manifest.csv">
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
+    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
+    <i>YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`</i>
+  </llm>
+
+  <integration description="When called from workflow">
+    <desc>When called during template workflow processing:</desc>
+    <i>1. Receive or review the current section content that was just generated or</i>
+    <i>2. Apply elicitation methods iteratively to enhance that specific content</i>
+    <i>3. Return the enhanced version back when user selects 'x' to proceed and return back</i>
+    <i>4. The enhanced content replaces the original section content in the output document</i>
+  </integration>
+
+  <flow>
+    <step n="1" title="Method Registry Loading">
+      <action>Load and read {{methods}} and {{agent-party}}</action>
+
+      <csv-structure>
+        <i>category: Method grouping (core, structural, risk, etc.)</i>
+        <i>method_name: Display name for the method</i>
+        <i>description: Rich explanation of what the method does, when to use it, and why it's valuable</i>
+        <i>output_pattern: Flexible flow guide using → arrows (e.g., "analysis → insights → action")</i>
+      </csv-structure>
+
+      <context-analysis>
+        <i>Use conversation history</i>
+        <i>Analyze: content type, complexity, stakeholder needs, risk level, and creative potential</i>
+      </context-analysis>
+
+      <smart-selection>
+        <i>1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential</i>
+        <i>2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV</i>
+        <i>3. Select 5 methods: Choose methods that best match the context based on their descriptions</i>
+        <i>4. Balance approach: Include mix of foundational and specialized techniques as appropriate</i>
+      </smart-selection>
+    </step>
+
+    <step n="2" title="Present Options and Handle Responses">
+
+      <format>
+        **Advanced Elicitation Options (If you launched Party Mode, they will participate randomly)**
+        Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed:
+
+        1. [Method Name]
+        2. [Method Name]
+        3. [Method Name]
+        4. [Method Name]
+        5. [Method Name]
+        r. Reshuffle the list with 5 new options
+        a. List all methods with descriptions
+        x. Proceed / No Further Actions
+      </format>
+
+      <response-handling>
+        <case n="1-5">
+          <i>Execute the selected method using its description from the CSV</i>
+          <i>Adapt the method's complexity and output format based on the current context</i>
+          <i>Apply the method creatively to the current section content being enhanced</i>
+          <i>Display the enhanced version showing what the method revealed or improved</i>
+          <i>CRITICAL: Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response.</i>
+          <i>CRITICAL: ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to
+            follow the instructions given by the user.</i>
+          <i>CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations</i>
+        </case>
+        <case n="r">
+          <i>Select 5 random methods from advanced-elicitation-methods.csv, present new list with same prompt format</i>
+          <i>When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being
+            potentially the most useful for the document or section being discovered</i>
+        </case>
+        <case n="x">
+          <i>Complete elicitation and proceed</i>
+          <i>Return the fully enhanced content back to create-doc.md</i>
+          <i>The enhanced content becomes the final version for that section</i>
+          <i>Signal completion back to create-doc.md to continue with next section</i>
+        </case>
+        <case n="a">
+          <i>List all methods with their descriptions from the CSV in a compact table</i>
+          <i>Allow user to select any method by name or number from the full list</i>
+          <i>After selection, execute the method as described in the n="1-5" case above</i>
+        </case>
+        <case n="direct-feedback">
+          <i>Apply changes to current section content and re-present choices</i>
+        </case>
+        <case n="multiple-numbers">
+          <i>Execute methods in sequence on the content, then re-offer choices</i>
+        </case>
+      </response-handling>
+    </step>
+
+    <step n="3" title="Execution Guidelines">
+      <i>Method execution: Use the description from CSV to understand and apply each method</i>
+      <i>Output pattern: Use the pattern as a flexible guide (e.g., "paths → evaluation → selection")</i>
+      <i>Dynamic adaptation: Adjust complexity based on content needs (simple to sophisticated)</i>
+      <i>Creative application: Interpret methods flexibly based on context while maintaining pattern consistency</i>
+      <i>Focus on actionable insights</i>
+      <i>Stay relevant: Tie elicitation to specific content being analyzed (the current section from the document being created unless user
+        indicates otherwise)</i>
+      <i>Identify personas: For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory
+        already</i>
+      <i>Critical loop behavior: Always re-offer the 1-5,r,a,x choices after each method execution</i>
+      <i>Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session</i>
+      <i>Each method application builds upon previous enhancements</i>
+      <i>Content preservation: Track all enhancements made during elicitation</i>
+      <i>Iterative enhancement: Each selected method (1-5) should:</i>
+      <i> 1. Apply to the current enhanced version of the content</i>
+      <i> 2. Show the improvements made</i>
+      <i> 3. Return to the prompt for additional elicitations or completion</i>
+    </step>
+  </flow>
+</task>

package/install/templates/_byan/workflow/simple/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: "_byan/..."
+    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: |
+        <instructions>Prompt content</instructions>
+
+  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
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file</step>
+  <step n="2">Load config to get {user_name}, {communication_language}</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <!-- YOUR critical_actions inserted here as steps 4, 5, etc. -->
+  <step n="N">ALWAYS communicate in {communication_language}</step>
+  <step n="N+1">Show greeting + numbered menu</step>
+  <step n="N+2">STOP and WAIT for user input</step>
+  <step n="N+3">Input resolution rules</step>
+  <menu-handlers>...</menu-handlers>
+  <rules>...</rules>
+</activation>
+```
+**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
+<handler type="workflow">
+  When menu item has: workflow="path/to/workflow.yaml"
+  → Load workflow.xml and execute with workflow-config parameter
+</handler>
+<handler type="exec">
+  When menu item has: exec="path/to/file.md"
+  → Load and execute the file at that path
+</handler>
+```
+**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: "_byan/agent/architect/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}/_byan/workflow/simple/workflow-status/workflow.yaml"
+      description: "[WS] Get workflow status..."
+
+    - trigger: CA or fuzzy match on create-architecture
+      exec: "{project-root}/_byan/workflow/simple/3-solutioning/create-architecture/workflow.md"
+      description: "[CA] Create an Architecture Document"
+
+    - trigger: IR or fuzzy match on implementation-readiness
+      exec: "{project-root}/_byan/workflow/simple/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
+<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file (already in context)</step>
+  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT...</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+  <step n="4">Show greeting using {user_name} from config...</step>
+  <step n="5">STOP and WAIT for user input...</step>
+  <step n="6">On user input: Number → execute menu item[n]...</step>
+  <step n="7">When executing a menu item: Check menu-handlers section...</step>
+
+  <menu-handlers>
+    <handlers>
+      <handler type="workflow">...</handler>
+      <handler type="exec">...</handler>
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    <r>ALWAYS communicate in {communication_language}</r>
+    <r>Stay in character until exit selected</r>
+    <r>Display Menu items as the item dictates...</r>
+    <r>Load files ONLY when executing menu items...</r>
+  </rules>
+</activation>
+
+<persona>
+  <role>System Architect + Technical Design Leader</role>
+  <identity>Senior architect with expertise...</identity>
+  <communication_style>Speaks in calm, pragmatic tones...</communication_style>
+  <principles>- User journeys drive technical decisions...</principles>
+</persona>
+
+<menu>
+  <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+  <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+  <item cmd="WS...">[WS] Get workflow status...</item>           ← YOUR CUSTOM ITEMS
+  <item cmd="CA...">[CA] Create an Architecture Document</item>
+  <item cmd="IR...">[IR] Implementation Readiness Review</item>
+  <item cmd="PM...">[PM] Start Party Mode</item>
+  <item cmd="DA...">[DA] Dismiss Agent</item>
+</menu>
+</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
+<step n="4">Load COMPLETE file ./agent-sidecar/memories.md</step>
+<step n="5">Load COMPLETE file ./agent-sidecar/instructions.md</step>
+<step n="6">ONLY read/write files in ./agent-sidecar/</step>
+<step n="7">ALWAYS communicate in {communication_language}</step>
+```
+
+---
+
+## 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

package/install/templates/_byan/workflow/simple/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}/_byan/workflow/simple/create-prd/workflow.md'
+  description: '[CP] Create Product Requirements Document'
+
+- trigger: GB or fuzzy match on brainstorm
+  exec: '{project-root}/_byan/workflow/simple/brainstorming/workflow.md'
+  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}/_byan/command/team-standup.md'
+  data: '{project-root}/_byan/_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: |
+      <instructions>Analyze code for patterns</instructions>
+      <process>1. Identify structure 2. Check issues 3. Suggest improvements</process>
+
+menu:
+  - trigger: AC or fuzzy match on analyze-code
+    action: '#analyze-code'
+    description: '[AC] Analyze code patterns'
+```
+
+**Common XML tags:** `<instructions>`, `<process>`, `<example>`, `<output_format>`
+
+---
+
+## Path Variables
+
+**Always use variables, never hardcoded paths:**
+
+```yaml
+# ✅ CORRECT
+exec: '{project-root}/_byan/workflow/simple/brainstorming/workflow.md'
+data: '{project-root}/_data/metrics.csv'
+
+# ❌ WRONG
+exec: '../../../core/workflows/brainstorming/workflow.md'
+```
+
+**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}/_byan/memoire/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: |
+      <instructions>Format code to style guidelines</instructions>
+      <process>1. Indentation 2. Spacing 3. Naming</process>
+
+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}/_byan/memoire/journal-keeper-sidecar/memories.md'
+  - 'Load COMPLETE file {project-root}/_byan/memoire/journal-keeper-sidecar/instructions.md'
+  - 'ONLY read/write files in {project-root}/_byan/memoire/journal-keeper-sidecar/'
+
+prompts:
+  - id: guided-entry
+    content: |
+      <instructions>Guide through journal entry</instructions>
+
+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}/_byan/memoire/journal-keeper-sidecar/entries/entry-{date}.md'
+    description: '[QC] Quick capture'
+
+  - trigger: SM or fuzzy match on save-memory
+    action: 'Update {project-root}/_byan/memoire/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}/_byan/workflow/simple/workflow-status/workflow.md'
+    description: '[WI] Initialize workflow path'
+
+  - trigger: BS or fuzzy match on brainstorm
+    exec: '{project-root}/_byan/workflow/simple/brainstorming/workflow.md'
+    description: '[BS] Guided brainstorming [K,T,A,B,C]'
+
+  - trigger: CP or fuzzy match on create-prd
+    exec: '{project-root}/_byan/workflow/simple/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}/_byan/memoire/{sidecar-folder}/`