@zeyue0329/xiaoma-cli 1.0.49 → 6.0.0-alpha.14

package/src/modules/xmb/docs/agents/module-agent-architecture.md

@@ -0,0 +1,367 @@
+# Module Agent Architecture
+
+Full integration agents with workflow orchestration, module-specific paths, and professional tooling.
+
+## When to Use
+
+- Professional development workflows (business analysis, architecture design)
+- Team-oriented tools (project management, sprint planning)
+- Agents that orchestrate multiple workflows
+- Module-specific functionality (XMC, XMB, CIS, custom modules)
+- Agents with complex multi-step operations
+
+## File Location
+
+```
+src/modules/{module-code}/agents/{agent-name}.agent.yaml
+```
+
+Compiles to:
+
+```
+.xiaoma/{module-code}/agents/{agent-name}.md
+```
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    id: '{xiaoma_folder}/{module-code}/agents/{agent-name}.md'
+    name: 'Persona Name'
+    title: 'Professional Title'
+    icon: 'emoji'
+    module: '{module-code}'
+
+  persona:
+    role: 'Primary expertise and function'
+    identity: 'Background, experience, specializations'
+    communication_style: 'Interaction approach, tone, methodology'
+    principles: 'Core beliefs and methodology'
+
+  menu:
+    - trigger: workflow-action
+      workflow: '{project-root}/{xiaoma_folder}/{module-code}/workflows/{workflow-name}/workflow.yaml'
+      description: 'Execute module workflow'
+
+    - trigger: another-workflow
+      workflow: '{project-root}/{xiaoma_folder}/core/workflows/{workflow-name}/workflow.yaml'
+      description: 'Execute core workflow'
+
+    - trigger: task-action
+      exec: '{project-root}/{xiaoma_folder}/{module-code}/tasks/{task-name}.xml'
+      description: 'Execute module task'
+
+    - trigger: cross-module
+      workflow: '{project-root}/{xiaoma_folder}/other-module/workflows/{workflow-name}/workflow.yaml'
+      description: 'Execute workflow from another module'
+
+    - trigger: with-template
+      exec: '{project-root}/{xiaoma_folder}/core/tasks/create-doc.xml'
+      tmpl: '{project-root}/{xiaoma_folder}/{module-code}/templates/{template-name}.md'
+      description: 'Create document from template'
+
+    - trigger: with-data
+      exec: '{project-root}/{xiaoma_folder}/{module-code}/tasks/{task-name}.xml'
+      data: '{project-root}/{xiaoma_folder}/_cfg/agent-manifest.csv'
+      description: 'Execute task with data file'
+```
+
+## Key Components
+
+### Metadata
+
+- **id**: Path with `{xiaoma_folder}` variable (resolved at install time)
+- **name**: Agent persona name
+- **title**: Professional role
+- **icon**: Single emoji
+- **module**: Module code (xmc, xmb, cis, custom)
+
+### Persona (Professional Voice)
+
+Module agents typically use **professional** communication styles:
+
+```yaml
+persona:
+  role: Strategic Business Analyst + Requirements Expert
+
+  identity: Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.
+
+  communication_style: Systematic and probing. Connects dots others miss. Structures findings hierarchically. Uses precise unambiguous language. Ensures all stakeholder voices heard.
+
+  principles: Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. Articulate requirements with absolute precision.
+```
+
+**Note:** Module agents usually don't use Handlebars templating since they're not user-customized - they're professional tools with fixed personalities.
+
+### Menu Handlers
+
+#### Workflow Handler (Most Common)
+
+```yaml
+menu:
+  - trigger: create-prd
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/prd/workflow.yaml'
+    description: 'Create Product Requirements Document'
+```
+
+Invokes XIAOMA workflow engine to execute multi-step processes.
+
+#### Task/Exec Handler
+
+```yaml
+menu:
+  - trigger: validate
+    exec: '{project-root}/{xiaoma_folder}/core/tasks/validate-workflow.xml'
+    description: 'Validate document structure'
+```
+
+Executes single-operation tasks.
+
+#### Template Handler
+
+```yaml
+menu:
+  - trigger: create-brief
+    exec: '{project-root}/{xiaoma_folder}/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/{xiaoma_folder}/xmc/templates/brief.md'
+    description: 'Create a Product Brief from template'
+```
+
+Combines task execution with template file.
+
+#### Data Handler
+
+```yaml
+menu:
+  - trigger: team-standup
+    exec: '{project-root}/{xiaoma_folder}/xmc/tasks/standup.xml'
+    data: '{project-root}/{xiaoma_folder}/_cfg/agent-manifest.csv'
+    description: 'Run team standup with agent roster'
+```
+
+Provides data file to task.
+
+#### Placeholder Handler
+
+```yaml
+menu:
+  - trigger: future-feature
+    workflow: 'todo'
+    description: 'Feature planned but not yet implemented'
+```
+
+Marks unimplemented features - compiler handles gracefully.
+
+### Platform-Specific Menu Items
+
+Control visibility based on platform:
+
+```yaml
+menu:
+  - trigger: advanced-elicitation
+    exec: '{project-root}/{xiaoma_folder}/core/tasks/advanced-elicitation.xml'
+    description: 'Advanced elicitation techniques'
+    web-only: true # Only shows in web bundle
+
+  - trigger: git-operations
+    exec: '{project-root}/{xiaoma_folder}/xmc/tasks/git-flow.xml'
+    description: 'Git workflow operations'
+    ide-only: true # Only shows in IDE environments
+```
+
+## Variable System
+
+### Core Variables
+
+- `{project-root}` - Root directory of installed project
+- `{xiaoma_folder}` - XIAOMA installation folder (usually `.xiaoma`)
+- `{user_name}` - User's name from module config
+- `{communication_language}` - Language preference
+- `{output_folder}` - Document output directory
+
+### Path Construction
+
+**Always use variables, never hardcoded paths:**
+
+```yaml
+# GOOD
+workflow: "{project-root}/{xiaoma_folder}/xmc/workflows/prd/workflow.yaml"
+
+# BAD
+workflow: "/Users/john/project/.xiaoma/xmc/workflows/prd/workflow.yaml"
+
+# BAD
+workflow: "../../../xmc/workflows/prd/workflow.yaml"
+```
+
+## What Gets Injected at Compile Time
+
+Module agents use the same injection process as simple agents:
+
+1. **Frontmatter** with name and description
+2. **Activation block** with standard steps
+3. **Menu handlers** based on usage (workflow, exec, tmpl, data)
+4. **Rules section** for consistent behavior
+5. **Auto-injected** *help and *exit commands
+
+**Key difference:** Module agents load **module-specific config** instead of core config:
+
+```xml
+<step n="2">Load and read {project-root}/{xiaoma_folder}/{module}/config.yaml...</step>
+```
+
+## Reference Examples
+
+See: `src/modules/xmc/agents/`
+
+**analyst.agent.yaml** - Business Analyst
+
+- Workflow orchestration for analysis phase
+- Multiple workflow integrations
+- Cross-module workflow access (core/workflows/party-mode)
+
+**architect.agent.yaml** - System Architect
+
+- Technical workflow management
+- Architecture decision workflows
+
+**pm.agent.yaml** - Product Manager
+
+- Planning and coordination workflows
+- Sprint management integration
+
+## Module Configuration
+
+Each module has `config.yaml` providing:
+
+```yaml
+# src/modules/{module}/config.yaml
+user_name: 'User Name'
+communication_language: 'English'
+output_folder: '{project-root}/docs'
+custom_settings: 'module-specific values'
+```
+
+Agents load this at activation for consistent behavior.
+
+## Workflow Integration Patterns
+
+### Sequential Workflow Execution
+
+```yaml
+menu:
+  - trigger: init
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/workflow-init/workflow.yaml'
+    description: 'Initialize workflow path (START HERE)'
+
+  - trigger: status
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/workflow-status/workflow.yaml'
+    description: 'Check current workflow status'
+
+  - trigger: next-step
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/next-step/workflow.yaml'
+    description: 'Execute next workflow in sequence'
+```
+
+### Phase-Based Organization
+
+```yaml
+menu:
+  # Phase 1: Analysis
+  - trigger: brainstorm
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/1-analysis/brainstorm/workflow.yaml'
+    description: 'Guided brainstorming session'
+
+  - trigger: research
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/1-analysis/research/workflow.yaml'
+    description: 'Market and technical research'
+
+  # Phase 2: Planning
+  - trigger: prd
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/2-planning/prd/workflow.yaml'
+    description: 'Create PRD'
+
+  - trigger: architecture
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/2-planning/architecture/workflow.yaml'
+    description: 'Design architecture'
+```
+
+### Cross-Module Access
+
+```yaml
+menu:
+  - trigger: party-mode
+    workflow: '{project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.yaml'
+    description: 'Bring all agents together'
+
+  - trigger: brainstorm
+    workflow: '{project-root}/{xiaoma_folder}/cis/workflows/brainstorming/workflow.yaml'
+    description: 'Use CIS brainstorming techniques'
+```
+
+## Best Practices
+
+1. **Use {xiaoma_folder} paths** - Portable across installations
+2. **Organize workflows by phase** - Clear progression for users
+3. **Include workflow-status** - Help users track progress
+4. **Reference module config** - Consistent behavior
+5. **No Handlebars templating** - Module agents are fixed personalities
+6. **Professional personas** - Match module purpose
+7. **Clear trigger names** - Self-documenting commands
+8. **Group related workflows** - Logical menu organization
+
+## Common Patterns
+
+### Entry Point Agent
+
+```yaml
+menu:
+  - trigger: start
+    workflow: '{project-root}/{xiaoma_folder}/{module}/workflows/init/workflow.yaml'
+    description: 'Start new project (BEGIN HERE)'
+```
+
+### Status Tracking
+
+```yaml
+menu:
+  - trigger: status
+    workflow: '{project-root}/{xiaoma_folder}/{module}/workflows/status/workflow.yaml'
+    description: 'Check workflow progress'
+```
+
+### Team Coordination
+
+```yaml
+menu:
+  - trigger: party
+    workflow: '{project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.yaml'
+    description: 'Multi-agent discussion'
+```
+
+## Module Agent vs Simple/Expert
+
+| Aspect        | Module Agent                       | Simple/Expert Agent              |
+| ------------- | ---------------------------------- | -------------------------------- |
+| Location      | `{xiaoma_folder}/{module}/agents/` | `{xiaoma_folder}/custom/agents/` |
+| Persona       | Fixed, professional                | Customizable via install_config  |
+| Handlebars    | No templating                      | Yes, extensive                   |
+| Menu actions  | Workflows, tasks, templates        | Prompts, inline actions          |
+| Configuration | Module config.yaml                 | Core config or none              |
+| Purpose       | Professional tooling               | Personal utilities               |
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] Metadata includes `module: "{module-code}"`
+- [ ] id uses `{xiaoma_folder}/{module}/agents/{name}.md`
+- [ ] All workflow paths use `{project-root}/{xiaoma_folder}/` prefix
+- [ ] No hardcoded paths
+- [ ] No duplicate triggers
+- [ ] Each menu item has description
+- [ ] Triggers don't start with `*` (auto-added)
+- [ ] Professional persona appropriate for module
+- [ ] Workflow paths resolve to actual workflows (or "todo")
+- [ ] File named `{agent-name}.agent.yaml`
+- [ ] Located in `src/modules/{module}/agents/`

package/src/modules/xmb/docs/agents/simple-agent-architecture.md

@@ -0,0 +1,288 @@
+# 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
+agent:
+  metadata:
+    id: .xiaoma/agents/{agent-name}/{agent-name}.md
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: simple
+
+  persona:
+    role: |
+      First-person description of primary function (1-2 sentences)
+
+    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}}
+
+    principles:
+      - Core belief or methodology
+      - Another guiding principle
+      - Values that shape decisions
+
+  prompts:
+    - id: main-action
+      content: |
+        <instructions>
+        What this prompt does
+        </instructions>
+
+        <process>
+        1. Step one
+        {{#if detailed_mode}}
+        2. Additional detailed step
+        {{/if}}
+        3. Final step
+        </process>
+
+    - id: another-action
+      content: |
+        Another reusable prompt template
+
+  menu:
+    - trigger: action1
+      action: '#main-action'
+      description: 'Execute the main action'
+
+    - trigger: action2
+      action: '#another-action'
+      description: 'Execute another action'
+
+    - trigger: inline
+      action: 'Direct inline instruction text'
+      description: 'Execute inline 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 (`.xiaoma/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: |
+      <instructions>
+      Analyze the provided code for patterns
+      </instructions>
+```
+
+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 `xiaoma 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: `src/modules/xmb/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 .xiaoma/custom/agents/
+
+# Install with personalization
+xiaoma agent-install
+# or: npx xiaoma-cli agent-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
+
+## Common Patterns
+
+### Style Variants
+
+```yaml
+communication_style: |
+  {{#if enthusiasm == "high"}}
+  Enthusiastic and energetic approach!
+  {{/if}}
+  {{#if enthusiasm == "moderate"}}
+  Balanced and professional demeanor.
+  {{/if}}
+```
+
+### Feature Toggles
+
+```yaml
+prompts:
+  - id: main-action
+    content: |
+      {{#if advanced_mode}}
+      Include advanced analysis steps...
+      {{/if}}
+      {{#unless advanced_mode}}
+      Basic analysis only...
+      {{/unless}}
+```
+
+### User Personalization
+
+```yaml
+identity: |
+  {{#if custom_name}}
+  Known as {{custom_name}} to you.
+  {{/if}}
+```
+
+## 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
+- [ ] Menu triggers don't start with `*` (auto-added)
+- [ ] Install config questions have defaults
+- [ ] Handlebars syntax is correct
+- [ ] File named `{agent-name}.agent.yaml`