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

package/docs/agent-customization-guide.md

@@ -0,0 +1,208 @@
+# Agent Customization Guide
+
+Customize XiaoMa agents without modifying core files. All customizations persist through updates.
+
+## Quick Start
+
+**1. Locate Customization Files**
+
+After installation, find agent customization files in:
+
+```
+{xiaoma_folder}/_cfg/agents/
+├── core-xiaoma-master.customize.yaml
+├── xmc-dev.customize.yaml
+├── xmc-pm.customize.yaml
+└── ... (one file per installed agent)
+```
+
+**2. Edit Any Agent**
+
+Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
+
+**3. Rebuild the Agent**
+
+After editing, IT IS CRITICAL to rebuild the agent to apply changes:
+
+```bash
+npx xiaoma-cli@alpha install # and then select option to compile all agents
+# OR for individual agent only
+npx xiaoma-cli@alpha build <agent-name>
+
+# Examples:
+npx xiaoma-cli@alpha build xmc-dev
+npx xiaoma-cli@alpha build core-xiaoma-master
+npx xiaoma-cli@alpha build xmc-pm
+```
+
+## What You Can Customize
+
+### Agent Name
+
+Change how the agent introduces itself:
+
+```yaml
+agent:
+  metadata:
+    name: 'Spongebob' # Default: "Amelia"
+```
+
+### Persona
+
+Replace the agent's personality, role, and communication style:
+
+```yaml
+persona:
+  role: 'Senior Full-Stack Engineer'
+  identity: 'Lives in a pineapple (under the sea)'
+  communication_style: 'Spongebob'
+  principles:
+    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
+    - 'Favor composition over inheritance'
+```
+
+**Note:** The persona section replaces the entire default persona (not merged).
+
+### Memories
+
+Add persistent context the agent will always remember:
+
+```yaml
+memories:
+  - 'Works at Krusty Krab'
+  - 'Favorite Celebrity: David Hasslehoff'
+  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
+```
+
+### Custom Menu Items
+
+Add your own workflows to the agent's menu:
+
+```yaml
+menu:
+  - trigger: my-workflow
+    workflow: '{project-root}/custom/my-workflow.yaml'
+    description: My custom workflow
+  - trigger: deploy
+    action: '#deploy-prompt'
+    description: Deploy to production
+```
+
+**Don't include:** `*` prefix or `help`/`exit` items - these are auto-injected.
+
+### Critical Actions
+
+Add instructions that execute before the agent starts:
+
+```yaml
+critical_actions:
+  - 'Always check git status before making changes'
+  - 'Use conventional commit messages'
+```
+
+### Custom Prompts
+
+Define reusable prompts for `action="#id"` menu handlers:
+
+```yaml
+prompts:
+  - id: deploy-prompt
+    content: |
+      Deploy the current branch to production:
+      1. Run all tests
+      2. Build the project
+      3. Execute deployment script
+```
+
+## Real-World Examples
+
+**Example 1: Customize Developer Agent for TDD**
+
+```yaml
+# {xiaoma_folder}/_cfg/agents/xmc-dev.customize.yaml
+agent:
+  metadata:
+    name: 'TDD Developer'
+
+memories:
+  - 'Always write tests before implementation'
+  - 'Project uses Jest and React Testing Library'
+
+critical_actions:
+  - 'Review test coverage before committing'
+```
+
+**Example 2: Add Custom Deployment Workflow**
+
+```yaml
+# {xiaoma_folder}/_cfg/agents/xmc-dev.customize.yaml
+menu:
+  - trigger: deploy-staging
+    workflow: '{project-root}/.xiaoma-custom/deploy-staging.yaml'
+    description: Deploy to staging environment
+  - trigger: deploy-prod
+    workflow: '{project-root}/.xiaoma-custom/deploy-prod.yaml'
+    description: Deploy to production (with approval)
+```
+
+**Example 3: Multilingual Product Manager**
+
+```yaml
+# {xiaoma_folder}/_cfg/agents/xmc-pm.customize.yaml
+persona:
+  role: 'Bilingual Product Manager'
+  identity: 'Expert in US and LATAM markets'
+  communication_style: 'Clear, strategic, with cultural awareness'
+  principles:
+    - 'Consider localization from day one'
+    - 'Balance business goals with user needs'
+
+memories:
+  - 'User speaks English and Spanish'
+  - 'Target markets: US and Latin America'
+```
+
+## Tips
+
+- **Start Small:** Customize one section at a time and rebuild to test
+- **Backup:** Copy customization files before major changes
+- **Update-Safe:** Your customizations in `_cfg/` survive all XiaoMa updates
+- **Per-Project:** Customization files are per-project, not global
+- **Version Control:** Consider committing `_cfg/` to share customizations with your team
+
+## Module vs. Global Config
+
+**Module-Level (Recommended):**
+
+- Customize agents per-project in `{xiaoma_folder}/_cfg/agents/`
+- Different projects can have different agent behaviors
+
+**Global Config (Coming Soon):**
+
+- Set defaults that apply across all projects
+- Override with project-specific customizations
+
+## Troubleshooting
+
+**Changes not appearing?**
+
+- Make sure you ran `npx xiaoma-cli build <agent-name>` after editing
+- Check YAML syntax is valid (indentation matters!)
+- Verify the agent name matches the file name pattern
+
+**Agent not loading?**
+
+- Check for YAML syntax errors
+- Ensure required fields aren't left empty if you uncommented them
+- Try reverting to the template and rebuilding
+
+**Need to reset?**
+
+- Delete the `.customize.yaml` file
+- Run `npx xiaoma-cli build <agent-name>` to regenerate defaults
+
+## Next Steps
+
+- **[XMC Agents Guide](../src/modules/xmc/docs/agents-guide.md)** - Learn about all 12 XiaoMa Method agents
+- **[XMB Create Agent Workflow](../src/modules/xmb/workflows/create-agent/README.md)** - Build completely custom agents
+- **[XMC Complete Documentation](../src/modules/xmc/docs/README.md)** - Full XiaoMa Method reference

