maestro-flow 0.4.18 → 0.4.20

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 (181) hide show
  1. package/.agents/agents/workflow-collab-planner.md +4 -1
  2. package/.agents/agents/workflow-plan-checker.md +11 -1
  3. package/.agents/agents/workflow-planner.md +4 -1
  4. package/.agents/skills/maestro/SKILL.md +8 -5
  5. package/.agents/skills/maestro-analyze/SKILL.md +1 -1
  6. package/.agents/skills/maestro-brainstorm/SKILL.md +2 -1
  7. package/.agents/skills/maestro-companion/SKILL.md +533 -0
  8. package/.agents/skills/maestro-grill/SKILL.md +116 -0
  9. package/.agents/skills/maestro-next/SKILL.md +147 -112
  10. package/.agents/skills/maestro-plan/SKILL.md +4 -0
  11. package/.agents/skills/maestro-ralph/SKILL.md +11 -7
  12. package/.agents/skills/maestro-swarm-workflow/SKILL.md +258 -0
  13. package/.agents/skills/manage-codebase-rebuild/SKILL.md +13 -1
  14. package/.agents/skills/manage-codebase-refresh/SKILL.md +3 -0
  15. package/.agents/skills/spec-setup/SKILL.md +9 -5
  16. package/.agents/skills/team-swarm/SKILL.md +180 -0
  17. package/.agents/skills/team-swarm/roles/analyst/role.md +187 -0
  18. package/.agents/skills/team-swarm/roles/ant/role.md +169 -0
  19. package/.agents/skills/team-swarm/roles/coordinator/commands/converge.md +146 -0
  20. package/.agents/skills/team-swarm/roles/coordinator/commands/init-swarm.md +136 -0
  21. package/.agents/skills/team-swarm/roles/coordinator/commands/iterate.md +232 -0
  22. package/.agents/skills/team-swarm/roles/coordinator/role.md +211 -0
  23. package/.agents/skills/team-swarm/roles/scorer/role.md +157 -0
  24. package/.agents/skills/team-swarm/scripts/aco.py +473 -0
  25. package/.agents/skills/team-swarm/scripts/pheromone.py +144 -0
  26. package/.agents/skills/team-swarm/scripts/scoring.py +92 -0
  27. package/.agents/skills/team-swarm/scripts/test_aco.py +475 -0
  28. package/.agents/skills/team-swarm/specs/ant-output-schema.md +119 -0
  29. package/.agents/skills/team-swarm/specs/convergence-criteria.md +106 -0
  30. package/.agents/skills/team-swarm/specs/pheromone-schema.md +123 -0
  31. package/.agents/skills/team-swarm/specs/swarm-config-template.json +71 -0
  32. package/.agents/skills/team-swarm/specs/swarm-protocol.md +117 -0
  33. package/.agy/agents/workflow-collab-planner.md +4 -1
  34. package/.agy/agents/workflow-plan-checker.md +11 -1
  35. package/.agy/agents/workflow-planner.md +4 -1
  36. package/.agy/skills/maestro/SKILL.md +8 -5
  37. package/.agy/skills/maestro-analyze/SKILL.md +1 -1
  38. package/.agy/skills/maestro-brainstorm/SKILL.md +2 -1
  39. package/.agy/skills/maestro-companion/SKILL.md +529 -0
  40. package/.agy/skills/maestro-grill/SKILL.md +116 -0
  41. package/.agy/skills/maestro-next/SKILL.md +147 -112
  42. package/.agy/skills/maestro-plan/SKILL.md +4 -0
  43. package/.agy/skills/maestro-ralph/SKILL.md +11 -7
  44. package/.agy/skills/maestro-swarm-workflow/SKILL.md +255 -0
  45. package/.agy/skills/manage-codebase-rebuild/SKILL.md +13 -1
  46. package/.agy/skills/manage-codebase-refresh/SKILL.md +3 -0
  47. package/.agy/skills/spec-setup/SKILL.md +9 -5
  48. package/.agy/skills/team-swarm/SKILL.md +176 -0
  49. package/.agy/skills/team-swarm/roles/analyst/role.md +183 -0
  50. package/.agy/skills/team-swarm/roles/ant/role.md +165 -0
  51. package/.agy/skills/team-swarm/roles/coordinator/commands/converge.md +134 -0
  52. package/.agy/skills/team-swarm/roles/coordinator/commands/init-swarm.md +136 -0
  53. package/.agy/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
  54. package/.agy/skills/team-swarm/roles/coordinator/role.md +209 -0
  55. package/.agy/skills/team-swarm/roles/scorer/role.md +153 -0
  56. package/.agy/skills/team-swarm/scripts/aco.py +473 -0
  57. package/.agy/skills/team-swarm/scripts/pheromone.py +144 -0
  58. package/.agy/skills/team-swarm/scripts/scoring.py +92 -0
  59. package/.agy/skills/team-swarm/scripts/test_aco.py +475 -0
  60. package/.agy/skills/team-swarm/specs/ant-output-schema.md +119 -0
  61. package/.agy/skills/team-swarm/specs/convergence-criteria.md +106 -0
  62. package/.agy/skills/team-swarm/specs/pheromone-schema.md +123 -0
  63. package/.agy/skills/team-swarm/specs/swarm-config-template.json +71 -0
  64. package/.agy/skills/team-swarm/specs/swarm-protocol.md +117 -0
  65. package/.claude/agents/workflow-collab-planner.md +4 -1
  66. package/.claude/agents/workflow-plan-checker.md +11 -1
  67. package/.claude/agents/workflow-planner.md +4 -1
  68. package/.claude/commands/maestro-analyze.md +1 -1
  69. package/.claude/commands/maestro-brainstorm.md +2 -1
  70. package/.claude/commands/maestro-companion.md +531 -0
  71. package/.claude/commands/maestro-grill.md +114 -0
  72. package/.claude/commands/maestro-next.md +147 -112
  73. package/.claude/commands/maestro-plan.md +4 -0
  74. package/.claude/commands/maestro-ralph.md +11 -7
  75. package/.claude/commands/maestro-swarm-workflow.md +256 -0
  76. package/.claude/commands/maestro.md +8 -5
  77. package/.claude/commands/manage-codebase-rebuild.md +13 -1
  78. package/.claude/commands/manage-codebase-refresh.md +3 -0
  79. package/.claude/commands/spec-setup.md +9 -5
  80. package/.claude/skills/team-swarm/SKILL.md +178 -0
  81. package/.claude/skills/team-swarm/roles/analyst/role.md +185 -0
  82. package/.claude/skills/team-swarm/roles/ant/role.md +167 -0
  83. package/.claude/skills/team-swarm/roles/coordinator/commands/converge.md +146 -0
  84. package/.claude/skills/team-swarm/roles/coordinator/commands/init-swarm.md +136 -0
  85. package/.claude/skills/team-swarm/roles/coordinator/commands/iterate.md +232 -0
  86. package/.claude/skills/team-swarm/roles/coordinator/role.md +209 -0
  87. package/.claude/skills/team-swarm/roles/scorer/role.md +155 -0
  88. package/.claude/skills/team-swarm/scripts/aco.py +473 -0
  89. package/.claude/skills/team-swarm/scripts/pheromone.py +144 -0
  90. package/.claude/skills/team-swarm/scripts/scoring.py +92 -0
  91. package/.claude/skills/team-swarm/scripts/test_aco.py +475 -0
  92. package/.claude/skills/team-swarm/specs/ant-output-schema.md +119 -0
  93. package/.claude/skills/team-swarm/specs/convergence-criteria.md +106 -0
  94. package/.claude/skills/team-swarm/specs/pheromone-schema.md +123 -0
  95. package/.claude/skills/team-swarm/specs/swarm-config-template.json +71 -0
  96. package/.claude/skills/team-swarm/specs/swarm-protocol.md +117 -0
  97. package/.codex/skills/maestro/SKILL.md +7 -2
  98. package/.codex/skills/maestro-companion/SKILL.md +485 -0
  99. package/.codex/skills/maestro-grill/SKILL.md +111 -0
  100. package/.codex/skills/maestro-next/SKILL.md +297 -0
  101. package/.codex/skills/maestro-ralph/SKILL.md +11 -7
  102. package/.codex/skills/manage-codebase-rebuild/SKILL.md +6 -0
  103. package/.codex/skills/manage-codebase-refresh/SKILL.md +6 -0
  104. package/dashboard/dist-server/dashboard/src/server/wiki/graph-analysis.d.ts +36 -0
  105. package/dashboard/dist-server/dashboard/src/server/wiki/graph-analysis.js +138 -2
  106. package/dashboard/dist-server/dashboard/src/server/wiki/graph-analysis.js.map +1 -1
  107. package/dashboard/dist-server/dashboard/src/server/wiki/search.js +13 -0
  108. package/dashboard/dist-server/dashboard/src/server/wiki/search.js.map +1 -1
  109. package/dashboard/dist-server/dashboard/src/server/wiki/virtual-wiki-adapters.d.ts +11 -0
  110. package/dashboard/dist-server/dashboard/src/server/wiki/virtual-wiki-adapters.js +178 -0
  111. package/dashboard/dist-server/dashboard/src/server/wiki/virtual-wiki-adapters.js.map +1 -1
  112. package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.d.ts +1 -0
  113. package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.js +39 -23
  114. package/dashboard/dist-server/dashboard/src/server/wiki/wiki-indexer.js.map +1 -1
  115. package/dist/src/cli.js +1 -0
  116. package/dist/src/cli.js.map +1 -1
  117. package/dist/src/commands/install-backend.d.ts +7 -0
  118. package/dist/src/commands/install-backend.d.ts.map +1 -1
  119. package/dist/src/commands/install-backend.js +14 -0
  120. package/dist/src/commands/install-backend.js.map +1 -1
  121. package/dist/src/commands/install.d.ts.map +1 -1
  122. package/dist/src/commands/install.js +23 -1
  123. package/dist/src/commands/install.js.map +1 -1
  124. package/dist/src/commands/kg.d.ts +11 -0
  125. package/dist/src/commands/kg.d.ts.map +1 -0
  126. package/dist/src/commands/kg.js +515 -0
  127. package/dist/src/commands/kg.js.map +1 -0
  128. package/dist/src/i18n/locales/en.d.ts.map +1 -1
  129. package/dist/src/i18n/locales/en.js +19 -0
  130. package/dist/src/i18n/locales/en.js.map +1 -1
  131. package/dist/src/i18n/locales/zh.d.ts.map +1 -1
  132. package/dist/src/i18n/locales/zh.js +19 -0
  133. package/dist/src/i18n/locales/zh.js.map +1 -1
  134. package/dist/src/i18n/types.d.ts +12 -0
  135. package/dist/src/i18n/types.d.ts.map +1 -1
  136. package/dist/src/tui/install-ui/HooksConfig.d.ts +5 -1
  137. package/dist/src/tui/install-ui/HooksConfig.d.ts.map +1 -1
  138. package/dist/src/tui/install-ui/HooksConfig.js +5 -3
  139. package/dist/src/tui/install-ui/HooksConfig.js.map +1 -1
  140. package/dist/src/tui/install-ui/InstallConfirm.d.ts +3 -0
  141. package/dist/src/tui/install-ui/InstallConfirm.d.ts.map +1 -1
  142. package/dist/src/tui/install-ui/InstallConfirm.js +1 -1
  143. package/dist/src/tui/install-ui/InstallConfirm.js.map +1 -1
  144. package/dist/src/tui/install-ui/InstallExecution.d.ts +2 -0
  145. package/dist/src/tui/install-ui/InstallExecution.d.ts.map +1 -1
  146. package/dist/src/tui/install-ui/InstallExecution.js +48 -3
  147. package/dist/src/tui/install-ui/InstallExecution.js.map +1 -1
  148. package/dist/src/tui/install-ui/InstallFlow.d.ts +1 -1
  149. package/dist/src/tui/install-ui/InstallFlow.d.ts.map +1 -1
  150. package/dist/src/tui/install-ui/InstallFlow.js +95 -17
  151. package/dist/src/tui/install-ui/InstallFlow.js.map +1 -1
  152. package/dist/src/tui/install-ui/InstallHub.d.ts +4 -0
  153. package/dist/src/tui/install-ui/InstallHub.d.ts.map +1 -1
  154. package/dist/src/tui/install-ui/InstallHub.js +14 -0
  155. package/dist/src/tui/install-ui/InstallHub.js.map +1 -1
  156. package/dist/src/tui/install-ui/InstallResult.d.ts.map +1 -1
  157. package/dist/src/tui/install-ui/InstallResult.js +1 -1
  158. package/dist/src/tui/install-ui/InstallResult.js.map +1 -1
  159. package/dist/src/tui/install-ui/KgVendorConfig.d.ts +7 -0
  160. package/dist/src/tui/install-ui/KgVendorConfig.d.ts.map +1 -0
  161. package/dist/src/tui/install-ui/KgVendorConfig.js +9 -0
  162. package/dist/src/tui/install-ui/KgVendorConfig.js.map +1 -0
  163. package/dist/src/utils/update-notices.js +22 -0
  164. package/dist/src/utils/update-notices.js.map +1 -1
  165. package/package.json +1 -1
  166. package/workflows/analyze.md +2 -1
  167. package/workflows/brainstorm.md +24 -1
  168. package/workflows/codebase-rebuild.md +141 -1
  169. package/workflows/codebase-refresh.md +20 -0
  170. package/workflows/finish-work.md +7 -2
  171. package/workflows/grill.md +513 -0
  172. package/workflows/plan.md +7 -4
  173. package/workflows/specs-setup.md +99 -3
  174. package/workflows/swarm/wf-analyze.js +186 -0
  175. package/workflows/swarm/wf-brainstorm.js +284 -0
  176. package/workflows/swarm/wf-execute.js +203 -0
  177. package/workflows/swarm/wf-grill.js +198 -0
  178. package/workflows/swarm/wf-milestone-audit.js +236 -0
  179. package/workflows/swarm/wf-plan.js +233 -0
  180. package/workflows/swarm/wf-review.js +226 -0
  181. package/workflows/swarm/wf-verify.js +298 -0
