@zeyue0329/xiaoma-cli 1.0.40 → 1.0.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/.idea/workspace.xml +8 -1
  2. package/.xiaoma-core/.coordinator-state.json +19 -0
  3. package/dist/agents/architect.txt +192 -0
  4. package/dist/agents/workflow-executor.txt +151 -1
  5. package/dist/agents/workflow-helper.txt +93 -0
  6. package/dist/teams/team-all.txt +396 -191
  7. package/dist/teams/team-fullstack-with-database.txt +2 -0
  8. package/dist/teams/team-fullstack.txt +2 -0
  9. package/dist/teams/team-no-ui.txt +2 -0
  10. package/docs/architecture/workflow-coordinator-implementation.md +1188 -0
  11. package/docs/prd/workflow-coordinator-prd.md +1214 -0
  12. package/package.json +6 -1
  13. package/tools/api-server.js +367 -0
  14. package/tools/installer/package.json +1 -1
  15. package/tools/workflow-coordinator/README.md +38 -0
  16. package/tools/workflow-coordinator/USAGE.md +548 -0
  17. package/tools/workflow-coordinator/package-lock.json +4868 -0
  18. package/tools/workflow-coordinator/package.json +35 -0
  19. package/tools/workflow-coordinator/src/api/server.js +207 -0
  20. package/tools/workflow-coordinator/src/controller/workflow-controller.js +263 -0
  21. package/tools/workflow-coordinator/src/index.js +113 -0
  22. package/tools/workflow-coordinator/src/parser/workflow-parser.js +144 -0
  23. package/tools/workflow-coordinator/src/utils/state-manager.js +59 -0
  24. package/tools/workflow-coordinator/src/utils/validator.js +86 -0
  25. package/tools/workflow-coordinator/test/integration-test.js +266 -0
  26. package/tools/workflow-coordinator/test/quick-test.js +127 -0
  27. package/xiaoma-core/agents/workflow-executor.md +155 -1
  28. package/xiaoma-core/agents/workflow-helper.md +481 -0
  29. package/xiaoma-core/workflows/automated-requirements-development.yaml +739 -0
@@ -296,6 +296,7 @@ commands:
296
296
  - execute-checklist {checklist}: 运行任务 execute-checklist (默认为->architect-checklist)
297
297
  - research {topic}: 执行任务 create-deep-research-prompt
298
298
  - shard-prd: 为提供的 architecture.md 运行任务 shard-doc.md (如果未找到则询问)
299
+ - shard-doc: 执行任务 shard-doc.md 切分大型文档到多个小文档
299
300
  - yolo: 切换 Yolo 模式
300
301
  - exit: 作为架构师道别,然后放弃扮演此角色
301
302
  dependencies:
@@ -308,6 +309,7 @@ dependencies:
308
309
  - create-doc.md
309
310
  - document-project.md
310
311
  - execute-checklist.md
312
+ - shard-doc.md
311
313
  templates:
312
314
  - architecture-tmpl.yaml
313
315
  - brownfield-architecture-tmpl.yaml
@@ -1526,6 +1528,7 @@ commands:
1526
1528
  - help: 显示以下命令的编号列表以供选择
1527
1529
  - run-requirements-analysis: 🔥 自动化需求分析工作流(完全自动执行,不暂停)- 加载 automated-requirements-analysis.yaml 并连续执行所有 6 个步骤,从 req.txt 到最终的架构设计文档,全程自动化无需人工干预
1528
1530
  - run-story-development: 🔥 自动化用户故事开发工作流(完全自动执行,不暂停)- 加载 automated-story-development.yaml 并循环执行所有用户故事的 SM→PO→Dev→QA 完整开发周期,全程自动化无需人工干预
1531
+ - run-requirements-development: '🔥🔥🔥 端到端全自动化工作流(完全自动执行,不暂停)- 加载 automated-requirements-development.yaml 并连续执行从需求分析到用户故事开发完成的完整流程 (阶段1: 需求分析 6步 + 阶段2: 用户故事开发循环), 实现从 req.txt 到所有代码完成的端到端自动化'
1529
1532
  - status: 显示当前工作流执行状态和进度
