@zeyue0329/xiaoma-cli 1.0.49 → 1.6.4

package/docs/explanation/adversarial-review.md

@@ -0,0 +1,59 @@
+---
+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

@@ -0,0 +1,33 @@
+---
+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

@@ -0,0 +1,50 @@
+---
+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

@@ -0,0 +1,59 @@
+---
+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.
+:::

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

@@ -0,0 +1,112 @@
+---
+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

@@ -0,0 +1,157 @@
+---
+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

@@ -0,0 +1,73 @@
+---
+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

@@ -0,0 +1,77 @@
+---
+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.