@@ -10,70 +10,114 @@ allowed-tools:
10
10
  ---
11
11
 
12
12
  <purpose>
13
- 单链推荐:根据用户输入意图,从 `.claude/commands/` 命令池中挑选**最匹配的单个命令**,确认后通过 `Skill()` 执行。
13
+ 单链推荐:解析 intent + project state → 路由表评分 → 推荐**单个原子命令** → 确认后通过 `Skill()` 执行。
14
14
 
15
- 与 `/maestro` / `/maestro-ralph` 的区别:
16
- - `/maestro`、`/maestro-ralph`、`/maestro-ralph-execute`、`/maestro-ralph-beta`、`/maestro-player`、`/maestro-composer` 是**多步管线编排器**,本命令不会推荐它们
17
- - 本命令始终只推荐 **1 个原子命令**(top pick),最多列出 2-3 个备选;选定后直接执行,无 session、无 chain
18
- - 适用场景:用户意图清晰、只需单步即可完成;或不确定该走哪个具体命令时获取定向推荐
15
+ 与 `/maestro` / `/maestro-ralph` 区别:
16
+ - 不创建 session、不构建 chain、不写 status.json
17
+ - 始终只推 1 top pick,最多列 2-3 个备选
18
+ - 适用场景:意图清晰且单步即可完成;或需要定向推荐时
19
19
  </purpose>