1530
1533
  - validate-prerequisites: 验证工作流执行的前置条件
1531
1534
  - resume-workflow: 从上次中断的位置恢复工作流执行(同样会自动连续执行剩余步骤)
@@ -1535,6 +1538,7 @@ dependencies:
1535
1538
  workflows:
1536
1539
  - automated-requirements-analysis.yaml
1537
1540
  - automated-story-development.yaml
1541
+ - automated-requirements-development.yaml
1538
1542
  ```
1539
1543
 
1540
1544
  ---
@@ -1648,7 +1652,77 @@ workflow_stages:
1648
1652
 
1649
1653
  ---
1650
1654
 
1651
- ### 2. 自动化用户故事开发工作流
1655
+ ### 2. 🔥🔥🔥 端到端全自动化工作流 (新增)
1656
+
1657
+ **命令**: `*run-requirements-development`
1658
+
1659
+ **功能**: 执行从需求分析到用户故事开发完成的完整端到端自动化流程
1660
+
1661
+ **工作流文件**: `xiaoma-core/workflows/automated-requirements-development.yaml`
1662
+
1663
+ **核心价值**:
1664
+ - ✅ **一键启动**: 只需执行一个命令,完成从 req.txt 到所有代码的端到端开发
1665
+ - ✅ **无缝衔接**: 需求分析阶段自动衔接用户故事开发阶段,无需人工干预
1666
+ - ✅ **全程自动化**: 整合了两个子工作流的所有优势,实现完整的自动化流程
1667
+ - ✅ **质量保证**: 两个阶段的所有质量门控都会自动执行
1668
+
1669
+ **执行流程**:
1670
+
1671
+ ```yaml
1672
+ 端到端工作流结构:
1673
+
1674
+ 阶段 1: 需求分析阶段 (1.5-2.5小时)
1675
+ ├─ 步骤 0/6: 前置环境验证
1676
+ ├─ 步骤 1/6: Analyst 需求分析
1677
+ ├─ 步骤 2/6: Architect 架构分析
1678
+ ├─ 步骤 3/6: PM 创建 PRD
1679
+ ├─ 步骤 4/6: PM 拆分史诗
1680
+ ├─ 步骤 5/6: Architect 架构设计
1681
+ └─ 步骤 6/6: 生成需求分析报告
1682
+
1683
+ 阶段间验证(无缝衔接)
1684
+
1685
+ 阶段 2: 用户故事开发阶段 (40-70分钟/故事)
1686
+ 循环执行(直到所有用户故事完成):
1687
+ ├─ 步骤 1: SM 创建用户故事
1688
+ ├─ 步骤 1.5: 快速构建验证
1689
+ ├─ 步骤 2: PO 验证故事
1690
+ ├─ 步骤 2.5: 预开发构建检查
1691
+ ├─ 步骤 3: Dev 开发故事
1692
+ ├─ 步骤 4: QA 测试验证
1693
+ └─ 步骤 5: 质量门控决策
1694
+
1695
+ 生成端到端完成报告
1696
+ ```
1697
+
1698
+ **总耗时**:
1699
+ - 阶段 1(需求分析): 约 1.5-2.5 小时
1700
+ - 阶段 2(用户故事开发): 约 40-70 分钟 × 用户故事数量
1701
+ - **典型小型项目(5-10个故事)**: 4-8 小时
1702
+ - **典型中型项目(10-20个故事)**: 8-16 小时
1703
+
1704
+ **成功标准**:
1705
+
1706
+ 阶段 1 成功标准:
1707
+ - ✅ 所有需求分析文档生成完成
1708
+ - ✅ PRD 和 Epic 文档创建完成
1709
+ - ✅ 架构设计和数据库脚本生成完成
1710
+ - ✅ 所有质量门控通过
1711
+
1712
+ 阶段 2 成功标准:
1713
+ - ✅ 所有用户故事状态为 Done
1714
+ - ✅ 所有测试通过(覆盖率 ≥80%)
1715
+ - ✅ 所有 QA 质量门控通过
1716
+ - ✅ 代码质量达标
1717
+
1718
+ 整体成功标准:
1719
+ - ✅ 两个阶段全部完成
1720
+ - ✅ 完整的文档和代码生成
1721
+ - ✅ 准备就绪进入集成测试和部署阶段
1722
+
1723
+ ---
1724
+
1725
+ ### 3. 自动化用户故事开发工作流
1652
1726
 
1653
1727
  **命令**: `*run-story-development`
1654
1728
 
@@ -1834,6 +1908,84 @@ quality_gates:
1834
1908
 
1835
1909
  ## 📊 使用示例
1836
1910
 
1911
+ ### 🔥🔥🔥 执行端到端全自动化工作流(推荐)
1912
+
1913
+ ```bash
1914
+ # 1. 准备工作
1915
+ # 确保 docs/req.txt 文件存在且包含 PM 提供的需求
1916
+
1917
+ # 2. 激活工作流执行器
1918
+ /workflow-executor
1919
+
1920
+ # 3. 执行端到端全自动化工作流(完全自动化,一键到底)
1921
+ *run-requirements-development
1922
+
1923
+ # ⚡ 核心优势:一个命令完成从需求分析到代码实现的全部工作!
1924
+ # ⚠️ 重要提示:工作流执行器会自动连续执行两个阶段的所有步骤,不会在中间暂停
1925
+ # 如果工作流在某个步骤停止,说明遇到了错误或质量门控失败,请查看错误信息
1926
+
1927
+ # 工作流执行器将自动完成以下所有工作(典型小项目 4-8 小时):
1928
+ #
1929
+ # 【阶段 1: 需求分析】(约 1.5-2.5 小时)
1930
+ # ✓ 步骤 0/6: 前置环境验证
1931
+ # ✓ 步骤 1/6: Analyst 需求分析 → 生成需求分析报告
1932
+ # ✓ 步骤 2/6: Architect 架构分析 → 生成架构分析报告
1933
+ # ✓ 步骤 3/6: PM 创建 PRD → 生成 Brownfield PRD
1934
+ # ✓ 步骤 4/6: PM 拆分史诗 → 生成 Epic 文档
1935
+ # ✓ 步骤 5/6: Architect 架构设计 → 生成架构设计和数据库脚本
1936
+ # ✓ 步骤 6/6: 生成需求分析完成报告
1937
+ # ↓
1938
+ # ✓ 阶段间无缝衔接验证
1939
+ # ↓
1940
+ # 【阶段 2: 用户故事开发】(约 40-70 分钟 × 故事数量)
1941
+ # 对每个用户故事循环执行:
1942
+ # ✓ SM 创建用户故事 → 快速构建验证
1943
+ # ✓ PO 验证故事(10步验证)
1944
+ # ✓ 预开发构建检查
1945
+ # ✓ Dev 开发实现 + 自测
1946
+ # ✓ QA 测试验证(真实数据测试)
1947
+ # ✓ 质量门控决策 → Done
1948
+ # 直到所有用户故事完成
1949
+ # ↓
1950
+ # ✓ 生成端到端完成报告
1951
+
1952
+ # 4. 工作流完成后检查所有输出
1953
+ # 阶段 1 输出:
1954
+ # - docs/requirements/requirements-analysis.md
1955
+ # - docs/architecture/current-architecture-analysis.md
1956
+ # - docs/prd/brownfield-iteration-prd.md
1957
+ # - docs/epics/史诗-*.md
1958
+ # - docs/architecture/iteration-backend-design.md
1959
+ # - docs/architecture/db-migration-scripts.sql
1960
+ # - docs/architecture/*.md (7个模块文档)
1961
+ #
1962
+ # 阶段 2 输出:
1963
+ # - docs/stories/epic{X}-story{Y}.md (所有故事状态: Done)
1964
+ # - src/ 目录下的实现代码
1965
+ # - 测试报告
1966
+ # - QA gate 文件
1967
+ #
1968
+ # 完成报告:
1969
+ # - docs/end-to-end-completion-report.md
1970
+ ```
1971
+
1972
+ **🌟 端到端工作流的特殊优势**:
1973
+
1974
+ - ✅ **一键到底**: 只需一个命令,无需在两个阶段间手动切换
1975
+ - ✅ **无缝衔接**: 阶段1完成后自动验证并进入阶段2,完全自动化
1976
+ - ✅ **全程监控**: 统一的进度追踪和质量控制
1977
+ - ✅ **完整报告**: 生成包含两个阶段的综合完成报告
1978
+ - ✅ **节省时间**: 避免手动操作和阶段间切换的开销
1979
+ - ⚠️ **执行时长**: 适合有充足时间的场景(典型小项目 4-8 小时)
1980
+
1981
+ **🔥 适用场景**:
1982
+ - 从零开始的新需求迭代
1983
+ - 需要完整的需求分析和代码实现
1984
+ - 有充足的执行时间(半天到一天)
1985
+ - 希望最小化人工干预
1986
+
1987
+ ---
1988
+
1837
1989
  ### 执行需求分析工作流
1838
1990
 
1839
1991
  ```bash
