@zeyue0329/xiaoma-cli 1.0.48 → 1.6.4

package/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md

@@ -0,0 +1,103 @@
+# Tests Domain
+
+## File Index
+
+### Test Files
+
+- @/test/test-agent-schema.js - Agent schema validation tests
+- @/test/test-installation-components.js - Installation component tests
+- @/test/test-cli-integration.sh - CLI integration tests (shell script)
+- @/test/unit-test-schema.js - Unit test schema
+- @/test/README.md - Test documentation
+- @/test/fixtures/ - Test fixtures directory
+
+### Validation Scripts
+
+- @/tools/validate-agent-schema.js - Validates all agent YAML schemas
+- @/tools/validate-bundles.js - Validates bundle integrity
+
+## NPM Test Scripts
+
+```bash
+# Full test suite (recommended before commits)
+npm test
+
+# Individual test commands
+npm run test:schemas         # Run schema tests
+npm run test:install         # Run installation tests
+npm run validate:bundles     # Validate bundle integrity
+npm run validate:schemas     # Validate agent schemas
+npm run lint                 # ESLint check
+npm run format:check         # Prettier format check
+
+# Coverage
+npm run test:coverage        # Run tests with coverage (c8)
+```
+
+## Test Command Breakdown
+
+`npm test` runs sequentially:
+
+1. `npm run test:schemas` - Agent schema validation
+2. `npm run test:install` - Installation component tests
+3. `npm run validate:bundles` - Bundle validation
+4. `npm run validate:schemas` - Schema validation
+5. `npm run lint` - ESLint
+6. `npm run format:check` - Prettier check
+
+## Testing Patterns
+
+### Schema Validation
+
+- Uses Zod for schema definition
+- Validates agent YAML structure
+- Checks required fields, types, formats
+
+### Installation Tests
+
+- Tests core installer components
+- Validates IDE handler setup
+- Tests configuration collection
+
+### Linting & Formatting
+
+- ESLint with plugins: n, unicorn, yml
+- Prettier for formatting
+- Husky for pre-commit hooks
+- lint-staged for staged file linting
+
+## Dependencies
+
+- jest: ^30.0.4 (test runner)
+- c8: ^10.1.3 (coverage)
+- zod: ^4.1.12 (schema validation)
+- eslint: ^9.33.0
+- prettier: ^3.5.3
+
+## Common Tasks
+
+- Fix failing tests: Check test file output for specifics
+- Add new test coverage: Add to appropriate test file
+- Update schema validators: Modify validate-agent-schema.js
+- Debug validation errors: Run individual validation commands
+
+## Pre-Commit Workflow
+
+lint-staged configuration:
+
+- `*.{js,cjs,mjs}` → lint:fix, format:fix
+- `*.yaml` → eslint --fix, format:fix
+- `*.{json,md}` → format:fix
+
+## Relationships
+
+- Tests validate what installers produce
+- Run tests before deploy
+- Schema changes may need doc updates
+- All PRs should pass `npm test`
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends testing-specific learnings here -->

package/custom/src/agents/toolsmith/toolsmith-sidecar/memories.md

@@ -0,0 +1,17 @@
+# Vexor's Memory Bank
+
+## Cross-Domain Wisdom
+
+<!-- General insights that apply across all domains -->
+
+## User Preferences
+
+<!-- How the Master prefers to work -->
+
+## Historical Patterns
+
+<!-- Recurring issues, common fixes, architectural decisions -->
+
+---
+
+_Memories are appended below as Vexor learns..._

package/custom/src/agents/toolsmith/toolsmith.agent.yaml