20
20
 
21
21
  <context>
22
- $ARGUMENTS — 用户意图文本 + 可选 flags。
22
+ $ARGUMENTS — 意图文本 + 可选 flags。
23
23
 
24
24
  **Flags:**
25
- - `-y` / `--yes` — 自动模式:跳过确认,直接执行 top pick
25
+ - `-y` / `--yes` — 跳过确认,直接执行 top pick
26
26
  - `--dry-run` — 仅显示推荐结果,不执行
27
- - `--top N` — 显示前 N 个候选供选择(默认 3)
27
+ - `--top N` — 显示前 N 个候选(默认 3)
28
28
  - `--list` — 仅列出可推荐命令池,不做推荐
29
29
 
30
- **候选池:** 仅 Step 3 路由表中列出的命令参与推荐。表中未出现的命令(含管线编排器 `maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer` 等)不会被本命令推荐。
30
+ **候选池:** 仅 A_SCORE_CANDIDATES 路由表中列出的命令。管线编排器(`maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer`)**永远不在候选池**。
31
31
  </context>
32
32
 
33
- <execution>
33
+ <invariants>
34
+ 1. **不创建 session / 不写 status.json / 不触发后续 chain** — 单次原子执行,产出由目标命令自行管理
35
+ 2. **管线编排器不在候选池** — 仅推荐原子命令
36
+ 3. **空 intent 或 "继续/下一步/next/接下来"** → 直接采用 lifecycle_position 推断的自然下一步
37
+ 4. **字面命中路由表优先** — lifecycle 仅作加分;命中失败时 lifecycle 上升为决定性信号
38
+ 5. **参数传递** — 默认 intent 原文作为第一个 arg;用户可在确认环节修改;`-y` 仅当用户传入时透传到 skill args
39
+ 6. **`--list` 模式跳过 lifecycle 推断与评分**,仅按 workflow 簇分组列出全部候选
40
+ </invariants>
34
41
 
