maestro-flow 0.4.11 → 0.4.12

package/.agents/skills/maestro-help/phases/02-search-present.md

@@ -70,7 +70,7 @@
 | 命令 | Guide 文档 |
 |------|-----------|
 | maestro-analyze/plan/execute/verify | `guide/command-usage-guide.md` (主干管线) |
-| maestro-init/roadmap | `guide/quick-start-guide.md` |
+| maestro-init/roadmap/blueprint | `guide/quick-start-guide.md` |
 | maestro-ralph | `guide/maestro-ralph-guide.md` |
 | maestro (协调器) | `guide/maestro-coordinator-guide.md` |
 | manage-* | `guide/command-usage-guide.md` (管理) |
@@ -91,9 +91,11 @@
 | 当前状态 | 推荐命令 | 原因 |
 |---------|---------|------|
 | 无 .workflow/ | `/maestro-init` | 项目未初始化，需要先创建工作区 |
-| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图指导后续 Phase |
-| roadmap 完成，phase=pending | `/maestro-analyze` | 准备开始分析阶段 |
-| analyze 完成 | `/maestro-plan` | 分析完成，进入规划 |
+| init 完成，无上游 context | `/maestro-brainstorm` 或 `/maestro-analyze "topic"` | 先探索再规划；brainstorm 用于发散，analyze 宏观用于代码库分析 |
+| analyze 完成，scope_verdict=large | `/maestro-roadmap --from analyze:ANL-xxx` | 大范围需求，需要 Milestone > Phase 分解 |
+| analyze 完成，scope_verdict=medium/small | `/maestro-plan --from analyze:ANL-xxx` | 跳过 roadmap，直接规划（Path C） |
+| roadmap 完成，phase=pending | `/maestro-analyze 1` | 微观分析：Phase 级深入探索 |
+| analyze (微观) 完成 | `/maestro-plan 1` | Phase 级规划 |
 | plan 完成 | `/maestro-execute` | 规划完成，开始执行 |
 | execute 完成 | `/maestro-verify` | 执行完成，验证成果 |
 | verify 有 gaps | `/maestro-analyze --gaps` | 发现差距，重新分析 |

package/.agents/skills/maestro-help/phases/03-workflow-guide.md

