@zeyue0329/xiaoma-cli 1.0.49 → 6.0.0-alpha.14

package/src/modules/xmc/docs/workflows-planning.md

@@ -0,0 +1,451 @@
+# XMC Planning Workflows (Phase 2)
+
+## Overview
+
+Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements using a **scale-adaptive system** that automatically selects the right planning depth based on project complexity.
+
+**Key principle:** One unified entry point (`workflow-init`) intelligently routes to the appropriate planning methodology - from quick tech-specs to comprehensive PRDs.
+
+**When to use:** All projects require planning. The system adapts depth automatically based on complexity.
+
+---
+
+## Phase 2 Planning Workflow Overview
+
+Phase 2 Planning uses a scale-adaptive system with three tracks:
+
+### Quick Flow (Simple Planning)
+
+- Entry: `workflow-init` routes based on project complexity
+- Workflow: `tech-spec`
+- Output: Technical document with story/epic structure
+- Story count: 1-15 (typical)
+- Next: Phase 4 (Implementation) - skips Phase 3
+
+### XiaoMa Method (Recommended)
+
+- Entry: `workflow-init` routes based on project complexity
+- Workflows: `prd` → (optional) `create-ux-design`
+- Output: PRD with FRs/NFRs
+- Story count: 10-50+ (typical)
+- Next: Phase 3 (Solutioning) → Phase 4
+
+### Enterprise Method
+
+- Planning: Same as XiaoMa Method (`prd` workflow)
+- Solutioning: Extended Phase 3 workflows (Architecture + Security + DevOps)
+- Story count: 30+ (typical)
+- Next: Phase 4
+
+The `correct-course` workflow can be used anytime for significant requirement changes.
+
+---
+
+## Quick Reference
+
+| Workflow             | Agent       | Track                     | Purpose                                         | Typical Stories |
+| -------------------- | ----------- | ------------------------- | ----------------------------------------------- | --------------- |
+| **workflow-init**    | PM/Analyst  | All                       | Entry point: discovery + routing                | N/A             |
+| **tech-spec**        | PM          | Quick Flow                | Technical document → Story or Epic+Stories      | 1-15            |
+| **prd**              | PM          | XiaoMa Method, Enterprise | Strategic PRD with FRs/NFRs (no epic breakdown) | 10-50+          |
+| **create-ux-design** | UX Designer | XiaoMa Method, Enterprise | Optional UX specification (after PRD)           | N/A             |
+| **correct-course**   | PM/SM       | All                       | Mid-stream requirement changes                  | N/A             |
+
+**Note:** Story counts are guidance. V6 improvement: Epic+Stories are created AFTER architecture for better quality.
+
+---
+
+## Scale-Adaptive Planning System
+
+XMC uses three distinct planning tracks that adapt to project complexity:
+
+### Track 1: Quick Flow
+
+**Best For:** Bug fixes, simple features, clear scope, enhancements
+
+**Planning:** Tech-spec only → Implementation
+
+**Time:** Hours to 1 day
+
+**Story Count:** Typically 1-15 (guidance)
+
+**Documents:** tech-spec.md + story files
+
+**Example:** "Fix authentication bug", "Add OAuth social login"
+
+---
+
+### Track 2: XiaoMa Method (RECOMMENDED)
+
+**Best For:** Products, platforms, complex features, multiple epics
+
+**Planning:** PRD + Architecture → Implementation
+
+**Time:** 1-3 days
+
+**Story Count:** Typically 10-50+ (guidance)
+
+**Documents:** PRD.md (FRs/NFRs) + architecture.md + epics.md + epic files
+
+**Greenfield:** Product Brief (optional) → PRD (FRs/NFRs) → UX (optional) → Architecture → Epics+Stories → Implementation
+
+**Brownfield:** document-project → PRD (FRs/NFRs) → Architecture (recommended) → Epics+Stories → Implementation
+
+**Example:** "Customer dashboard", "E-commerce platform", "Add search to existing app"
+
+**Why Architecture for Brownfield?** Distills massive codebase context into focused solution design for your specific project.
+
+---
+
+### Track 3: Enterprise Method
+
+**Best For:** Enterprise requirements, multi-tenant, compliance, security-sensitive
+
+**Planning (Phase 2):** Uses XiaoMa Method planning (PRD with FRs/NFRs)
+
+**Solutioning (Phase 3):** Extended workflows (Architecture + Security + DevOps + SecOps as optional additions) → Epics+Stories
+
+**Time:** 3-7 days total (1-3 days planning + 2-4 days extended solutioning)
+
+**Story Count:** Typically 30+ (but defined by enterprise needs)
+
+**Documents Phase 2:** PRD.md (FRs/NFRs)
+
+**Documents Phase 3:** architecture.md + epics.md + epic files + security-architecture.md (optional) + devops-strategy.md (optional) + secops-strategy.md (optional)
+
+**Example:** "Multi-tenant SaaS", "HIPAA-compliant portal", "Add SOC2 audit logging"
+
+---
+
+## How Track Selection Works
+
+`workflow-init` guides you through educational choice:
+
+1. **Description Analysis** - Analyzes project description for complexity
+2. **Educational Presentation** - Shows all three tracks with trade-offs
+3. **Recommendation** - Suggests track based on keywords and context
+4. **User Choice** - You select the track that fits
+
+The system guides but never forces. You can override recommendations.
+
+---
+
+## Workflow Descriptions
+
+### workflow-init (Entry Point)
+
+**Purpose:** Single unified entry point for all planning. Discovers project needs and intelligently routes to appropriate track.
+
+**Agent:** PM (orchestrates others as needed)
+
+**Always Use:** This is your planning starting point. Don't call prd/tech-spec directly unless skipping discovery.
+
+**Process:**
+
+1. Discovery (understand context, assess complexity, identify concerns)
+2. Routing Decision (determine track, explain rationale, confirm)
+3. Execute Target Workflow (invoke planning workflow, pass context)
+4. Handoff (document decisions, recommend next phase)
+
+---
+
+### tech-spec (Quick Flow)
+
+**Purpose:** Lightweight technical specification for simple changes (Quick Flow track). Produces technical document and story or epic+stories structure.
+
+**Agent:** PM
+
+**When to Use:**
+
+- Bug fixes
+- Single API endpoint additions
+- Configuration changes
+- Small UI component additions
+- Isolated validation rules
+
+**Key Outputs:**
+
+- **tech-spec.md** - Technical document containing:
+  - Problem statement and solution
+  - Source tree changes
+  - Implementation details
+  - Testing strategy
+  - Acceptance criteria
+- **Story file(s)** - Single story OR epic+stories structure (1-15 stories typically)
+
+**Skip To Phase:** 4 (Implementation) - no Phase 3 architecture needed
+
+**Example:** "Fix null pointer when user has no profile image" → Single file change, null check, unit test, no DB migration.
+
+---
+
+### prd (Product Requirements Document)
+
+**Purpose:** Strategic PRD with Functional Requirements (FRs) and Non-Functional Requirements (NFRs) for software products (XiaoMa Method track).
+
+**Agent:** PM (with Architect and Analyst support)
+
+**When to Use:**
+
+- Medium to large feature sets
+- Multi-screen user experiences
+- Complex business logic
+- Multiple system integrations
+- Phased delivery required
+
+**Scale-Adaptive Structure:**
+
+- **Light:** Focused FRs/NFRs, simplified analysis (10-15 pages)
+- **Standard:** Comprehensive FRs/NFRs, thorough analysis (20-30 pages)
+- **Comprehensive:** Extensive FRs/NFRs, multi-phase, stakeholder analysis (30-50+ pages)
+
+**Key Outputs:**
+
+- PRD.md (complete requirements with FRs and NFRs)
+
+**Note:** V6 improvement - PRD focuses on WHAT to build (requirements). Epic+Stories are created AFTER architecture via `create-epics-and-stories` workflow for better quality.
+
+**Integration:** Feeds into Architecture (Phase 3)
+
+**Example:** E-commerce checkout → PRD with 15 FRs (user account, cart management, payment flow) and 8 NFRs (performance, security, scalability).
+
+---
+
+### create-ux-design (UX Design)
+
+**Purpose:** UX specification for projects where user experience is the primary differentiator (XiaoMa Method track).
+
+**Agent:** UX Designer
+
+**When to Use:**
+
+- UX is primary competitive advantage
+- Complex user workflows needing design thinking
+- Innovative interaction patterns
+- Design system creation
+- Accessibility-critical experiences
+
+**Collaborative Approach:**
+
+1. Visual exploration (generate multiple options)
+2. Informed decisions (evaluate with user needs)
+3. Collaborative design (refine iteratively)
+4. Living documentation (evolves with project)
+
+**Key Outputs:**
+
+- ux-spec.md (complete UX specification)
+- User journeys
+- Wireframes and mockups
+- Interaction specifications
+- Design system (components, patterns, tokens)
+- Epic breakdown (UX stories)
+
+**Integration:** Feeds PRD or updates epics, then Architecture (Phase 3)
+
+**Example:** Dashboard redesign → Card-based layout with split-pane toggle, 5 card components, 12 color tokens, responsive grid, 3 epics (Layout, Visualization, Accessibility).
+
+---
+
+### correct-course
+
+**Purpose:** Handle significant requirement changes during implementation (all tracks).
+
+**Agent:** PM, Architect, or SM
+
+**When to Use:**
+
+- Priorities change mid-project
+- New requirements emerge
+- Scope adjustments needed
+- Technical blockers require replanning
+
+**Process:**
+
+1. Analyze impact of change
+2. Propose solutions (continue, pivot, pause)
+3. Update affected documents (PRD, epics, stories)
+4. Re-route for implementation
+
+**Integration:** Updates planning artifacts, may trigger architecture review
+
+---
+
+## Decision Guide
+
+### Which Planning Workflow?
+
+**Use `workflow-init` (Recommended):** Let the system discover needs and route appropriately.
+
+**Direct Selection (Advanced):**
+
+- **Bug fix or single change** → `tech-spec` (Quick Flow)
+- **Software product** → `prd` (XiaoMa Method)
+- **UX innovation project** → `create-ux-design` + `prd` (XiaoMa Method)
+- **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method
+
+---
+
+## Integration with Phase 3 (Solutioning)
+
+Planning outputs feed into Solutioning:
+
+| Planning Output | Solutioning Input                  | Track Decision               |
+| --------------- | ---------------------------------- | ---------------------------- |
+| tech-spec.md    | Skip Phase 3 → Phase 4 directly    | Quick Flow (no architecture) |
+| PRD.md          | **architecture** (Level 3-4)       | XiaoMa Method (recommended)  |
+| ux-spec.md      | **architecture** (frontend design) | XiaoMa Method                |
+| Enterprise docs | **architecture** + security/ops    | Enterprise Method (required) |
+
+**Key Decision Points:**
+
+- **Quick Flow:** Skip Phase 3 entirely → Phase 4 (Implementation)
+- **XiaoMa Method:** Optional Phase 3 (simple), Required Phase 3 (complex)
+- **Enterprise:** Required Phase 3 (architecture + extended planning)
+
+See: [workflows-solutioning.md](workflows-solutioning.md)
+
+---
+
+## Best Practices
+
+### 1. Always Start with workflow-init
+
+Let the entry point guide you. It prevents over-planning simple features or under-planning complex initiatives.
+
+### 2. Trust the Recommendation
+
+If `workflow-init` suggests XiaoMa Method, there's likely complexity you haven't considered. Review carefully before overriding.
+
+### 3. Iterate on Requirements
+
+Planning documents are living. Refine PRDs as you learn during Solutioning and Implementation.
+
+### 4. Involve Stakeholders Early
+
+Review PRDs with stakeholders before Solutioning. Catch misalignment early.
+
+### 5. Focus on "What" Not "How"
+
+Planning defines **what** to build and **why**. Leave **how** (technical design) to Phase 3 (Solutioning).
+
+### 6. Document-Project First for Brownfield
+
+Always run `document-project` before planning brownfield projects. AI agents need existing codebase context.
+
+---
+
+## Common Patterns
+
+### Greenfield Software (XiaoMa Method)
+
+```
+1. (Optional) Analysis: product-brief, research
+2. workflow-init → routes to prd
+3. PM: prd workflow
+4. (Optional) UX Designer: create-ux-design workflow
+5. → Phase 3: architecture
+```
+
+### Brownfield Software (XiaoMa Method)
+
+```
+1. Technical Writer or Analyst: document-project
+2. workflow-init → routes to prd
+3. PM: prd workflow
+4. → Phase 3: architecture (recommended for focused solution design)
+```
+
+### Bug Fix (Quick Flow)
+
+```
+1. workflow-init → routes to tech-spec
+2. PM: tech-spec workflow
+3. → Phase 4: Implementation (skip Phase 3)
+```
+
+### Enterprise Project (Enterprise Method)
+
+```
+1. (Recommended) Analysis: research (compliance, security)
+2. workflow-init → routes to Enterprise Method
+3. PM: prd workflow
+4. (Optional) UX Designer: ux workflow
+5. PM: create-epics-and-stories
+6. → Phase 3: architecture + security + devops + test strategy
+```
+
+---
+
+## Common Anti-Patterns
+
+### ❌ Skipping Planning
+
+"We'll just start coding and figure it out."
+**Result:** Scope creep, rework, missed requirements
+
+### ❌ Over-Planning Simple Changes
+
+"Let me write a 20-page PRD for this button color change."
+**Result:** Wasted time, analysis paralysis
+
+### ❌ Planning Without Discovery
+
+"I already know what I want, skip the questions."
+**Result:** Solving wrong problem, missing opportunities
+
+### ❌ Treating PRD as Immutable
+
+"The PRD is locked, no changes allowed."
+**Result:** Ignoring new information, rigid planning
+
+### ✅ Correct Approach
+
+- Use scale-adaptive planning (right depth for complexity)
+- Involve stakeholders in review
+- Iterate as you learn
+- Keep planning docs living and updated
+- Use `correct-course` for significant changes
+
+---
+
+## Related Documentation
+
+- [Phase 1: Analysis Workflows](workflows-analysis.md) - Optional discovery phase
+- [Phase 3: Solutioning Workflows](workflows-solutioning.md) - Next phase
+- [Phase 4: Implementation Workflows](workflows-implementation.md)
+- [Scale Adaptive System](scale-adaptive-system.md) - Understanding the three tracks
+- [Quick Spec Flow](./quick-spec-flow.md) - Quick Flow track details
+- [Agents Guide](agents-guide.md) - Complete agent reference
+
+---
+
+## Troubleshooting
+
+**Q: Which workflow should I run first?**
+A: Run `workflow-init`. It analyzes your project and routes to the right planning workflow.
+
+**Q: Do I always need a PRD?**
+A: No. Simple changes use `tech-spec` (Quick Flow). Only XiaoMa Method and Enterprise tracks create PRDs.
+
+**Q: Can I skip Phase 3 (Solutioning)?**
+A: Yes for Quick Flow. Optional for XiaoMa Method (simple projects). Required for XiaoMa Method (complex projects) and Enterprise.
+
+**Q: How do I know which track to choose?**
+A: Use `workflow-init` - it recommends based on your description. Story counts are guidance, not definitions.
+
+**Q: What if requirements change mid-project?**
+A: Run `correct-course` workflow. It analyzes impact and updates planning artifacts.
+
+**Q: Do brownfield projects need architecture?**
+A: Recommended! Architecture distills massive codebase into focused solution design for your specific project.
+
+**Q: When do I run create-epics-and-stories?**
+A: In Phase 3 (Solutioning), after architecture is complete.
+
+**Q: Should I use product-brief before PRD?**
+A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context.
+
+---
+
+_Phase 2 Planning - Scale-adaptive requirements for every project._