@@ -2321,6 +2473,59 @@ completion_report:
2321
2473
  祝你使用愉快!工作流执行器将协调所有智能体,像流水线一样自动完成从需求分析到代码实现的完整流程。🎉
2322
2474
  ==================== END: .xiaoma-core/agents/workflow-executor.md ====================
2323
2475
 
2476
+ ==================== START: .xiaoma-core/agents/workflow-helper.md ====================
2477
+ # agent
2478
+
2479
+ CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
2480
+
2481
+ ```yaml
2482
+ on_failure:
2483
+ max_retries: 3
2484
+ escalation: 请检查架构模板完整性
2485
+ ```
2486
+
2487
+ ## 调试
2488
+
2489
+ ### 启用详细日志
2490
+
2491
+ 在协调器启动时查看详细日志:
2492
+ ```bash
2493
+ DEBUG=* node src/index.js start automated-requirements-analysis
2494
+ ```
2495
+
2496
+ ### 查看状态文件
2497
+
2498
+ 工作流状态保存在:`.xiaoma-core/.coordinator-state.json`
2499
+
2500
+ 查看:
2501
+ ```bash
2502
+ cat .xiaoma-core/.coordinator-state.json
2503
+ ```
2504
+
2505
+ ## 使用提示
2506
+
2507
+ 1. **先启动协调器**:在Claude Code中启动工作流前,确保协调器已运行
2508
+ 2. **保持终端开启**:协调器需要持续运行,不要关闭终端
2509
+ 3. **监控日志**:协调器日志会显示详细的执行进度和问题
2510
+ 4. **状态恢复**:如果中断,状态文件允许从中断点恢复
2511
+ 5. **工作流定义**:所有工作流定义在`xiaoma-core/workflows/`目录
2512
+
2513
+ ## 与workflow-executor的区别
2514
+
2515
+ **workflow-executor**(旧方案):
2516
+ - 完全由AI驱动,基于AI判断决定下一步
2517
+ - 会在关键点暂停询问用户
2518
+ - 无法完全自动化
2519
+
2520
+ **workflow-helper + Coordinator**(新方案):
2521
+ - 程序化流程控制,消除AI决策延迟
2522
+ - 完全自动执行,无需人工确认
2523
+ - 状态持久化,支持恢复
2524
+ - 质量门控,自动验证输出
2525
+
2526
+ workflow-helper专注于"执行层",协调器负责"控制层",实现关注点分离和更可靠的自动化。
2527
+ ==================== END: .xiaoma-core/agents/workflow-helper.md ====================
2528
+
2324
2529
  ==================== START: .xiaoma-core/tasks/advanced-elicitation.md ====================
