maestro-flow 0.4.11 → 0.4.12

package/.codex/skills/maestro-help/SKILL.md

@@ -42,13 +42,13 @@ $ARGUMENTS 匹配关键词 → 路由到对应模式：
 
 | 字段 | 内容 |
 |------|------|
-| `commands[]` | 55 个 slash 命令（name, command, category, description, source） |
+| `commands[]` | 56 个 slash 命令（name, command, category, description, source） |
 | `skills[]` | 10 个 Skill（name, category, description, source） |
 | `agents[]` | 22 个 Agent（name, category, description） |
 | `cli_commands[]` | 21 个终端命令（command, description, category） |
 | `guide_files[]` | 17 个 Guide 文档索引 |
 | `essential_commands[]` | 10 个核心命令 |
-| `workflows` | 4 大工作流模板（main_pipeline, quick, issue_loop, init_paths） |
+| `workflows` | 拓扑 + 6 条合法路径 (Path A-F) + 3 个辅助流程 |
 
 ## Project State Detection
 
@@ -96,7 +96,7 @@ Mode 3 (Smart Recommendations) 需要检测项目状态：
 
 Guide 映射：
 - analyze/plan/execute/verify → `guide/command-usage-guide.md`
-- init/roadmap → `guide/quick-start-guide.md`
+- init/roadmap/blueprint → `guide/quick-start-guide.md`
 - ralph → `guide/maestro-ralph-guide.md`
 - maestro (协调器) → `guide/maestro-coordinator-guide.md`
 - delegate → `guide/delegate-async-guide.md`
@@ -109,9 +109,11 @@ Guide 映射：
 | 当前状态 | 推荐命令 | 原因 |
 |---------|---------|------|
 | 无 .workflow/ | `/maestro-init` | 项目未初始化 |
-| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图 |
-| roadmap 完成 | `/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` | 重新分析 |
@@ -123,16 +125,24 @@ Guide 映射：
 
 根据任务类型推荐工作流和命令序列：
 
-**新项目**:
-- 最简: `/maestro-init` → `/maestro-roadmap "目标" -y`
-- 头脑风暴: `/maestro-brainstorm "描述"` → `/maestro-init --from-brainstorm ANL-xxx`
-- 完整规范: `/maestro-init` → `/maestro-spec-generate`
+**Path A — 完整新项目**:
+- `brainstorm` → `blueprint`(可选) → `analyze "topic"`(宏观) → `roadmap` → `analyze 1`(微观) → `plan 1` → `execute` → `verify`
 
-**功能开发**:
-- 标准: analyze → plan → execute → verify
+**Path B — 旧项目大功能**:
+- `analyze "feature X"`(宏观) → `roadmap` → `analyze 1`(微观) → `plan 1` → `execute` → `verify`
+
+**Path C — 中等功能（跳过 roadmap）**:
+- `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` → `verify`
+
+**Path D — 小改动**:
+- `plan "fix auth bug"` → `execute` → `verify`
 - 快速: `/maestro-quick "功能描述"`
 - 全自动: `/maestro -y "功能描述"`
 
+**Path E/F — 纯文档/纯探索**:
+- `blueprint "project idea"` → (供人阅读)
+- `brainstorm "idea"` → (供人决策)
+
 **Bug 修复**:
 - 快速: `/maestro-quick "Bug 描述"`
 - Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
@@ -149,14 +159,14 @@ Guide 映射：
 |------|------|---------|
 | `/maestro` | 智能协调器 | 不确定用哪个命令时 |
 | `/maestro-init` | 初始化项目 | 首次使用 |
