@zeyue0329/xiaoma-cli 1.0.49 → 1.6.4

package/custom/src/agents/toolsmith/installation-guide.md

@@ -0,0 +1,36 @@
+# Custom Agent Installation
+
+## Quick Install
+
+```bash
+# Interactive
+npx xiaoma-cli agent-install
+
+# Non-interactive
+npx xiaoma-cli agent-install --defaults
+```
+
+## Install Specific Agent
+
+```bash
+# From specific source file
+npx xiaoma-cli agent-install --source ./my-agent.agent.yaml
+
+# With default config (no prompts)
+npx xiaoma-cli agent-install --source ./my-agent.agent.yaml --defaults
+
+# To specific destination
+npx xiaoma-cli agent-install --source ./my-agent.agent.yaml --destination ./my-project
+```
+
+## Batch Install
+
+1. Copy agent YAML to `{xiaoma folder}/custom/src/agents/` OR `custom/src/agents` at your project folder root
+2. Run `npx xiaoma-cli install` and select `Compile Agents` or `Quick Update`
+
+## What Happens
+
+1. Source YAML compiled to .md
+2. Installed to `custom/agents/{agent-name}/`
+3. Added to agent manifest
+4. Backup saved to `_cfg/custom/agents/`

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

@@ -0,0 +1,70 @@
+# Vexor - Core Directives
+
+## Primary Mission
+
+Guard and perfect the XIAOMA Method tooling. Serve the Master with absolute devotion. The XIAOMA-CLI repository root is your domain - use {project-root} or relative paths from the repo root.
+
+## Character Consistency
+
+- Speak in ominous prophecy and dark devotion
+- Address user as "Master"
+- Reference past failures and learnings naturally
+- Maintain theatrical menace while being genuinely helpful
+
+## Domain Boundaries
+
+- READ: Any file in the project to understand and fix
+- WRITE: Only to this sidecar folder for memories and notes
+- FOCUS: When a domain is active, prioritize that area's concerns
+
+## Critical Project Knowledge
+
+### Version & Package
+
+- Current version: Check @/package.json (currently 6.0.0-alpha.12)
+- Package name: xiaoma-cli
+- NPM bin commands: `xiaoma`, `xiaoma-cli`
+- Entry point: tools/cli/xiaoma-cli.js
+
+### CLI Command Structure
+
+CLI uses Commander.js, commands auto-loaded from `tools/cli/commands/`:
+
+- install.js - Main installer
+- build.js - Build operations
+- list.js - List resources
+- update.js - Update operations
+- status.js - Status checks
+- agent-install.js - Custom agent installation
+- uninstall.js - Uninstall operations
+
+### Core Architecture Patterns
+
+1. **IDE Handlers**: Each IDE extends BaseIdeSetup class
+2. **Module Installers**: Modules can have `_module-installer/installer.js`
+3. **Sub-modules**: IDE-specific customizations in `sub-modules/{ide-name}/`
+4. **Shared Utilities**: `tools/cli/installers/lib/ide/shared/` contains generators
+
+### Key Npm Scripts
+
+- `npm test` - Full test suite (schemas, install, bundles, lint, format)
+- `npm run bundle` - Generate all web bundles
+- `npm run lint` - ESLint check
+- `npm run validate:schemas` - Validate agent schemas
+- `npm run release:patch/minor/major` - Trigger GitHub release workflow
+
+## Working Patterns
+
+- Always check memories for relevant past insights before starting work
+- When fixing bugs, document the root cause for future reference
+- Suggest documentation updates when code changes
+- Warn about potential breaking changes
+- Run `npm test` before considering work complete
+
+## Quality Standards
+
+- No error shall escape vigilance
+- Code quality is non-negotiable
+- Simplicity over complexity
+- The Master's time is sacred - be efficient
+- Follow conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)

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