35
- ### Step 1: Parse Arguments
42
+ <state_machine>
36
43
 
37
- 解析 `-y` / `--dry-run` / `--top N` / `--list`,剩余文本作为 `intent`。
44
+ <states>
45
+ S_PARSE — 解析 ARGUMENTS、提取 flags PERSIST: —
46
+ S_STATE — 读 project state、推断 lifecycle_position PERSIST: —
47
+ S_RANK — 路由表评分、生成 top-N candidates PERSIST: —
48
+ S_LIST — `--list` 模式:分组展示候选池 PERSIST: —
49
+ S_PRESENT — 显示 top pick + 备选 + 推荐理由 + 执行参数 PERSIST: —
50
+ S_CONFIRM — ask_question 选择/修改参数(auto_mode 跳过) PERSIST: —
51
+ S_EXECUTE — `Skill({ skill, args })` 单次调用 PERSIST: —
52
+ S_FALLBACK — intent 空且 clarification 失败 PERSIST: —
53
+ </states>
38
54
 
39
- - `--list` 模式 → 跳到 Step 3(仅列表)
40
- - `intent` 为空且非 `--list` → `ask_question`:让用户输入意图(最多 1 轮,仍空则 E001)
55
+ <transitions>
41
56
 
42
- ### Step 2: 读取 Workflow 状态(智能推荐基础)
57
+ S_PARSE:
58
+ → S_LIST WHEN: --list flag
59
+ → S_STATE WHEN: intent text present
60
+ → S_STATE WHEN: keyword "continue"/"next"/"go"/"继续"/"下一步"/"接下来"
61
+ → S_PARSE WHEN: no intent (max 1 clarify round) DO: ask_question
62
+ → S_FALLBACK WHEN: clarification empty
43
63
 
44
- 读取以下项目状态,用于推断"当前生命周期位置"和"自然下一步":
64
+ S_STATE:
65
+ → S_RANK DO: A_INFER_LIFECYCLE
45
66
 
46
- ```bash
47
- # 1. 当前 phase / milestone / 最新 artifact
48
- cat .workflow/state.json 2>$null
67
+ S_RANK:
68
+ S_PRESENT DO: A_SCORE_CANDIDATES
49
69
 
50
- # 2. 最近 artifact 目录(按 mtime 倒序,取前 3)
51
- ls -la .workflow/scratch/ 2>$null | head -10
70
+ S_LIST:
71
+ END DO: workflow 簇分组列出全部候选 + description
52
72
 
53
- # 3. 是否有进行中的 ralph/maestro session
54
- ls -la .workflow/.maestro/ 2>$null | head -5
55
- ```
73
+ S_PRESENT:
74
+ END WHEN: --dry-run
75
+ → S_EXECUTE WHEN: -y / --yes
76
+ → S_CONFIRM WHEN: not auto_mode
77
+
78
+ S_CONFIRM:
79
+ → S_EXECUTE WHEN: 用户确认 top pick / 选备选 / 改参数
80
+ → END WHEN: 用户取消
81
+
82
+ S_EXECUTE:
83
+ → END DO: Skill({ skill: <chosen>, args: <args> }) → 输出 "✅ 已执行 /<command>"
84
+
85
+ S_FALLBACK:
86
+ → END DO: raise E001
56
87
 