-| `/maestro-roadmap` | 路线图 | 初始化后规划 |
-| `/maestro-analyze` | 分析 | 开始 Phase 分析 |
-| `/maestro-plan` | 规划 | 分析完成后 |
+| `/maestro-brainstorm` | 头脑风暴 | 新项目发散探索、多角色创意 |
+| `/maestro-blueprint` | 规格文档化 | 正式 7-phase 收敛规格链 |
+| `/maestro-analyze` | 双层分析 | 宏观: `"topic"` 探索影响面；微观: `1` Phase 级深入 |
+| `/maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
+| `/maestro-plan` | 规划 | 分析完成后，支持 `--from analyze:ANL-xxx` 直达 |
 | `/maestro-execute` | 执行 | 计划完成后 |
 | `/maestro-verify` | 验证 | 执行完成后 |
 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
-| `/quality-review` | 代码审查 | 执行后质量检查 |
-| `/manage-issue` | Issue 管理 | 追踪和解决 Bug |
 
 快速上手路径：
 1. `maestro install --force`
@@ -175,7 +185,7 @@ Guide 映射：
 
 - **Workflow (15)**: analyzer, planner, executor, verifier, reviewer, debugger, research-agent, roadmapper, plan-checker, phase-researcher, project-researcher, research-synthesizer, codebase-mapper, nyquist-auditor, integration-checker, external-researcher, collab-planner
 - **Team (2)**: supervisor, worker
-- **Planning (1)**: conceptual-planning-agent
+- **Brainstorm (2)**: role-design-author, cross-role-reviewer
 - **CLI (1)**: cli-explore-agent
 - **UI (1)**: ui-design-agent
 

package/.codex/skills/maestro-help/catalog.json

@@ -7,10 +7,11 @@
   "commands": [
     {"name": "maestro", "command": "/maestro", "category": "core", "description": "智能协调器 — 根据意图和项目状态自动选择最优命令链", "source": "../../commands/maestro.md"},
     {"name": "maestro-init", "command": "/maestro-init", "category": "core", "description": "项目初始化 — 创建 .workflow/ 目录结构和状态文件", "source": "../../commands/maestro-init.md"},
-    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图生成 — 基于目标创建里程碑和 Phase 分解", "source": "../../commands/maestro-roadmap.md"},
-    {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "多角色头脑风暴 — 生成分析文档和功能规格", "source": "../../commands/maestro-brainstorm.md"},
-    {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "多维度分析 — Phase 分析、CLI 辅助探索、gap 分析", "source": "../../commands/maestro-analyze.md"},
-    {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 生成执行计划、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
+    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — 消费上游 context，纯 Milestone > Phase 分解（不做技术探索）", "source": "../../commands/maestro-roadmap.md"},
+    {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "头脑风暴 — 发散探索，多角色创意，上游起源命令", "source": "../../commands/maestro-brainstorm.md"},
+    {"name": "maestro-blueprint", "command": "/maestro-blueprint", "category": "core", "description": "正式规格文档化 — 7-phase 收敛规格链，上游起源命令，产出 .workflow/blueprint/", "source": "../../commands/maestro-blueprint.md"},
+    {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "双层分析 — 宏观(文本参数)探索影响面+scope_verdict / 微观(数字参数)Phase 级深入", "source": "../../commands/maestro-analyze.md"},
+    {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 支持 --from analyze:ANL-xxx 直达、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
     {"name": "maestro-execute", "command": "/maestro-execute", "category": "pipeline", "description": "任务执行 — wave 并行执行、delegate 编排、自动提交", "source": "../../commands/maestro-execute.md"},
     {"name": "maestro-verify", "command": "/maestro-verify", "category": "pipeline", "description": "验证确认 — 成果检查、gap 发现、下一阶段建议", "source": "../../commands/maestro-verify.md"},
     {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
@@ -147,16 +148,33 @@
   "essential_commands": [
     "/maestro",
     "/maestro-init",
-    "/maestro-roadmap",
+    "/maestro-brainstorm",
+    "/maestro-blueprint",
     "/maestro-analyze",
+    "/maestro-roadmap",
     "/maestro-plan",
     "/maestro-execute",
     "/maestro-verify",
-    "/maestro-quick",
-    "/quality-review",
-    "/manage-issue"
+    "/maestro-quick"
   ],
   "workflows": {
+    "topology": {
+      "hierarchy": "Roadmap > Milestone > Phase > Task",
+      "layers": {
+        "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
+        "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
+        "orchestration": "roadmap (可选，消费上游 context)",
+        "execution": ["plan", "execute", "verify"]
+      }
+    },
+    "paths": {
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
+      "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute → verify",
+      "D_small_fix": "plan → execute → verify",
+      "E_spec_only": "blueprint → (供人阅读)",
+      "F_explore_only": "brainstorm → (供人决策)"
+    },
     "main_pipeline": {
       "name": "主干管线",
       "phases": ["analyze", "plan", "execute", "verify"],
@@ -174,9 +192,9 @@
     },
     "init_paths": {
       "name": "初始化路径",
-      "minimal": "/maestro-init → /maestro-roadmap",
-      "from_brainstorm": "/maestro-brainstorm → /maestro-init --from-brainstorm → /maestro-roadmap",
-      "full_spec": "/maestro-init → /maestro-spec-generate"
+      "from_brainstorm": "/maestro-brainstorm → /maestro-init --from brainstorm:<id> → /maestro-analyze 宏观",
+      "from_blueprint": "/maestro-blueprint → /maestro-init → /maestro-analyze 宏观",
+      "direct": "/maestro-init → /maestro-analyze 宏观"
     }
   }
 }

package/.codex/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, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -16,12 +16,12 @@ When `-y`: After config questions, run research without further interaction. Exp
 ```bash
 $maestro-init ""
 $maestro-init "-y"