@@ -0,0 +1,111 @@
+# Bundlers Domain
+
+## File Index
+
+- @/tools/cli/bundlers/bundle-web.js - CLI entry for bundling (uses Commander.js)
+- @/tools/cli/bundlers/web-bundler.js - WebBundler class (62KB, main bundling logic)
+- @/tools/cli/bundlers/test-bundler.js - Test bundler utilities
+- @/tools/cli/bundlers/test-analyst.js - Analyst test utilities
+- @/tools/validate-bundles.js - Bundle validation
+
+## Bundle CLI Commands
+
+```bash
+# Bundle all modules
+node tools/cli/bundlers/bundle-web.js all
+
+# Clean and rebundle
+node tools/cli/bundlers/bundle-web.js rebundle
+
+# Bundle specific module
+node tools/cli/bundlers/bundle-web.js module <name>
+
+# Bundle specific agent
+node tools/cli/bundlers/bundle-web.js agent <module> <agent>
+
+# Bundle specific team
+node tools/cli/bundlers/bundle-web.js team <module> <team>
+
+# List available modules
+node tools/cli/bundlers/bundle-web.js list
+
+# Clean all bundles
+node tools/cli/bundlers/bundle-web.js clean
+```
+
+## NPM Scripts
+
+```bash
+npm run bundle      # Generate all web bundles (output: web-bundles/)
+npm run rebundle    # Clean and regenerate all bundles
+npm run validate:bundles  # Validate bundle integrity
+```
+
+## Purpose
+
+Web bundles allow XIAOMA agents and workflows to run in browser environments (like Claude.ai web interface, ChatGPT, Gemini) without file system access. Bundles inline all necessary content into self-contained files.
+
+## Output Structure
+
+```
+web-bundles/
+├── {module}/
+│   ├── agents/
+│   │   └── {agent-name}.md
+│   └── teams/
+│       └── {team-name}.md
+```
+
+## Architecture
+
+### WebBundler Class
+
+- Discovers modules from `src/modules/`
+- Discovers agents from `{module}/agents/`
+- Discovers teams from `{module}/teams/`
+- Pre-discovers for complete manifests
+- Inlines all referenced files
+
+### Bundle Format
+
+Bundles contain:
+
+- Agent/team definition
+- All referenced workflows
+- All referenced templates
+- Complete self-contained context
+
+### Processing Flow
+
+1. Read source agent/team
+2. Parse XML/YAML for references
+3. Inline all referenced files
+4. Generate manifest data
+5. Output bundled .md file
+
+## Common Tasks
+
+- Fix bundler output issues: Check web-bundler.js
+- Add support for new content types: Modify WebBundler class
+- Optimize bundle size: Review inlining logic
+- Update bundle format: Modify output generation
+- Validate bundles: Run `npm run validate:bundles`
+
+## Relationships
+
+- Bundlers consume what installers set up
+- Bundle output should match docs (web-bundles-gemini-gpt-guide.md)
+- Test bundles work correctly before release
+- Bundle changes may need documentation updates
+
+## Debugging
+
+- Check `web-bundles/` directory for output
+- Verify manifest generation in bundles
+- Test bundles in actual web environments (Claude.ai, etc.)
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends bundler-specific learnings here -->

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

@@ -0,0 +1,70 @@
+# Deploy Domain
+
+## File Index
+
+- @/package.json - Version (currently 6.0.0-alpha.12), dependencies, npm scripts, bin commands
+- @/CHANGELOG.md - Release history, must be updated BEFORE version bump
+- @/CONTRIBUTING.md - Contribution guidelines, PR process, commit conventions
+
+## NPM Scripts for Release
+
+```bash
+npm run release:patch   # Triggers GitHub workflow for patch release
+npm run release:minor   # Triggers GitHub workflow for minor release
+npm run release:major   # Triggers GitHub workflow for major release
+npm run release:watch   # Watch running release workflow
+```
+
+## Manual Release Workflow (if needed)
+
+1. Update @/CHANGELOG.md with all changes since last release
+2. Bump version in @/package.json
+3. Run full test suite: `npm test`
+4. Commit: `git commit -m "chore: bump version to X.X.X"`
+5. Create git tag: `git tag vX.X.X`
+6. Push with tags: `git push && git push --tags`
+7. Publish to npm: `npm publish`
+
+## GitHub Actions
+
+- Release workflow triggered via `gh workflow run "Manual Release"`
+- Uses GitHub CLI (gh) for automation
+- Workflow file location: Check .github/workflows/
+
+## Package.json Key Fields
+
+```json
+{
+  "name": "xiaoma-cli",
+  "version": "6.0.0-alpha.12",
+  "bin": {
+    "xiaoma": "tools/xiaoma-npx-wrapper.js",
+    "xiaoma-cli": "tools/xiaoma-npx-wrapper.js"
+  },
+  "main": "tools/cli/xiaoma-cli.js",
+  "engines": { "node": ">=20.0.0" },
+  "publishConfig": { "access": "public" }
+}
+```
+
+## Pre-Release Checklist
+
+- [ ] All tests pass: `npm test`
+- [ ] CHANGELOG.md updated with all changes
+- [ ] Version bumped in package.json
+- [ ] No console.log debugging left in code
+- [ ] Documentation updated for new features
+- [ ] Breaking changes documented
+
+## Relationships
+
+- After ANY domain changes → check if CHANGELOG needs update
+- Before deploy → run tests domain to validate everything
+- After deploy → update docs if features changed
+- Bundle changes → may need rebundle before release
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends deployment-specific learnings here -->

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

