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

package/docs/core-architecture.md

@@ -1,219 +0,0 @@
-# XiaoMa Cli: Core Architecture
-
-## 1. Overview
-
-The XiaoMa Cli is designed to provide agentic modes, tasks and templates to allow repeatable helpful workflows be it for agile agentic development, or expansion into vastly different domains. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex tasks, guided discussions, or other meaningful domain specific flows in a predictable, high-quality manner.
-
-The systems core module facilitates a full development lifecycle tailored to the challenges of current modern AI Agentic tooling:
-
-1. **Ideation & Planning**: Brainstorming, market research, and creating project briefs.
-2. **Architecture & Design**: Defining system architecture and UI/UX specifications.
-3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories with extremely specific context and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects.
-
-## 2. System Architecture Diagram
-
-The entire XiaoMa-Cli ecosystem is designed around the installed `xiaoma-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
-
-```mermaid
-graph TD
-    subgraph XiaoMa Cli Project
-        subgraph Core Framework
-            A["xiaoma-core"]
-            A --> B["agents"]
-            A --> C["agent-teams"]
-            A --> D["workflows"]
-            A --> E["templates"]
-            A --> F["tasks"]
-            A --> G["checklists"]
-            A --> H["data (KB)"]
-        end
-
-        subgraph Tooling
-            I["tools/builders/web-builder.js"]
-        end
-
-        subgraph Outputs
-            J["dist"]
-        end
-
-        B -- defines dependencies for --> E
-        B -- defines dependencies for --> F
-        B -- defines dependencies for --> G
-        B -- defines dependencies for --> H
-
-        C -- bundles --> B
-        I -- reads from --> A
-        I -- creates --> J
-    end
-
-    subgraph Target Environments
-        K["IDE (Cursor, VS Code, etc.)"]
-        L["Web UI (Gemini, ChatGPT)"]
-    end
-
-    B --> K
-    J --> L
-
-    style A fill:#1a73e8,color:#fff
-    style I fill:#f9ab00,color:#fff
-    style J fill:#34a853,color:#fff
-```
-
-## 3. Core Components
-
-The `xiaoma-core` directory contains all the definitions and resources that give the agents their capabilities.
-
-### 3.1. Agents (`xiaoma-core/agents/`)
-
-- **Purpose**: These are the foundational building blocks of the system. Each markdown file (e.g., `bmad-master.md`, `pm.md`, `dev.md`) defines the persona, capabilities, and dependencies of a single AI agent.
-- **Structure**: An agent file contains a YAML header that specifies its role, persona, dependencies, and startup instructions. These dependencies are lists of tasks, templates, checklists, and data files that the agent is allowed to use.
-- **Startup Instructions**: Agents can include startup sequences that load project-specific documentation from the `docs/` folder, such as coding standards, API specifications, or project structure documents. This provides immediate project context upon activation.
-- **Document Integration**: Agents can reference and load documents from the project's `docs/` folder as part of tasks, workflows, or startup sequences. Users can also drag documents directly into chat interfaces to provide additional context.
-- **Example**: The `bmad-master` agent lists its dependencies, which tells the build tool which files to include in a web bundle and informs the agent of its own capabilities.
-
-### 3.2. Agent Teams (`xiaoma-core/agent-teams/`)
-
-- **Purpose**: Team files (e.g., `team-all.yaml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
-- **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`.
-
-### 3.3. Workflows (`xiaoma-core/workflows/`)
-
-- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yaml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
-- **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization.
-
-### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`)
-
-- **Purpose**: These folders house the modular components that are dynamically loaded by agents based on their dependencies.
-  - **`templates/`**: Contains markdown templates for common documents like PRDs, architecture specifications, and user stories.
-  - **`tasks/`**: Defines the instructions for carrying out specific, repeatable actions like "shard-doc" or "create-next-story".
-  - **`checklists/`**: Provides quality assurance checklists for agents like the Product Owner (`po`) or Architect.
-  - **`data/`**: Contains the core knowledge base (`bmad-kb.md`), technical preferences (`technical-preferences.md`), and other key data files.
-
-#### 3.4.1. Template Processing System
-
-A key architectural principle of BMad is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic.
-
-The BMad framework employs a sophisticated template processing system orchestrated by three key components:
-
-- **`template-format.md`** (`xiaoma-core/utils/`): Defines the foundational markup language used throughout all BMad templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system.
-
-- **`create-doc.md`** (`xiaoma-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system.
-
-- **`advanced-elicitation.md`** (`xiaoma-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality.
-
-The system maintains a clean separation of concerns: template markup is processed internally by AI agents but never exposed to users, while providing sophisticated AI processing capabilities through embedded intelligence within the templates themselves.
-
-#### 3.4.2. Technical Preferences System
-
-BMad includes a personalization layer through the `technical-preferences.md` file in `xiaoma-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
-
-**Purpose and Benefits:**
-
-- **Consistency**: Ensures all agents reference the same technical preferences
-- **Efficiency**: Eliminates the need to repeatedly specify preferred technologies
-- **Personalization**: Agents provide recommendations aligned with user preferences
-- **Learning**: Captures lessons learned and preferences that evolve over time
-
-**Content Structure:**
-The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions.
-
-**Integration Points:**
-
-- Templates can reference technical preferences during document generation
-- Agents suggest preferred technologies when appropriate for project requirements
-- When preferences don't fit project needs, agents explain alternatives
-- Web bundles can include preferences content for consistent behavior across platforms
-
-**Evolution Over Time:**
-Users are encouraged to continuously update this file with discoveries from projects, adding both positive preferences and technologies to avoid, creating a personalized knowledge base that improves agent recommendations over time.
-
-## 4. The Build & Delivery Process
-
-The framework is designed for two primary environments: local IDEs and web-based AI chat interfaces. The `web-builder.js` script is the key to supporting the latter.
-
-### 4.1. Web Builder (`tools/builders/web-builder.js`)
-
-- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `dist`.
-- **Process**:
-  1. **Resolves Dependencies**: For a given agent or team, the script reads its definition file.
-  2. It recursively finds all dependent resources (tasks, templates, etc.) that the agent/team needs.
-  3. **Bundles Content**: It reads the content of all these files and concatenates them into a single, large text file, with clear separators indicating the original file path of each section.
-  4. **Outputs Bundle**: The final `.txt` file is saved in the `dist` directory, ready to be uploaded to a web UI.
-
-### 4.2. Environment-Specific Usage
-
-- **For IDEs**: Users interact with the agents directly via their markdown files in `xiaoma-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents.
-- **For Web UIs**: Users upload a pre-built bundle from `dist`. This single file provides the AI with the context of the entire team and all their required tools and knowledge.
-
-## 5. BMad Workflows
-
-### 5.1. The Planning Workflow
-
-Before development begins, BMad follows a structured planning workflow that establishes the foundation for successful project execution:
-
-```mermaid
-graph TD
-    A["Start: Project Idea"] --> B{"Optional: Analyst Brainstorming"}
-    B -->|Yes| C["Analyst: Market Research & Analysis"]
-    B -->|No| D["Create Project Brief"]
-    C --> D["Analyst: Create Project Brief"]
-    D --> E["PM: Create PRD from Brief"]
-    E --> F["Architect: Create Architecture from PRD"]
-    F --> G["PO: Run Master Checklist"]
-    G --> H{"Documents Aligned?"}
-    H -->|Yes| I["Planning Complete"]
-    H -->|No| J["PO: Update Epics & Stories"]
-    J --> K["Update PRD/Architecture as needed"]
-    K --> G
-    I --> L["📁 Switch to IDE"]
-    L --> M["PO: Shard Documents"]
-    M --> N["Ready for SM/Dev Cycle"]
-
-    style I fill:#34a853,color:#fff
-    style G fill:#f9ab00,color:#fff
-    style L fill:#1a73e8,color:#fff
-    style N fill:#34a853,color:#fff
-```
-
-**Key Planning Phases:**
-
-1. **Optional Analysis**: Analyst conducts market research and competitive analysis
-2. **Project Brief**: Foundation document created by Analyst or user
-3. **PRD Creation**: PM transforms brief into comprehensive product requirements
-4. **Architecture Design**: Architect creates technical foundation based on PRD
-5. **Validation & Alignment**: PO ensures all documents are consistent and complete
-6. **Refinement**: Updates to epics, stories, and documents as needed
-7. **Environment Transition**: Critical switch from web UI to IDE for development workflow
-8. **Document Preparation**: PO shards large documents for development consumption
-
-**Workflow Orchestration**: The `bmad-orchestrator` agent uses these workflow definitions to guide users through the complete process, ensuring proper transitions between planning (web UI) and development (IDE) phases.
-
-### 5.2. The Core Development Cycle
-
-Once the initial planning and architecture phases are complete, the project moves into a cyclical development workflow, as detailed in the `bmad-kb.md`. This ensures a steady, sequential, and quality-controlled implementation process.
-
-```mermaid
-graph TD
-    A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"]
-    B --> C["PO: Shard Arch"]
-    C --> D["Development Phase"]
-    D --> E["Scrum Master: Drafts next story from sharded epic"]
-    E --> F{"User Approval"}
-    F -->|Approved| G["Dev: Implement Story"]
-    F -->|Needs Changes| E
-    G --> H["Dev: Complete story Tasks"]
-    H --> I["Dev: Mark Ready for Review"]
-    I --> J{"User Verification"}
-    J -->|Request QA Review| K["QA: Run review-story task"]
-    J -->|Approve Without QA| M["Mark Story as Done"]
-    K --> L{"QA Review Results"}
-    L -->|Needs Work| G
-    L -->|Approved| M["Mark Story as Done"]
-    J -->|Needs Fixes| G
-    M --> E
-
-    style M fill:#34a853,color:#fff
-    style K fill:#f9ab00,color:#fff
-```
-
-This cycle continues, with the Scrum Master, Developer, and optionally QA agents working together. The QA agent provides senior developer review capabilities through the `review-story` task, offering code refactoring, quality improvements, and knowledge transfer. This ensures high code quality while maintaining development velocity.

package/docs/enhanced-ide-development-workflow.md

@@ -1,248 +0,0 @@
-# Enhanced IDE Development Workflow
-
-This is a simple step-by-step guide to help you efficiently manage your development workflow using the XiaoMa Cli. The workflow integrates the Test Architect (QA agent) throughout the development lifecycle to ensure quality, prevent regressions, and maintain high standards. Refer to the **[<ins>User Guide</ins>](user-guide.md)** for any scenario that is not covered here.
-
-## Create New Branch
-
-1. **Start new branch**
-
-## Story Creation (Scrum Master)
-
-1. **Start new chat/conversation**
-2. **Load SM agent**
-3. **Execute**: `*draft` (runs create-next-story task)
-4. **Review generated story** in `docs/stories/`
-5. **Update status**: Change from "Draft" to "Approved"
-
-## Story Implementation (Developer)
-
-1. **Start new chat/conversation**
-2. **Load Dev agent**
-3. **Execute**: `*develop-story {selected-story}` (runs execute-checklist task)
-4. **Review generated report** in `{selected-story}`
-
-## Test Architect Integration Throughout Workflow
-
-The Test Architect (Quinn) provides comprehensive quality assurance throughout the development lifecycle. Here's how to leverage each capability at the right time.
-
-**Command Aliases:** Documentation uses short forms (`*risk`, `*design`, `*nfr`, `*trace`) for the full commands (`*risk-profile`, `*test-design`, `*nfr-assess`, `*trace-requirements`).
-
-### Quick Command Reference
-
-| **Stage**                | **Command** | **Purpose**                             | **Output**                                                      | **Priority**                |
-| ------------------------ | ----------- | --------------------------------------- | --------------------------------------------------------------- | --------------------------- |
-| **After Story Approval** | `*risk`     | Identify integration & regression risks | `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md`         | High for complex/brownfield |
-|                          | `*design`   | Create test strategy for dev            | `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md`  | High for new features       |
-| **During Development**   | `*trace`    | Verify test coverage                    | `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`        | Medium                      |
-|                          | `*nfr`      | Validate quality attributes             | `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`          | High for critical features  |
-| **After Development**    | `*review`   | Comprehensive assessment                | QA Results in story + `docs/qa/gates/{epic}.{story}-{slug}.yml` | **Required**                |
-| **Post-Review**          | `*gate`     | Update quality decision                 | Updated `docs/qa/gates/{epic}.{story}-{slug}.yml`               | As needed                   |
-
-### Stage 1: After Story Creation (Before Dev Starts)
-
-**RECOMMENDED - Set Developer Up for Success:**
-
-```bash
-# 1. RISK ASSESSMENT (Run FIRST for complex stories)
-@qa *risk {approved-story}
-# Identifies:
-#   - Technical debt impact
-#   - Integration complexity
-#   - Regression potential (1-9 scoring)
-#   - Mitigation strategies
-# Critical for: Brownfield, API changes, data migrations
-
-# 2. TEST DESIGN (Run SECOND to guide implementation)
-@qa *design {approved-story}
-# Provides:
-#   - Test scenarios per acceptance criterion
-#   - Test level recommendations (unit/integration/E2E)
-#   - Risk-based priorities (P0/P1/P2)
-#   - Test data requirements
-# Share with Dev: Include in story comments or attach to ticket
-```
-
-### Stage 2: During Development (Mid-Implementation Checkpoints)
-
-**Developer Self-Service Quality Checks:**
-
-```bash
-# 3. REQUIREMENTS TRACING (Verify coverage mid-development)
-@qa *trace {story-in-progress}
-# Validates:
-#   - All acceptance criteria have tests
-#   - No missing test scenarios
-#   - Appropriate test levels
-#   - Given-When-Then documentation clarity
-# Run when: After writing initial tests
-
-# 4. NFR VALIDATION (Check quality attributes)
-@qa *nfr {story-in-progress}
-# Assesses:
-#   - Security: Authentication, authorization, data protection
-#   - Performance: Response times, resource usage
-#   - Reliability: Error handling, recovery
-#   - Maintainability: Code quality, documentation
-# Run when: Before marking "Ready for Review"
-```
-
-### Stage 3: Story Review (Quality Gate Assessment)
-
-**REQUIRED - Comprehensive Test Architecture Review:**
-
-**Prerequisite:** All tests green locally; lint & type checks pass.
-
-```bash
-# 5. FULL REVIEW (Standard review process)
-@qa *review {completed-story}
-```
-
-**What Happens During Review:**
-
-1. **Deep Code Analysis**
-   - Architecture pattern compliance
-   - Code quality and maintainability
-   - Security vulnerability scanning
-   - Performance bottleneck detection
-
-2. **Active Refactoring**
-   - Improves code directly when safe
-   - Fixes obvious issues immediately
-   - Suggests complex refactoring for dev
-
-3. **Test Validation**
-   - Coverage at all levels (unit/integration/E2E)
-   - Test quality (no flaky tests, proper assertions)
-   - Regression test adequacy
-
-4. **Gate Decision**
-   - Creates: `docs/qa/gates/{epic}.{story}-{slug}.yml`
-   - Adds: QA Results section to story file
-   - Status: PASS/CONCERNS/FAIL/WAIVED
-
-### Stage 4: Post-Review (After Addressing Issues)
-
-**Update Gate Status After Fixes:**
-
-```bash
-# 6. GATE UPDATE (Document final decision)
-@qa *gate {reviewed-story}
-# Updates: Quality gate with new status
-# Use when: After addressing review feedback
-# Documents: What was fixed, what was waived
-```
-
-### Understanding Gate Decisions
-
-| **Status**   | **Meaning**                                  | **Action Required**     | **Can Proceed?** |
-| ------------ | -------------------------------------------- | ----------------------- | ---------------- |
-| **PASS**     | All critical requirements met                | None                    | ✅ Yes           |
-| **CONCERNS** | Non-critical issues found                    | Team review recommended | ⚠️ With caution  |
-| **FAIL**     | Critical issues (security, missing P0 tests) | Must fix                | ❌ No            |
-| **WAIVED**   | Issues acknowledged and accepted             | Document reasoning      | ✅ With approval |
-
-### Risk-Based Testing Strategy
-
-The Test Architect uses risk scoring to prioritize testing:
-
-| **Risk Score** | **Calculation**                | **Testing Priority**      | **Gate Impact**          |
-| -------------- | ------------------------------ | ------------------------- | ------------------------ |
-| **9**          | High probability × High impact | P0 - Must test thoroughly | FAIL if untested         |
-| **6**          | Medium-high combinations       | P1 - Should test well     | CONCERNS if gaps         |
-| **4**          | Medium combinations            | P1 - Should test          | CONCERNS if notable gaps |
-| **2-3**        | Low-medium combinations        | P2 - Nice to have         | Note in review           |
-| **1**          | Minimal risk                   | P2 - Minimal              | Note in review           |
-
-### Special Situations & Best Practices
-
-#### High-Risk or Brownfield Stories
-
-```bash
-# ALWAYS run this sequence:
-@qa *risk {story}    # First - identify dangers
-@qa *design {story}  # Second - plan defense
-# Then during dev:
-@qa *trace {story}   # Verify regression coverage
-@qa *nfr {story}     # Check performance impact
-# Finally:
-@qa *review {story}  # Deep integration analysis
-```
-
-#### Complex Integrations
-
-- Run `*trace` multiple times during development
-- Focus on integration test coverage
-- Use `*nfr` to validate cross-system performance
-- Review with extra attention to API contracts
-
-#### Performance-Critical Features
-
-- Run `*nfr` early and often (not just at review)
-- Establish performance baselines before changes
-- Document acceptable performance degradation
-- Consider load testing requirements in `*design`
-
-### Test Quality Standards Enforced
-
-Quinn ensures all tests meet these standards:
-
-- **No Flaky Tests**: Proper async handling, explicit waits
-- **No Hard Waits**: Dynamic strategies only (polling, events)
-- **Stateless**: Tests run independently and in parallel
-- **Self-Cleaning**: Tests manage their own test data
-- **Appropriate Levels**: Unit for logic, integration for interactions, E2E for journeys
-- **Clear Assertions**: Keep assertions in tests, not buried in helpers
-
-### Documentation & Audit Trail
-
-All Test Architect activities create permanent records:
-
-- **Assessment Reports**: Timestamped analysis in `docs/qa/assessments/`
-- **Gate Files**: Decision records in `docs/qa/gates/`
-- **Story Updates**: QA Results sections in story files
-- **Traceability**: Requirements to test mapping maintained
-
-## Commit Changes and Push
-
-1. **Commit changes**
-2. **Push to remote**
-
-## Complete Development Cycle Flow
-
-### The Full Workflow with Test Architect
-
-1. **SM**: Create next story → Review → Approve
-2. **QA (Optional)**: Risk assessment (`*risk`) → Test design (`*design`)
-3. **Dev**: Implement story → Write tests → Complete
-4. **QA (Optional)**: Mid-dev checks (`*trace`, `*nfr`)
-5. **Dev**: Mark Ready for Review
-6. **QA (Required)**: Review story (`*review`) → Gate decision
-7. **Dev (If needed)**: Address issues
-8. **QA (If needed)**: Update gate (`*gate`)
-9. **Commit**: All changes
-10. **Push**: To remote
-11. **Continue**: Until all features implemented
-
-### Quick Decision Guide
-
-**Should I run Test Architect commands?**
-
-| **Scenario**             | **Before Dev**                  | **During Dev**               | **After Dev**                |
-| ------------------------ | ------------------------------- | ---------------------------- | ---------------------------- |
-| **Simple bug fix**       | Optional                        | Optional                     | Required `*review`           |
-| **New feature**          | Recommended `*risk`, `*design`  | Optional `*trace`            | Required `*review`           |
-| **Brownfield change**    | **Required** `*risk`, `*design` | Recommended `*trace`, `*nfr` | Required `*review`           |
-| **API modification**     | **Required** `*risk`, `*design` | **Required** `*trace`        | Required `*review`           |
-| **Performance-critical** | Recommended `*design`           | **Required** `*nfr`          | Required `*review`           |
-| **Data migration**       | **Required** `*risk`, `*design` | **Required** `*trace`        | Required `*review` + `*gate` |
-
-### Success Metrics
-
-The Test Architect helps achieve:
-
-- **Zero regression defects** in production
-- **100% requirements coverage** with tests
-- **Clear quality gates** for go/no-go decisions
-- **Documented risk acceptance** for technical debt
-- **Consistent test quality** across the team
-- **Shift-left testing** with early risk identification