maestro-flow 0.3.8 → 0.3.10

package/README.zh-CN.md

@@ -32,12 +32,13 @@ Maestro-Flow 是一个面向 Claude Code、Codex、Gemini 等多智能体的工
 # 或者一步步来
 /maestro-init                    # 初始化项目工作区
 /maestro-roadmap                 # 交互式创建路线图
-/maestro-plan 1                  # 生成第一阶段执行计划
-/maestro-execute 1               # 波次并行多智能体执行
-/maestro-verify 1                # 目标反推验证
+/maestro-analyze                 # 多维度分析
+/maestro-plan                    # 生成执行计划
+/maestro-execute                 # 波次并行多智能体执行
+/maestro-verify                  # 目标反推验证
 ```
 
-### 阶段管线
+### 里程碑管线
 
 ```mermaid
 graph LR
@@ -48,11 +49,13 @@ graph LR
     E --> F[execute]
     F --> G[verify]
     G --> H[review]
-    H --> I[test]
-    I --> J[transition]
-    J -->|下一阶段| D
+    H --> I[milestone-audit]
+    I --> J[milestone-complete]
+    J -->|下一里程碑| D
 ```
 
+所有工作产物存放在 `.workflow/scratch/`，通过 `state.json` artifact registry 追踪。Phase 是 roadmap 中的标签，不是目录。
+
 ### 快速通道
 
 | 通道 | 流程 | 适用场景 |
@@ -67,9 +70,9 @@ graph LR
 
 ### 1. 结构化管线
 
-基于阶段的执行模型，每个阶段经历 analyze > plan > execute > verify > review > test > transition。仪表盘展示正在发生什么、下一步该做什么。
+基于 Scratch 的里程碑工作流，通过 artifact registry 追踪进度。每个里程碑经历 analyze > plan > execute > verify > review > milestone-audit > milestone-complete。所有产物存放在 `.workflow/scratch/`，`state.json` 是唯一状态源。
 
-51 个斜杠命令覆盖 6 大类别，驱动从项目初始化到质量复盘的每一个环节。
+49 个斜杠命令覆盖 6 大类别，驱动从项目初始化到质量复盘的每一个环节。
 
 ### 2. 自主驾驶
 
@@ -94,10 +97,10 @@ graph LR
 | 阶段 | 命令 | 做了什么 |
 |------|------|---------|
 | **发现** | `/manage-issue-discover` | 8 视角扫描: Bug、UX、技术债、安全、性能、测试缺口、代码质量、文档 |
-| **分析** | `/manage-issue-analyze` | CLI 探索式根因分析 |
-| **规划** | `/manage-issue-plan` | 生成解决方案步骤、目标文件、验证条件 |
-| **执行** | `/manage-issue-execute` | Dashboard API 派发或 CLI 直接执行 |
-| **关闭** | 自动 | 验证通过 -> resolved -> closed |
+| **分析** | `/maestro-analyze --gaps` | CLI 探索式根因分析，写入 `issue.analysis` |
+| **规划** | `/maestro-plan --gaps` | 生成 TASK 文件并通过 `task_refs` 关联到 Issue |
+| **执行** | `/maestro-execute` | 基于 wave 的并行执行，自动同步 Issue 状态 |
+| **关闭** | 自动 | 所有关联 task 完成 → resolved → closed |
 
 质量命令（`review`、`test`、`verify`）自动为发现的问题创建 Issue。Issue 修复的代码回流到阶段管线。闭环自动关闭。
 
@@ -168,7 +171,7 @@ Maestro-Flow 协调多个 AI 智能体并行工作:
 | `context-monitor` | 监控上下文用量，接近上限时注入警告 |
 | `spec-injector` | 按智能体类型自动注入项目规范到子 Agent 提示词 |
 | `delegate-monitor` | 跟踪异步 delegate 任务完成状态 |
-| `team-monitor` | 团队协作消息感知 |
+| `team-monitor` | Collab 心跳 -- 向 `.workflow/collab/activity.jsonl` 上报活动，供队友感知 |
 | `telemetry` | 执行遥测收集 |
 | `session-context` | 会话启动时注入工作流状态 |
 | `skill-context` | 调用工作流 Skill 时注入工作流状态 |
@@ -195,7 +198,7 @@ maestro overlay bundle -o team.json    # 打包分享
 
 ---
 
-## 51 个命令，21 个 Agent
+## 49 个命令，21 个 Agent
 
 ### 命令
 
@@ -287,7 +290,7 @@ maestro/
 |       |   +-- execution/   # ExecutionScheduler + WaveExecutor
 |       +-- shared/          # 共享类型
 +-- .claude/
-|   +-- commands/            # 51 个斜杠命令 (.md)
+|   +-- commands/            # 49 个斜杠命令 (.md)
 |   +-- agents/              # 21 个 Agent 定义 (.md)
 +-- workflows/               # 47 个工作流实现 (.md)
 +-- templates/               # JSON 模板 (task, plan, issue, ...)
@@ -309,12 +312,13 @@ maestro/
 
 ## 文档
 
-- **[命令使用指南](guide/command-usage-guide.md)** -- 全部 51 个命令，含工作流图表、管线衔接、Issue 闭环、快速通道
+- **[命令使用指南](guide/command-usage-guide.md)** -- 全部 49 个命令，含工作流图表、管线衔接、Issue 闭环、快速通道
 - **[Delegate 异步执行指南](guide/delegate-async-guide.md)** -- 异步任务委派: CLI & MCP 用法、消息注入、链式调用、Broker 生命周期
 - **[Overlay 系统指南](guide/overlay-guide.md)** -- 非侵入式命令扩展: overlay 格式、section 注入、bundle 打包/导入、交互式 TUI 管理
 - **[Hook 系统指南](guide/hooks-guide.md)** -- Hook 系统架构、9 个 Hook、Spec 注入、上下文预算、配置
-- **[Team Lite -- 使用指南](guide/team-lite-guide.md)** -- 2-8 人小团队日常协作: 加入、同步、队友活跃、冲突预飞检
-- **[Team Lite -- 设计文档](guide/team-lite-design.md)** -- 架构、数据模型、人机协作与智能体管线的命名空间边界
+- **[Worktree 并行开发指南](guide/worktree-guide.md)** -- 里程碑级 worktree 并行: fork、sync、merge、scope 保护、Dashboard 集成
+- **[Collab 协作 -- 使用指南](guide/team-lite-guide.md)** -- 2-8 人小团队协作: 加入、同步、活动感知、冲突预检、任务管理、命名空间隔离
+- **[Collab 协作 -- 设计文档](guide/team-lite-design.md)** -- 架构、数据模型、人类协作域 (`.workflow/collab/`) 与智能体管线 (`.workflow/.team/`) 的命名空间边界
 
 ---
 

package/bin/maestro-mcp.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import '../dist/src/mcp/server.js';

package/chains/_intent-map.json

@@ -117,16 +117,10 @@
       "route": { "graph": "singles/sync" }
     },
     {
-      "type": "phase_transition",
-      "regex": "phase.*transit|next.*phase|推进|切换.*阶段",
+      "type": "milestone_close",
+      "regex": "phase.*transit|next.*phase|推进|切换.*阶段|close.*milestone|结束.*里程碑",
       "flags": "i",
-      "route": { "graph": "singles/phase-transition" }
-    },
-    {
-      "type": "phase_add",
-      "regex": "phase.*add|add.*phase|添加.*阶段",
-      "flags": "i",
-      "route": { "graph": "singles/phase-add" }
+      "route": { "graph": "milestone-close" }
     },
     {
       "type": "milestone_audit",
@@ -254,6 +248,24 @@
       "flags": "i",
       "route": { "graph": "singles/team-tech-debt" }
     },
+    {
+      "type": "learn",
+      "regex": "\\blearn|capture.*insight|eureka|记录.*洞察",
+      "flags": "i",
+      "route": { "graph": "singles/memory-capture" }
+    },
+    {
+      "type": "fork",
+      "regex": "\\bfork|worktree.*creat|parallel.*milestone|分叉|并行.*里程碑",
+      "flags": "i",
+      "route": { "graph": "milestone-fork-merge" }
+    },
+    {
+      "type": "merge",
+      "regex": "merge.*worktree|merge.*milestone|合并.*工作树",
+      "flags": "i",
+      "route": { "graph": "milestone-fork-merge" }
+    },
     {
       "type": "quick",
       "regex": "quick|small.*task|ad.?hoc|简单|快速",

package/chains/_router.json

@@ -2,8 +2,8 @@
   "$schema": "./chain-graph.schema.json",
   "id": "_router",
   "name": "State Router",
-  "description": "Route to appropriate graph based on project state",
-  "version": "1.0.0",
+  "description": "Route to appropriate graph based on project state and artifact registry",
+  "version": "2.0.0",
   "tags": ["internal", "router"],
   "entry": "check_init",
   "inputs": {
@@ -21,10 +21,10 @@
     },
     "check_has_roadmap": {
       "type": "decision",
-      "eval": "ctx.project.phases_total",
+      "eval": "ctx.project.milestones_total",
       "edges": [
-        { "match": "ctx.project.phases_total == 0", "target": "check_accumulated_context" },
-        { "default": true, "target": "check_phase_status" }
+        { "match": "ctx.project.milestones_total == 0", "target": "check_accumulated_context" },
+        { "default": true, "target": "check_artifact_state" }
       ]
     },
     "check_accumulated_context": {
@@ -35,98 +35,61 @@
         { "default": true, "target": "to_brainstorm_driven" }
       ]
     },
-    "check_phase_status": {
+    "check_artifact_state": {
       "type": "decision",
-      "eval": "ctx.project.phase_status",
+      "description": "Determine next step from artifact registry — what's the latest completed artifact type for current milestone?",
+      "eval": "ctx.project.latest_artifact_type",
       "edges": [
-        { "value": "pending", "target": "check_pending_artifacts" },
-        { "value": "exploring", "target": "check_has_plan" },
-        { "value": "planning", "target": "check_has_plan" },
-        { "value": "executing", "target": "check_tasks_done" },
-        { "value": "verifying", "target": "check_verification" },
-        { "value": "testing", "target": "check_uat" },
-        { "value": "completed", "target": "check_all_phases" },
-        { "value": "blocked", "target": "to_debug" }
-      ]
-    },
-    "check_pending_artifacts": {
-      "type": "decision",
-      "eval": "ctx.project.artifacts.context",
-      "edges": [
-        { "value": true, "target": "to_plan" },
+        { "value": null, "target": "to_analyze" },
+        { "value": "analyze", "target": "check_has_plan" },
+        { "value": "brainstorm", "target": "to_analyze" },
+        { "value": "plan", "target": "to_execute" },
+        { "value": "execute", "target": "to_verify" },
+        { "value": "verify", "target": "check_verify_result" },
         { "default": true, "target": "to_analyze" }
       ]
     },
     "check_has_plan": {
       "type": "decision",
-      "eval": "ctx.project.artifacts.plan",
+      "eval": "ctx.project.has_pending_plans",
       "edges": [
         { "value": true, "target": "to_execute_verify" },
         { "default": true, "target": "to_plan" }
       ]
     },
-    "check_tasks_done": {
-      "type": "decision",
-      "eval": "ctx.project.execution.tasks_completed",
-      "edges": [
-        {
-          "match": "ctx.project.execution.tasks_completed >= ctx.project.execution.tasks_total && ctx.project.execution.tasks_total > 0",
-          "target": "to_verify"
-        },
-        { "default": true, "target": "to_execute" }
-      ]
-    },
-    "check_verification": {
+    "check_verify_result": {
       "type": "decision",
       "eval": "ctx.project.verification_status",
       "edges": [
-        { "value": "passed", "target": "check_business_test" },
+        { "value": "passed", "target": "check_review" },
         { "default": true, "target": "to_quality_loop_partial" }
       ]
     },
-    "check_business_test": {
-      "type": "decision",
-      "eval": "ctx.project.business_test_status",
-      "edges": [
-        { "value": null, "target": "to_business_test" },
-        { "value": "passed", "target": "check_review_after_verify" },
-        { "default": true, "target": "to_quality_loop_partial" }
-      ]
-    },
-    "check_review_after_verify": {
+    "check_review": {
       "type": "decision",
       "eval": "ctx.project.review_verdict",
       "edges": [
         { "value": null, "target": "to_review" },
-        { "default": true, "target": "check_uat_after_review" }
-      ]
-    },
-    "check_uat_after_review": {
-      "type": "decision",
-      "eval": "ctx.project.uat_status",
-      "edges": [
-        { "value": "pending", "target": "to_test" },
-        { "value": "passed", "target": "to_phase_transition" },
-        { "default": true, "target": "to_debug_from_uat" }
+        { "value": "BLOCK", "target": "to_quality_loop_partial" },
+        { "default": true, "target": "check_uat" }
       ]
     },
     "check_uat": {
       "type": "decision",
       "eval": "ctx.project.uat_status",
       "edges": [
-        { "value": "passed", "target": "to_phase_transition" },
+        { "value": null, "target": "to_test" },
+        { "value": "passed", "target": "check_all_phases" },
         { "default": true, "target": "to_debug_from_uat" }
       ]
     },
     "check_all_phases": {
       "type": "decision",
-      "eval": "ctx.project.phases_completed",
+      "description": "Check if all phases in milestone have completed execute artifacts",
+      "eval": "ctx.project.all_phases_executed",
       "edges": [
-        {
-          "match": "ctx.project.phases_completed >= ctx.project.phases_total",
-          "target": "to_milestone_close"
-        },
-        { "default": true, "target": "to_phase_transition" }
+        { "value": true, "target": "to_milestone_close" },
+        { "default": true, "target": "to_analyze" }
       ]
     },
     "to_init": {
@@ -154,25 +117,20 @@
       "status": "delegate",
       "delegate_graph": "singles/verify"
     },
-    "to_business_test": {
-      "type": "terminal",
-      "status": "delegate",
-      "delegate_graph": "singles/business-test"
-    },
     "to_review": {
       "type": "terminal",
       "status": "delegate",
       "delegate_graph": "singles/review"
     },
-    "to_test": {
+    "to_debug": {
       "type": "terminal",
       "status": "delegate",
-      "delegate_graph": "singles/test"
+      "delegate_graph": "singles/debug"
     },
-    "to_debug": {
+    "to_test": {
       "type": "terminal",
       "status": "delegate",
-      "delegate_graph": "singles/debug"
+      "delegate_graph": "singles/test"
     },
     "to_debug_from_uat": {
       "type": "terminal",
@@ -185,11 +143,6 @@
       "status": "delegate",
       "delegate_graph": "execute-verify"
     },
-    "to_phase_transition": {
-      "type": "terminal",
-      "status": "delegate",
-      "delegate_graph": "singles/phase-transition"
-    },
     "to_milestone_close": {
       "type": "terminal",
       "status": "delegate",

package/chains/brainstorm-driven.json

@@ -62,18 +62,29 @@
       "eval": "ctx.result.verification_status",
       "edges": [
         { "value": "passed", "target": "done" },
-        { "default": true, "target": "done_with_issues" }
+        { "default": true, "target": "fix_plan" }
       ]
     },
+    "fix_plan": {
+      "type": "command",
+      "cmd": "maestro-plan",
+      "description": "Re-plan to address verification gaps",
+      "args": "{phase} --gaps",
+      "auto_flag": "--auto",
+      "next": "fix_execute"
+    },
+    "fix_execute": {
+      "type": "command",
+      "cmd": "maestro-execute",
+      "description": "Re-execute from gap-fix plan",
+      "args": "{phase}",
+      "next": "verify",
+      "max_visits": 2
+    },
     "done": {
       "type": "terminal",
       "status": "success",
       "summary": "Brainstorm-driven pipeline completed successfully"
-    },
-    "done_with_issues": {
-      "type": "terminal",
-      "status": "paused",
-      "summary": "Brainstorm-driven pipeline completed with verification issues"
     }
   }
 }

package/chains/full-lifecycle.json

@@ -2,12 +2,12 @@
   "$schema": "./chain-graph.schema.json",
   "id": "full-lifecycle",
   "name": "Full Lifecycle",
-  "description": "Plan -> Execute -> Verify -> Review -> Test -> Transition with decision points",
-  "version": "1.0.0",
-  "tags": ["lifecycle", "phase"],
+  "description": "Plan -> Execute -> Verify -> Review -> Test -> Milestone Audit/Complete with decision points",
+  "version": "2.0.0",
+  "tags": ["lifecycle", "milestone"],
   "entry": "plan",
   "inputs": {
-    "phase": { "type": "string", "required": true },
+    "phase": { "type": "string", "required": false },
     "description": { "type": "string" }
   },
   "defaults": { "analyze": true },
@@ -38,21 +38,6 @@
     "check_verify": {
       "type": "decision",
       "eval": "ctx.result.verification_status",
-      "edges": [
-        { "value": "passed", "target": "business_test" },
-        { "default": true, "target": "fix_plan" }
-      ]
-    },
-    "business_test": {
-      "type": "command",
-      "cmd": "quality-business-test",
-      "description": "PRD-forward business testing with requirement traceability",
-      "args": "{phase} --auto",
-      "next": "check_business_test"
-    },
-    "check_business_test": {
-      "type": "decision",
-      "eval": "ctx.result.business_test_status",
       "edges": [
         { "value": "passed", "target": "review" },
         { "default": true, "target": "fix_plan" }
@@ -101,7 +86,7 @@
       "type": "decision",
       "eval": "ctx.result.uat_status",
       "edges": [
-        { "value": "passed", "target": "transition" },
+        { "value": "passed", "target": "milestone_audit" },
         { "default": true, "target": "debug" }
       ]
     },
@@ -113,10 +98,24 @@
       "next": "fix_execute",
       "max_visits": 2
     },
-    "transition": {
+    "milestone_audit": {
+      "type": "command",
+      "cmd": "maestro-milestone-audit",
+      "description": "Audit milestone for cross-phase integration gaps using artifact registry",
+      "next": "check_audit"
+    },
+    "check_audit": {
+      "type": "decision",
+      "eval": "ctx.result.audit_verdict",
+      "edges": [
+        { "value": "PASS", "target": "milestone_complete" },
+        { "default": true, "target": "fix_plan" }
+      ]
+    },
+    "milestone_complete": {
       "type": "command",
-      "cmd": "maestro-phase-transition",
-      "description": "Complete phase, extract learnings, advance to next",
+      "cmd": "maestro-milestone-complete",
+      "description": "Archive scratch artifacts, move to milestone_history, advance to next milestone",
       "next": "done"
     },
     "done": {

package/chains/issue-lifecycle.json

@@ -23,23 +23,23 @@
     },
     "analyze": {
       "type": "command",
-      "cmd": "manage-issue-analyze",
-      "description": "Root cause analysis for the issue using CLI exploration",
-      "args": "{issue_id}",
+      "cmd": "maestro-analyze",
+      "description": "Root cause analysis for the issue via --gaps mode",
+      "args": "--gaps {issue_id}",
       "next": "plan"
     },
     "plan": {
       "type": "command",
-      "cmd": "manage-issue-plan",
-      "description": "Generate codebase-aware solution plan with step decomposition",
-      "args": "{issue_id}",
+      "cmd": "maestro-plan",
+      "description": "Generate TASK files linked to issue via task_refs",
+      "args": "--gaps",
       "next": "execute"
     },
     "execute": {
       "type": "command",
-      "cmd": "manage-issue-execute",
-      "description": "Execute planned solution via dual-mode agent dispatch",
-      "args": "{issue_id}",
+      "cmd": "maestro-execute",
+      "description": "Wave-based execution with automatic issue status sync",
+      "args": "",
       "next": "check_result"
     },
     "check_result": {
@@ -52,17 +52,17 @@
     },
     "retry_plan": {
       "type": "command",
-      "cmd": "manage-issue-plan",
+      "cmd": "maestro-plan",
       "description": "Re-plan after execution failure with updated context",
-      "args": "{issue_id} --retry",
+      "args": "--gaps",
       "next": "retry_execute",
       "max_visits": 2
     },
     "retry_execute": {
       "type": "command",
-      "cmd": "manage-issue-execute",
+      "cmd": "maestro-execute",
       "description": "Re-execute with revised plan",
-      "args": "{issue_id}",
+      "args": "",
       "next": "done",
       "max_visits": 2
     },

package/chains/milestone-close.json

@@ -2,8 +2,8 @@
   "$schema": "./chain-graph.schema.json",
   "id": "milestone-close",
   "name": "Milestone Close",
-  "description": "Milestone Audit -> Phase Transition -> Done",
-  "version": "1.0.0",
+  "description": "Milestone Audit -> Milestone Complete",
+  "version": "2.0.0",
   "tags": ["milestone"],
   "entry": "audit",
   "inputs": {},
@@ -11,19 +11,32 @@
     "audit": {
       "type": "command",
       "cmd": "maestro-milestone-audit",
-      "description": "Audit current milestone for cross-phase integration gaps",
-      "next": "transition"
+      "description": "Audit current milestone using artifact registry for cross-phase integration gaps",
+      "next": "check_audit"
     },
-    "transition": {
+    "check_audit": {
+      "type": "decision",
+      "eval": "ctx.result.audit_verdict",
+      "edges": [
+        { "value": "PASS", "target": "complete" },
+        { "default": true, "target": "failed" }
+      ]
+    },
+    "complete": {
       "type": "command",
-      "cmd": "maestro-phase-transition",
-      "description": "Complete phase, extract learnings, advance to next",
+      "cmd": "maestro-milestone-complete",
+      "description": "Archive scratch artifacts to milestones/, move artifact entries to history, advance state",
       "next": "done"
     },
     "done": {
       "type": "terminal",
       "status": "success",
       "summary": "Milestone closed successfully"
+    },
+    "failed": {
+      "type": "terminal",
+      "status": "failed",
+      "summary": "Audit failed — fix integration gaps before completing milestone"
     }
   }
 }

package/chains/milestone-fork-merge.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "./chain-graph.schema.json",
+  "id": "milestone-fork-merge",
+  "name": "Milestone Fork & Merge",
+  "description": "Fork a milestone into a worktree, run full lifecycle, then merge back",
+  "version": "1.0.0",
+  "tags": ["worktree", "milestone", "parallel"],
+  "entry": "fork",
+  "inputs": {
+    "milestone_num": { "type": "number", "required": true }
+  },
+  "nodes": {
+    "fork": {
+      "type": "command",
+      "cmd": "maestro-fork",
+      "description": "Create worktree for milestone with all phases",
+      "args": "-m {milestone_num}",
+      "next": "lifecycle_in_worktree"
+    },
+    "lifecycle_in_worktree": {
+      "type": "command",
+      "cmd": "maestro",
+      "description": "Run sequential lifecycle for all phases in worktree (analyze, plan, execute, verify, transition per phase)",
+      "args": "continue",
+      "cwd": ".worktrees/m{milestone_num}-{milestone_slug}",
+      "next": "merge_decision"
+    },
+    "merge_decision": {
+      "type": "decision",
+      "description": "Check if all milestone phases are completed",
+      "condition": "all_phases_completed",
+      "branches": {
+        "true": "merge",
+        "false": "lifecycle_in_worktree"
+      }
+    },
+    "merge": {
+      "type": "command",
+      "cmd": "maestro-merge",
+      "description": "Merge milestone worktree back into main",
+      "args": "-m {milestone_num}",
+      "next": "done"
+    },
+    "done": {
+      "type": "terminal",
+      "status": "success",
+      "summary": "Milestone {milestone_num} forked, developed, and merged successfully"
+    }
+  }
+}

package/chains/roadmap-driven.json

@@ -53,18 +53,29 @@
       "eval": "ctx.result.verification_status",
       "edges": [
         { "value": "passed", "target": "done" },
-        { "default": true, "target": "done_with_issues" }
+        { "default": true, "target": "fix_plan" }
       ]
     },
+    "fix_plan": {
+      "type": "command",
+      "cmd": "maestro-plan",
+      "description": "Re-plan to address verification gaps",
+      "args": "{phase} --gaps",
+      "auto_flag": "--auto",
+      "next": "fix_execute"
+    },
+    "fix_execute": {
+      "type": "command",
+      "cmd": "maestro-execute",
+      "description": "Re-execute from gap-fix plan",
+      "args": "{phase}",
+      "next": "verify",
+      "max_visits": 2
+    },
     "done": {
       "type": "terminal",
       "status": "success",
       "summary": "Roadmap-driven pipeline completed successfully"
-    },
-    "done_with_issues": {
-      "type": "terminal",
-      "status": "paused",
-      "summary": "Roadmap-driven pipeline completed with verification issues"
     }
   }
 }