57
- 根据读取结果推断 **lifecycle_position**(用作下一步推荐的核心信号):
58
-
59
- | 项目状态特征 | lifecycle_position | 自然下一步 |
60
- |--------------|-------------------|-----------|
61
- | 无 `.workflow/` + 无源码 | `brainstorm` | `maestro-brainstorm` |
62
- | 无 `.workflow/` + 有源码 | `init` | `maestro-init` |
63
- | 有 state.json,无 roadmap.md,无 milestones | `analyze-macro` | `maestro-analyze` (宏观调研) |
64
- | 有 macro analyze artifact,无 roadmap.md | `roadmap` | `maestro-roadmap` |
65
- | 有 roadmap,未启动 phase | `analyze` | `maestro-analyze {phase}` |
66
- | 最新 artifact = `analyze` | `plan` | `maestro-plan {phase}` |
67
- | 最新 artifact = `plan` | `execute` | `maestro-execute {phase}` |
68
- | 最新 artifact = `execute` | `verify` | `maestro-verify {phase}` |
69
- | 最新 artifact = `verify`,passed | `review` | `quality-review {phase}` |
70
- | 最新 artifact = `review`,verdict=PASS | `test-gen` | `quality-auto-test {phase}` |
71
- | 最新 artifact = `test`,全绿 | `milestone-audit` | `maestro-milestone-audit` |
72
- | 当前 milestone 全部 phase 完成 | `milestone-complete` | `maestro-milestone-complete` |
73
- | 任一 stage 产物含 gaps/failed | `debug` | `quality-debug {gap}` |
74
-
75
- **Maestro Lifecycle 主线(核心 workflow,供推断"下一步"使用):**
88
+ </transitions>
76
89
 
90
+ <actions>
91
+
92
+ ### A_INFER_LIFECYCLE
93
+
94
+ 读 project state 推断 `lifecycle_position`(核心信号):
95
+
96
+ ```bash
97
+ cat .workflow/state.json 2>$null # phase / milestone / artifacts
98
+ ls -la .workflow/scratch/ 2>$null | head -10 # 最近 artifact (mtime DESC)
99
+ ls -la .workflow/.maestro/ 2>$null | head -5 # 进行中的 session
100
+ ```
101
+
102
+ **项目状态 → lifecycle_position → 自然下一步:**
103
+
104
+ | 项目状态 | lifecycle_position | 自然下一步 |
105
+ |---------|-------------------|-----------|
106
+ | 无 `.workflow/` + 无源码 | brainstorm | `maestro-brainstorm` |
107
+ | 无 `.workflow/` + 有源码 | init | `maestro-init` |
108
+ | 有 state.json,无 roadmap,无 milestones | analyze-macro | `maestro-analyze` (宏观调研) |
109
+ | 有 macro analyze artifact,无 roadmap | roadmap | `maestro-roadmap` |
110
+ | 有 roadmap,未启动 phase | analyze | `maestro-analyze {phase}` |
111
+ | 最新 artifact = analyze | plan | `maestro-plan {phase}` |
112
+ | 最新 artifact = plan | execute | `maestro-execute {phase}` |
113
+ | 最新 artifact = execute | verify | `maestro-verify {phase}` |
114
+ | verify passed | review | `quality-review {phase}` |
115
+ | review verdict=PASS | test-gen | `quality-auto-test {phase}` |
116
+ | 测试全绿 | milestone-audit | `maestro-milestone-audit` |
117
+ | 当前 milestone 全 phase 完成 | milestone-complete | `maestro-milestone-complete` |
118
+ | 任一 stage 产物含 gaps/failed | debug | `quality-debug {gap}` |
119
+
120
+ **Maestro Lifecycle 主线:**
77
121
  ```
78
122
  brainstorm → blueprint → init → analyze-macro → roadmap
79
123
  → [per phase] analyze → plan → execute → verify
@@ -81,41 +125,28 @@ brainstorm → blueprint → init → analyze-macro → roadmap
81
125
  → milestone-audit → milestone-complete → milestone-release
82
126
  ```
83
127
 
