maestro-flow 0.4.11 → 0.4.13

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

@@ -21,7 +21,7 @@ Since `.workflow/` is gitignored, this command explicitly copies project context
 
 Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
 
-Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree.
+Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree, and writes a scoped `state.json` inside the worktree containing only the forked milestone's artifacts.
 </purpose>
 
 <required_reading>

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

@@ -79,10 +79,11 @@ Read `.workflow/config.json`. If file missing, initialize with empty guard secti
 - Write config
 
 **`deny <path>`:**
-- Normalize path to forward slashes
+- Normalize path to forward slashes, ensure trailing slash for directories
+- If `guard.mode` is `allow`, switch to `deny` and clear paths with warning
 - Set `guard.mode = "deny"`
 - Add path to `guard.paths` (deduplicate)
-- Set `guard.enabled = true` if not already
+- Set `guard.enabled = true` if not already (symmetric with `allow`: adding a deny path auto-enables the guard)
 - Write config
 
 **Step 4: Confirm**

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

@@ -49,7 +49,7 @@ Single source of truth: **[index/catalog.json](index/catalog.json)**
 
 | Field | Purpose |
 |-------|---------|
-| `commands[]` | 55 个 slash 命令，含分类和描述 |
+| `commands[]` | 56 个 slash 命令，含分类和描述 |
 | `skills[]` | 10 个 Skill，含分类和描述 |
 | `agents[]` | 22 个 Agent，含分类和描述 |
 | `cli_commands[]` | 21 个终端命令 |
@@ -177,24 +177,25 @@ $ARGUMENTS → Parse:
 
 ## Command Catalog Quick Reference
 
-### 核心工作流 (core)
+### 上游起源 + 核心 (core)
 
 | 命令 | 用途 |
 |------|------|
 | `/maestro` | 智能协调器，自动路由 |
 | `/maestro-init` | 项目初始化 |
-| `/maestro-roadmap` | 路线图生成 |
+| `/maestro-brainstorm` | 头脑风暴 — 发散探索，多角色创意 |
+| `/maestro-blueprint` | 正式规格文档化 — 7-phase 收敛规格链 |
+| `/maestro-roadmap` | 路线图编排 — 消费上游 context，纯 Milestone > Phase 分解 |
 | `/maestro-quick` | 快速任务 |
-| `/maestro-brainstorm` | 头脑风暴 |
 | `/maestro-overlay` | Overlay 管理 |
 | `/maestro-amend` | 修正补丁 |
 
-### Phase 管线 (pipeline)
+### 理解层 + 执行管线 (pipeline)
 
 | 命令 | 用途 |
 |------|------|
-| `/maestro-analyze` | 多维分析 |
-| `/maestro-plan` | 任务规划 |
+| `/maestro-analyze` | 双层分析 — 宏观(文本参数)探索影响面 / 微观(数字参数)Phase 级深入 |
+| `/maestro-plan` | 任务规划 — 支持 `--from analyze:ANL-xxx` 直达 |
 | `/maestro-execute` | 任务执行 |
 | `/maestro-verify` | 验证确认 |
 
@@ -222,11 +223,44 @@ $ARGUMENTS → Parse:
 
 ## Workflow Mapping
 