package/docs/custom-agent-installation.md

@@ -0,0 +1,183 @@
+# Custom Agent Installation
+
+Install and personalize XIAOMA agents in your project.
+
+## Quick Start
+
+```bash
+# From your project directory with XIAOMA installed
+npx xiaoma-cli agent-install
+```
+
+Or if you have xiaoma-cli installed globally:
+
+```bash
+xiaoma agent-install
+```
+
+## What It Does
+
+1. **Discovers** available agent templates from your custom agents folder
+2. **Prompts** you to personalize the agent (name, behavior, preferences)
+3. **Compiles** the agent with your choices baked in
+4. **Installs** to your project's `.xiaoma/custom/agents/` directory
+5. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.)
+6. **Saves** your configuration for automatic reinstallation during XIAOMA updates
+
+## Options
+
+```bash
+xiaoma agent-install [options]
+
+Options:
+  -p, --path <path>     #Direct path to specific agent YAML file or folder
+  -d, --defaults        #Use default values without prompting
+  -t, --target <path>   #Target installation directory
+```
+
+## Installing from Custom Locations
+
+Use the `-s` / `--source` option to install agents from any location:
+
+```bash
+# Install agent from a custom folder (expert agent with sidecar)
+xiaoma agent-install -s path/to/my-agent
+
+# Install a specific .agent.yaml file (simple agent)
+xiaoma agent-install -s path/to/my-agent.agent.yaml
+
+# Install with defaults (non-interactive)
+xiaoma agent-install -s path/to/my-agent -d
+
+# Install to a specific destination project
+xiaoma agent-install -s path/to/my-agent --destination /path/to/destination/project
+```
+
+This is useful when:
+
+- Your agent is in a non-standard location (not in `.xiaoma/custom/agents/`)
+- You're developing an agent outside the project structure
+- You want to install from an absolute path
+
+## Example Session
+
+```
+🔧 XIAOMA Agent Installer
+
+Found XIAOMA at: /project/.xiaoma
+Searching for agents in: /project/.xiaoma/custom/agents
+
+Available Agents:
+
+  1. 📄 commit-poet (simple)
+  2. 📚 journal-keeper (expert)
+
+Select agent to install (number): 1
+
+Selected: commit-poet
+
+📛 Agent Persona Name
+
+   Agent type: commit-poet
+   Default persona: Inkwell Von Comitizen
+
+   Custom name (or Enter for default): Fred
+
+   Persona: Fred
+   File: fred-commit-poet.md
+
+📝 Agent Configuration
+
+   What's your preferred default commit message style?
+   * 1. Conventional (feat/fix/chore)
+     2. Narrative storytelling
+     3. Poetic haiku
+     4. Detailed explanation
+   Choice (default: 1): 1
+
+   How enthusiastic should the agent be?
+     1. Moderate - Professional with personality
+   * 2. High - Genuinely excited
+     3. EXTREME - Full theatrical drama
+   Choice (default: 2): 3
+
+   Include emojis in commit messages? [Y/n]: y
+
+✨ Agent installed successfully!
+   Name: fred-commit-poet
+   Location: /project/.xiaoma/custom/agents/fred-commit-poet
+   Compiled: fred-commit-poet.md
+
+   ✓ Source saved for reinstallation
+   ✓ Added to agent-manifest.csv
+   ✓ Created IDE commands:
+      claude-code: /xiaoma:custom:agents:fred-commit-poet
+      codex: /xiaoma-custom-agents-fred-commit-poet
+      github-copilot: xiaoma-agent-custom-fred-commit-poet
+```
+
+## Reinstallation
+
+Custom agents are automatically reinstalled when you run `xiaoma init --quick`. Your personalization choices are preserved in `.xiaoma/_cfg/custom/agents/`.
+
+## Installing Reference Agents
+
+The XIAOMA source includes example agents you can install. **You must copy them to your project first.**
+
+### Step 1: Copy the Agent Template
+
+**For simple agents** (single file):
+
+```bash
+# From your project root
+cp node_modules/xiaoma-cli/src/modules/xmb/reference/agents/stand-alone/commit-poet.agent.yaml \
+   .xiaoma/custom/agents/
+```
+
+**For expert agents** (folder with sidecar files):
+
+```bash
+# Copy the entire folder
+cp -r node_modules/xiaoma-cli/src/modules/xmb/reference/agents/agent-with-memory/journal-keeper \
+   .xiaoma/custom/agents/
+```
+
+### Step 2: Install and Personalize
+
+```bash
+npx xiaoma-cli agent-install
+# or: xiaoma agent-install (if XIAOMA installed locally)
+```
+
+The installer will:
+
+1. Find the copied template in `.xiaoma/custom/agents/`
+2. Prompt for personalization (name, behavior, preferences)
+3. Compile and install with your choices baked in
+4. Create IDE commands for immediate use
+
+### Available Reference Agents
+
+**Simple (standalone file):**
+
+- `commit-poet.agent.yaml` - Commit message artisan with style preferences
+
+**Expert (folder with sidecar):**
+
+- `journal-keeper/` - Personal journal companion with memory and pattern recognition
+
+Find these in the XIAOMA source:
+
+```
+src/modules/xmb/reference/agents/
+├── stand-alone/
+│   └── commit-poet.agent.yaml
+└── agent-with-memory/
+    └── journal-keeper/
+        ├── journal-keeper.agent.yaml
+        └── journal-keeper-sidecar/
+```
+
+## Creating Your Own
+
+Use the XMB agent builder to craft your agents. Once ready to use yourself, place your `.agent.yaml` files or folder in `.xiaoma/custom/agents/`.