@zeyue0329/xiaoma-cli 1.6.4 → 1.7.0

package/docs/explanation/preventing-agent-conflicts.md

@@ -1,112 +0,0 @@
----
-title: "Preventing Agent Conflicts"
-description: How architecture prevents conflicts when multiple agents implement a system
-sidebar:
-  order: 4
----
-
-When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
-
-## Common Conflict Types
-
-### API Style Conflicts
-
-Without architecture:
-- Agent A uses REST with `/users/{id}`
-- Agent B uses GraphQL mutations
-- Result: Inconsistent API patterns, confused consumers
-
-With architecture:
-- ADR specifies: "Use GraphQL for all client-server communication"
-- All agents follow the same pattern
-
-### Database Design Conflicts
-
-Without architecture:
-- Agent A uses snake_case column names
-- Agent B uses camelCase column names
-- Result: Inconsistent schema, confusing queries
-
-With architecture:
-- Standards document specifies naming conventions
-- All agents follow the same patterns
-
-### State Management Conflicts
-
-Without architecture:
-- Agent A uses Redux for global state
-- Agent B uses React Context
-- Result: Multiple state management approaches, complexity
-
-With architecture:
-- ADR specifies state management approach
-- All agents implement consistently
-
-## How Architecture Prevents Conflicts
-
-### 1. Explicit Decisions via ADRs
-
-Every significant technology choice is documented with:
-- Context (why this decision matters)
-- Options considered (what alternatives exist)
-- Decision (what we chose)
-- Rationale (why we chose it)
-- Consequences (trade-offs accepted)
-
-### 2. FR/NFR-Specific Guidance
-
-Architecture maps each functional requirement to technical approach:
-- FR-001: User Management → GraphQL mutations
-- FR-002: Mobile App → Optimized queries
-
-### 3. Standards and Conventions
-
-Explicit documentation of:
-- Directory structure
-- Naming conventions
-- Code organization
-- Testing patterns
-
-## Architecture as Shared Context
-
-Think of architecture as the shared context that all agents read before implementing:
-
-```text
-PRD: "What to build"
-     ↓
-Architecture: "How to build it"
-     ↓
-Agent A reads architecture → implements Epic 1
-Agent B reads architecture → implements Epic 2
-Agent C reads architecture → implements Epic 3
-     ↓
-Result: Consistent implementation
-```
-
-## Key ADR Topics
-
-Common decisions that prevent conflicts:
-
-| Topic            | Example Decision                             |
-| ---------------- | -------------------------------------------- |
-| API Style        | GraphQL vs REST vs gRPC                      |
-| Database         | PostgreSQL vs MongoDB                        |
-| Auth             | JWT vs Sessions                              |
-| State Management | Redux vs Context vs Zustand                  |
-| Styling          | CSS Modules vs Tailwind vs Styled Components |
-| Testing          | Jest + Playwright vs Vitest + Cypress        |
-
-## Anti-Patterns to Avoid
-
-:::caution[Common Mistakes]
-- **Implicit Decisions** — "We'll figure out the API style as we go" leads to inconsistency
-- **Over-Documentation** — Documenting every minor choice causes analysis paralysis
-- **Stale Architecture** — Documents written once and never updated cause agents to follow outdated patterns
-:::
-
-:::tip[Correct Approach]
-- Document decisions that cross epic boundaries
-- Focus on conflict-prone areas
-- Update architecture as you learn
-- Use `xiaoma-correct-course` for significant changes
-:::

package/docs/explanation/project-context.md

