@zeyue0329/xiaoma-cli 1.0.49 → 1.6.4

package/docs/superpowers/plans/2026-03-11-upstream-sync-with-branding.md

@@ -0,0 +1,586 @@
+# Upstream Sync with XiaoMa Branding Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fully overwrite `src/`, `tools/`, `test/` with upstream XiaoMa content, then re-apply XiaoMa branding, preserving XiaoMa-only additions (CLAUDE.md, custom/, external-official-modules.yaml branding, package.json).
+
+**Architecture:** Use `git checkout upstream/main -- src/ tools/ test/` to wholesale replace code, then apply a systematic branding script (xiaoma→xiaoma, bmm→xmc, bmb→xmb, etc.) plus targeted manual fixes for file renames and config values. XiaoMa-only files (custom agents, CLAUDE.md, bundlers, flattener) are backed up and restored.
+
+**Tech Stack:** Git, Node.js, sed/bash for bulk text replacement, npm for validation.
+
+---
+
+## Branding Mapping Reference
+
+All tasks reference this canonical mapping:
+
+| Upstream (XiaoMa) | XiaoMa | Scope |
+|-----------------|--------|-------|
+| `xiaoma-cli` (pkg name) | `@zeyue0329/xiaoma-cli` | package.json only |
+| `xiaoma` (folder constant) | `xiaoma` | Code: `XiaoMa_FOLDER_NAME` → `XIAOMA_FOLDER_NAME` |
+| `_xiaoma` (install folder) | `_xiaoma` | Code + content |
+| `.xiaoma` (legacy folder) | `.xiaoma` | Code + content |
+| `xiaoma` (general brand) | `xiaoma` | Content text, comments, UI strings |
+| `XiaoMa` (uppercase) | `XIAOMA` | Constants, comments |
+| `XiaoMa` (mixed case) | `XiaoMa` | UI text, module names |
+| `bmm` (module code) | `xmc` | Code + config |
+| `BMM` (uppercase) | `XMC` | Comments, docs |
+| `bmb` (builder code) | `xmb` | external-official-modules.yaml |
+| `src/xmc/` (module path) | `src/xmc/` | Directory structure |
+| `xiaoma-cli.js` (CLI entry) | `xiaoma-cli.js` | File name |
+| `xiaoma-npx-wrapper.js` | `xiaoma-npx-wrapper.js` | File name |
+| `xiaoma-code-org` (GitHub org) | `zqyl-xiaoma` | external-official-modules.yaml |
+| `xiaoma-org` (module type) | `xiaoma-org` | external-official-modules.yaml |
+| `xiaoma-skill-manifest.yaml` | `xiaoma-skill-manifest.yaml` | File names throughout src/ |
+| `Brian (XiaoMa) Madison` | `zeyue0329` | package.json author |
+| `_xiaoma-output` | `_xiaoma-output` | Default output folder |
+| `xiaoma-master` | `xiaoma-master` | Master agent name |
+| `xiaoma-help` | `xiaoma-help` | Help task name |
+| `xiaoma-review-*` | `xiaoma-review-*` | Review task names |
+
+---
+
+## Chunk 1: Backup, Upstream Checkout, and Module Restructure
+
+### Task 1: Backup XiaoMa-only files
+
+XiaoMa has files that don't exist upstream. Back them up before the overwrite.
+
+**Files:**
+- Various files under `tools/cli/bundlers/`, `tools/flattener/`, `tools/cli/commands/`, `custom/`
+
+- [ ] **Step 1: Create backup of XiaoMa-only files**
+
+```bash
+mkdir -p /tmp/xiaoma-backup
+
+# Backup XiaoMa-only tooling
+cp -r tools/cli/bundlers /tmp/xiaoma-backup/bundlers 2>/dev/null || true
+cp -r tools/flattener /tmp/xiaoma-backup/flattener 2>/dev/null || true
+cp tools/validate-bundles.js /tmp/xiaoma-backup/ 2>/dev/null || true
+
+# Backup XiaoMa-only CLI files
+cp tools/cli/xiaoma-cli.js /tmp/xiaoma-backup/ 2>/dev/null || true
+cp tools/xiaoma-npx-wrapper.js /tmp/xiaoma-backup/ 2>/dev/null || true
+cp tools/cli/regenerate-manifests.js /tmp/xiaoma-backup/ 2>/dev/null || true
+cp tools/cli/test-yaml-builder.js /tmp/xiaoma-backup/ 2>/dev/null || true
+
+# Backup XiaoMa-only commands
+cp tools/cli/commands/agent-install.js /tmp/xiaoma-backup/ 2>/dev/null || true
+cp tools/cli/commands/build.js /tmp/xiaoma-backup/ 2>/dev/null || true
+cp tools/cli/commands/cleanup.js /tmp/xiaoma-backup/ 2>/dev/null || true
+cp tools/cli/commands/list.js /tmp/xiaoma-backup/ 2>/dev/null || true
+cp tools/cli/commands/update.js /tmp/xiaoma-backup/ 2>/dev/null || true
+
+# Backup XiaoMa-only IDE handlers
+mkdir -p /tmp/xiaoma-backup/ide
+for f in antigravity auggie claude-code cline codex crush cursor gemini github-copilot iflow kilo opencode qwen roo rovo-dev rovodev trae windsurf; do
+  cp "tools/cli/installers/lib/ide/${f}.js" "/tmp/xiaoma-backup/ide/" 2>/dev/null || true
+done
+
+# Backup XiaoMa-only IDE templates
+mkdir -p /tmp/xiaoma-backup/templates
+cp tools/cli/installers/lib/ide/templates/gemini-agent-command.toml /tmp/xiaoma-backup/templates/ 2>/dev/null || true
+cp tools/cli/installers/lib/ide/templates/gemini-task-command.toml /tmp/xiaoma-backup/templates/ 2>/dev/null || true
+cp tools/cli/installers/lib/ide/templates/workflow-command-template.md /tmp/xiaoma-backup/templates/ 2>/dev/null || true
+cp tools/cli/installers/lib/ide/templates/workflow-commander.md /tmp/xiaoma-backup/templates/ 2>/dev/null || true
+cp tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md /tmp/xiaoma-backup/templates/ 2>/dev/null || true
+cp tools/cli/installers/lib/ide/templates/combined/kiro-workflow-yaml.md /tmp/xiaoma-backup/templates/ 2>/dev/null || true
+
+# Backup XiaoMa-only utility files
+mkdir -p /tmp/xiaoma-backup/utility
+cp -r src/utility/models /tmp/xiaoma-backup/utility/ 2>/dev/null || true
+cp -r src/utility/agent-components /tmp/xiaoma-backup/utility/ 2>/dev/null || true
+cp src/utility/templates/agent.customize.template.yaml /tmp/xiaoma-backup/utility/ 2>/dev/null || true
+
+# Backup XiaoMa-only core files
+mkdir -p /tmp/xiaoma-backup/core
+cp -r src/core/_module-installer /tmp/xiaoma-backup/core/ 2>/dev/null || true
+cp src/core/agents/xiaoma-web-orchestrator.agent.xml /tmp/xiaoma-backup/core/ 2>/dev/null || true
+cp -r src/core/resources /tmp/xiaoma-backup/core/ 2>/dev/null || true
+cp -r src/core/tools /tmp/xiaoma-backup/core/ 2>/dev/null || true
+
+# Backup XiaoMa-only XMC files
+mkdir -p /tmp/xiaoma-backup/xmc
+cp -r src/xmc/_module-installer /tmp/xiaoma-backup/xmc/ 2>/dev/null || true
+cp -r src/xmc/sub-modules /tmp/xiaoma-backup/xmc/ 2>/dev/null || true
+cp -r src/xmc/testarch /tmp/xiaoma-backup/xmc/ 2>/dev/null || true
+
+# Backup other XiaoMa-only files
+cp tools/cli/lib/replace-project-root.js /tmp/xiaoma-backup/ 2>/dev/null || true
+```
+
+- [ ] **Step 2: Verify backup**
+
+```bash
+find /tmp/xiaoma-backup -type f | wc -l
+# Expected: 80+ files backed up
+```
+
+---
+
+### Task 2: Wholesale checkout upstream content
+
+**Files:**
+- All files under `src/`, `tools/`, `test/`
+
+- [ ] **Step 3: Checkout upstream content for src/, tools/, test/**
+
+```bash
+git checkout upstream/main -- src/ tools/ test/
+```
+
+This replaces ALL content in these directories with upstream. The upstream has:
+- `src/xmc/` (not `src/xmc/`)
+- `tools/cli/xiaoma-cli.js` (not `xiaoma-cli.js`)
+- XiaoMa branding everywhere
+
+- [ ] **Step 4: Verify upstream content landed**
+
+```bash
+ls src/          # Should show: bmm/ core/ utility/
+ls src/xmc/      # Should show agents, workflows, etc.
+git status | head -20
+```
+
+---
+
+### Task 3: Restore XiaoMa-only files
+
+- [ ] **Step 5: Restore backed-up XiaoMa-only files**
+
+```bash
+# Restore bundlers
+cp -r /tmp/xiaoma-backup/bundlers tools/cli/bundlers 2>/dev/null || true
+cp -r /tmp/xiaoma-backup/flattener tools/flattener 2>/dev/null || true
+cp /tmp/xiaoma-backup/validate-bundles.js tools/ 2>/dev/null || true
+
+# Restore CLI entry point (will be rebranded, but need the file)
+cp /tmp/xiaoma-backup/xiaoma-cli.js tools/cli/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/xiaoma-npx-wrapper.js tools/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/regenerate-manifests.js tools/cli/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/test-yaml-builder.js tools/cli/ 2>/dev/null || true
+
+# Restore commands
+cp /tmp/xiaoma-backup/agent-install.js tools/cli/commands/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/build.js tools/cli/commands/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/cleanup.js tools/cli/commands/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/list.js tools/cli/commands/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/update.js tools/cli/commands/ 2>/dev/null || true
+
+# Restore IDE handlers
+for f in /tmp/xiaoma-backup/ide/*.js; do
+  cp "$f" tools/cli/installers/lib/ide/ 2>/dev/null || true
+done
+
+# Restore IDE templates
+cp /tmp/xiaoma-backup/templates/gemini-agent-command.toml tools/cli/installers/lib/ide/templates/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/templates/gemini-task-command.toml tools/cli/installers/lib/ide/templates/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/templates/workflow-command-template.md tools/cli/installers/lib/ide/templates/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/templates/workflow-commander.md tools/cli/installers/lib/ide/templates/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/templates/default-workflow-yaml.md tools/cli/installers/lib/ide/templates/combined/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/templates/kiro-workflow-yaml.md tools/cli/installers/lib/ide/templates/combined/ 2>/dev/null || true
+
+# Restore utility files
+cp -r /tmp/xiaoma-backup/utility/models src/utility/ 2>/dev/null || true
+cp -r /tmp/xiaoma-backup/utility/agent-components src/utility/ 2>/dev/null || true
+mkdir -p src/utility/templates
+cp /tmp/xiaoma-backup/utility/agent.customize.template.yaml src/utility/templates/ 2>/dev/null || true
+
+# Restore core XiaoMa-only files
+cp -r /tmp/xiaoma-backup/core/_module-installer src/core/ 2>/dev/null || true
+cp /tmp/xiaoma-backup/core/xiaoma-web-orchestrator.agent.xml src/core/agents/ 2>/dev/null || true
+cp -r /tmp/xiaoma-backup/core/resources src/core/ 2>/dev/null || true
+cp -r /tmp/xiaoma-backup/core/tools src/core/ 2>/dev/null || true
+
+# Restore other files
+cp /tmp/xiaoma-backup/replace-project-root.js tools/cli/lib/ 2>/dev/null || true
+```
+
+- [ ] **Step 6: Commit raw upstream sync + restore**
+
+```bash
+git add -A src/ tools/ test/
+git commit -m "chore: sync upstream XiaoMa latest + restore XiaoMa-only files"
+```
+
+---
+
+## Chunk 2: Module Restructure (bmm → xmc)
+
+### Task 4: Rename src/bmm to src/xmc
+
+- [ ] **Step 7: Move bmm directory to xmc**
+
+```bash
+git mv src/bmm src/xmc
+```
+
+- [ ] **Step 8: Update module.yaml code**
+
+In `src/xmc/module.yaml`, change:
+- `code: bmm` → `code: xmc`
+- `name: "XiaoMa Method..."` → `name: "XiaoMa Method..."`
+
+- [ ] **Step 9: Restore XiaoMa-only XMC files**
+
+```bash
+cp -r /tmp/xiaoma-backup/xmc/_module-installer src/xmc/ 2>/dev/null || true
+cp -r /tmp/xiaoma-backup/xmc/sub-modules src/xmc/ 2>/dev/null || true
+cp -r /tmp/xiaoma-backup/xmc/testarch src/xmc/ 2>/dev/null || true
+```
+
+- [ ] **Step 10: Rename xiaoma-skill-manifest.yaml files to xiaoma-skill-manifest.yaml**
+
+```bash
+find src/ -name "xiaoma-skill-manifest.yaml" -exec bash -c 'mv "$1" "$(dirname "$1")/xiaoma-skill-manifest.yaml"' _ {} \;
+```
+
+- [ ] **Step 11: Rename xiaoma-master agent to xiaoma-master**
+
+```bash
+mv src/core/agents/xiaoma-master.agent.yaml src/core/agents/xiaoma-master.agent.yaml
+```
+
+- [ ] **Step 12: Rename xiaoma-help and xiaoma-review task directories**
+
+```bash
+mv src/core/tasks/xiaoma-help src/core/tasks/xiaoma-help 2>/dev/null || true
+mv src/core/tasks/xiaoma-review-adversarial-general src/core/tasks/xiaoma-review-adversarial-general 2>/dev/null || true
+mv src/core/tasks/xiaoma-review-edge-case-hunter src/core/tasks/xiaoma-review-edge-case-hunter 2>/dev/null || true
+```
+
+- [ ] **Step 13: Rename xiaoma-quick-dev-new-preview workflow directory**
+
+```bash
+# In src/xmc/workflows/xiaoma-quick-flow/ - keep the xiaoma-quick-flow name (it's an upstream name)
+# but rename the inner preview dir if needed
+mv src/xmc/workflows/xiaoma-quick-flow/xiaoma-quick-dev-new-preview src/xmc/workflows/xiaoma-quick-flow/xiaoma-quick-dev-new-preview 2>/dev/null || true
+```
+
+- [ ] **Step 14: Commit module restructure**
+
+```bash
+git add -A
+git commit -m "refactor: rename src/bmm to src/xmc with XiaoMa branding"
+```
+
+---
+
+## Chunk 3: Bulk Text Branding Replacement
+
+### Task 5: Apply branding replacements across all files
+
+The order of replacements matters - do specific/longer patterns first to avoid partial matches.
+
+- [ ] **Step 15: Apply branding in JS files (tools/ and test/)**
+
+```bash
+# Phase 1: Constants and variable names (exact code patterns)
+find tools/ test/ -name '*.js' -exec sed -i '' \
+  -e "s/XiaoMa_FOLDER_NAME/XIAOMA_FOLDER_NAME/g" \
+  -e "s/xiaomaFolderName/xiaomaFolderName/g" \
+  -e "s/xiaomaFolder/xiaomaFolder/g" \
+  -e "s/xiaomaDir/xiaomaDir/g" \
+  -e "s/xiaomaVersion/xiaomaVersion/g" \
+  -e "s/xiaomaMethod/xiaomaMethod/g" \
+  -e "s/findXiaomaDir/findXiaomaDir/g" \
+  {} +
+
+# Phase 2: Package name reference
+find tools/ test/ -name '*.js' -exec sed -i '' \
+  -e "s/'xiaoma-cli'/'xiaoma-cli'/g" \
+  -e 's/"xiaoma-cli"/"xiaoma-cli"/g' \
+  {} +
+
+# Phase 3: Module code names
+find tools/ test/ -name '*.js' -exec sed -i '' \
+  -e "s/'xmc'/'xmc'/g" \
+  -e "s/\"bmm\"/\"xmc\"/g" \
+  -e "s/'bmb'/'xmb'/g" \
+  -e "s/\"bmb\"/\"xmb\"/g" \
+  {} +
+
+# Phase 4: Path patterns (longer first)
+find tools/ test/ -name '*.js' -exec sed -i '' \
+  -e "s|src/xmc/|src/xmc/|g" \
+  -e "s|'bmm/|'xmc/|g" \
+  -e "s|/xmc/|/xmc/|g" \
+  {} +
+
+# Phase 5: Folder names in strings
+find tools/ test/ -name '*.js' -exec sed -i '' \
+  -e "s/'_xiaoma'/'_xiaoma'/g" \
+  -e 's/"_xiaoma"/"_xiaoma"/g' \
+  -e "s/'\\.xiaoma'/'.xiaoma'/g" \
+  -e "s/'xiaoma'/'xiaoma'/g" \
+  {} +
+
+# Phase 6: Brand text in comments and strings
+find tools/ test/ -name '*.js' -exec sed -i '' \
+  -e "s/XiaoMa-CORE/XIAOMA-CORE/g" \
+  -e "s/XiaoMa_/XIAOMA_/g" \
+  -e "s/XiaoMa/XiaoMa/g" \
+  {} +
+
+# Phase 7: Case-sensitive remaining xiaoma references in strings/comments
+find tools/ test/ -name '*.js' -exec sed -i '' \
+  -e "s/xiaoma-agent-/xiaoma-agent-/g" \
+  -e "s/xiaoma-module-/xiaoma-module-/g" \
+  -e "s/xiaoma-master/xiaoma-master/g" \
+  -e "s/xiaoma-help/xiaoma-help/g" \
+  -e "s/xiaoma-review/xiaoma-review/g" \
+  -e "s/xiaoma-install/xiaoma-install/g" \
+  {} +
+```
+
+- [ ] **Step 16: Apply branding in YAML files**
+
+```bash
+find src/ tools/ test/ -name '*.yaml' -exec sed -i '' \
+  -e "s/xiaoma-skill-manifest/xiaoma-skill-manifest/g" \
+  -e "s/xiaoma-master/xiaoma-master/g" \
+  -e "s/xiaoma-help/xiaoma-help/g" \
+  -e "s/xiaoma-review/xiaoma-review/g" \
+  -e "s/xiaoma-cli/xiaoma-cli/g" \
+  -e "s/xiaoma-code-org/zqyl-xiaoma/g" \
+  -e "s/xiaoma-org/xiaoma-org/g" \
+  -e "s/XiaoMa/XiaoMa/g" \
+  -e "s/_xiaoma/_xiaoma/g" \
+  -e "s/\\.xiaoma/.xiaoma/g" \
+  -e "s/code: bmm/code: xmc/g" \
+  -e "s/code: bmb/code: xmb/g" \
+  {} +
+```
+
+- [ ] **Step 17: Apply branding in Markdown/template files under src/**
+
+```bash
+find src/ -name '*.md' -exec sed -i '' \
+  -e "s/xiaoma-master/xiaoma-master/g" \
+  -e "s/xiaoma-help/xiaoma-help/g" \
+  -e "s/xiaoma-review/xiaoma-review/g" \
+  -e "s/xiaoma-skill-manifest/xiaoma-skill-manifest/g" \
+  -e "s/XiaoMa/XiaoMa/g" \
+  -e "s/XiaoMa/XIAOMA/g" \
+  -e "s/_xiaoma/_xiaoma/g" \
+  -e "s/\\.xiaoma/.xiaoma/g" \
+  -e "s|/xmc/|/xmc/|g" \
+  {} +
+```
+
+- [ ] **Step 18: Apply branding in template files (toml, md, xml, txt, csv)**
+
+```bash
+find tools/ -name '*.md' -o -name '*.toml' -exec sed -i '' \
+  -e "s/xiaoma-master/xiaoma-master/g" \
+  -e "s/xiaoma-help/xiaoma-help/g" \
+  -e "s/XiaoMa/XiaoMa/g" \
+  -e "s/XiaoMa/XIAOMA/g" \
+  -e "s/_xiaoma/_xiaoma/g" \
+  -e "s/\\.xiaoma/.xiaoma/g" \
+  -e "s|/xmc/|/xmc/|g" \
+  {} +
+
+find src/ -name '*.xml' -o -name '*.txt' -o -name '*.csv' -exec sed -i '' \
+  -e "s/XiaoMa/XiaoMa/g" \
+  -e "s/XiaoMa/XIAOMA/g" \
+  -e "s/_xiaoma/_xiaoma/g" \
+  -e "s|/xmc/|/xmc/|g" \
+  {} +
+```
+
+- [ ] **Step 19: Commit bulk branding**
+
+```bash
+git add -A
+git commit -m "chore: apply XiaoMa branding replacements"
+```
+
+---
+
+## Chunk 4: Targeted Manual Fixes
+
+### Task 6: Fix project-root.js
+
+The upstream `getModulePath()` has specific `bmm` handling. We need it for `xmc`.
+
+**Files:**
+- Modify: `tools/cli/lib/project-root.js`
+
+- [ ] **Step 20: Fix getModulePath**
+
+After bulk replacement, the file should reference `xmc` instead of `bmm`. Verify and ensure:
+```js
+function getModulePath(moduleName, ...segments) {
+  return getSourcePath(moduleName, ...segments);
+}
+```
+(All modules directly under `src/`, matching our prior refactor.)
+
+---
+
+### Task 7: Fix core module.yaml
+
+**Files:**
+- Modify: `src/core/module.yaml`
+
+- [ ] **Step 21: Verify core module.yaml branding**
+
+Ensure these values after bulk replacement:
+- `name: "XiaoMa Core Module"`
+- `header: "XiaoMa Core Configuration"`
+- `user_name.default: "XiaoMa"`
+- `output_folder.default: "_xiaoma-output"`
+
+---
+
+### Task 8: Fix external-official-modules.yaml
+
+**Files:**
+- Modify: `tools/cli/external-official-modules.yaml`
+
+- [ ] **Step 22: Verify external modules branding**
+
+Ensure:
+- URLs point to `github.com/zqyl-xiaoma/`
+- Module codes: `xmb`, `cis`, `gds`, `tea`
+- Names: "XiaoMa Builder", "XiaoMa Creative Intelligence Suite", etc.
+- NPM packages: `xiaoma-builder`, `xiaoma-creative-intelligence-suite`, etc.
+- Type: `xiaoma-org`
+
+---
+
+### Task 9: Fix package.json references in code
+
+**Files:**
+- Modify: `tools/cli/lib/project-root.js` (package name check)
+
+- [ ] **Step 23: Ensure package name check uses xiaoma-cli**
+
+In `findProjectRoot()`, the line `pkg.name === 'xiaoma-cli'` should be `pkg.name === 'xiaoma-cli'` (after bulk sed, should already be `'xiaoma-cli'` but verify).
+
+---
+
+### Task 10: Fix eslint config
+
+**Files:**
+- Modify: `eslint.config.mjs`
+
+- [ ] **Step 24: Update eslint ignores for XiaoMa structure**
+
+Ensure these ignores exist:
+```js
+'src/*/_module-installer/**',
+'src/*/sub-modules/**',
+```
+
+---
+
+### Task 11: Fix schema validation glob
+
+**Files:**
+- Modify: `tools/validate-agent-schema.js`
+
+- [ ] **Step 25: Verify agent schema glob**
+
+Should be: `src/{core,xmc}/agents/**/*.agent.yaml`
+
+---
+
+### Task 12: Fix regenerate-manifests.js
+
+**Files:**
+- Modify: `tools/cli/regenerate-manifests.js`
+
+- [ ] **Step 26: Verify selected modules**
+
+Should be: `const selectedModules = ['xmc'];`
+
+---
+
+### Task 13: Commit targeted fixes
+
+- [ ] **Step 27: Commit**
+
+```bash
+git add -A
+git commit -m "fix: targeted branding fixes for XiaoMa"
+```
+
+---
+
+## Chunk 5: Validation
+
+### Task 14: Run all validations
+
+- [ ] **Step 28: Verify directory structure**
+
+```bash
+ls src/           # Should: core/ utility/ xmc/
+ls src/xmc/       # Should have agents/, workflows/, module.yaml, etc.
+```
+
+- [ ] **Step 29: Check no residual xiaoma/bmm code references**
+
+```bash
+# Check JS files for xiaoma references (some comments about upstream are OK)
+grep -rn "'xiaoma\|\"xiaoma\|XiaoMa_\|xiaomaDir\|xiaomaFolder\|'xmc'\|\"bmm\"" tools/ test/ --include='*.js' | grep -v node_modules
+# Expected: 0 functional results (comments referencing upstream structure are acceptable)
+```
+
+- [ ] **Step 30: Run schema validation**
+
+```bash
+npm run validate:schemas
+# Expected: All agents pass (tea.agent.yaml and dev.agent.yaml may fail on pre-existing webskip issue)
+```
+
+- [ ] **Step 31: Run schema tests**
+
+```bash
+npm run test:schemas
+# Expected: All 52 tests pass
+```
+
+- [ ] **Step 32: Run installation tests**
+
+```bash
+npm run test:install
+# Expected: All 12 tests pass
+```
+
+- [ ] **Step 33: Run lint**
+
+```bash
+npm run lint
+# Expected: 0 errors, 0 warnings
+```
+
+- [ ] **Step 34: Run format check**
+
+```bash
+npm run format:check
+# Fix any formatting issues with: npm run format:fix
+```
+
+- [ ] **Step 35: Final commit if needed**
+
+```bash
+git add -A
+git commit -m "fix: post-sync validation fixes"
+```
+
+---
+
+## Important Notes
+
+1. **The upstream has removed many files** that XiaoMa still uses (bundlers, flattener, IDE handlers, XML workflows). These are restored from backup. The upstream has moved to a "skills" architecture with `xiaoma-skill-manifest.yaml` files and `SKILL.md` files - we rename these to `xiaoma-skill-manifest.yaml`.
+
+2. **The `xiaoma-quick-flow` directory name** is kept as-is since it's a workflow family name from upstream. Only the file contents get rebranded.
+
+3. **The `xiaoma-quick-dev-new-preview` workflow** is an upstream addition - rename the directory but keep the content structure.
+
+4. **Test fixtures** with `src/modules/xmc` path references need updating to `src/xmc` after the bulk replacement.
+
+5. **The `custom/` directory** at project root is untouched by this plan (it's not under `src/`, `tools/`, or `test/`).