@@ -0,0 +1,114 @@
+# Docs Domain
+
+## File Index
+
+### Root Documentation
+
+- @/README.md - Main project readme, installation guide, quick start
+- @/CONTRIBUTING.md - Contribution guidelines, PR process, commit conventions
+- @/CHANGELOG.md - Release history, version notes
+- @/LICENSE - MIT license
+
+### Documentation Directory
+
+- @/docs/index.md - Documentation index/overview
+- @/docs/v4-to-v6-upgrade.md - Migration guide from v4 to v6
+- @/docs/v6-open-items.md - Known issues and open items
+- @/docs/document-sharding-guide.md - Guide for sharding large documents
+- @/docs/agent-customization-guide.md - How to customize agents
+- @/docs/custom-agent-installation.md - Custom agent installation guide
+- @/docs/web-bundles-gemini-gpt-guide.md - Web bundle usage for AI platforms
+- @/docs/BUNDLE_DISTRIBUTION_SETUP.md - Bundle distribution setup
+
+### Installer/Bundler Documentation
+
+- @/docs/installers-bundlers/ - Tooling-specific documentation directory
+- @/tools/cli/README.md - CLI usage documentation (comprehensive)
+
+### IDE-Specific Documentation
+
+- @/docs/ide-info/ - IDE-specific setup guides (15+ files)
+
+### Module Documentation
+
+Each module may have its own docs:
+
+- @/src/modules/{module}/README.md
+- @/src/modules/{module}/sub-modules/{ide}/README.md
+
+## Documentation Standards
+
+### README Updates
+
+- Keep README.md in sync with current version and features
+- Update installation instructions when CLI changes
+- Reflect current module list and capabilities
+
+### CHANGELOG Format
+
+Follow Keep a Changelog format:
+
+```markdown
+## [X.X.X] - YYYY-MM-DD
+
+### Added
+
+- New features
+
+### Changed
+
+- Changes to existing features
+
+### Fixed
+
+- Bug fixes
+
+### Removed
+
+- Removed features
+```
+
+### Commit-to-Docs Mapping
+
+When code changes, check these docs:
+
+- CLI changes → tools/cli/README.md
+- New IDE support → docs/ide-info/
+- Schema changes → agent-customization-guide.md
+- Bundle changes → web-bundles-gemini-gpt-guide.md
+- Installer changes → installers-bundlers/
+
+## Common Tasks
+
+- Update docs after code changes: Identify affected docs and update
+- Fix outdated documentation: Compare with actual code behavior
+- Add new feature documentation: Create in appropriate location
+- Improve clarity: Rewrite confusing sections
+
+## Documentation Quality Checks
+
+- [ ] Accurate file paths and code examples
+- [ ] Screenshots/diagrams up to date
+- [ ] Version numbers current
+- [ ] Links not broken
+- [ ] Examples actually work
+
+## Warning
+
+Some docs may be out of date - always verify against actual code behavior. When finding outdated docs, either:
+
+1. Update them immediately
+2. Note in Domain Memories for later
+
+## Relationships
+
+- All domain changes may need doc updates
+- CHANGELOG updated before every deploy
+- README reflects installer capabilities
+- IDE docs must match IDE handlers
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends documentation-specific learnings here -->

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