@@ -33,36 +33,46 @@ const taskPatterns = [
 
 #### Step 4.2: 推荐工作流
 
-**新项目** (复杂度: 高):
+**新项目 — Path A** (复杂度: 高):
 
 ```markdown
 ## 新项目工作流
 
-### 路径 1: 最简路径（适合快速启动）
-1. `/maestro-init` — 初始化 .workflow/ 目录
-2. `/maestro-roadmap "项目目标" -y` — 生成路线图
-3. 按里程碑执行: analyze → plan → execute → verify
+### 路径 A: 完整新项目
+1. `/maestro-brainstorm "项目描述"` — 发散探索，多角色创意
+2. `/maestro-blueprint` — (可选) 7-phase 正式规格文档化
+3. `/maestro-init --from brainstorm:ID`
+4. `/maestro-analyze "topic"` — 宏观分析，探索影响面 → scope_verdict
+5. `/maestro-roadmap --from analyze:ANL-xxx` — 纯编排，Milestone > Phase 分解
+6. `/maestro-analyze 1` — 微观分析，Phase 级深入
+7. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
 
-### 路径 2: 从头脑风暴开始（适合需要创意探索）
-1. `/maestro-brainstorm "项目描述"` — 多角色头脑风暴
-2. `/maestro-init --from-brainstorm ANL-xxx` — 基于分析初始化
-3. `/maestro-roadmap "创建路线图" -y`
+### 路径 E: 纯规格文档（不进执行链）
+1. `/maestro-blueprint "project idea"` — 供人阅读和决策
 
-### 路径 3: 完整规范链（适合大型项目）
-1. `/maestro-init`
-2. `/maestro-spec-generate` — 7 阶段规范生成
+### 路径 F: 纯探索（不进执行链）
+1. `/maestro-brainstorm "idea"` — 供人决策
 ```
 
-**功能开发** (复杂度: 中):
+**旧项目大功能 — Path B** (复杂度: 高):
 
 ```markdown
-## 功能开发工作流
+## 旧项目大功能工作流
 
-### 主干管线（标准流程）
-1. `/maestro-analyze [phase]` — 分析需求和现有代码
-2. `/maestro-plan [phase]` — 生成执行计划
-3. `/maestro-execute [phase]` — 执行实现
-4. `/maestro-verify [phase]` — 验证成果
+1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=large
+2. `/maestro-roadmap --from analyze:ANL-xxx` — Milestone > Phase 分解
+3. `/maestro-analyze 1` — 微观分析
+4. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
+```
+
+**中等功能 — Path C** (复杂度: 中，跳过 roadmap):
+
+```markdown
+## 中等功能工作流
+
+1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=medium
+2. `/maestro-plan --from analyze:ANL-xxx` — 直达规划，跳过 roadmap
+3. `/maestro-execute` → `/maestro-verify`
 
 ### 快速渠道（简单功能）
 1. `/maestro-quick "功能描述"` — 一键完成
@@ -71,13 +81,22 @@ const taskPatterns = [
 1. `/maestro -y "功能描述"` — 自动选择并执行完整流程
 ```
 
-**Bug 修复** (复杂度: 低-中):
+**小改动 — Path D** (复杂度: 低):
 
 ```markdown
-## Bug 修复工作流
+## 小改动工作流
+
+1. `/maestro-plan "fix auth bug"` — 直接规划
+2. `/maestro-execute` → `/maestro-verify`
 
 ### 快速修复（已知问题）
 1. `/maestro-quick "修复 Bug 描述"`
+```
+
+**Bug 追踪** (Issue 闭环):
+
+```markdown
+## Bug 追踪工作流
 
 ### Issue 闭环（需要追踪）
 1. `/manage-issue-discover by-prompt "问题描述"` — 发现 Issue
@@ -109,7 +128,10 @@ const taskPatterns = [
 对需要全景视角的用户，展示 Mermaid 图：
 
 ```
-主干管线: analyze → plan → execute → verify → quality (review/test) → milestone-audit → milestone-complete
+上游起源: brainstorm(发散) | blueprint(收敛) → 可选
+理解层:   analyze "topic"(宏观) → scope_verdict 路由
+编排层:   roadmap(可选，仅 scope_verdict=large 时建议)
+执行层:   plan → execute → verify → quality → milestone-audit → milestone-complete
 快速渠道: maestro-quick → (直接完成)
 Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
 全自动: /maestro -y → (自动路由)
@@ -122,11 +144,16 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 ```markdown
 ## 核心概念
 
-- **Milestone**: 项目阶段，包含多个 Phase
-- **Phase**: 单个工作单元，走 analyze → plan → execute → verify 生命周期
+- **Roadmap**: 项目级常驻规划文档，包含多个 Milestone
+- **Milestone**: 可独立交付的版本节点（v0.1.0-rc1），包含多个 Phase
+- **Phase**: Milestone 内的同步屏障执行阶段，走 analyze → plan → execute → verify 生命周期
+- **Task**: Phase 内的具体代码修改单元（wave DAG 管理并行）
+- **Blueprint**: 正式规格文档化命令（7-phase 收敛），与 brainstorm 并列作为上游起源
+- **Analyze 双层**: 宏观(文本参数)探索影响面产出 scope_verdict；微观(数字参数)Phase 级深入分析
+- **scope_verdict**: analyze 宏观完成后的路由建议 — large→roadmap, medium/small→直达 plan
 - **Overlay**: 非侵入式命令补丁，扩展命令行为而不修改源文件
 - **Delegate**: 将子任务委派给外部 AI 工具（Gemini/Claude/Codex）
-- **Spec**: 项目规范，自动注入到工作流中作为约束
+- **Spec**: 项目约束规则（coding/arch/debug/test），自动注入到工作流
 - **Wiki**: 知识图谱，存储详细技术文档
 - **Ralph**: 自适应决策引擎，动态调整执行链
 ```
@@ -146,14 +173,14 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 |---|------|------|---------|
 | 1 | `/maestro` | 智能协调器 | 不确定用哪个命令时，告诉它你的目标 |
 | 2 | `/maestro-init` | 初始化项目 | 首次使用，创建 .workflow/ 结构 |
-| 3 | `/maestro-roadmap` | 生成路线图 | 初始化后，规划里程碑 |
-| 4 | `/maestro-analyze` | 分析 | 开始一个 Phase 的分析 |
-| 5 | `/maestro-plan` | 规划 | 分析完成后，生成执行计划 |
-| 6 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
-| 7 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
-| 8 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
-| 9 | `/quality-review` | 代码审查 | 执行后进行质量检查 |
-| 10 | `/manage-issue` | Issue 管理 | 追踪和解决 Bug |
+| 3 | `/maestro-brainstorm` | 头脑风暴 | 新项目发散探索、多角色创意 |
+| 4 | `/maestro-blueprint` | 规格文档化 | 正式 7-phase 收敛规格链 |
+| 5 | `/maestro-analyze` | 双层分析 | 宏观: `"topic"` 探索影响面；微观: `1` Phase 级深入 |
+| 6 | `/maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
+| 7 | `/maestro-plan` | 规划 | 分析完成后生成执行计划，支持 `--from analyze:ANL-xxx` 直达 |
+| 8 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
+| 9 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
+| 10 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
 ```
 
 #### Step 5.2: 快速入门路径

package/.agents/skills/maestro-init/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-init
 description: Initialize project with auto state detection
-argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
+argument-hint: "[-y] [--from <source>]"
 allowed-tools:
   - read_file
   - write_file
@@ -27,7 +27,7 @@ Initialize a new project through auto state detection and unified flow. Invoked
 <context>
 **Flags:**
 - `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
-- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
+- `--from <source>` -- Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm`
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
@@ -65,7 +65,7 @@ Other commands:
 |------|----------|-----------|----------|
 | E001 | error | No arguments provided when -y requires @ reference | Check arguments format, re-run with correct input |
 | E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
-| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
+| E003 | error | Context source not found (--from / --from-brainstorm) | Check arguments format, re-run with correct input |
 | W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
 </error_codes>
 

package/.agents/skills/maestro-milestone-audit/SKILL.md

@@ -36,8 +36,10 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 
 **Data source:**
 - `.workflow/state.json` — artifacts[], current_milestone, milestones[]
-- `.workflow/roadmap.md` — milestone-to-phase mapping
+- `.workflow/roadmap.md` — milestone-to-phase mapping (standard milestones only)
 - Plan scratch dirs — for task status verification
+
+**Adhoc milestone support (D-008):** When the target milestone has `type == "adhoc"` (or `type` field is missing, defaulting to `"standard"`), the audit skips roadmap.md parsing and phase coverage checks. It only validates artifact chain completeness (PLN→EXC exists) and runs integration checks.
 </context>
 
 <execution>
@@ -61,8 +63,8 @@ Audit checklist steps (phase coverage, ad-hoc completeness, execution completene
 </error_codes>
 
 <success_criteria>
-- [ ] All phases in milestone identified from roadmap
-- [ ] Artifact chains verified (ANL→PLN→EXC) per phase
+- [ ] All phases in milestone identified from roadmap (standard) or milestone_obj.phases (adhoc)
+- [ ] Artifact chains verified: ANL→PLN→EXC per phase (standard) or PLN→EXC exists (adhoc)
 - [ ] Ad-hoc artifacts checked for completion
 - [ ] Integration check completed (shared interfaces, data contracts)
 - [ ] Audit report written with clear PASS/FAIL verdict

package/.agents/skills/maestro-milestone-complete/SKILL.md

@@ -28,8 +28,8 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 **Requires:** `/maestro-milestone-audit` should have passed.
 
 **State files:**
-- `.workflow/state.json` — artifacts[], milestones[], current_milestone, milestone_history[]
-- `.workflow/roadmap.md` — milestone structure
+- `.workflow/state.json` — artifacts[], milestones[] (with `type` field: `"standard"` | `"adhoc"`), current_milestone, milestone_history[]
+- `.workflow/roadmap.md` — milestone structure (standard milestones only; adhoc milestones may not have roadmap)
 - `.workflow/milestones/{milestone}/audit-report.md` — audit results
 </context>
 
@@ -54,8 +54,10 @@ If user confirms promotion, invoke `invoke_skill({ skill: "spec-add", args: "<ca
 
 **Next-step routing on completion:**
 - Cut a release → `/maestro-milestone-release`
-- Next milestone → `/maestro-analyze` or `/maestro-plan 1`
+- Next milestone → `/maestro-analyze` or `/maestro-plan 1` (standard milestones only)
 - View state → `/manage-status`
+
+**Adhoc milestone (D-008):** When completing an adhoc milestone, skip roadmap snapshot and do not advance to next milestone. Set `current_milestone = null`, `status = "idle"`. Adhoc milestones are self-contained — no successor in roadmap chain.
 </execution>
 
 <error_codes>
@@ -71,7 +73,7 @@ If user confirms promotion, invoke `invoke_skill({ skill: "spec-add", args: "<ca
 - [ ] Scratch artifacts moved to milestones/{M}/artifacts/
 - [ ] Artifact entries archived to milestone_history
 - [ ] Knowhow extracted to specs/learnings.md
-- [ ] state.json updated: next milestone as current, artifacts[] cleared
-- [ ] Roadmap snapshot saved
+- [ ] state.json updated: next milestone as current (standard) or current_milestone=null (adhoc), artifacts[] cleared
+- [ ] Roadmap snapshot saved (standard only; adhoc skips)
 - [ ] project.md Context updated with milestone summary
 </success_criteria>

package/.agents/skills/maestro-plan/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-plan
 description: Use when creating, revising, or verifying an execution plan for a phase or task
-argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]"
 allowed-tools:
   - read_file
   - write_file
@@ -41,12 +41,22 @@ $ARGUMENTS — phase number, or no args for milestone-wide planning, with option
 Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
 
 **Command-level flags** (extensions beyond workflow base):
+- `--from <source>`: Load upstream context directly (bypasses roadmap requirement):
+  - `analyze:ANL-xxx` → CONTEXT_DIR = artifact path, scope = "standalone"
+  - `blueprint:BLP-xxx` → CONTEXT_DIR = blueprint path, scope = "standalone"
+  - `@file` or `path/` → load context-package.json from path
 - `--revise [instructions]` -- See workflow plan.md § Revise Mode
 - `--check <plan-dir>` -- See workflow plan.md § Check Mode
 
-**Upstream context:**
-- Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
-- Reads `conclusions.json` if available (implementation_scope seeds task generation)
+**Upstream context (resolution priority):**
+1. `--from analyze:ANL-xxx` → uses analyze conclusions.implementation_scope directly
+2. `--from blueprint:BLP-xxx` → uses blueprint requirements + architecture
+3. `--dir <path>` → explicit context directory (unchanged)
+4. Numeric arg → scope = "phase", resolve from roadmap (unchanged)
+5. No args + roadmap → scope = "milestone" (unchanged)
+6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone
+
+**Ad-hoc milestone (D-008):** When scope resolves to "standalone" and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
 
 ### Role Knowledge
 `maestro wiki list --category arch` → select relevant → `maestro wiki load`