@zeyue0329/xiaoma-cli 1.6.4 → 1.7.0

package/docs/document-sharding-guide.md

@@ -1,449 +0,0 @@
-# Document Sharding Guide
-
-Comprehensive guide to XiaoMa Method's document sharding system for managing large planning and architecture documents.
-
-## Table of Contents
-
-- [What is Document Sharding?](#what-is-document-sharding)
-- [When to Use Sharding](#when-to-use-sharding)
-- [How Sharding Works](#how-sharding-works)
-- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
-- [Workflow Support](#workflow-support)
-- [Best Practices](#best-practices)
-- [Examples](#examples)
-
-## What is Document Sharding?
-
-Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
-
-- **Selective Loading** - Workflows load only the sections they need
-- **Reduced Token Usage** - Massive efficiency gains for large projects
-- **Better Organization** - Logical section-based file structure
-- **Maintained Context** - Index file preserves document structure
-
-### Architecture
-
-```
-Before Sharding:
-docs/
-└── PRD.md (large 50k token file)
-
-After Sharding:
-docs/
-└── prd/
-    ├── index.md                    # Table of contents with descriptions
-    ├── overview.md                 # Section 1
-    ├── user-requirements.md        # Section 2
-    ├── technical-requirements.md   # Section 3
-    └── ...                         # Additional sections
-```
-
-## When to Use Sharding
-
-### Ideal Candidates
-
-**Large Multi-Epic Projects:**
-
-- Very large complex PRDs
-- Architecture documents with multiple system layers
-- Epic files with 4+ epics (especially for Phase 4)
-- UX design specs covering multiple subsystems
-
-**Token Thresholds:**
-
-- **Consider sharding**: Documents > 20k tokens
-- **Strongly recommended**: Documents > 40k tokens
-- **Critical for efficiency**: Documents > 60k tokens
-
-### When NOT to Shard
-
-**Small Projects:**
-
-- Single epic projects
-- Level 0-1 projects (tech-spec only)
-- Documents under 10k tokens
-- Quick prototypes
-
-**Frequently Updated Docs:**
-
-- Active work-in-progress documents
-- Documents updated daily
-- Documents where whole-file context is essential
-
-## How Sharding Works
-
-### Sharding Process
-
-1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools.
-2. **Section Extraction**: Tool splits by level 2 headings
-3. **File Creation**: Each section becomes a separate file
-4. **Index Generation**: `index.md` created with structure and descriptions
-
-### Workflow Discovery
-
-XiaoMa workflows use a **dual discovery system**:
-
-1. **Try whole document first** - Look for `document-name.md`
-2. **Check for sharded version** - Look for `document-name/index.md`
-3. **Priority rule** - Whole document takes precedence if both exist
-
-### Loading Strategies
-
-**Full Load (Phase 1-3 workflows):**
-
-```
-If sharded:
-  - Read index.md
-  - Read ALL section files
-  - Treat as single combined document
-```
-
-**Selective Load (Phase 4 workflows):**
-
-```
-If sharded epics and working on Epic 3:
-  - Read epics/index.md
-  - Load ONLY epics/epic-3.md
-  - Skip all other epic files
-  - 90%+ token savings!
-```
-
-## Using the Shard-Doc Tool
-
-### CLI Command
-
-```bash
-# Activate xiaoma-master or analyst agent, then:
-/shard-doc
-```
-
-### Interactive Process
-
-```
-Agent: Which document would you like to shard?
-User: docs/PRD.md
-
-Agent: Default destination: docs/prd/
-       Accept default? [y/n]
-User: y
-
-Agent: Sharding PRD.md...
-       ✓ Created 12 section files
-       ✓ Generated index.md
-       ✓ Complete!
-```
-
-### What Gets Created
-
-**index.md structure:**
-
-```markdown
-# PRD - Index
-
-## Sections
-
-1. [Overview](./overview.md) - Project vision and objectives
-2. [User Requirements](./user-requirements.md) - Feature specifications
-3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
-4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
-   ...
-```
-
-**Individual section files:**
-
-- Named from heading text (kebab-case)
-- Contains complete section content
-- Preserves all markdown formatting
-- Can be read independently
-
-## Workflow Support
-
-### Universal Support
-
-**All XMC workflows support both formats:**
-
-- ✅ Whole documents
-- ✅ Sharded documents
-- ✅ Automatic detection
-- ✅ Transparent to user
-
-### Workflow-Specific Patterns
-
-#### Phase 1-3 (Full Load)
-
-Workflows load entire sharded documents:
-
-- `product-brief` - Research, brainstorming docs
-- `prd` - Product brief, research
-- `gdd` - Game brief, research
-- `create-ux-design` - PRD, brief, architecture (if available)
-- `tech-spec` - Brief, research
-- `architecture` - PRD, UX design (if available)
-- `create-epics-and-stories` - PRD, architecture
-- `implementation-readiness` - All planning docs
-
-#### Phase 4 (Selective Load)
-
-Workflows load only needed sections:
-
-**sprint-planning** (Full Load):
-
-- Needs ALL epics to build complete status
-
-**create-story, code-review** (Selective):
-
-```
-Working on Epic 3, Story 2:
-  ✓ Load epics/epic-3.md only
-  ✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc.
-
-Result: 90%+ token reduction for 10-epic projects!
-```
-
-### Input File Patterns
-
-Workflows use standardized patterns:
-
-```yaml
-input_file_patterns:
-  prd:
-    whole: '{output_folder}/*prd*.md'
-    sharded: '{output_folder}/*prd*/index.md'
-
-  epics:
-    whole: '{output_folder}/*epic*.md'
-    sharded_index: '{output_folder}/*epic*/index.md'
-    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
-```
-
-## Best Practices
-
-### Sharding Strategy
-
-**Do:**
-
-- ✅ Shard after planning phase complete
-- ✅ Keep level 2 headings well-organized
-- ✅ Use descriptive section names
-- ✅ Shard before Phase 4 implementation
-- ✅ Keep original file as backup initially
-
-**Don't:**
-
-- ❌ Shard work-in-progress documents
-- ❌ Shard small documents (<20k tokens)
-- ❌ Mix sharded and whole versions
-- ❌ Manually edit index.md structure
-
-### Naming Conventions
-
-**Good Section Names:**
-
-```markdown
-## Epic 1: User Authentication
-
-## Technical Requirements
-
-## System Architecture
-
-## UX Design Principles
-```
-
-**Poor Section Names:**
-
-```markdown
-## Section 1
-
-## Part A
-
-## Details
-
-## More Info
-```
-
-### File Management
-
-**When to Re-shard:**
-
-- Significant structural changes to document
-- Adding/removing major sections
-- After major refactoring
-
-**Updating Sharded Docs:**
-
-1. Edit individual section files directly
-2. OR edit original, delete sharded folder, re-shard
-3. Don't manually edit index.md
-
-## Examples
-
-### Example 1: Large PRD
-
-**Scenario:** 15-epic project, PRD is 45k tokens
-
-**Before Sharding:**
-
-```
-Every workflow loads entire 45k token PRD
-Architecture workflow: 45k tokens
-UX design workflow: 45k tokens
-```
-
-**After Sharding:**
-
-```bash
-/shard-doc
-Source: docs/PRD.md
-Destination: docs/prd/
-
-Created:
-  prd/index.md
-  prd/overview.md (3k tokens)
-  prd/functional-requirements.md (8k tokens)
-  prd/non-functional-requirements.md (6k tokens)
-  prd/user-personas.md (4k tokens)
-  ...additional FR/NFR sections
-```
-
-**Result:**
-
-```
-Architecture workflow: Can load specific sections needed
-UX design workflow: Can load specific sections needed
-Significant token reduction for large requirement docs!
-```
-
-### Example 2: Sharding Epics File
-
-**Scenario:** 8 epics with detailed stories, 35k tokens total
-
-```bash
-/shard-doc
-Source: docs/xmc-epics.md
-Destination: docs/epics/
-
-Created:
-  epics/index.md
-  epics/epic-1.md
-  epics/epic-2.md
-  ...
-  epics/epic-8.md
-```
-
-**Efficiency Gain:**
-
-```
-Working on Epic 5 stories:
-  Old: Load all 8 epics (35k tokens)
-  New: Load epic-5.md only (4k tokens)
-  Savings: 88% reduction
-```
-
-### Example 3: Architecture Document
-
-**Scenario:** Multi-layer system architecture, 28k tokens
-
-```bash
-/shard-doc
-Source: docs/architecture.md
-Destination: docs/architecture/
-
-Created:
-  architecture/index.md
-  architecture/system-overview.md
-  architecture/frontend-architecture.md
-  architecture/backend-services.md
-  architecture/data-layer.md
-  architecture/infrastructure.md
-  architecture/security-architecture.md
-```
-
-**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc.
-
-## Custom Workflow Integration
-
-### For Workflow Builders
-
-When creating custom workflows that load large documents:
-
-**1. Add input_file_patterns to workflow.yaml:**
-
-```yaml
-input_file_patterns:
-  your_document:
-    whole: '{output_folder}/*your-doc*.md'
-    sharded: '{output_folder}/*your-doc*/index.md'
-```
-
-**2. Add discovery instructions to instructions.md:**
-
-```markdown
-## Document Discovery
-
-1. Search for whole document: _your-doc_.md
-2. Check for sharded version: _your-doc_/index.md
-3. If sharded: Read index + ALL sections (or specific sections if selective load)
-4. Priority: Whole document first
-```
-
-**3. Choose loading strategy:**
-
-- **Full Load**: Read all sections when sharded
-- **Selective Load**: Read only relevant sections (requires section identification logic)
-
-### Pattern Templates
-
-**Full Load Pattern:**
-
-```xml
-<action>Search for document: {output_folder}/*doc-name*.md</action>
-<action>If not found, check for sharded: {output_folder}/*doc-name*/index.md</action>
-<action if="sharded found">Read index.md to understand structure</action>
-<action if="sharded found">Read ALL section files listed in index</action>
-<action if="sharded found">Combine content as single document</action>
-```
-
-**Selective Load Pattern (with section ID):**
-
-```xml
-<action>Determine section needed (e.g., epic_num = 3)</action>
-<action>Check for sharded version: {output_folder}/*doc-name*/index.md</action>
-<action if="sharded found">Read ONLY the specific section file needed</action>
-<action if="sharded found">Skip all other section files</action>
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**Both whole and sharded exist:**
-
-- Workflows will use whole document (priority rule)
-- Delete or archive the one you don't want
-
-**Index.md out of sync:**
-
-- Delete sharded folder
-- Re-run shard-doc on original
-
-**Workflow can't find document:**
-
-- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.)
-- Verify index.md exists in sharded folder
-- Check output_folder path in config
-
-**Sections too granular:**
-
-- Combine sections in original document
-- Use fewer level 2 headings
-- Re-shard
-
-## Related Documentation
-
-- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation
-- [XMC Workflows Guide](../src/modules/xmc/workflows/README.md) - Workflow overview
-- [Workflow Creation Guide](../src/modules/xmb/workflows/create-workflow/workflow-creation-guide.md) - Custom workflow patterns
-
----
-
-**Document sharding is optional but powerful** - use it when efficiency matters for large projects!

package/docs/explanation/advanced-elicitation.md

@@ -1,49 +0,0 @@
----
-title: "Advanced Elicitation"
-description: Push the LLM to rethink its work using structured reasoning methods
-sidebar:
-  order: 6
----
-
-Make the LLM reconsider what it just generated. You pick a reasoning method, it applies that method to its own output, you decide whether to keep the improvements.
-
-## What is Advanced Elicitation?
-
-A structured second pass. Instead of asking the AI to "try again" or "make it better," you select a specific reasoning method and the AI re-examines its own output through that lens.
-
-The difference matters. Vague requests produce vague revisions. A named method forces a particular angle of attack, surfacing insights that a generic retry would miss.
-
-## When to Use It
-
-- After a workflow generates content and you want alternatives
-- When output seems okay but you suspect there's more depth
-- To stress-test assumptions or find weaknesses
-- For high-stakes content where rethinking helps
-
-Workflows offer advanced elicitation at decision points - after the LLM has generated something, you'll be asked if you want to run it.
-
-## How It Works
-
-1. LLM suggests 5 relevant methods for your content
-2. You pick one (or reshuffle for different options)
-3. Method is applied, improvements shown
-4. Accept or discard, repeat or continue
-
-## Built-in Methods
-
-Dozens of reasoning methods are available. A few examples:
-
-- **Pre-mortem Analysis** - Assume the project already failed, work backward to find why
-- **First Principles Thinking** - Strip away assumptions, rebuild from ground truth
-- **Inversion** - Ask how to guarantee failure, then avoid those things
-- **Red Team vs Blue Team** - Attack your own work, then defend it
-- **Socratic Questioning** - Challenge every claim with "why?" and "how do you know?"
-- **Constraint Removal** - Drop all constraints, see what changes, add them back selectively
-- **Stakeholder Mapping** - Re-evaluate from each stakeholder's perspective
-- **Analogical Reasoning** - Find parallels in other domains and apply their lessons
-
-And many more. The AI picks the most relevant options for your content - you choose which to run.
-
-:::tip[Start Here]
-Pre-mortem Analysis is a good first pick for any spec or plan. It consistently finds gaps that a standard review misses.
-:::

package/docs/explanation/adversarial-review.md

@@ -1,59 +0,0 @@
----
-title: "Adversarial Review"
-description: Forced reasoning technique that prevents lazy "looks good" reviews
-sidebar:
-  order: 5
----
-
-Force deeper analysis by requiring problems to be found.
-
-## What is Adversarial Review?
-
-A review technique where the reviewer *must* find issues. No "looks good" allowed. The reviewer adopts a cynical stance - assume problems exist and find them.
-
-This isn't about being negative. It's about forcing genuine analysis instead of a cursory glance that rubber-stamps whatever was submitted.
-
-**The core rule:** You must find issues. Zero findings triggers a halt - re-analyze or explain why.
-
-## Why It Works
-
-Normal reviews suffer from confirmation bias. You skim the work, nothing jumps out, you approve it. The "find problems" mandate breaks this pattern:
-
-- **Forces thoroughness** - Can't approve until you've looked hard enough to find issues
-- **Catches missing things** - "What's not here?" becomes a natural question
-- **Improves signal quality** - Findings are specific and actionable, not vague concerns
-- **Information asymmetry** - Run reviews with fresh context (no access to original reasoning) so you evaluate the artifact, not the intent
-
-## Where It's Used
-
-Adversarial review appears throughout XiaoMa workflows - code review, implementation readiness checks, spec validation, and others. Sometimes it's a required step, sometimes optional (like advanced elicitation or party mode). The pattern adapts to whatever artifact needs scrutiny.
-
-## Human Filtering Required
-
-Because the AI is *instructed* to find problems, it will find problems - even when they don't exist. Expect false positives: nitpicks dressed as issues, misunderstandings of intent, or outright hallucinated concerns.
-
-**You decide what's real.** Review each finding, dismiss the noise, fix what matters.
-
-## Example
-
-Instead of:
-
-> "The authentication implementation looks reasonable. Approved."
-
-An adversarial review produces:
-
-> 1. **HIGH** - `login.ts:47` - No rate limiting on failed attempts
-> 2. **HIGH** - Session token stored in localStorage (XSS vulnerable)
-> 3. **MEDIUM** - Password validation happens client-side only
-> 4. **MEDIUM** - No audit logging for failed login attempts
-> 5. **LOW** - Magic number `3600` should be `SESSION_TIMEOUT_SECONDS`
-
-The first review might miss a security vulnerability. The second caught four.
-
-## Iteration and Diminishing Returns
-
-After addressing findings, consider running it again. A second pass usually catches more. A third isn't always useless either. But each pass takes time, and eventually you hit diminishing returns - just nitpicks and false findings.
-
-:::tip[Better Reviews]
-Assume problems exist. Look for what's missing, not just what's wrong.
-:::

package/docs/explanation/brainstorming.md

@@ -1,33 +0,0 @@
----
-title: "Brainstorming"
-description: Interactive creative sessions using 60+ proven ideation techniques
-sidebar:
-  order: 2
----
-
-Unlock your creativity through guided exploration.
-
-## What is Brainstorming?
-
-Run `xiaoma-brainstorming` and you've got a creative facilitator pulling ideas out of you - not generating them for you. The AI acts as coach and guide, using proven techniques to create conditions where your best thinking emerges.
-
-**Good for:**
-
-- Breaking through creative blocks
-- Generating product or feature ideas
-- Exploring problems from new angles
-- Developing raw concepts into action plans
-
-## How It Works
-
-1. **Setup** - Define topic, goals, constraints
-2. **Choose approach** - Pick techniques yourself, get AI recommendations, go random, or follow a progressive flow
-3. **Facilitation** - Work through techniques with probing questions and collaborative coaching
-4. **Organize** - Ideas grouped into themes and prioritized
-5. **Action** - Top ideas get next steps and success metrics
-
-Everything gets captured in a session document you can reference later or share with stakeholders.
-
-:::note[Your Ideas]
-Every idea comes from you. The workflow creates conditions for insight - you're the source.
-:::

package/docs/explanation/established-projects-faq.md

@@ -1,50 +0,0 @@
----
-title: "Established Projects FAQ"
-description: Common questions about using XiaoMa Method on established projects
-sidebar:
-  order: 8
----
-Quick answers to common questions about working on established projects with the XiaoMa Method (BMM).
-
-## Questions
-
-- [Do I have to run document-project first?](#do-i-have-to-run-document-project-first)
-- [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project)
-- [Can I use Quick Flow for established projects?](#can-i-use-quick-flow-for-established-projects)
-- [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices)
-
-### Do I have to run document-project first?
-
-Highly recommended, especially if:
-
-- No existing documentation
-- Documentation is outdated
-- AI agents need context about existing code
-
-You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system.
-
-### What if I forget to run document-project?
-
-Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date.
-
-### Can I use Quick Flow for established projects?
-
-Yes! Quick Flow works great for established projects. It will:
-
-- Auto-detect your existing stack
-- Analyze existing code patterns
-- Detect conventions and ask for confirmation
-- Generate context-rich tech-spec that respects existing code
-
-Perfect for bug fixes and small features in existing codebases.
-
-### What if my existing code doesn't follow best practices?
-
-Quick Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide:
-
-- **Yes** → Maintain consistency with current codebase
-- **No** → Establish new standards (document why in tech-spec)
-
-BMM respects your choice — it won't force modernization, but it will offer it.
-
-**Have a question not answered here?** Please [open an issue](https://github.com/xiaoma-code-org/XiaoMa-Cli/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

package/docs/explanation/party-mode.md

@@ -1,59 +0,0 @@
----
-title: "Party Mode"
-description: Multi-agent collaboration - get all your AI agents in one conversation
-sidebar:
-  order: 7
----
-
-Get all your AI agents in one conversation.
-
-## What is Party Mode?
-
-Run `xiaoma-party-mode` and you've got your whole AI team in one room - PM, Architect, Dev, UX Designer, whoever you need. XiaoMa Master orchestrates, picking relevant agents per message. Agents respond in character, agree, disagree, and build on each other's ideas.
-
-The conversation continues as long as you want. Ask follow-ups, push back on answers, redirect the discussion - it's a real back-and-forth with your agents until you're done.
-
-**Good for:**
-
-- Big decisions with tradeoffs
-- Brainstorming sessions
-- Post-mortems when things go wrong
-- Sprint retrospectives and planning
-
-## Examples
-
-### Calling Out Bad Architecture
-
-**You:** "Okay team, our last sprint was a disaster. The authentication service went down three times. Who screwed this up?"
-
-**Architect:** "The design was sound - distributed authentication with proper fallbacks. If implementation deviated from the spec..."
-
-**Dev:** "I followed the architecture doc exactly. The spec didn't account for concurrent session invalidation race conditions."
-
-**PM:** "Both of you missed the bigger issue - we didn't validate session management requirements in the PRD. This is on me for not catching it."
-
-**TEA:** "And I should've caught this in integration tests. The test scenarios didn't cover concurrent invalidation."
-
-### Creative Brainstorming
-
-**You:** "How do we make onboarding feel magical instead of boring?"
-
-**UX Designer:** "Start with progressive disclosure - reveal features as users need them, not all at once in a tutorial."
-
-**Storyteller:** "What if onboarding was a story? Each step reveals a character's journey - the user IS the hero."
-
-**Game Designer:** "Building on that - what if the first 'quest' is actually solving a real user problem? They learn by doing something valuable."
-
-### Technical Decision
-
-**You:** "Monolith or microservices for MVP?"
-
-**Architect:** "Start monolith. Microservices add complexity you don't need at 1000 users."
-
-**PM:** "Agree. Time to market matters more than theoretical scalability."
-
-**Dev:** "Monolith with clear module boundaries. We can extract services later if needed."
-
-:::tip[Better Decisions]
-Better decisions through diverse perspectives. Welcome to party mode.
-:::