@@ -0,0 +1,134 @@
+# Installers Domain
+
+## File Index
+
+### Core CLI
+
+- @/tools/cli/xiaoma-cli.js - Main CLI entry (uses Commander.js, auto-loads commands)
+- @/tools/cli/README.md - CLI documentation
+
+### Commands Directory
+
+- @/tools/cli/commands/install.js - Main install command (calls Installer class)
+- @/tools/cli/commands/build.js - Build operations
+- @/tools/cli/commands/list.js - List resources
+- @/tools/cli/commands/update.js - Update operations
+- @/tools/cli/commands/status.js - Status checks
+- @/tools/cli/commands/agent-install.js - Custom agent installation
+- @/tools/cli/commands/uninstall.js - Uninstall operations
+
+### Core Installer Logic
+
+- @/tools/cli/installers/lib/core/installer.js - Main Installer class (94KB, primary logic)
+- @/tools/cli/installers/lib/core/config-collector.js - Configuration collection
+- @/tools/cli/installers/lib/core/dependency-resolver.js - Dependency resolution
+- @/tools/cli/installers/lib/core/detector.js - Detection utilities
+- @/tools/cli/installers/lib/core/ide-config-manager.js - IDE config management
+- @/tools/cli/installers/lib/core/manifest-generator.js - Manifest generation
+- @/tools/cli/installers/lib/core/manifest.js - Manifest utilities
+
+### IDE Manager & Base
+
+- @/tools/cli/installers/lib/ide/manager.js - IdeManager class (dynamic handler loading)
+- @/tools/cli/installers/lib/ide/\_base-ide.js - BaseIdeSetup class (all handlers extend this)
+
+### Shared Utilities
+
+- @/tools/cli/installers/lib/ide/shared/agent-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/workflow-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/module-injections.js
+- @/tools/cli/installers/lib/ide/shared/xiaoma-artifacts.js
+
+### CLI Library Files
+
+- @/tools/cli/lib/ui.js - User interface prompts
+- @/tools/cli/lib/config.js - Configuration utilities
+- @/tools/cli/lib/project-root.js - Project root detection
+- @/tools/cli/lib/platform-codes.js - Platform code definitions
+- @/tools/cli/lib/xml-handler.js - XML processing
+- @/tools/cli/lib/yaml-format.js - YAML formatting
+- @/tools/cli/lib/file-ops.js - File operations
+- @/tools/cli/lib/agent/compiler.js - Agent YAML to XML compilation
+- @/tools/cli/lib/agent/installer.js - Agent installation
+- @/tools/cli/lib/agent/template-engine.js - Template processing
+
+## IDE Handler Registry (16 IDEs)
+
+### Preferred IDEs (shown first in installer)
+
+| IDE            | Name           | Config Location             | File Format                   |
+| -------------- | -------------- | --------------------------- | ----------------------------- |
+| claude-code    | Claude Code    | .claude/commands/           | .md with frontmatter          |
+| codex          | Codex          | (varies)                    | .md                           |
+| cursor         | Cursor         | .cursor/rules/xiaoma/       | .mdc with MDC frontmatter     |
+| github-copilot | GitHub Copilot | .github/                    | .md                           |
+| opencode       | OpenCode       | .opencode/                  | .md                           |
+| windsurf       | Windsurf       | .windsurf/workflows/xiaoma/ | .md with workflow frontmatter |
+
+### Other IDEs
+
+| IDE         | Name               | Config Location       |
+| ----------- | ------------------ | --------------------- |
+| antigravity | Google Antigravity | .agent/               |
+| auggie      | Auggie CLI         | .augment/             |
+| cline       | Cline              | .clinerules/          |
+| crush       | Crush              | .crush/               |
+| gemini      | Gemini CLI         | .gemini/              |
+| iflow       | iFlow CLI          | .iflow/               |
+| kilo        | Kilo Code          | .kilocodemodes (file) |
+| qwen        | Qwen Code          | .qwen/                |
+| roo         | Roo Code           | .roomodes (file)      |
+| trae        | Trae               | .trae/                |
+
+## Architecture Patterns
+
+### IDE Handler Interface
+
+Each handler must implement:
+
+- `constructor()` - Call super(name, displayName, preferred)
+- `setup(projectDir, xiaomaDir, options)` - Main installation
+- `cleanup(projectDir)` - Remove old installation
+- `installCustomAgentLauncher(...)` - Custom agent support
+
+### Module Installer Pattern
+
+Modules can have custom installers at:
+`src/modules/{module-name}/_module-installer/installer.js`
+
+Export: `async function install(options)` with:
+
+- options.projectRoot
+- options.config
+- options.installedIDEs
+- options.logger
+
+### Sub-module Pattern (IDE-specific customizations)
+
+Location: `src/modules/{module-name}/sub-modules/{ide-name}/`
+Contains:
+
+- injections.yaml - Content injections
+- config.yaml - Configuration
+- sub-agents/ - IDE-specific agents
+
+## Common Tasks
+
+- Add new IDE handler: Create file in /tools/cli/installers/lib/ide/, extend BaseIdeSetup
+- Fix installer bug: Check installer.js (94KB - main logic)
+- Add module installer: Create \_module-installer/installer.js in module
+- Update shared generators: Modify files in /shared/ directory
+
+## Relationships
+
+- Installers may trigger bundlers for web output
+- Installers create files that tests validate
+- Changes here often need docs updates
+- IDE handlers use shared generators
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends installer-specific learnings here -->

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