2325
2530
  <!-- Powered by XiaoMa™ Core -->
2326
2531
 
@@ -5555,6 +5760,196 @@ The LLM will:
5555
5760
  - Offer to provide detailed analysis of any section, especially those with warnings or failures
5556
5761
  ==================== END: .xiaoma-core/tasks/execute-checklist.md ====================
5557
5762
 
5763
+ ==================== START: .xiaoma-core/tasks/shard-doc.md ====================
5764
+ <!-- Powered by XiaoMa™ Core -->
5765
+
5766
+ # Document Sharding Task
5767
+
5768
+ ## Purpose
5769
+
5770
+ - Split a large document into multiple smaller documents based on level 2 sections
5771
+ - Create a folder structure to organize the sharded documents
5772
+ - Maintain all content integrity including code blocks, diagrams, and markdown formatting
5773
+
5774
+ ## Primary Method: Automatic with markdown-tree
5775
+
5776
+ [[LLM: First, check if markdownExploder is set to true in .xiaoma-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
5777
+
5778
+ If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
5779
+
5780
+ If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
5781
+
5782
+ 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
5783
+ 2. Or set markdownExploder to false in .xiaoma-core/core-config.yaml
5784
+
5785
+ **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
5786
+
5787
+ If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
5788
+
5789
+ 1. Set markdownExploder to true in .xiaoma-core/core-config.yaml
5790
+ 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
5791
+
5792
+ I will now proceed with the manual sharding process."
5793
+
5794
+ Then proceed with the manual method below ONLY if markdownExploder is false.]]
5795
+
5796
+ ### Installation and Usage
5797
+
5798
+ 1. **Install globally**:
5799
+
5800
+ ```bash
5801
+ npm install -g @kayvan/markdown-tree-parser
5802
+ ```
5803
+
5804
+ 2. **Use the explode command**:
5805
+
5806
+ ```bash
5807
+ # For PRD
5808
+ md-tree explode docs/prd.md docs/prd
5809
+
5810
+ # For Architecture
5811
+ md-tree explode docs/architecture.md docs/architecture
5812
+
5813
+ # For any document
5814
+ md-tree explode [source-document] [destination-folder]
5815
+ ```
5816
+
5817
+ 3. **What it does**:
5818
+ - Automatically splits the document by level 2 sections
5819
+ - Creates properly named files
5820
+ - Adjusts heading levels appropriately
5821
+ - Handles all edge cases with code blocks and special markdown
5822
+
5823
+ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below.
5824
+
5825
+ ---
5826
+
5827
+ ## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
5828
+
5829
+ ### Task Instructions
5830
+
5831
+ 1. Identify Document and Target Location
5832
+
5833
+ - Determine which document to shard (user-provided path)
5834
+ - Create a new folder under `docs/` with the same name as the document (without extension)
5835
+ - Example: `docs/prd.md` → create folder `docs/prd/`
5836
+
5837
+ 2. Parse and Extract Sections
5838
+
5839
+ CRITICAL AEGNT SHARDING RULES:
5840
+
5841
+ 1. Read the entire document content
5842
+ 2. Identify all level 2 sections (## headings)
5843
+ 3. For each level 2 section:
5844
+ - Extract the section heading and ALL content until the next level 2 section
5845
+ - Include all subsections, code blocks, diagrams, lists, tables, etc.
5846
+ - Be extremely careful with:
5847
+ - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
5848
+ - Mermaid diagrams - preserve the complete diagram syntax
5849
+ - Nested markdown elements
5850
+ - Multi-line content that might contain ## inside code blocks
5851
+
5852
+ CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]
5853
+
5854
+ ### 3. Create Individual Files
5855
+
5856
+ For each extracted section:
5857
+
5858
+ 1. **Generate filename**: Convert the section heading to lowercase-dash-case
5859
+ - Remove special characters
5860
+ - Replace spaces with dashes
5861
+ - Example: "## Tech Stack" → `tech-stack.md`
5862
+
5863
+ 2. **Adjust heading levels**:
5864
+ - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
5865
+ - All subsection levels decrease by 1:
5866
+
5867
+ ```txt
5868
+ - ### → ##
5869
+ - #### → ###
5870
+ - ##### → ####
5871
+ - etc.
5872
+ ```
5873
+
5874
+ 3. **Write content**: Save the adjusted content to the new file
5875
+
5876
+ ### 4. Create Index File
5877
+
5878
+ Create an `index.md` file in the sharded folder that:
5879
+
5880
+ 1. Contains the original level 1 heading and any content before the first level 2 section
5881
+ 2. Lists all the sharded files with links:
5882
+
5883
+ ```markdown
5884
+ # Original Document Title
5885
+
5886
+ [Original introduction content if any]
5887
+
5888
+ ## Sections
5889
+
5890
+ - [Section Name 1](./section-name-1.md)
5891
+ - [Section Name 2](./section-name-2.md)
5892
+ - [Section Name 3](./section-name-3.md)
5893
+ ...
5894
+ ```
5895
+
5896
+ ### 5. Preserve Special Content
5897
+
5898
+ 1. **Code blocks**: Must capture complete blocks including:
5899
+
5900
+ ```language
5901
+ content
5902
+ ```
5903
+
5904
+ 2. **Mermaid diagrams**: Preserve complete syntax:
5905
+
5906
+ ```mermaid
5907
+ graph TD
5908
+ ...
5909
+ ```
5910
+
5911
+ 3. **Tables**: Maintain proper markdown table formatting
5912
+
5913
+ 4. **Lists**: Preserve indentation and nesting
5914
+
5915
+ 5. **Inline code**: Preserve backticks
5916
+
5917
+ 6. **Links and references**: Keep all markdown links intact
5918
+
5919
+ 7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
5920
+
5921
+ ### 6. Validation
5922
+
5923
+ After sharding:
5924
+
5925
+ 1. Verify all sections were extracted
5926
+ 2. Check that no content was lost
5927
+ 3. Ensure heading levels were properly adjusted
5928
+ 4. Confirm all files were created successfully
5929
+
5930
+ ### 7. Report Results
5931
+
5932
+ Provide a summary:
5933
+
5934
+ ```text
5935
+ Document sharded successfully:
5936
+ - Source: [original document path]
5937
+ - Destination: docs/[folder-name]/
5938
+ - Files created: [count]
5939
+ - Sections:
5940
+ - section-name-1.md: "Section Title 1"
5941
+ - section-name-2.md: "Section Title 2"
5942
+ ...
5943
+ ```
5944
+
5945
+ ## Important Notes
5946
+
5947
+ - Never modify the actual content, only adjust heading levels
5948
+ - Preserve ALL formatting, including whitespace where significant
5949
+ - Handle edge cases like sections with code blocks containing ## symbols
5950
+ - Ensure the sharding is reversible (could reconstruct the original from shards)
5951
+ ==================== END: .xiaoma-core/tasks/shard-doc.md ====================
5952
+
5558
5953
  ==================== START: .xiaoma-core/templates/architecture-tmpl.yaml ====================