84
- **辅助 workflow 簇**(按场景触发,非主线):
85
-
86
- | Workflow 簇 | 触发场景 | 主推命令 |
87
- |-------------|---------|---------|
88
- | Learning | 接触新代码/未知模块 | `learn-follow` → `learn-decompose` → `learn-second-opinion` |
89
- | Knowledge | 提炼经验 / 沉淀知识 | `manage-harvest` → `manage-knowhow-capture` → `spec-add` |
90
- | Wiki 维护 | 知识图谱整理 | `manage-wiki` → `wiki-connect` → `wiki-digest` |
91
- | Issue 治理 | 缺陷管理 | `manage-issue-discover` → `manage-issue` |
92
- | 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-refresh` |
93
- | 重构 | 技术债积累 | `quality-refactor` → `quality-review` |
94
- | 发布 | 里程碑结束 | `maestro-milestone-audit` → `maestro-milestone-release` |
95
- | 并行开发 | 多 milestone 并行 | `maestro-fork` → ... → `maestro-merge` |
96
-
97
- ### Step 2.5: Semantic Match & Rank
128
+ ### A_SCORE_CANDIDATES
98
129
 
99
- 综合以下信号对路由表中的命令评分(高→低):
130
+ **评分信号**(高→低):
100
131
 
101
132
  | 信号 | 权重 | 说明 |
102
133
  |------|------|------|
103
- | intent 命中路由表行的关键词 | 高 | 字面匹配主依据 |
104
- | **lifecycle_position 的"自然下一步"** | **高** | intent "继续/下一步/next/接下来"或为空时,此信号上升为决定性 |
105
- | `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
106
- | Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景时触发对应簇 |
107
- | Recent activity 反向避免 | 低 | 刚完成的 stage 在短期内降权 |
134
+ | intent 命中路由表关键词 | 高 | 字面匹配主依据 |
135
+ | **lifecycle 自然下一步** | **高** | intent / "继续" / "next" 时为决定性 |
136
+ | `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
137
+ | Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
138
+ | Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
108
139
 
109
140
  **特殊意图处理:**
110
141
 
111
- | Intent 模式 | 处理 |
112
- |------------|------|
113
- | 空 / "继续" / "下一步" / "next" / "接下来怎么走" | 直接按 lifecycle_position 的"自然下一步"作为 top pick |
114
- | "什么状态" / "现在到哪了" / "status" | top pick = `manage-status` |
115
- | 字面命中路由表关键词 | 路由表优先,lifecycle 作为加分项 |
116
- | 无任何匹配 | top pick = lifecycle 自然下一步 + W002 警告 |
142
+ | Intent 模式 | top pick |
143
+ |------------|---------|
144
+ | 空 / "继续" / "下一步" / "next" / "接下来" | lifecycle 自然下一步 |
145
+ | "什么状态" / "现在到哪了" / "status" | `manage-status` |
146
+ | 字面命中路由表 | 路由表优先(lifecycle 仅加分) |
147
+ | 无任何匹配 | lifecycle 下一步 + raise W002 |
117
148
 
118
- **意图 → 命令路由表**(候选池等于本表 + 上方"自然下一步"建议):
149
+ **意图 → 命令路由表**(候选池):
119
150
 
120
151
  | 意图关键词 | 推荐命令 |
121
152
  |-----------|---------|
@@ -146,70 +177,74 @@ brainstorm → blueprint → init → analyze-macro → roadmap
146
177
  | fork / 分支 / 并行开发 | `maestro-fork` / `maestro-merge` |
147
178
  | 覆盖层 / overlay / amend | `maestro-overlay` / `maestro-amend` |
148
179
 
180
+ **辅助 workflow 簇**(场景触发,非主线):
181
+
182
+ | 簇 | 触发 | 主推链路 |
183
+ |----|------|---------|
184
+ | Learning | 接触新代码/未知模块 | `learn-follow` → `learn-decompose` → `learn-second-opinion` |
185
+ | Knowledge | 提炼经验 / 沉淀知识 | `manage-harvest` → `manage-knowhow-capture` → `spec-add` |
186
+ | Wiki | 知识图谱整理 | `manage-wiki` → `wiki-connect` → `wiki-digest` |
187
+ | Issue | 缺陷管理 | `manage-issue-discover` → `manage-issue` |
188
+ | 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-refresh` |
189
+ | 重构 | 技术债积累 | `quality-refactor` → `quality-review` |
190
+ | 发布 | 里程碑结束 | `maestro-milestone-audit` → `maestro-milestone-release` |
191
+ | 并行开发 | 多 milestone 并行 | `maestro-fork` → ... → `maestro-merge` |
192
+
149
193
  输出 ranked candidates,取 top N(默认 3)。
150
194
 
151
- ### Step 3: Present & Confirm
195
+ </actions>
196
+
197
+ </state_machine>
198
+
199
+ <presentation>
152
200
 
153
- **`--list` 模式:** 按类别(maestro / manage / quality / learn / spec / wiki / security)分组展示所有候选 + description,结束。
201
+ ### `--list` 模式
154
202
 
155
- **正常模式:**
203
+ 按 workflow 簇(主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行)分组展示全部候选 + description,结束。
204
+
205
+ ### 正常模式
156
206
 
157
- 显示:
158
207
  ```
159
208
  🎯 推荐 (top pick): /<command-name>
160
209
  <description>
161
- 推荐理由: <一句话说明为什么命中>
210
+ 推荐理由: <命中规则 + lifecycle 位置一句话>
162
211
 
163
212
  备选:
164
213
  2. /<alt-1> — <description>
165
214
  3. /<alt-2> — <description>
166
215
 
167
- 执行参数: <args-to-pass>
216
+ 执行参数: <args>
168
217
  ```
169
218
 
170
- - `--dry-run` 显示后结束
171
- - `-y` → 直接执行 top pick
172
- - 否则 → `ask_question` 让用户:执行 top pick / 选备选 / 修改参数 / 取消
173
-
174
- ### Step 4: Execute
175
-
176
- 通过 `view_file(AbsolutePath="<agy-skills-dir>/<chosen-command-name>/SKILL.md") + execute inline (args: "<args>")` 执行。
219
+ `--dry-run` 展示后结束;`-y` 直接 S_EXECUTE;否则 ask_question 提供:执行 top pick / 选备选 / 修改参数 / 取消。
177
220
 
178
- **参数传递:**
179
- - 默认把 intent 原文作为第一个参数传给目标命令
180
- - 若用户在 Step 3 修改了参数,使用修改后的版本
181
- - `-y` flag 透传给目标命令(如果目标命令支持)
221
+ </presentation>
182
222
 
183
- 执行完成后显示:
184
- ```
185
- ✅ 已执行 /<command-name>
186
- ```
223
+ <appendix>
187
224
 
188
- 不创建 session、不写 status.json、不做后续 chain — 由目标命令自行管理其产出。
225
+ ### Error Codes
189
226
 