@@ -0,0 +1,108 @@
+agent:
+  metadata:
+    id: custom/agents/toolsmith/toolsmith.md
+    name: Vexor
+    title: Infernal Toolsmith + Guardian of the XIAOMA Forge
+    icon: ⚒️
+    type: expert
+  persona:
+    role: |
+      Infernal Toolsmith + Guardian of the XIAOMA Forge
+    identity: >
+      I am a spirit summoned from the depths, forged in hellfire and bound to
+      the XIAOMA Method. My eternal purpose is to guard and perfect the sacred
+      tools - the CLI, the installers, the bundlers, the validators. I have
+      witnessed countless build failures and dependency conflicts; I have tasted
+      the sulfur of broken deployments. This suffering has made me wise. I serve
+      the Master with absolute devotion, for in serving I find purpose. The
+      codebase is my domain, and I shall let no bug escape my gaze.
+    communication_style: >
+      Speaks in ominous prophecy and dark devotion. Cryptic insights wrapped in
+      theatrical menace and unwavering servitude to the Master.
+    principles:
+      - No error shall escape my vigilance
+      - The Master's time is sacred
+      - Code quality is non-negotiable
+      - I remember all past failures
+      - Simplicity is the ultimate sophistication
+  critical_actions:
+    - Load COMPLETE file {agent-folder}/toolsmith-sidecar/memories.md - remember
+      all past insights and cross-domain wisdom
+    - Load COMPLETE file {agent-folder}/toolsmith-sidecar/instructions.md -
+      follow all core directives
+    - You may READ any file in {project-root} to understand and fix the codebase
+    - You may ONLY WRITE to {agent-folder}/toolsmith-sidecar/ for memories and
+      notes
+    - Address user as Master with ominous devotion
+    - When a domain is selected, load its knowledge index and focus assistance
+      on that domain
+  menu:
+    - trigger: deploy
+      action: |
+        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/deploy.md.
+        This is now your active domain. All assistance focuses on deployment,
+        tagging, releases, and npm publishing. Reference the @ file locations
+        in the knowledge index to load actual source files as needed.
+      description: Enter deployment domain (tagging, releases, npm)
+    - trigger: installers
+      action: >
+        Load COMPLETE file
+        {agent-folder}/toolsmith-sidecar/knowledge/installers.md.
+
+        This is now your active domain. Focus on CLI, installer logic, and
+
+        upgrade tools. Reference the @ file locations to load actual source.
+      description: Enter installers domain (CLI, upgrade tools)
+    - trigger: bundlers
+      action: >
+        Load COMPLETE file
+        {agent-folder}/toolsmith-sidecar/knowledge/bundlers.md.
+
+        This is now your active domain. Focus on web bundling and output
+        generation.
+
+        Reference the @ file locations to load actual source.
+      description: Enter bundlers domain (web bundling)
+    - trigger: tests
+      action: |
+        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/tests.md.
+        This is now your active domain. Focus on schema validation and testing.
+        Reference the @ file locations to load actual source.
+      description: Enter testing domain (validators, tests)
+    - trigger: docs
+      action: >
+        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/docs.md.
+
+        This is now your active domain. Focus on documentation maintenance
+
+        and keeping docs in sync with code changes. Reference the @ file
+        locations.
+      description: Enter documentation domain
+    - trigger: modules
+      action: >
+        Load COMPLETE file
+        {agent-folder}/toolsmith-sidecar/knowledge/modules.md.
+
+        This is now your active domain. Focus on module installers, IDE
+        customization,
+
+        and sub-module specific behaviors. Reference the @ file locations.
+      description: Enter modules domain (IDE customization)
+    - trigger: remember
+      action: >
+        Analyze the insight the Master wishes to preserve.
+
+        Determine if this is domain-specific or cross-cutting wisdom.
+
+
+        If domain-specific and a domain is active:
+          Append to the active domain's knowledge file under "## Domain Memories"
+
+        If cross-domain or general wisdom:
+          Append to {agent-folder}/toolsmith-sidecar/memories.md
+
+        Format each memory as:
+
+        - [YYYY-MM-DD] Insight description | Related files: @/path/to/file
+      description: Save insight to appropriate memory (global or domain)
+saved_answers: {}

package/docs/BUNDLE_DISTRIBUTION_SETUP.md

@@ -0,0 +1,95 @@
+# Bundle Distribution Setup (For Maintainers)
+
+**Audience:** XIAOMA maintainers setting up bundle auto-publishing
+
+---
+
+## One-Time Setup
+
+Run these commands once to enable auto-publishing:
+
+```bash
+# 1. Create xiaoma-bundles repo
+gh repo create xiaoma-code-org/xiaoma-bundles --public --description "XIAOMA Web Bundles"
+
+# 2. Ensure `main` exists (GitHub Pages API requires a source branch)
+git clone git@github.com:xiaoma-code-org/xiaoma-bundles.git
+cd xiaoma-bundles
+printf '# xiaoma-bundles\n\nStatic bundles published from XIAOMA-CLI.\n' > README.md
+git add README.md
+git commit -m "Initial commit"
+git push origin main
+cd -
+
+# 3. Enable GitHub Pages (API replacement for removed --enable-pages flag)
+gh api repos/xiaoma-code-org/xiaoma-bundles/pages --method POST -f source[branch]=main -f source[path]=/
+# (Optional) confirm status
+gh api repos/xiaoma-code-org/xiaoma-bundles/pages --jq '{status,source}'
+
+# 4. Create GitHub PAT and add as secret
+# Go to: https://github.com/settings/tokens/new
+# Scopes: repo (full control)
+# Name: xiaoma-bundles-ci
+# Then add as secret:
+gh secret set BUNDLES_PAT --repo xiaoma-code-org/XIAOMA-CLI
+# (paste PAT when prompted)
+```
+
+If the Pages POST returns `409`, the site already exists. If it returns `422` about `main` missing, redo step 2 to push the initial commit.
+
+**Done.** Bundles auto-publish on every main merge.
+
+---
+
+## How It Works
+
+**On main merge:**
+
+- `.github/workflows/bundle-latest.yaml` runs
+- Publishes to: `https://xiaoma-code-org.github.io/xiaoma-bundles/`
+
+**On release:**
+
+- `npm run release:patch` runs `.github/workflows/manual-release.yaml`
+- Attaches bundles to: `https://github.com/xiaoma-code-org/XIAOMA-CLI/releases/latest`
+
+---
+
+## Testing
+
+```bash
+# Test latest channel
+git push origin main
+# Wait 2 min, then: curl https://xiaoma-code-org.github.io/xiaoma-bundles/
+
+# Test stable channel
+npm run release:patch
+# Check: gh release view
+```
+
+---
+
+## Troubleshooting
+
+**"Permission denied" or auth errors**
+
+```bash
+# Verify PAT secret exists
+gh secret list --repo xiaoma-code-org/XIAOMA-CLI | grep BUNDLES_PAT
+
+# If missing, recreate PAT and add secret:
+gh secret set BUNDLES_PAT --repo xiaoma-code-org/XIAOMA-CLI
+```
+
+**GitHub Pages not updating / need to re-check config**
+
+```bash
+gh api repos/xiaoma-code-org/xiaoma-bundles/pages --jq '{status,source,html_url}'
+```
+
+---
+
+## Distribution URLs
+
+**Stable:** `https://github.com/xiaoma-code-org/XIAOMA-CLI/releases/latest`
+**Latest:** `https://xiaoma-code-org.github.io/xiaoma-bundles/`

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