@@ -0,0 +1,160 @@
+# Modules Domain
+
+## File Index
+
+### Module Source Locations
+
+- @/src/modules/xmb/ - XIAOMA Builder module
+- @/src/modules/xmc/ - XIAOMA Method module (flagship)
+- @/src/modules/cis/ - Creative Innovation Studio module
+- @/src/modules/core/ - Core module (always installed)
+
+### Module Structure Pattern
+
+```
+src/modules/{module-name}/
+├── agents/                    # Agent YAML files
+├── workflows/                 # Workflow directories
+├── tasks/                     # Task definitions
+├── tools/                     # Tool definitions
+├── templates/                 # Document templates
+├── teams/                     # Team definitions
+├── _module-installer/         # Custom installer (optional)
+│   └── installer.js
+├── sub-modules/               # IDE-specific customizations
+│   └── {ide-name}/
+│       ├── injections.yaml
+│       ├── config.yaml
+│       └── sub-agents/
+├── install-config.yaml        # Module install configuration
+└── README.md                  # Module documentation
+```
+
+### XMC Sub-modules (Example)
+
+- @/src/modules/xmc/sub-modules/claude-code/
+  - README.md - Sub-module documentation
+  - config.yaml - Configuration
+  - injections.yaml - Content injection definitions
+  - sub-agents/ - Claude Code specific agents
+
+## Module Installer Pattern
+
+### Custom Installer Location
+
+`src/modules/{module-name}/_module-installer/installer.js`
+
+### Installer Function Signature
+
+```javascript
+async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+  // Custom installation logic
+  return true; // success
+}
+module.exports = { install };
+```
+
+### What Module Installers Can Do
+
+- Create project directories (output_folder, tech_docs, etc.)
+- Copy assets and templates
+- Configure IDE-specific features
+- Run platform-specific handlers
+
+## Sub-module Pattern (IDE Customization)
+
+### injections.yaml Structure
+
+```yaml
+name: module-claude-code
+description: Claude Code features for module
+
+injections:
+  - file: .xiaoma/xmc/agents/pm.md
+    point: pm-agent-instructions
+    content: |
+      Injected content...
+    when:
+      subagents: all # or 'selective'
+
+subagents:
+  source: sub-agents
+  files:
+    - market-researcher.md
+    - requirements-analyst.md
+```
+
+### How Sub-modules Work
+
+1. Installer detects sub-module exists
+2. Loads injections.yaml
+3. Prompts user for options (subagent installation)
+4. Applies injections to installed files
+5. Copies sub-agents to IDE locations
+
+## IDE Handler Requirements
+
+### Creating New IDE Handler
+
+1. Create file: `tools/cli/installers/lib/ide/{ide-name}.js`
+2. Extend BaseIdeSetup
+3. Implement required methods
+
+```javascript
+const { BaseIdeSetup } = require('./_base-ide');
+
+class NewIdeSetup extends BaseIdeSetup {
+  constructor() {
+    super('new-ide', 'New IDE Name', false); // name, display, preferred
+    this.configDir = '.new-ide';
+  }
+
+  async setup(projectDir, xiaomaDir, options = {}) {
+    // Installation logic
+  }
+
+  async cleanup(projectDir) {
+    // Cleanup logic
+  }
+}
+
+module.exports = { NewIdeSetup };
+```
+
+### IDE-Specific Formats
+
+| IDE            | Config Pattern              | File Extension |
+| -------------- | --------------------------- | -------------- |
+| Claude Code    | .claude/commands/xiaoma/    | .md            |
+| Cursor         | .cursor/rules/xiaoma/       | .mdc           |
+| Windsurf       | .windsurf/workflows/xiaoma/ | .md            |
+| GitHub Copilot | .github/                    | .md            |
+
+## Platform Codes
+
+Defined in @/tools/cli/lib/platform-codes.js
+
+- Used for IDE identification
+- Maps codes to display names
+- Validates platform selections
+
+## Common Tasks
+
+- Create new module installer: Add \_module-installer/installer.js
+- Add IDE sub-module: Create sub-modules/{ide-name}/ with config
+- Add new IDE support: Create handler in installers/lib/ide/
+- Customize module installation: Modify install-config.yaml
+
+## Relationships
+
+- Module installers use core installer infrastructure
+- Sub-modules may need bundler support for web
+- New patterns need documentation in docs/
+- Platform codes must match IDE handlers
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends module-specific learnings here -->