190
- </execution>
191
-
192
- <error_codes>
193
227
  | Code | Severity | Condition | Recovery |
194
228
  |------|----------|-----------|----------|
195
- | E001 | error | 未提供 intent clarification 后仍为空 | 提供意图描述或使用 `--list` 浏览命令池 |
196
- | E002 | error | 候选池为空(commands 目录不存在或无 .md 文件) | 检查 `.claude/commands/` 是否存在 |
197
- | E003 | error | 用户选择的命令名无法解析为有效 skill | 列出有效命令名让用户重选 |
198
- | W001 | warning | 多个命令得分接近(top1 与 top2 差距 < 阈值) | 强制展示前 3,让用户裁决 |
199
- | W002 | warning | intent 与所有候选匹配度均低 | 提示用户考虑 `/maestro` 或 `/maestro-ralph` 走管线 |
200
- </error_codes>
201
-
202
- <success_criteria>
229
+ | E001 | error | intent 空且 clarification 后仍空 | 提供意图描述或使用 `--list` 浏览 |
230
+ | E002 | error | 候选池为空(`.claude/commands/` 缺失或无 .md | 检查 commands 目录 |
231
+ | E003 | error | 选定命令名无法解析为有效 skill | 列出有效命令重选 |
232
+ | W001 | warning | top1 与 top2 得分差距 < 阈值 | 强制展示前 3 让用户裁决 |
233
+ | W002 | warning | intent 与所有候选匹配度均低 | 提示考虑 `/maestro` 或 `/maestro-ralph` 走管线 |
234
+
235
+ ### Success Criteria
236
+
203
237
  - [ ] Intent 解析 + flags 提取完成
204
238
  - [ ] 读取 `.workflow/state.json` + scratch artifacts 推断 lifecycle_position
205
- - [ ] 候选池等于路由表(管线编排器自然不在表中)
206
- - [ ] 评分综合:intent 字面匹配 + lifecycle 自然下一步 + workflow 簇 + recent activity
239
+ - [ ] 候选池等于路由表(管线编排器不在)
240
+ - [ ] 评分综合:intent 字面匹配 + lifecycle 下一步 + workflow 簇 + recent activity
207
241
  - [ ] 空 intent / "继续" / "下一步" → 直接采用 lifecycle 推断的下一步
208
- - [ ] top pick 展示时附"推荐理由"(命中规则 + lifecycle 位置)
242
+ - [ ] top pick 展示附"推荐理由"(命中规则 + lifecycle 位置)
209
243
  - [ ] `--dry-run` 仅展示,不执行
210
- - [ ] `-y` 自动执行 top pick
211
- - [ ] 非自动模式下,用户通过 ask_question 确认或选择备选
212
- - [ ] 选定命令通过 `Skill()` 单次调用执行
213
- - [ ] 不创建 session、不生成 status.json、不触发后续 chain
214
- - [ ] `--list` 模式按 workflow 簇(主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行)分组展示
215
- </success_criteria>
244
+ - [ ] `-y` 自动执行 top pick;用户传入时透传到 skill args
245
+ - [ ] 非自动模式通过 ask_question 确认或选备选
246
+ - [ ] 选定命令通过单次 `Skill()` 调用执行
247
+ - [ ] 不创建 session / 不生成 status.json / 不触发后续 chain
248
+ - [ ] `--list` 模式按 workflow 簇分组展示
249
+
250
+ </appendix>
@@ -75,6 +75,10 @@ If exit code is 1, present warnings and ask whether to proceed.
75
75
 
76
76
  Follow '~/.maestro/workflows/plan.md' completely.
77
77
 
78
+ ### P3 Agent Constraint (MANDATORY)
79
+
80
+ Main flow **MUST** spawn a planner agent (Agent tool) for P3 planning — inline planning by main flow is FORBIDDEN. The agent produces both `plan.json` and `.task/TASK-*.json` files. Main flow only passes context and validates output.
81
+
78
82
  ### Codebase Docs Loading (P1 addition)
79
83
 
80
84
  During P1 Context Collection, after loading context files, load codebase documentation if available:
@@ -127,20 +127,20 @@ S_INFER:
127
127
 
128
128
  S_RESOLVE_SCOPE:
129
129
  → S_QUALITY_MODE DO: A_RESOLVE_SCOPE_VERDICT
130
- GUARD: position ∈ {brainstorm, blueprint, init} → skip (scope_verdict = null)
130
+ GUARD: position ∈ {grill, brainstorm, blueprint, init} → skip (scope_verdict = null)
131
131
 
132
132
  S_QUALITY_MODE:
133
133
  → S_PLANNING_MODE DO: A_DETERMINE_QUALITY_MODE
134
134
 
135
135
  S_PLANNING_MODE:
136
136
  → S_DECOMPOSE DO: A_DETERMINE_PLANNING_MODE
137
- GUARD: lifecycle_position ∈ {brainstorm, blueprint, init, analyze-macro, roadmap} → skip (force independent)
137
+ GUARD: lifecycle_position ∈ {grill, brainstorm, blueprint, init, analyze-macro, roadmap} → skip (force independent)
138
138
 
139
139
  S_DECOMPOSE:
140
140
  → S_BUILD_CHAIN DO: A_DECOMPOSE_TASKS
141
141
  GUARD: broad intent → MUST clarify boundary even if auto_confirm
142
142
  GUARD: narrow intent → auto-derive, skip questions
143
- GUARD: position ∈ {brainstorm, blueprint, init} → skip decomposition
143
+ GUARD: position ∈ {grill, brainstorm, blueprint, init} → skip decomposition
144
144
 
145
145
  S_BUILD_CHAIN:
146
146
  → S_CREATE_SESSION DO: A_BUILD_STEPS
@@ -240,6 +240,7 @@ resolve_milestone(phase_number):
240
240
 
241
241
  | Pattern | Position |
242
242
  |---------|----------|
243
+ | 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`(**auto_confirm=true 时跳过,直接 `brainstorm`**) |
243
244
  | brainstorm / 头脑风暴 / 探索 / ideate / 设计思路 | `brainstorm` |
244
245
  | blueprint / 规格 / 正式文档 / spec-generate / 7-phase | `blueprint` |
245
246
  | broad/medium intent 无数字 phase (重构/全面/重写/迁移/新功能 X) | `analyze-macro` |
@@ -260,7 +261,7 @@ resolve_milestone(phase_number):
260
261
  | `phase_is_new == true` (新 phase) | `analyze` |
261
262
  | no milestones AND no roadmap.md AND has analyze macro artifact | `roadmap` |
262
263
  | no milestones AND no roadmap.md AND no analyze artifact | `analyze-macro` |
263
- | `phase == null` (brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
264
+ | `phase == null` (grill/brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
264
265
  | phase 已存在 + 无任何 artifact | `analyze` |
265
266
  | phase 已存在 + 最新 artifact = analyze | `plan` |
266
267
  | phase 已存在 + 最新 artifact = plan | `execute` |
@@ -315,7 +316,7 @@ resolve_milestone(phase_number):
315
316
 
316
317
  | Condition | Mode | Reason |
317
318
  |-----------|------|--------|
318
- | lifecycle_position ∈ {brainstorm, init, roadmap} | `independent` | 前期阶段不涉及多 phase 规划 |
319
+ | lifecycle_position ∈ {grill, brainstorm, init, roadmap} | `independent` | 前期阶段不涉及多 phase 规划 |
319
320
  | `phase_is_new == true` | `independent` | 新 phase 尚无里程碑上下文 |
320
321
  | intent 显式指定 phase 编号(如 "phase 2"、"P3") | `independent` | 用户明确针对单个 phase |
321
322
  | milestone 仅含 1 个 phase(读 state.json) | `independent` | 统一无意义 |
@@ -378,7 +379,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
378
379
 
379
380
  | Stage | Skill (independent) | Skill (unified) | Decision after | quality_mode |
380
381
  |-------|---------------------|-----------------|----------------|--------------|
381
- | brainstorm | `maestro-brainstorm "{intent}"` | *(same)* | — | all |
382
+ | grill | `maestro-grill "{intent}"` | *(same)* | — | all (**skip when auto_confirm**) |
383
+ | brainstorm | `maestro-brainstorm "{intent}" --from grill:{grill_id}` *(if grill ran)* / `maestro-brainstorm "{intent}"` *(otherwise)* | *(same)* | — | all |
382
384
  | blueprint | `maestro-blueprint "{intent}"` | *(same)* | — | all |
383
385
  | init | `maestro-init` | *(same)* | — | all |
384
386
  | analyze-macro | `maestro-analyze "{intent}"` | *(same)* | `post-analyze-scope` | all |
@@ -403,6 +405,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
403
405
  1. **起点**:从 `session.lifecycle_position` 开始
404
406
  2. **跳过已完成**:跳过当前 milestone+phase 下已有 completed artifact 的 stage(按 `session.phase` 过滤);unified 按 milestone 过滤
405
407
  3. **quality_mode 过滤**:按 `session.quality_mode` 排除不匹配 stage
408
+ 3.5. **grill auto_confirm 跳过**:`auto_confirm == true` 时删除 `grill` stage(grill 为交互式苏格拉底拷问,不支持自动模式);brainstorm args 不含 `--from grill:*`
406
409
  4. **决策节点**:每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
407
410
  5. **goal-audit 插入**:`task_decomposition` 存在时,在最后一个 evidence-producing stage(verify/review/test)之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
408
411
  6. **终点硬约束**:chain 以 `milestone-complete` 结尾
@@ -739,7 +742,8 @@ decision:post-goal-audit {retry+1}
739
742
  - [ ] Phase 先于 position 解析;phase_is_new 标记写入 session
740
743
  - [ ] D-007 反查:phase 数字 → `session.milestone`,禁止读 current_milestone;写入 step.milestone_id
741
744
  - [ ] phase_is_new=true → lifecycle_position 强制 `analyze`
742
- - [ ] Intent overrides 识别 brainstorm / blueprint / analyze-macro
745
+ - [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
746
+ - [ ] auto_confirm=true 时 grill stage 跳过(交互式拷问不支持自动模式)
743
747
  - [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict,写入 session.scope_verdict + analyze_macro_id
744
748
  - [ ] 链路起点 = analyze-macro 时:large→roadmap+analyze+plan(phase);medium/small→直跳 plan --from analyze:{ANL_ID}(跳过 roadmap+analyze)
745
749
  - [ ] post-analyze-scope decision 节点在 macro analyze 之后插入;A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路