-$maestro-init "--from-brainstorm 20260318-brainstorm-auth"
+$maestro-init "--from brainstorm:20260318-brainstorm-auth"
 ```
 
 **Flags**:
 - `-y`: Skip interactive questioning; extract from provided document
-- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
+- `--from <source>`: Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json. Alias: `--from-brainstorm`
 
 **Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
 
@@ -41,7 +41,7 @@ $maestro-init "--from-brainstorm 20260318-brainstorm-auth"
 
 Extract flags from arguments:
 - `-y` flag presence
-- `--from-brainstorm SESSION-ID` value
+- `--from <source>` value (or `--from-brainstorm SESSION-ID` alias)
 - Remaining text as project description
 
 ### Step 2: Detect Project State
@@ -55,7 +55,7 @@ Classify as:
 
 ### Step 3: Gather Project Information
 
-**If `--from-brainstorm`**:
+**If `--from` (or `--from-brainstorm`)**:
 - Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
 - Extract these fields from the document (match by heading or frontmatter key):
   - `## Vision` or `vision:` → project.md Core Value Proposition
@@ -132,7 +132,7 @@ If project state is **empty** (greenfield, no source files found in Step 2):
 
 ### Step 10: Completion Report
 
-Display created files and next steps: `$maestro-roadmap --mode full` (full spec), `$maestro-roadmap` (light), `$manage-status`, `$maestro-brainstorm`, `$maestro-quick`.
+Display created files and next steps: `$maestro-blueprint` (full spec), `$maestro-roadmap` (roadmap), `$manage-status`, `$maestro-brainstorm`, `$maestro-quick`.
 
 </execution>
 
@@ -142,7 +142,7 @@ Display created files and next steps: `$maestro-roadmap --mode full` (full spec)
 |------|----------|-------------|----------|
 | E001 | error | No arguments when -y requires document | Ask user for document reference |
 | E002 | error | .workflow/ already exists | Show status, suggest manage-status |
-| E003 | error | Brainstorm session not found | List available sessions |
+| E003 | error | Context source not found (--from / --from-brainstorm) | List available sessions |
 | W001 | warning | Could not detect tech stack | Continue with manual input |
 
 </error_codes>

package/.codex/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: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--dir <path>] [--gaps] [--spec SPEC-xxx] [--collab]\""
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--dir <path>] [--from <source>] [--gaps] [--spec SPEC-xxx] [--collab]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -65,14 +65,30 @@ All mean: **follow the cycle anyway**.
 <context>
 $ARGUMENTS — phase number/text and optional flags.
 
-**Flags**: `-y` (auto), `-c N` (concurrency, default 4), `--continue` (resume), `--dir <path>`, `--gaps` (issue-linked), `--spec SPEC-xxx`, `--collab`, `--revise`, `--check`, `--tdd` (RED-GREEN-REFACTOR task chains)
+**Flags**: `-y` (auto), `-c N` (concurrency, default 4), `--continue` (resume), `--dir <path>`, `--from <source>` (load upstream context directly: analyze:ANL-xxx, blueprint:BLP-xxx, brainstorm:ID, @file, path), `--gaps` (issue-linked), `--spec SPEC-xxx`, `--collab`, `--revise`, `--check`, `--tdd` (RED-GREEN-REFACTOR task chains)
 