-| 任务类型 | 推荐工作流 | 命令序列 |
-|---------|-----------|---------|
-| 新项目 | 初始化路径 | `/maestro-init` → `/maestro-roadmap` |
-| 正常开发 | 主干管线 | `/maestro-analyze` → `/maestro-plan` → `/maestro-execute` → `/maestro-verify` |
-| 快速修复 | 快速渠道 | `/maestro-quick "修复描述"` |
+### 层级模型
+
+```
+Roadmap > Milestone > Phase > Task
+```
+
+- **Roadmap** = 项目级常驻规划文档
+- **Milestone** = 可独立交付的版本节点（v0.1.0-rc1, v0.2.0）
+- **Phase** = Milestone 内的同步屏障执行阶段
+- **Task** = Phase 内的具体代码修改单元（wave DAG 管理并行）
+
+### 命令拓扑
+
+```
+上游起源层（并列，可选）
+  brainstorm（发散/轻量）  |  blueprint（收敛/重型）
+
+理解层
+  analyze 双层: 宏观(文本参数) → scope_verdict | 微观(数字参数) → Phase 级决策
+
+编排层（可选）
+  roadmap — 消费上游 context，纯 Milestone > Phase 分解
+
+执行层
+  plan → execute → verify
+```
+
+### 合法路径
+
+| 路径 | 场景 | 命令序列 |
+|------|------|---------|
+| Path A | 完整新项目 | `brainstorm` → `blueprint`(可选) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
+| Path B | 旧项目大功能 | `analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
+| Path C | 中等功能 | `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` → `verify` |
+| Path D | 小改动 | `plan "fix auth bug"` → `execute` → `verify` |
+| Path E | 纯规格文档 | `blueprint "project idea"` → (供人阅读) |
+| Path F | 纯探索 | `brainstorm "idea"` → (供人决策) |
+| 快速修复 | 已知简单问题 | `/maestro-quick "修复描述"` |
 | Bug 追踪 | Issue 闭环 | `/manage-issue-discover` → `/manage-issue create` → analyze/plan/execute → close |
 | 全自动 | /maestro 入口 | `/maestro -y "任务描述"` |
 | 代码审查 | 质量管线 | `/quality-review` → `/quality-auto-test` → `/quality-test` |
@@ -258,9 +292,9 @@ $ARGUMENTS → Parse:
 
 ## Statistics
 
-- **Slash 命令**: 55 个（7 个分类）
+- **Slash 命令**: 56 个（7 个分类）
 - **CLI 命令**: 21 个
 - **Skills**: 10 个（3 个分类）
 - **Agents**: 22 个（5 个分类）
 - **Guide 文档**: 17 个
-- **工作流**: 4 个主要模板
+- **工作流路径**: 6 个合法路径 (Path A-F) + 3 个辅助流程

package/.agents/skills/maestro-help/index/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"},
@@ -149,16 +150,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"],
@@ -176,9 +194,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/.agents/skills/maestro-help/phases/01-parse-intent.md

@@ -59,7 +59,7 @@ const commandPrefixes = ["/", "maestro-", "manage-", "quality-", "spec-", "learn
 // Known command names from catalog (without prefix)
 const knownCommands = [
   "maestro", "analyze", "plan", "execute", "verify", "init", "roadmap",
-  "brainstorm", "quick", "overlay", "amend", "fork", "merge", "collab",
+  "brainstorm", "blueprint", "quick", "overlay", "amend", "fork", "merge", "collab",
   "milestone-audit", "milestone-complete", "milestone-release",
   "composer", "player", "ralph", "ralph-execute", "learn",
   "impeccable", "ui-codify", "update",

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-impeccable/SKILL.md

@@ -76,6 +76,8 @@ responsive-design.md, spatial-design.md, typography.md, ux-writing.md
 
 ## Chains
 
+Chain step names below reuse Command Routing names but resolve through the chain runner. To avoid ambiguity with Direct command invocation, internal display, todo items, and session status records always tag chain steps with the `impeccable:` prefix (e.g. `impeccable:craft`, `impeccable:critique`). The bare names in this table refer to the workflow file at `~/.maestro/workflows/impeccable/{name}.md` that the chain step reads.
+
 | Chain | Steps | Scenario |
 |-------|-------|----------|
 | build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | New from scratch |
@@ -183,17 +185,17 @@ Before reading any command workflow:
 ## Chain Execution
 
 1. Prerequisites ✓
-2. **Display chain preview**: parse chain definition, output full step preview:
+2. **Display chain preview**: parse chain definition, output full step preview (chain steps prefixed `impeccable:` to disambiguate from Direct commands):
    ```
    ── Chain: build ──────────────────────────
-    1. teach        (conditional: PRODUCT.md missing)
-    2. explore      (conditional: DESIGN.md missing)
-    3. shape
-    4. craft
-    5. critique     ◆ quality gate (threshold: 26/40)
-    6. [refine]     ↺ auto-fix loop (max: 3)
-    7. audit        ◆ quality gate (threshold: 14/20)
-    8. polish
+    1. impeccable:teach        (conditional: PRODUCT.md missing)
+    2. impeccable:explore      (conditional: DESIGN.md missing)
+    3. impeccable:shape
+    4. impeccable:craft
+    5. impeccable:critique     ◆ quality gate (threshold: 26/40)
+    6. impeccable:[refine]     ↺ auto-fix loop (max: 3)
+    7. impeccable:audit        ◆ quality gate (threshold: 14/20)
+    8. impeccable:polish
    ─────────────────────────────────────────
    Target: {target}
    ```
@@ -207,9 +209,9 @@ Before reading any command workflow:
      "gate_history": [], "loop_count": 0, "status": "running" }
    ```
 4. **track_tasks init**: create todo items for all chain steps
-   - One item per step, format: `[chain] step N: {command} — {description}`
+   - One item per step, format: `[chain] step N: impeccable:{command} — {description}` (use `impeccable:` prefix to disambiguate from Direct command items)
    - If conditional step is skipped, immediately mark completed
-   - Quality gate steps include threshold: `[chain] step 5: critique ◆ gate ≥26/40`
+   - Quality gate steps include threshold: `[chain] step 5: impeccable:critique ◆ gate ≥26/40`
 5. For each step:
    - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
    - **Step start**: track_tasks marks current step in_progress

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-milestone-release/SKILL.md

@@ -46,7 +46,7 @@ $ARGUMENTS -- optional explicit version string and flags.
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/release.md' completely.
+Follow '~/.maestro/workflows/milestone-release.md' completely.
 
 **High-level flow:**
 1. Validate preconditions (milestone completed, clean tree, audit PASS)

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,24 @@ $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" via the standard standalone resolution (no `--from` source), 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".
+
+**Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".
 
 ### Role Knowledge
 `maestro wiki list --category arch` → select relevant → `maestro wiki load`