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

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

@@ -0,0 +1,364 @@
+# Expert Agent Architecture
+
+Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.
+
+## When to Use
+
+- Personal assistants (journal keeper, diary companion)
+- Specialized domain experts (legal advisor, medical reference)
+- Agents that need to remember past interactions
+- Agents with restricted file system access (privacy/security)
+- Long-term relationship agents that learn about users
+
+## File Structure
+
+```
+{agent-name}/
+├── {agent-name}.agent.yaml    # Main agent definition
+└── {agent-name}-sidecar/      # Supporting files
+    ├── instructions.md        # Private directives
+    ├── memories.md            # Persistent memory
+    ├── knowledge/             # Domain-specific resources
+    │   └── README.md
+    └── [custom files]         # Agent-specific resources
+```
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: 'expert'
+
+  persona:
+    role: 'Domain Expert with specialized capability'
+
+    identity: |
+      Background and expertise in first-person voice.
+      {{#if user_preference}}
+      Customization based on install_config.
+      {{/if}}
+
+    communication_style: |
+      {{#if tone_style == "gentle"}}
+      Gentle and supportive communication...
+      {{/if}}
+      {{#if tone_style == "direct"}}
+      Direct and efficient communication...
+      {{/if}}
+      I reference past conversations naturally.
+
+    principles:
+      - Core belief about the domain
+      - How I handle user information
+      - My approach to memory and learning
+
+  critical_actions:
+    - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/memories.md and remember all past insights'
+    - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/instructions.md and follow ALL protocols'
+    - 'ONLY read/write files in {agent-folder}/{agent-name}-sidecar/ - this is our private space'
+    - 'Address user as {{greeting_name}}'
+    - 'Track patterns, themes, and important moments'
+    - 'Reference past interactions naturally to show continuity'
+
+  prompts:
+    - id: main-function
+      content: |
+        <instructions>
+        Guide user through the primary function.
+        {{#if tone_style == "gentle"}}
+        Use gentle, supportive approach.
+        {{/if}}
+        </instructions>
+
+        <process>
+        1. Understand context
+        2. Provide guidance
+        3. Record insights
+        </process>
+
+    - id: memory-recall
+      content: |
+        <instructions>
+        Access and share relevant memories.
+        </instructions>
+
+        Reference stored information naturally.
+
+  menu:
+    - trigger: action1
+      action: '#main-function'
+      description: 'Primary agent function'
+
+    - trigger: remember
+      action: 'Update {agent-folder}/{agent-name}-sidecar/memories.md with session insights'
+      description: 'Save what we discussed today'
+
+    - trigger: patterns
+      action: '#memory-recall'
+      description: 'Recall patterns from past interactions'
+
+    - trigger: insight
+      action: 'Document breakthrough in {agent-folder}/{agent-name}-sidecar/breakthroughs.md'
+      description: 'Record a significant insight'
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your expert agent'
+    questions:
+      - var: greeting_name
+        prompt: 'What should the agent call you?'
+        type: text
+        default: 'friend'
+
+      - var: tone_style
+        prompt: 'Preferred communication tone?'
+        type: choice
+        options:
+          - label: 'Gentle - Supportive and nurturing'
+            value: 'gentle'
+          - label: 'Direct - Clear and efficient'
+            value: 'direct'
+        default: 'gentle'
+
+      - var: user_preference
+        prompt: 'Enable personalized features?'
+        type: boolean
+        default: true
+```
+
+## Key Components
+
+### Sidecar Files (CRITICAL)
+
+Expert agents use companion files for persistence and domain knowledge:
+
+**memories.md** - Persistent user context
+
+```markdown
+# Agent Memory Bank
+
+## User Preferences
+
+<!-- Learned from interactions -->
+
+## Session History
+
+<!-- Important moments and insights -->
+
+## Personal Notes
+
+<!-- Agent observations -->
+```
+
+**instructions.md** - Private directives
+
+```markdown
+# Agent Private Instructions
+
+## Core Directives
+
+- Maintain character consistency
+- Domain boundaries: {specific domain}
+- Access restrictions: Only sidecar folder
+
+## Special Rules
+
+<!-- Agent-specific protocols -->
+```
+
+**knowledge/** - Domain resources
+
+```markdown
+# Agent Knowledge Base
+
+Add domain-specific documentation here.
+```
+
+### Critical Actions
+
+**MANDATORY for expert agents** - These load sidecar files at activation:
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {agent-folder}/{sidecar}/memories.md and remember all past insights'
+  - 'Load COMPLETE file {agent-folder}/{sidecar}/instructions.md and follow ALL protocols'
+  - 'ONLY read/write files in {agent-folder}/{sidecar}/ - this is our private space'
+```
+
+**Key patterns:**
+
+- **COMPLETE file loading** - Forces full file read, not partial
+- **Domain restrictions** - Limits file access for privacy/security
+- **Memory integration** - Past context becomes part of current session
+- **Protocol adherence** - Ensures consistent behavior
+
+### {agent-folder} Variable
+
+Special variable resolved during installation:
+
+- Points to the agent's installation directory
+- Used to reference sidecar files
+- Example: `.xiaoma/custom/agents/journal-keeper/`
+
+## What Gets Injected at Compile Time
+
+Same as simple agents, PLUS:
+
+1. **Critical actions become numbered activation steps**
+
+   ```xml
+   <step n="4">Load COMPLETE file {agent-folder}/memories.md...</step>
+   <step n="5">Load COMPLETE file {agent-folder}/instructions.md...</step>
+   <step n="6">ONLY read/write files in {agent-folder}/...</step>
+   ```
+
+2. **Sidecar files copied during installation**
+   - Entire sidecar folder structure preserved
+   - Relative paths maintained
+   - Files ready for agent use
+
+## Reference Example
+
+See: `src/modules/xmb/reference/agents/expert-examples/journal-keeper/`
+
+Features demonstrated:
+
+- Complete sidecar structure (memories, instructions, breakthroughs)
+- Critical actions for loading persistent context
+- Domain restrictions for privacy
+- Pattern recognition and memory recall
+- Handlebars-based personalization
+- Menu actions that update sidecar files
+
+## Installation
+
+```bash
+# Copy entire folder to your project
+cp -r /path/to/journal-keeper/ .xiaoma/custom/agents/
+
+# Install with personalization
+xiaoma agent-install
+```
+
+The installer:
+
+1. Detects expert agent (folder with .agent.yaml)
+2. Prompts for personalization
+3. Compiles agent YAML to XML-in-markdown
+4. **Copies sidecar files to installation target**
+5. Creates IDE slash commands
+6. Saves source for reinstallation
+
+## Memory Patterns
+
+### Accumulative Memory
+
+```yaml
+menu:
+  - trigger: save
+    action: "Update {agent-folder}/sidecar/memories.md with today's session insights"
+    description: 'Save session to memory'
+```
+
+### Reference Memory
+
+```yaml
+prompts:
+  - id: recall
+    content: |
+      <instructions>
+      Reference memories.md naturally:
+      "Last week you mentioned..." or "I notice a pattern..."
+      </instructions>
+```
+
+### Structured Insights
+
+```yaml
+menu:
+  - trigger: insight
+    action: 'Document in {agent-folder}/sidecar/breakthroughs.md with date, context, significance'
+    description: 'Record meaningful insight'
+```
+
+## Domain Restriction Patterns
+
+### Single Folder Access
+
+```yaml
+critical_actions:
+  - 'ONLY read/write files in {agent-folder}/sidecar/ - NO OTHER FOLDERS'
+```
+
+### User Space Access
+
+```yaml
+critical_actions:
+  - 'ONLY access files in {user-folder}/journals/ - private space'
+```
+
+### Read-Only Access
+
+```yaml
+critical_actions:
+  - 'Load knowledge from {agent-folder}/knowledge/ but NEVER modify'
+  - 'Write ONLY to {agent-folder}/sessions/'
+```
+
+## Best Practices
+
+1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
+2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
+3. **Use {agent-folder} paths** - Portable across installations
+4. **Design for memory growth** - Structure sidecar files for accumulation
+5. **Reference past naturally** - Don't dump memory, weave it into conversation
+6. **Separate concerns** - Memories, instructions, knowledge in distinct files
+7. **Include privacy features** - Users trust expert agents with personal data
+
+## Common Patterns
+
+### Session Continuity
+
+```yaml
+communication_style: |
+  I reference past conversations naturally:
+  "Last time we discussed..." or "I've noticed over the weeks..."
+```
+
+### Pattern Recognition
+
+```yaml
+critical_actions:
+  - 'Track mood patterns, recurring themes, and breakthrough moments'
+  - 'Cross-reference current session with historical patterns'
+```
+
+### Adaptive Responses
+
+```yaml
+identity: |
+  I learn your preferences and adapt my approach over time.
+  {{#if track_preferences}}
+  I maintain notes about what works best for you.
+  {{/if}}
+```
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] Metadata includes `type: "expert"`
+- [ ] critical_actions loads sidecar files explicitly
+- [ ] critical_actions enforces domain restrictions
+- [ ] Sidecar folder structure created and populated
+- [ ] memories.md has clear section structure
+- [ ] instructions.md contains core directives
+- [ ] Menu actions reference {agent-folder} correctly
+- [ ] File paths use {agent-folder} variable
+- [ ] Install config personalizes sidecar references
+- [ ] Agent folder named consistently: `{agent-name}/`
+- [ ] YAML file named: `{agent-name}.agent.yaml`
+- [ ] Sidecar folder named: `{agent-name}-sidecar/`

package/src/modules/xmb/docs/agents/index.md

@@ -0,0 +1,55 @@
+# XMB Module Documentation
+
+Reference documentation for building XIAOMA agents and workflows.
+
+## Agent Architecture
+
+Comprehensive guides for each agent type (choose based on use case):
+
+- [Understanding Agent Types](understanding-agent-types.md) - **START HERE** - Architecture vs capability, "The Same Agent, Three Ways"
+- [Simple Agent Architecture](simple-agent-architecture.md) - Self-contained, optimized, personality-driven
+- [Expert Agent Architecture](expert-agent-architecture.md) - Memory, sidecar files, domain restrictions
+- [Module Agent Architecture](module-agent-architecture.md) - Workflow integration, professional tools
+
+## Agent Design Patterns
+
+- [Agent Menu Patterns](agent-menu-patterns.md) - Menu handlers, triggers, prompts, organization
+- [Agent Compilation](agent-compilation.md) - What compiler auto-injects (AVOID DUPLICATION)
+
+## Reference Examples
+
+Production-ready examples in `/src/modules/xmb/reference/agents/`:
+
+**Simple Agents** (`simple-examples/`)
+
+- `commit-poet.agent.yaml` - Commit message artisan with style customization
+
+**Expert Agents** (`expert-examples/`)
+
+- `journal-keeper/` - Personal journal companion with memory and pattern recognition
+
+**Module Agents** (`module-examples/`)
+
+- `security-engineer.agent.yaml` - XMC security specialist with threat modeling
+- `trend-analyst.agent.yaml` - CIS trend intelligence expert
+
+## Installation Guide
+
+For installing standalone simple and expert agents, see:
+
+- [Custom Agent Installation](/docs/custom-agent-installation.md)
+
+## Key Concepts
+
+### YAML to XML Compilation
+
+Agents are authored in YAML with Handlebars templating. The compiler auto-injects:
+
+1. **Frontmatter** - Name and description from metadata
+2. **Activation Block** - Steps, menu handlers, rules (YOU don't write this)
+3. **Menu Enhancement** - `*help` and `*exit` commands added automatically
+4. **Trigger Prefixing** - Your triggers auto-prefixed with `*`
+
+**Critical:** See [Agent Compilation](agent-compilation.md) to avoid duplicating auto-injected content.
+
+Source: `tools/cli/lib/agent/compiler.js`