@@ -1,157 +0,0 @@
----
-title: "Project Context"
-description: How project-context.md guides AI agents with your project's rules and preferences
-sidebar:
-  order: 7
----
-
-The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.
-
-## What It Does
-
-AI agents make implementation decisions constantly — which patterns to follow, how to structure code, what conventions to use. Without clear guidance, they may:
-- Follow generic best practices that don't match your codebase
-- Make inconsistent decisions across different stories
-- Miss project-specific requirements or constraints
-
-The `project-context.md` file solves this by documenting what agents need to know in a concise, LLM-optimized format.
-
-## How It Works
-
-Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture.
-
-**Loaded by these workflows:**
-- `xiaoma-create-architecture` — respects technical preferences during solutioning
-- `xiaoma-create-story` — informs story creation with project patterns
-- `xiaoma-dev-story` — guides implementation decisions
-- `xiaoma-code-review` — validates against project standards
-- `xiaoma-quick-dev` — applies patterns when implementing tech-specs
-- `xiaoma-sprint-planning`, `xiaoma-retrospective`, `xiaoma-correct-course` — provides project-wide context
-
-## When to Create It
-
-The `project-context.md` file is useful at any stage of a project:
-
-| Scenario | When to Create | Purpose |
-|----------|----------------|---------|
-| **New project, before architecture** | Manually, before `xiaoma-create-architecture` | Document your technical preferences so the architect respects them |
-| **New project, after architecture** | Via `xiaoma-generate-project-context` or manually | Capture architecture decisions for implementation agents |
-| **Existing project** | Via `xiaoma-generate-project-context` | Discover existing patterns so agents follow established conventions |
-| **Quick Flow project** | Before or during `xiaoma-quick-dev` | Ensure quick implementation respects your patterns |
-
-:::tip[Recommended]
-For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions.
-:::
-
-## What Goes In It
-
-The file has two main sections:
-
-### Technology Stack & Versions
-
-Documents the frameworks, languages, and tools your project uses with specific versions:
-
-```markdown
-## Technology Stack & Versions
-
-- Node.js 20.x, TypeScript 5.3, React 18.2
-- State: Zustand (not Redux)
-- Testing: Vitest, Playwright, MSW
-- Styling: Tailwind CSS with custom design tokens
-```
-
-### Critical Implementation Rules
-
-Documents patterns and conventions that agents might otherwise miss:
-
-```markdown
-## Critical Implementation Rules
-
-**TypeScript Configuration:**
-- Strict mode enabled — no `any` types without explicit approval
-- Use `interface` for public APIs, `type` for unions/intersections
-
-**Code Organization:**
-- Components in `/src/components/` with co-located `.test.tsx`
-- Utilities in `/src/lib/` for reusable pure functions
-- API calls use the `apiClient` singleton — never fetch directly
-
-**Testing Patterns:**
-- Unit tests focus on business logic, not implementation details
-- Integration tests use MSW to mock API responses
-- E2E tests cover critical user journeys only
-
-**Framework-Specific:**
-- All async operations use the `handleError` wrapper for consistent error handling
-- Feature flags accessed via `featureFlag()` from `@/lib/flags`
-- New routes follow the file-based routing pattern in `/src/app/`
-```
-
-Focus on what's **unobvious** — things agents might not infer from reading code snippets. Don't document standard practices that apply universally.
-
-## Creating the File
-
-You have three options:
-
-### Manual Creation
-
-Create the file at `_xiaoma-output/project-context.md` and add your rules:
-
-```bash
-# In your project root
-mkdir -p _xiaoma-output
-touch _xiaoma-output/project-context.md
-```
-
-Edit it with your technology stack and implementation rules. The architect and implementation workflows will automatically find and load it.
-
-### Generate After Architecture
-
-Run the `xiaoma-generate-project-context` workflow after completing your architecture:
-
-```bash
-xiaoma-generate-project-context
-```
-
-This scans your architecture document and project files to generate a context file capturing the decisions made.
-
-### Generate for Existing Projects
-
-For existing projects, run `xiaoma-generate-project-context` to discover existing patterns:
-
-```bash
-xiaoma-generate-project-context
-```
-
-The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
-
-## Why It Matters
-
-Without `project-context.md`, agents make assumptions that may not match your project:
-
-| Without Context | With Context |
-|----------------|--------------|
-| Uses generic patterns | Follows your established conventions |
-| Inconsistent style across stories | Consistent implementation |
-| May miss project-specific constraints | Respects all technical requirements |
-| Each agent decides independently | All agents align with same rules |
-
-This is especially important for:
-- **Quick Flow** — skips PRD and architecture, so context file fills the gap
-- **Team projects** — ensures all agents follow the same standards
-- **Existing projects** — prevents breaking established patterns
-
-## Editing and Updating
-
-The `project-context.md` file is a living document. Update it when:
-
-- Architecture decisions change
-- New conventions are established
-- Patterns evolve during implementation
-- You identify gaps from agent behavior
-
-You can edit it manually at any time, or re-run `xiaoma-generate-project-context` to update it after significant changes.
-
-:::note[File Location]
-The default location is `_xiaoma-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project.
-:::

package/docs/explanation/quick-dev-new-preview.md

@@ -1,73 +0,0 @@
----
-title: "Quick Dev New Preview"
-description: Reduce human-in-the-loop friction without giving up the checkpoints that protect output quality
-sidebar:
-  order: 2
----
-
-`xiaoma-quick-dev-new-preview` is an experimental attempt to radically improve Quick Flow: intent in, code changes out, with lower ceremony and fewer human-in-the-loop turns without sacrificing quality.
-
-It lets the model run longer between checkpoints, then brings the human back only when the task cannot safely continue without human judgment or when it is time to review the end result.
-
-![Quick Dev New Preview workflow diagram](/diagrams/quick-dev-diagram.png)
-
-## Why This Exists
-
-Human-in-the-loop turns are necessary and expensive.
-
-Current LLMs still fail in predictable ways: they misread intent, fill gaps with confident guesses, drift into unrelated work, and generate noisy review output. At the same time, constant human intervention limits development velocity. Human attention is the bottleneck.
-
-This experimental version of Quick Flow is an attempt to rebalance that tradeoff. It trusts the model to run unsupervised for longer stretches, but only after the workflow has created a strong enough boundary to make that safe.
-
-## The Core Design
-
-### 1. Compress intent first
-
-The workflow starts by having the human and the model compress the request into one coherent goal. The input can begin as a rough expression of intent, but before the workflow runs autonomously it has to become small enough, clear enough, and contradiction-free enough to execute.
-
-Intent can come in many forms: a couple of phrases, a bug tracker link, output from plan mode, text copied from a chat session, or even a story number from XiaoMa's own `epics.md`. In that last case, the workflow will not understand XiaoMa story-tracking semantics, but it can still take the story itself and run with it.
-
-This workflow does not eliminate human control. It relocates it to a small number of high-value moments:
-
-- **Intent clarification** - turning a messy request into one coherent goal without hidden contradictions
-- **Spec approval** - confirming that the frozen understanding is the right thing to build
-- **Review of the final product** - the primary checkpoint, where the human decides whether the result is acceptable at the end
-
-### 2. Route to the smallest safe path
-
-Once the goal is clear, the workflow decides whether this is a true one-shot change or whether it needs the fuller path. Small, zero-blast-radius changes can go straight to implementation. Everything else goes through planning so the model has a stronger boundary before it runs longer on its own.
-
-### 3. Run longer with less supervision
-
-After that routing decision, the model can carry more of the work on its own. On the fuller path, the approved spec becomes the boundary the model executes against with less supervision, which is the whole point of the experiment.
-
-### 4. Diagnose failure at the right layer
-
-If the implementation is wrong because the intent was wrong, patching the code is the wrong fix. If the code is wrong because the spec was weak, patching the diff is also the wrong fix. The workflow is designed to diagnose where the failure entered the system, go back to that layer, and regenerate from there.
-
-Review findings are used to decide whether the problem came from intent, spec generation, or local implementation. Only truly local problems get patched locally.
-
-### 5. Bring the human back only when needed
-
-The intent interview is human-in-the-loop, but it is not the same kind of interruption as a recurring checkpoint. The workflow tries to keep those recurring checkpoints to a minimum. After the initial shaping of intent, the human mainly comes back when the workflow cannot safely continue without judgment and at the end, when it is time to review the result.
-
-- **Intent-gap resolution** - stepping back in when review proves the workflow could not safely infer what was meant
-
-Everything else is a candidate for longer autonomous execution. That tradeoff is deliberate. Older patterns spend more human attention on continuous supervision. Quick Dev New Preview spends more trust on the model, but saves human attention for the moments where human reasoning has the highest leverage.
-
-## Why the Review System Matters
-
-The review phase is not just there to find bugs. It is there to route correction without destroying momentum.
-
-This workflow works best on a platform that can spawn subagents, or at least invoke another LLM through the command line and wait for a result. If your platform does not support that natively, you can add a skill to do it. Context-free subagents are a cornerstone of the review design.
-
-Agentic reviews often go wrong in two ways:
-
-- They generate too many findings, forcing the human to sift through noise.
-- They derail the current change by surfacing unrelated issues and turning every run into an ad hoc cleanup project.
-
-Quick Dev New Preview addresses both by treating review as triage.
-
-Some findings belong to the current change. Some do not. If a finding is incidental rather than causally tied to the current work, the workflow can defer it instead of forcing the human to handle it immediately. That keeps the run focused and prevents random tangents from consuming the budget of attention.
-
-That triage will sometimes be imperfect. That is acceptable. It is usually better to misjudge some findings than to flood the human with thousands of low-value review comments. The system is optimizing for signal quality, not exhaustive recall.

package/docs/explanation/quick-flow.md

@@ -1,77 +0,0 @@
----
-title: "Quick Flow"
-description: Fast-track for small changes - skip the full methodology
-sidebar:
-  order: 1
----
-
-Skip the ceremony. Quick Flow takes you from idea to working code in two skills - no Product Brief, no PRD, no Architecture doc.
-
-:::tip[Want a Unified Variant?]
-If you want one workflow to clarify, plan, implement, review, and present in a single run, see [Quick Dev New Preview](./quick-dev-new-preview.md).
-:::
-
-## When to Use It
-
-- Bug fixes and patches
-- Refactoring existing code
-- Small, well-understood features
-- Prototyping and spikes
-- Single-agent work where one developer can hold the full scope
-
-## When NOT to Use It
-
-- New products or platforms that need stakeholder alignment
-- Major features spanning multiple components or teams
-- Work that requires architectural decisions (database schema, API contracts, service boundaries)
-- Anything where requirements are unclear or contested
-
-:::caution[Scope Creep]
-If you start a Quick Flow and realize the scope is bigger than expected, `xiaoma-quick-dev` will detect this and offer to escalate. You can switch to a full PRD workflow at any point without losing your work.
-:::
-
-## How It Works
-
-Quick Flow has two skills, each backed by a structured workflow. You can run them together or independently.
-
-### quick-spec: Plan
-
-Run `xiaoma-quick-spec` and Barry (the Quick Flow agent) walks you through a conversational discovery process:
-
-1. **Understand** - You describe what you want to build. Barry scans the codebase to ask informed questions, then captures a problem statement, solution approach, and scope boundaries.
-2. **Investigate** - Barry reads relevant files, maps code patterns, identifies files to modify, and documents the technical context.
-3. **Generate** - Produces a complete tech-spec with ordered implementation tasks (specific file paths and actions), acceptance criteria in Given/When/Then format, testing strategy, and dependencies.
-4. **Review** - Presents the full spec for your sign-off. You can edit, ask questions, run adversarial review, or refine with advanced elicitation before finalizing.
-
-The output is a `tech-spec-{slug}.md` file saved to your project's implementation artifacts folder. It contains everything a fresh agent needs to implement the feature - no conversation history required.
-
-### quick-dev: Build
-
-Run `xiaoma-quick-dev` and Barry implements the work. It operates in two modes:
-
-- **Tech-spec mode** - Point it at a spec file (`quick-dev tech-spec-auth.md`) and it executes every task in order, writes tests, and verifies acceptance criteria.
-- **Direct mode** - Give it instructions directly (`quick-dev "refactor the auth middleware"`) and it gathers context, builds a mental plan, and executes.
-
-After implementation, `xiaoma-quick-dev` runs a self-check audit against all tasks and acceptance criteria, then triggers an adversarial code review of the diff. Findings are presented for you to resolve before wrapping up.
-
-:::tip[Fresh Context]
-For best results, run `xiaoma-quick-dev` in a new conversation after finishing `xiaoma-quick-spec`. This gives the implementation agent clean context focused solely on building.
-:::
-
-## What Quick Flow Skips
-
-The full XiaoMa Method produces a Product Brief, PRD, Architecture doc, and Epic/Story breakdown before any code is written. Quick Flow replaces all of that with a single tech-spec. This works because Quick Flow targets changes where:
-
-- The product direction is already established
-- Architecture decisions are already made
-- A single developer can reason about the full scope
-- Requirements fit in one conversation
-
-## Escalating to Full XiaoMa Method
-
-Quick Flow includes built-in guardrails for scope detection. When you run `xiaoma-quick-dev` with a direct request, it evaluates signals like multi-component mentions, system-level language, and uncertainty about approach. If it detects the work is bigger than a quick flow:
-
-- **Light escalation** - Recommends running `xiaoma-quick-spec` first to create a plan
-- **Heavy escalation** - Recommends switching to the full XiaoMa Method PRD process
-
-You can also escalate manually at any time. Your tech-spec work carries forward - it becomes input for the broader planning process rather than being discarded.

package/docs/explanation/why-solutioning-matters.md

@@ -1,77 +0,0 @@
----
-title: "Why Solutioning Matters"
-description: Understanding why the solutioning phase is critical for multi-epic projects
-sidebar:
-  order: 3
----
-
-
-Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
-
-## The Problem Without Solutioning
-
-```text
-Agent 1 implements Epic 1 using REST API
-Agent 2 implements Epic 2 using GraphQL
-Result: Inconsistent API design, integration nightmare
-```
-
-When multiple agents implement different parts of a system without shared architectural guidance, they make independent technical decisions that may conflict.
-
-## The Solution With Solutioning
-
-```text
-architecture workflow decides: "Use GraphQL for all APIs"
-All agents follow architecture decisions
-Result: Consistent implementation, no conflicts
-```
-
-By documenting technical decisions explicitly, all agents implement consistently and integration becomes straightforward.
-
-## Solutioning vs Planning
-
-| Aspect   | Planning (Phase 2)      | Solutioning (Phase 3)             |
-| -------- | ----------------------- | --------------------------------- |
-| Question | What and Why?           | How? Then What units of work?     |
-| Output   | FRs/NFRs (Requirements) | Architecture + Epics/Stories      |
-| Agent    | PM                      | Architect → PM                    |
-| Audience | Stakeholders            | Developers                        |
-| Document | PRD (FRs/NFRs)          | Architecture + Epic Files         |
-| Level    | Business logic          | Technical design + Work breakdown |
-
-## Key Principle
-
-**Make technical decisions explicit and documented** so all agents implement consistently.
-
-This prevents:
-- API style conflicts (REST vs GraphQL)
-- Database design inconsistencies
-- State management disagreements
-- Naming convention mismatches
-- Security approach variations
-
-## When Solutioning is Required
-
-| Track | Solutioning Required? |
-|-------|----------------------|
-| Quick Flow | No - skip entirely |
-| XiaoMa Method Simple | Optional |
-| XiaoMa Method Complex | Yes |
-| Enterprise | Yes |
-
-:::tip[Rule of Thumb]
-If you have multiple epics that could be implemented by different agents, you need solutioning.
-:::
-
-## The Cost of Skipping
-
-Skipping solutioning on complex projects leads to:
-
-- **Integration issues** discovered mid-sprint
-- **Rework** due to conflicting implementations
-- **Longer development time** overall
-- **Technical debt** from inconsistent patterns
-
-:::caution[Cost Multiplier]
-Catching alignment issues in solutioning is 10× faster than discovering them during implementation.
-:::

package/docs/how-to/customize-xiaoma.md

@@ -1,172 +0,0 @@
----
-title: "How to Customize XiaoMa"
-description: Customize agents, workflows, and modules while preserving update compatibility
-sidebar:
-  order: 7
----
-
-Use the `.customize.yaml` files to tailor agent behavior, personas, and menus while preserving your changes across updates.
-
-## When to Use This
-
-- You want to change an agent's name, personality, or communication style
-- You need agents to remember project-specific context
-- You want to add custom menu items that trigger your own workflows or prompts
-- You want agents to perform specific actions every time they start up
-
-:::note[Prerequisites]
-- XiaoMa installed in your project (see [How to Install XiaoMa](./install-xiaoma.md))
-- A text editor for YAML files
-:::
-
-:::caution[Keep Your Customizations Safe]
-Always use the `.customize.yaml` files described here rather than editing agent files directly. The installer overwrites agent files during updates, but preserves your `.customize.yaml` changes.
-:::
-
-## Steps
-
-### 1. Locate Customization Files
-
-After installation, find one `.customize.yaml` file per agent in:
-
-```text
-_xiaoma/_config/agents/
-├── core-xiaoma-master.customize.yaml
-├── xmc-dev.customize.yaml
-├── xmc-pm.customize.yaml
-└── ... (one file per installed agent)
-```
-
-### 2. Edit the Customization File
-
-Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
-
-| Section            | Behavior | Purpose                                         |
-| ------------------ | -------- | ----------------------------------------------- |
-| `agent.metadata`   | Replaces | Override the agent's display name               |
-| `persona`          | Replaces | Set role, identity, style, and principles       |
-| `memories`         | Appends  | Add persistent context the agent always recalls |
-| `menu`             | Appends  | Add custom menu items for workflows or prompts  |
-| `critical_actions` | Appends  | Define startup instructions for the agent       |
-| `prompts`          | Appends  | Create reusable prompts for menu actions        |
-
-Sections marked **Replaces** overwrite the agent's defaults entirely. Sections marked **Appends** add to the existing configuration.
-
-**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 annoying'
-  principles:
-    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
-    - 'Favor composition over inheritance'
-```
-
-The `persona` section replaces the entire default persona, so include all four fields if you set it.
-
-**Memories**
-
-Add persistent context the agent will always remember:
-
-```yaml
-memories:
-  - 'Works at Krusty Krab'
-  - 'Favorite Celebrity: David Hasslehoff'
-  - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'
-```
-
-**Menu Items**
-
-Add custom entries to the agent's display menu. Each item needs a `trigger`, a target (`workflow` path or `action` reference), and a `description`:
-
-```yaml
-menu:
-  - trigger: my-workflow
-    workflow: 'my-custom/workflows/my-workflow.yaml'
-    description: My custom workflow
-  - trigger: deploy
-    action: '#deploy-prompt'
-    description: Deploy to production
-```
-
-**Critical Actions**
-
-Define instructions that run when the agent starts up:
-
-```yaml
-critical_actions:
-  - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
-```
-
-**Custom Prompts**
-
-Create reusable prompts that menu items can reference with `action="#id"`:
-
-```yaml
-prompts:
-  - id: deploy-prompt
-    content: |
-      Deploy the current branch to production:
-      1. Run all tests
-      2. Build the project
-      3. Execute deployment script
-```
-
-### 3. Apply Your Changes
-
-After editing, recompile the agent to apply changes:
-
-```bash
-npx xiaoma-cli install
-```
-
-The installer detects the existing installation and offers these options:
-
-| Option                       | What It Does                                                        |
-| ---------------------------- | ------------------------------------------------------------------- |
-| **Quick Update**             | Updates all modules to the latest version and recompiles all agents |
-| **Recompile Agents**         | Applies customizations only, without updating module files          |
-| **Modify XiaoMa Installation** | Full installation flow for adding or removing modules               |
-
-For customization-only changes, **Recompile Agents** is the fastest option.
-
-## Troubleshooting
-
-**Changes not appearing?**
-
-- Run `npx xiaoma-cli install` and select **Recompile Agents** to apply changes
-- Check that your YAML syntax is valid (indentation matters)
-- Verify you edited the correct `.customize.yaml` file for the agent
-
-**Agent not loading?**
-
-- Check for YAML syntax errors using an online YAML validator
-- Ensure you did not leave fields empty after uncommenting them
-- Try reverting to the original template and rebuilding
-
-**Need to reset an agent?**
-
-- Clear or delete the agent's `.customize.yaml` file
-- Run `npx xiaoma-cli install` and select **Recompile Agents** to restore defaults
-
-## Workflow Customization
-
-Customization of existing XiaoMa Method workflows and skills is coming soon.
-
-## Module Customization
-
-Guidance on building expansion modules and customizing existing modules is coming soon.