5559
5954
  template:
5560
5955
  id: architecture-template-v2
@@ -9124,196 +9519,6 @@ The story creation is successful when:
9124
9519
  - **Implicit:** An annotated change-checklist (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
9125
9520
  ==================== END: .xiaoma-core/tasks/correct-course.md ====================
9126
9521
 
9127
- ==================== START: .xiaoma-core/tasks/shard-doc.md ====================
9128
- <!-- Powered by XiaoMa™ Core -->
9129
-
9130
- # Document Sharding Task
9131
-
9132
- ## Purpose
9133
-
9134
- - Split a large document into multiple smaller documents based on level 2 sections
9135
- - Create a folder structure to organize the sharded documents
9136
- - Maintain all content integrity including code blocks, diagrams, and markdown formatting
9137
-
9138
- ## Primary Method: Automatic with markdown-tree
9139
-
9140
- [[LLM: First, check if markdownExploder is set to true in .xiaoma-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
9141
-
9142
- If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
9143
-
9144
- If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
9145
-
9146
- 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
9147
- 2. Or set markdownExploder to false in .xiaoma-core/core-config.yaml
9148
-
9149
- **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
9150
-
9151
- If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
9152
-
9153
- 1. Set markdownExploder to true in .xiaoma-core/core-config.yaml
9154
- 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
9155
-
9156
- I will now proceed with the manual sharding process."
9157
-
9158
- Then proceed with the manual method below ONLY if markdownExploder is false.]]
9159
-
9160
- ### Installation and Usage
9161
-
9162
- 1. **Install globally**:
9163
-
9164
- ```bash
9165
- npm install -g @kayvan/markdown-tree-parser
9166
- ```
9167
-
9168
- 2. **Use the explode command**:
9169
-
9170
- ```bash
9171
- # For PRD
9172
- md-tree explode docs/prd.md docs/prd
9173
-
9174
- # For Architecture
9175
- md-tree explode docs/architecture.md docs/architecture
9176
-
9177
- # For any document
9178
- md-tree explode [source-document] [destination-folder]
9179
- ```
9180
-
9181
- 3. **What it does**:
9182
- - Automatically splits the document by level 2 sections
9183
- - Creates properly named files
9184
- - Adjusts heading levels appropriately
9185
- - Handles all edge cases with code blocks and special markdown
9186
-
9187
- If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below.
9188
-
9189
- ---
9190
-
9191
- ## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
9192
-
9193
- ### Task Instructions
9194
-
9195
- 1. Identify Document and Target Location
9196
-
9197
- - Determine which document to shard (user-provided path)
9198
- - Create a new folder under `docs/` with the same name as the document (without extension)
9199
- - Example: `docs/prd.md` → create folder `docs/prd/`
9200
-
9201
- 2. Parse and Extract Sections
9202
-
9203
- CRITICAL AEGNT SHARDING RULES:
9204
-
9205
- 1. Read the entire document content
9206
- 2. Identify all level 2 sections (## headings)
9207
- 3. For each level 2 section:
9208
- - Extract the section heading and ALL content until the next level 2 section
9209
- - Include all subsections, code blocks, diagrams, lists, tables, etc.
9210
- - Be extremely careful with:
9211
- - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
9212
- - Mermaid diagrams - preserve the complete diagram syntax
9213
- - Nested markdown elements
9214
- - Multi-line content that might contain ## inside code blocks
9215
-
9216
- CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]
9217
-
9218
- ### 3. Create Individual Files
9219
-
9220
- For each extracted section:
9221
-
9222
- 1. **Generate filename**: Convert the section heading to lowercase-dash-case
9223
- - Remove special characters
9224
- - Replace spaces with dashes
9225
- - Example: "## Tech Stack" → `tech-stack.md`
9226
-
9227
- 2. **Adjust heading levels**:
9228
- - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
9229
- - All subsection levels decrease by 1:
9230
-
9231
- ```txt
9232
- - ### → ##
9233
- - #### → ###
9234
- - ##### → ####
9235
- - etc.
9236
- ```
9237
-
9238
- 3. **Write content**: Save the adjusted content to the new file
9239
-
9240
- ### 4. Create Index File
9241
-
9242
- Create an `index.md` file in the sharded folder that:
9243
-
9244
- 1. Contains the original level 1 heading and any content before the first level 2 section
9245
- 2. Lists all the sharded files with links:
9246
-
9247
- ```markdown
9248
- # Original Document Title
9249
-
9250
- [Original introduction content if any]
9251
-
9252
- ## Sections
9253
-
9254
- - [Section Name 1](./section-name-1.md)
9255
- - [Section Name 2](./section-name-2.md)
9256
- - [Section Name 3](./section-name-3.md)
9257
- ...
9258
- ```
9259
-
9260
- ### 5. Preserve Special Content
9261
-
9262
- 1. **Code blocks**: Must capture complete blocks including:
9263
-
9264
- ```language
9265
- content
9266
- ```
9267
-
9268
- 2. **Mermaid diagrams**: Preserve complete syntax:
9269
-
9270
- ```mermaid
9271
- graph TD
9272
- ...
9273
- ```
9274
-
9275
- 3. **Tables**: Maintain proper markdown table formatting
9276
-
9277
- 4. **Lists**: Preserve indentation and nesting
9278
-
9279
- 5. **Inline code**: Preserve backticks
9280
-
9281
- 6. **Links and references**: Keep all markdown links intact
9282
-
9283
- 7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
9284
-
9285
- ### 6. Validation
9286
-
9287
- After sharding:
9288
-
9289
- 1. Verify all sections were extracted
9290
- 2. Check that no content was lost
9291
- 3. Ensure heading levels were properly adjusted
9292
- 4. Confirm all files were created successfully
9293
-
9294
- ### 7. Report Results
9295
-
9296
- Provide a summary:
9297
-
9298
- ```text
9299
- Document sharded successfully:
9300
- - Source: [original document path]
9301
- - Destination: docs/[folder-name]/
9302
- - Files created: [count]
9303
- - Sections:
9304
- - section-name-1.md: "Section Title 1"
9305
- - section-name-2.md: "Section Title 2"
9306
- ...
9307
- ```
9308
-
9309
- ## Important Notes
9310
-
9311
- - Never modify the actual content, only adjust heading levels
9312
- - Preserve ALL formatting, including whitespace where significant
9313
- - Handle edge cases like sections with code blocks containing ## symbols
9314
- - Ensure the sharding is reversible (could reconstruct the original from shards)
9315
- ==================== END: .xiaoma-core/tasks/shard-doc.md ====================
9316
-
9317
9522
  ==================== START: .xiaoma-core/templates/brownfield-prd-tmpl.yaml ====================
9318
9523
  template:
9319
9524
  id: brownfield-prd-template-v2
@@ -1242,6 +1242,7 @@ commands:
1242
1242
  - execute-checklist {checklist}: 运行任务 execute-checklist (默认为->architect-checklist)
1243
1243
  - research {topic}: 执行任务 create-deep-research-prompt
1244
1244
  - shard-prd: 为提供的 architecture.md 运行任务 shard-doc.md (如果未找到则询问)
1245
+ - shard-doc: 执行任务 shard-doc.md 切分大型文档到多个小文档
1245
1246
  - yolo: 切换 Yolo 模式
1246
1247
  - exit: 作为架构师道别,然后放弃扮演此角色
1247
1248
  dependencies:
@@ -1254,6 +1255,7 @@ dependencies:
1254
1255
  - create-doc.md
1255
1256
  - document-project.md
1256
1257
  - execute-checklist.md
1258
+ - shard-doc.md
1257
1259
  templates:
1258
1260
  - architecture-tmpl.yaml
1259
1261
  - brownfield-architecture-tmpl.yaml
@@ -413,6 +413,7 @@ commands:
413
413
  - execute-checklist {checklist}: 运行任务 execute-checklist (默认为->architect-checklist)
414
414
  - research {topic}: 执行任务 create-deep-research-prompt
415
415
  - shard-prd: 为提供的 architecture.md 运行任务 shard-doc.md (如果未找到则询问)
416
+ - shard-doc: 执行任务 shard-doc.md 切分大型文档到多个小文档
416
417
  - yolo: 切换 Yolo 模式
417
418
  - exit: 作为架构师道别,然后放弃扮演此角色
418
419
  dependencies:
@@ -425,6 +426,7 @@ dependencies:
425
426
  - create-doc.md
426
427
  - document-project.md
427
428
  - execute-checklist.md
429
+ - shard-doc.md
428
430
  templates:
429
431
  - architecture-tmpl.yaml
430
432
  - brownfield-architecture-tmpl.yaml
@@ -359,6 +359,7 @@ commands:
359
359
  - execute-checklist {checklist}: 运行任务 execute-checklist (默认为->architect-checklist)
360
360
  - research {topic}: 执行任务 create-deep-research-prompt
361
361
  - shard-prd: 为提供的 architecture.md 运行任务 shard-doc.md (如果未找到则询问)
362
+ - shard-doc: 执行任务 shard-doc.md 切分大型文档到多个小文档
362
363
  - yolo: 切换 Yolo 模式
363
364
  - exit: 作为架构师道别,然后放弃扮演此角色
364
365
  dependencies:
@@ -371,6 +372,7 @@ dependencies:
371
372
  - create-doc.md
372
373
  - document-project.md
373
374
  - execute-checklist.md
375
+ - shard-doc.md
374
376
  templates:
375
377
  - architecture-tmpl.yaml
376
378
  - brownfield-architecture-tmpl.yaml