-**Scope routing** (priority): --dir → from parent artifact; no args → milestone; digit → phase; text → adhoc/standalone.
+**Scope routing** (priority, per redesign §5.2):
+1. `--from analyze:ANL-xxx` → CONTEXT_DIR = ANL artifact path; scope=`standalone`
+2. `--from blueprint:BLP-xxx` → CONTEXT_DIR = BLP path; scope=`standalone`
+3. `--dir <path>` → CONTEXT_DIR = path; scope=`standalone`
+4. Numeric arg + roadmap → scope=`phase`; D-007 reverse-lookup milestone via `state.json.milestones[].phase_slugs`
+5. No args + roadmap → scope=`milestone` (plans all pending phases in current milestone)
+6. No args + no roadmap → search `state.json.artifacts[]` for latest `type=="analyze"` (DESC by created_at). Found → scope=`standalone`, CONTEXT_DIR = artifact.path. None → ERROR E001.
+7. Text arg + no upstream → scope=`adhoc/standalone`
+
+**D-007 milestone reverse lookup** (numeric scope only):
+```
+resolve_milestone(phase_number):
+  for ms in state.json.milestones[]:
+    if str(phase_number) in ms.phase_slugs: return ms.id
+  return state.json.current_milestone   # fallback
+```
+Write resolved milestone into PLN artifact registration and `plan.json.milestone`; NEVER read `current_milestone` directly for phase-scoped runs.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-plan-P{N}-{slug}/`
 **Scratch**: `.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/` (.task/ subdir)
 
-**Pre-load** (optional): context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro wiki search`, `maestro spec load --category arch`, team preflight `maestro collab preflight`.
+**Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro wiki search`, `maestro spec load --category arch`, team preflight `maestro collab preflight`.
 </context>
 
 <csv_schema>
@@ -110,14 +126,15 @@ S_REGISTER    — 注册 PLN artifact、更新 index.json           PERSIST: sta
 
 <transitions>
 S_PARSE → S_RESUME     WHEN: --continue
-S_PARSE → S_CONTEXT    WHEN: phase/dir resolved
-S_PARSE → ERROR        WHEN: no args and no roadmap
+S_PARSE → S_CONTEXT    WHEN: phase/dir/--from resolved (D-007 reverse lookup for numeric)
+S_PARSE → S_CONTEXT    WHEN: no args + no roadmap AND latest analyze artifact found in state.json (scope=standalone)
+S_PARSE → ERROR        WHEN: no args + no roadmap + no analyze artifact
 
 S_RESUME → S_WAVE_1    WHEN: W1 incomplete    DO: load session, resume
 S_RESUME → S_WAVE_2    WHEN: W1 done, W2 pending
 S_RESUME → S_CHECK     WHEN: W2 done, check pending
 
-S_CONTEXT → S_CSV_GEN  DO: load context.md, conclusions.json, specs, wiki, codebase docs
+S_CONTEXT → S_CSV_GEN  DO: if --from: resolve context-package.json (precedence over context.md); load context.md, conclusions.json, specs, wiki, codebase docs
 
 S_CSV_GEN → S_WAVE_1   DO: pre-flight (`maestro collab preflight --phase N`; exit 1 → warn + ask), determine exploration angles, generate tasks.csv, user validates (skip -y)
 
@@ -173,7 +190,7 @@ Collision detection against same-milestone plans.
 <error_codes>
 | Condition | Recovery |
 |-----------|----------|
-| No args and no roadmap | Provide phase number or topic |
+| No args and no roadmap and no analyze artifact in state.json | Provide phase number, topic, or run analyze first |
 | --gaps but no gap source | Run maestro-verify first |
 | Planning agent fails | Retry once with simplified context |
 | Plan-checker exceeds 3 rounds | Accept with warnings |
@@ -190,6 +207,7 @@ Collision detection against same-milestone plans.
 - [ ] Pressure pass completed on highest-complexity task
 - [ ] Collision detection against same-milestone plans (non-blocking)
 - [ ] Plan-checker passed (or minor issues acknowledged, max 3 iterations)
-- [ ] PLN artifact registered in state.json
+- [ ] PLN artifact registered in state.json (numeric scope: milestone resolved via D-007 `phase_slugs` reverse lookup, NOT direct `current_milestone` read)
+- [ ] No-args fallback honored: latest analyze artifact auto-discovered when roadmap absent (§5.2 priority 6)
 - [ ] If --gaps: issues linked bidirectionally (task_refs[], task_plan_dir in issues.jsonl)
 </success_criteria>