maestro-flow 0.4.18 → 0.4.20

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

@@ -0,0 +1,116 @@
+---
+name: maestro-grill
+description: Use when stress-testing a plan, idea, or requirement against codebase reality before brainstorming
+argument-hint: "<topic|plan> [-y] [-c] [--from <source>] [--depth shallow|standard|deep]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Socratic stress-testing of a plan, idea, or requirement against codebase reality. Walks every branch of the decision tree one question at a time — challenging vague terminology against existing code, probing edge cases with concrete scenarios, and verifying assumptions with code evidence. Produces a verified context package (grill-report.md + terminology.md + context-package.json) for downstream brainstorm/analyze/roadmap consumption.
+
+Positioned BEFORE brainstorm in the pipeline: grill stress-tests and sharpens; brainstorm generates and elaborates.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/grill.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstream input.
+
+**Mode selection:**
+- **Interactive mode** (default): Topic text triggers full Socratic grilling with user Q&A
+- **Auto mode** (`-y`): Code exploration answers questions instead of the user
+- **Resume mode** (`-c` or `--session ID`): Continue from a previous grill session
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — CLI exploration replaces human answers
+- `-c` / `--continue`: Resume from last grill session
+- `--session ID`: Resume specific session
+- `--depth shallow|standard|deep`: Branch count 3/5/8 (default: standard)
+- `--from <source>`: Load upstream material (`blueprint:ID`, `@file`, or path)
+
+**Output directory**: `.workflow/scratch/{YYYYMMDD}-grill-{slug}/`
+**Produced files**: `grill-report.md`, `terminology.md`, `context-package.json`
+
+### Role Knowledge
+`maestro wiki search "{topic keywords}"` → load relevant entries before grilling.
+`maestro spec load --category arch` → load architecture constraints.
+</context>
+
+<interview_protocol>
+Grill the user relentlessly until every branch of the decision tree is walked. This is NOT a menu-driven interview — it is adversarial Socratic questioning. Active only in interactive mode; skip when `-y/--yes` or `-c/--continue`.
+
+Core protocol:
+- **One question per turn**. Each question probes ONE specific aspect. Never ask compound questions.
+- **Code-grounded**: Before asking, search the codebase for evidence. Use findings to sharpen the question or challenge the user's answer. Never ask what code can verify — search first, then confront.
+- **Escalating depth**: Start with scope boundaries, progress to data model, edge cases, failure modes. Each branch goes basic → specific → adversarial.
+- **Immediate writeback**: After each answered question, immediately append the Q&A + decision to `grill-report.md`. Do NOT batch — partial progress must be on disk before the next question.
+- **Challenge contradictions**: If an answer conflicts with code evidence or a prior answer, immediately surface the contradiction and demand resolution.
+- **Terminology enforcement**: When the user uses a term that conflicts with codebase naming, challenge it immediately. Propose the code-consistent alternative. Update `terminology.md` as terms crystallize.
+
+Question framing rules:
+- Reference specific code findings: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
+- Use concrete scenarios: "What happens when a user does {action} while {condition} is true?"
+- Probe boundaries: "You said {X} is in scope — does that include {edge_case}, or is that separate?"
+- Challenge scale: "This touches `{table}` — at 10x current data volume, which query breaks first?"
+
+Branch walking order: Scope & Boundaries → Data Model & State → Edge Cases & Failure Modes → Integration & Dependencies → Scale & Performance → Security & Access Control → Observability & Operations → Migration & Rollback. Number of branches determined by `--depth`.
+
+Exit: When all depth-selected branches are fully walked (every question answered or explicitly deferred), finalize the report and generate context-package.json.
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/grill.md' completely.
+
+**Next-step routing on completion:**
+
+Standard routing:
+- Need multi-role elaboration → invoke_skill({ skill: "maestro-brainstorm", args: "{topic} --from grill:{artifact_id}" })
+- Need deep technical analysis → invoke_skill({ skill: "maestro-analyze", args: "{topic} --from grill:{artifact_id}" })
+- Scope is clear, ready for roadmap → invoke_skill({ skill: "maestro-roadmap", args: "--from grill:{artifact_id}" })
+- Need formal spec package → invoke_skill({ skill: "maestro-blueprint", args: "--from grill:{artifact_id}" })
+
+Resume routing:
+- More branches to walk → invoke_skill({ skill: "maestro-grill", args: "{topic} -c" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No topic/plan and no --from/--continue flag | Prompt user for topic text |
+| E002 | error | --session ID not found | Show available sessions |
+| W001 | warning | Codebase scan failed or returned empty | Continue without code grounding, note limitation |
+| W002 | warning | CLI exploration timeout in auto mode | Skip question, mark as open |
+| W003 | warning | Max branch depth reached without resolution | Force synthesis, offer continuation |
+</error_codes>
+
+<success_criteria>
+- [ ] Interactive mode: all depth-selected branches walked (shallow=3, standard=5, deep=8)
+- [ ] Each branch has >= 2 question-answer pairs with evidence or explicit user input
+- [ ] `grill-report.md` written with Branch Log table, all Q&A entries, synthesis section
+- [ ] `terminology.md` written with >= 5 terms, code references where applicable
+- [ ] Every locked decision has evidence (code reference or explicit user confirmation)
+- [ ] Contradictions between answers and code surfaced and resolved (or logged as risks)
+- [ ] Risk register captures all unresolved tensions
+- [ ] `context-package.json` generated with schema "context-package/1.0"
+- [ ] Artifact registered in state.json (type=grill, id=GRL-xxx)
+- [ ] Session sealed via finish-work
+</success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=grill, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
+</on_complete>

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

@@ -14,70 +14,114 @@ allowed-tools:
 
 
 <purpose>
-单链推荐：根据用户输入意图，从 `.claude/commands/` 命令池中挑选**最匹配的单个命令**，确认后通过 `invoke_skill()` 执行。
+单链推荐：解析 intent + project state → 路由表评分 → 推荐**单个原子命令** → 确认后通过 `invoke_skill()` 执行。
 
-与 `/maestro` / `/maestro-ralph` 的区别：
-- `/maestro`、`/maestro-ralph`、`/maestro-ralph-execute`、`/maestro-ralph-beta`、`/maestro-player`、`/maestro-composer` 是**多步管线编排器**，本命令不会推荐它们
-- 本命令始终只推荐 **1 个原子命令**（top pick），最多列出 2-3 个备选；选定后直接执行，无 session、无 chain
-- 适用场景：用户意图清晰、只需单步即可完成；或不确定该走哪个具体命令时获取定向推荐
+与 `/maestro` / `/maestro-ralph` 区别：
+- 不创建 session、不构建 chain、不写 status.json
+- 始终只推 1 个 top pick，最多列 2-3 个备选
+- 适用场景：意图清晰且单步即可完成；或需要定向推荐时
 </purpose>
 
 <context>
-$ARGUMENTS — 用户意图文本 + 可选 flags。
+$ARGUMENTS — 意图文本 + 可选 flags。
 
 **Flags:**
-- `-y` / `--yes` — 自动模式：跳过确认，直接执行 top pick
+- `-y` / `--yes` — 跳过确认，直接执行 top pick
 - `--dry-run` — 仅显示推荐结果，不执行
-- `--top N` — 显示前 N 个候选供选择（默认 3）
+- `--top N` — 显示前 N 个候选（默认 3）
 - `--list` — 仅列出可推荐命令池，不做推荐
 
-**候选池：** 仅 Step 3 路由表中列出的命令参与推荐。表中未出现的命令（含管线编排器 `maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer` 等）不会被本命令推荐。
+**候选池：** 仅 A_SCORE_CANDIDATES 路由表中列出的命令。管线编排器（`maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer`）**永远不在候选池**。
 </context>
 
-<execution>
+<invariants>
+1. **不创建 session / 不写 status.json / 不触发后续 chain** — 单次原子执行，产出由目标命令自行管理
+2. **管线编排器不在候选池** — 仅推荐原子命令
+3. **空 intent 或 "继续/下一步/next/接下来"** → 直接采用 lifecycle_position 推断的自然下一步
+4. **字面命中路由表优先** — lifecycle 仅作加分；命中失败时 lifecycle 上升为决定性信号
+5. **参数传递** — 默认 intent 原文作为第一个 arg；用户可在确认环节修改；`-y` 仅当用户传入时透传到 skill args
+6. **`--list` 模式跳过 lifecycle 推断与评分**，仅按 workflow 簇分组列出全部候选
+</invariants>
 
-### Step 1: Parse Arguments
+<state_machine>
 
-解析 `-y` / `--dry-run` / `--top N` / `--list`，剩余文本作为 `intent`。
+<states>
+S_PARSE     — 解析 ARGUMENTS、提取 flags                       PERSIST: —
+S_STATE     — 读 project state、推断 lifecycle_position         PERSIST: —
+S_RANK      — 路由表评分、生成 top-N candidates                 PERSIST: —
+S_LIST      — `--list` 模式：分组展示候选池                     PERSIST: —
+S_PRESENT   — 显示 top pick + 备选 + 推荐理由 + 执行参数        PERSIST: —
+S_CONFIRM   — ask_user 选择/修改参数（auto_mode 跳过）    PERSIST: —
+S_EXECUTE   — `invoke_skill({ skill, args })` 单次调用                 PERSIST: —
+S_FALLBACK  — intent 空且 clarification 失败                    PERSIST: —
+</states>
 
-- `--list` 模式 → 跳到 Step 3（仅列表）
-- `intent` 为空且非 `--list` → `ask_user`：让用户输入意图（最多 1 轮，仍空则 E001）
+<transitions>
 
-### Step 2: 读取 Workflow 状态（智能推荐基础）
+S_PARSE:
+  → S_LIST       WHEN: --list flag
+  → S_STATE      WHEN: intent text present
+  → S_STATE      WHEN: keyword "continue"/"next"/"go"/"继续"/"下一步"/"接下来"
+  → S_PARSE      WHEN: no intent (max 1 clarify round)    DO: ask_user
+  → S_FALLBACK   WHEN: clarification empty
 
-读取以下项目状态，用于推断"当前生命周期位置"和"自然下一步"：
+S_STATE:
+  → S_RANK       DO: A_INFER_LIFECYCLE
 
-```bash
-# 1. 当前 phase / milestone / 最新 artifact
-cat .workflow/state.json 2>$null
+S_RANK:
+  → S_PRESENT    DO: A_SCORE_CANDIDATES
 
-# 2. 最近 artifact 目录（按 mtime 倒序，取前 3）
-ls -la .workflow/scratch/ 2>$null | head -10
+S_LIST:
+  → END          DO: 按 workflow 簇分组列出全部候选 + description
 
-# 3. 是否有进行中的 ralph/maestro session
-ls -la .workflow/.maestro/ 2>$null | head -5
-```
+S_PRESENT:
+  → END          WHEN: --dry-run
+  → S_EXECUTE    WHEN: -y / --yes
+  → S_CONFIRM    WHEN: not auto_mode
+
+S_CONFIRM:
+  → S_EXECUTE    WHEN: 用户确认 top pick / 选备选 / 改参数
+  → END          WHEN: 用户取消
+
+S_EXECUTE:
+  → END          DO: invoke_skill({ skill: <chosen>, args: <args> }) → 输出 "✅ 已执行 /<command>"
+
+S_FALLBACK:
+  → END          DO: raise E001
 
-根据读取结果推断 **lifecycle_position**（用作下一步推荐的核心信号）：
-
-| 项目状态特征 | lifecycle_position | 自然下一步 |
-|--------------|-------------------|-----------|
-| 无 `.workflow/` + 无源码 | `brainstorm` | `maestro-brainstorm` |
-| 无 `.workflow/` + 有源码 | `init` | `maestro-init` |
-| 有 state.json，无 roadmap.md，无 milestones | `analyze-macro` | `maestro-analyze` (宏观调研) |
-| 有 macro analyze artifact，无 roadmap.md | `roadmap` | `maestro-roadmap` |
-| 有 roadmap，未启动 phase | `analyze` | `maestro-analyze {phase}` |
-| 最新 artifact = `analyze` | `plan` | `maestro-plan {phase}` |
-| 最新 artifact = `plan` | `execute` | `maestro-execute {phase}` |
-| 最新 artifact = `execute` | `verify` | `maestro-verify {phase}` |
-| 最新 artifact = `verify`，passed | `review` | `quality-review {phase}` |
-| 最新 artifact = `review`，verdict=PASS | `test-gen` | `quality-auto-test {phase}` |
-| 最新 artifact = `test`，全绿 | `milestone-audit` | `maestro-milestone-audit` |
-| 当前 milestone 全部 phase 完成 | `milestone-complete` | `maestro-milestone-complete` |
-| 任一 stage 产物含 gaps/failed | `debug` | `quality-debug {gap}` |
-
-**Maestro Lifecycle 主线（核心 workflow，供推断"下一步"使用）：**
+</transitions>
 
+<actions>
+
+### A_INFER_LIFECYCLE
+
+读 project state 推断 `lifecycle_position`（核心信号）：
+
+```bash
+cat .workflow/state.json 2>$null              # phase / milestone / artifacts
+ls -la .workflow/scratch/ 2>$null | head -10  # 最近 artifact (mtime DESC)
+ls -la .workflow/.maestro/ 2>$null | head -5  # 进行中的 session
+```
+
+**项目状态 → lifecycle_position → 自然下一步：**
+
+| 项目状态 | lifecycle_position | 自然下一步 |
+|---------|-------------------|-----------|
+| 无 `.workflow/` + 无源码 | brainstorm | `maestro-brainstorm` |
+| 无 `.workflow/` + 有源码 | init | `maestro-init` |
+| 有 state.json，无 roadmap，无 milestones | analyze-macro | `maestro-analyze` (宏观调研) |
+| 有 macro analyze artifact，无 roadmap | roadmap | `maestro-roadmap` |
+| 有 roadmap，未启动 phase | analyze | `maestro-analyze {phase}` |
+| 最新 artifact = analyze | plan | `maestro-plan {phase}` |
+| 最新 artifact = plan | execute | `maestro-execute {phase}` |
+| 最新 artifact = execute | verify | `maestro-verify {phase}` |
+| verify passed | review | `quality-review {phase}` |
+| review verdict=PASS | test-gen | `quality-auto-test {phase}` |
+| 测试全绿 | milestone-audit | `maestro-milestone-audit` |
+| 当前 milestone 全 phase 完成 | milestone-complete | `maestro-milestone-complete` |
+| 任一 stage 产物含 gaps/failed | debug | `quality-debug {gap}` |
+
+**Maestro Lifecycle 主线：**
 ```
 brainstorm → blueprint → init → analyze-macro → roadmap
    → [per phase] analyze → plan → execute → verify
@@ -85,41 +129,28 @@ brainstorm → blueprint → init → analyze-macro → roadmap
    → milestone-audit → milestone-complete → milestone-release
 ```
 
-**辅助 workflow 簇**（按场景触发，非主线）：
-
-| Workflow 簇 | 触发场景 | 主推命令 |
-|-------------|---------|---------|
-| Learning | 接触新代码/未知模块 | `learn-follow` → `learn-decompose` → `learn-second-opinion` |
-| Knowledge | 提炼经验 / 沉淀知识 | `manage-harvest` → `manage-knowhow-capture` → `spec-add` |
-| Wiki 维护 | 知识图谱整理 | `manage-wiki` → `wiki-connect` → `wiki-digest` |
-| Issue 治理 | 缺陷管理 | `manage-issue-discover` → `manage-issue` |
-| 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-refresh` |
-| 重构 | 技术债积累 | `quality-refactor` → `quality-review` |
-| 发布 | 里程碑结束 | `maestro-milestone-audit` → `maestro-milestone-release` |
-| 并行开发 | 多 milestone 并行 | `maestro-fork` → ... → `maestro-merge` |
-
-### Step 2.5: Semantic Match & Rank
+### A_SCORE_CANDIDATES
 
-综合以下信号对路由表中的命令评分（高→低）：
+**评分信号**（高→低）：
 
 | 信号 | 权重 | 说明 |
 |------|------|------|
-| intent 命中路由表行的关键词 | 高 | 字面匹配主依据 |
-| **lifecycle_position 的"自然下一步"** | **高** | 当 intent 含"继续/下一步/next/接下来"或为空时，此信号上升为决定性 |
-| `name` 关键词命中 intent | 中 | 如 intent 含 "test" → quality-test/quality-auto-test 加分 |
-| Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景时触发对应簇 |
-| Recent activity 反向避免 | 低 | 刚完成的 stage 在短期内降权 |
+| intent 命中路由表关键词 | 高 | 字面匹配主依据 |
+| **lifecycle 自然下一步** | **高** | 空 intent / "继续" / "next" 时为决定性 |
+| `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
+| Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
+| Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
 
 **特殊意图处理：**
 
-| Intent 模式 | 处理 |
-|------------|------|
-| 空 / "继续" / "下一步" / "next" / "接下来怎么走" | 直接按 lifecycle_position 的"自然下一步"作为 top pick |
-| "什么状态" / "现在到哪了" / "status" | top pick = `manage-status` |
-| 字面命中路由表关键词 | 路由表优先，lifecycle 作为加分项 |
-| 无任何匹配 | top pick = lifecycle 自然下一步 + W002 警告 |
+| Intent 模式 | top pick |
+|------------|---------|
+| 空 / "继续" / "下一步" / "next" / "接下来" | lifecycle 自然下一步 |
+| "什么状态" / "现在到哪了" / "status" | `manage-status` |
+| 字面命中路由表 | 路由表优先（lifecycle 仅加分） |
+| 无任何匹配 | lifecycle 下一步 + raise W002 |
 
-**意图 → 命令路由表**（候选池等于本表 + 上方"自然下一步"建议）：
+**意图 → 命令路由表**（候选池）：
 
 | 意图关键词 | 推荐命令 |
 |-----------|---------|
@@ -150,70 +181,74 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 | fork / 分支 / 并行开发 | `maestro-fork` / `maestro-merge` |
 | 覆盖层 / overlay / amend | `maestro-overlay` / `maestro-amend` |
 
+**辅助 workflow 簇**（场景触发，非主线）：
+
+| 簇 | 触发 | 主推链路 |
+|----|------|---------|
+| Learning | 接触新代码/未知模块 | `learn-follow` → `learn-decompose` → `learn-second-opinion` |
+| Knowledge | 提炼经验 / 沉淀知识 | `manage-harvest` → `manage-knowhow-capture` → `spec-add` |
+| Wiki | 知识图谱整理 | `manage-wiki` → `wiki-connect` → `wiki-digest` |
+| Issue | 缺陷管理 | `manage-issue-discover` → `manage-issue` |
+| 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-refresh` |
+| 重构 | 技术债积累 | `quality-refactor` → `quality-review` |
+| 发布 | 里程碑结束 | `maestro-milestone-audit` → `maestro-milestone-release` |
+| 并行开发 | 多 milestone 并行 | `maestro-fork` → ... → `maestro-merge` |
+
 输出 ranked candidates，取 top N（默认 3）。
 
-### Step 3: Present & Confirm
+</actions>
+
+</state_machine>
+
+<presentation>
 
-**`--list` 模式：** 按类别（maestro / manage / quality / learn / spec / wiki / security）分组展示所有候选 + description，结束。
+### `--list` 模式
 
-**正常模式：**
+按 workflow 簇（主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行）分组展示全部候选 + description，结束。
+
+### 正常模式
 
-显示：
 ```
 🎯 推荐 (top pick): /<command-name>
    <description>
-   推荐理由: <一句话说明为什么命中>
+   推荐理由: <命中规则 + lifecycle 位置一句话>
 
 备选:
   2. /<alt-1> — <description>
   3. /<alt-2> — <description>
 
-执行参数: <args-to-pass>
+执行参数: <args>
 ```
 
-- `--dry-run` → 显示后结束
-- `-y` → 直接执行 top pick
-- 否则 → `ask_user` 让用户：执行 top pick / 选备选 / 修改参数 / 取消
-
-### Step 4: Execute
-
-通过 `invoke_skill({ skill: "<chosen-command-name>", args: "<args>" })` 执行。
+`--dry-run` 展示后结束；`-y` 直接 S_EXECUTE；否则 ask_user 提供：执行 top pick / 选备选 / 修改参数 / 取消。
 
-**参数传递：**
-- 默认把 intent 原文作为第一个参数传给目标命令
-- 若用户在 Step 3 修改了参数，使用修改后的版本
-- `-y` flag 透传给目标命令（如果目标命令支持）
+</presentation>
 
-执行完成后显示：
-```
-✅ 已执行 /<command-name>
-```
+<appendix>
 
-不创建 session、不写 status.json、不做后续 chain — 由目标命令自行管理其产出。
+### Error Codes
 
-</execution>
-
-<error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | 未提供 intent 且 clarification 后仍为空 | 提供意图描述或使用 `--list` 浏览命令池 |
-| E002 | error | 候选池为空（commands 目录不存在或无 .md 文件） | 检查 `.claude/commands/` 是否存在 |
-| E003 | error | 用户选择的命令名无法解析为有效 skill | 列出有效命令名让用户重选 |
-| W001 | warning | 多个命令得分接近（top1 与 top2 差距 < 阈值） | 强制展示前 3，让用户裁决 |
-| W002 | warning | intent 与所有候选匹配度均低 | 提示用户考虑 `/maestro` 或 `/maestro-ralph` 走管线 |
-</error_codes>
-
-<success_criteria>
+| E001 | error | intent 空且 clarification 后仍空 | 提供意图描述或使用 `--list` 浏览 |
+| E002 | error | 候选池为空（`.claude/commands/` 缺失或无 .md） | 检查 commands 目录 |
+| E003 | error | 选定命令名无法解析为有效 skill | 列出有效命令重选 |
+| W001 | warning | top1 与 top2 得分差距 < 阈值 | 强制展示前 3 让用户裁决 |
+| W002 | warning | intent 与所有候选匹配度均低 | 提示考虑 `/maestro` 或 `/maestro-ralph` 走管线 |
+
+### Success Criteria
+
 - [ ] Intent 解析 + flags 提取完成
 - [ ] 读取 `.workflow/state.json` + scratch artifacts 推断 lifecycle_position
-- [ ] 候选池等于路由表（管线编排器自然不在表中）
-- [ ] 评分综合：intent 字面匹配 + lifecycle 自然下一步 + workflow 簇 + recent activity
+- [ ] 候选池等于路由表（管线编排器不在）
+- [ ] 评分综合：intent 字面匹配 + lifecycle 下一步 + workflow 簇 + recent activity
 - [ ] 空 intent / "继续" / "下一步" → 直接采用 lifecycle 推断的下一步
-- [ ] top pick 展示时附"推荐理由"（命中规则 + lifecycle 位置）
+- [ ] top pick 展示附"推荐理由"（命中规则 + lifecycle 位置）
 - [ ] `--dry-run` 仅展示，不执行
-- [ ] `-y` 自动执行 top pick
-- [ ] 非自动模式下，用户通过 ask_user 确认或选择备选
-- [ ] 选定命令通过 `invoke_skill()` 单次调用执行
-- [ ] 不创建 session、不生成 status.json、不触发后续 chain
-- [ ] `--list` 模式按 workflow 簇（主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行）分组展示
-</success_criteria>
+- [ ] `-y` 自动执行 top pick；用户传入时透传到 skill args
+- [ ] 非自动模式通过 ask_user 确认或选备选
+- [ ] 选定命令通过单次 `invoke_skill()` 调用执行
+- [ ] 不创建 session / 不生成 status.json / 不触发后续 chain
+- [ ] `--list` 模式按 workflow 簇分组展示
+
+</appendix>

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

@@ -75,6 +75,10 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/plan.md' completely.
 
+### P3 Agent Constraint (MANDATORY)
+
+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.
+
 ### Codebase Docs Loading (P1 addition)
 
 During P1 Context Collection, after loading context files, load codebase documentation if available:

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

@@ -131,20 +131,20 @@ S_INFER:
 
 S_RESOLVE_SCOPE:
   → S_QUALITY_MODE  DO: A_RESOLVE_SCOPE_VERDICT
-                     GUARD: position ∈ {brainstorm, blueprint, init} → skip (scope_verdict = null)
+                     GUARD: position ∈ {grill, brainstorm, blueprint, init} → skip (scope_verdict = null)
 
 S_QUALITY_MODE:
   → S_PLANNING_MODE DO: A_DETERMINE_QUALITY_MODE
 
 S_PLANNING_MODE:
   → S_DECOMPOSE     DO: A_DETERMINE_PLANNING_MODE
-                     GUARD: lifecycle_position ∈ {brainstorm, blueprint, init, analyze-macro, roadmap} → skip (force independent)
+                     GUARD: lifecycle_position ∈ {grill, brainstorm, blueprint, init, analyze-macro, roadmap} → skip (force independent)
 
 S_DECOMPOSE:
   → S_BUILD_CHAIN   DO: A_DECOMPOSE_TASKS
                      GUARD: broad intent → MUST clarify boundary even if auto_confirm
                      GUARD: narrow intent → auto-derive, skip questions
-                     GUARD: position ∈ {brainstorm, blueprint, init} → skip decomposition
+                     GUARD: position ∈ {grill, brainstorm, blueprint, init} → skip decomposition
 
 S_BUILD_CHAIN:
   → S_CREATE_SESSION DO: A_BUILD_STEPS
@@ -244,6 +244,7 @@ resolve_milestone(phase_number):
 
 | Pattern | Position |
 |---------|----------|
+| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时跳过，直接 `brainstorm`**） |
 | brainstorm / 头脑风暴 / 探索 / ideate / 设计思路 | `brainstorm` |
 | blueprint / 规格 / 正式文档 / spec-generate / 7-phase | `blueprint` |
 | broad/medium intent 无数字 phase (重构/全面/重写/迁移/新功能 X) | `analyze-macro` |
@@ -264,7 +265,7 @@ resolve_milestone(phase_number):
 | `phase_is_new == true` (新 phase) | `analyze` |
 | no milestones AND no roadmap.md AND has analyze macro artifact | `roadmap` |
 | no milestones AND no roadmap.md AND no analyze artifact | `analyze-macro` |
-| `phase == null` (brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
+| `phase == null` (grill/brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
 | phase 已存在 + 无任何 artifact | `analyze` |
 | phase 已存在 + 最新 artifact = analyze | `plan` |
 | phase 已存在 + 最新 artifact = plan | `execute` |
@@ -319,7 +320,7 @@ resolve_milestone(phase_number):
 
 | Condition | Mode | Reason |
 |-----------|------|--------|
-| lifecycle_position ∈ {brainstorm, init, roadmap} | `independent` | 前期阶段不涉及多 phase 规划 |
+| lifecycle_position ∈ {grill, brainstorm, init, roadmap} | `independent` | 前期阶段不涉及多 phase 规划 |
 | `phase_is_new == true` | `independent` | 新 phase 尚无里程碑上下文 |
 | intent 显式指定 phase 编号（如 "phase 2"、"P3"） | `independent` | 用户明确针对单个 phase |
 | milestone 仅含 1 个 phase（读 state.json） | `independent` | 统一无意义 |
@@ -382,7 +383,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 
 | Stage | invoke_skill(independent) | invoke_skill(unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
-| brainstorm | `maestro-brainstorm "{intent}"` | *(same)* | — | all |
+| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**skip when auto_confirm**) |
+| brainstorm | `maestro-brainstorm "{intent}" --from grill:{grill_id}` *(if grill ran)* / `maestro-brainstorm "{intent}"` *(otherwise)* | *(same)* | — | all |
 | blueprint | `maestro-blueprint "{intent}"` | *(same)* | — | all |
 | init | `maestro-init` | *(same)* | — | all |
 | analyze-macro | `maestro-analyze "{intent}"` | *(same)* | `post-analyze-scope` | all |
@@ -407,6 +409,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 1. **起点**：从 `session.lifecycle_position` 开始
 2. **跳过已完成**：跳过当前 milestone+phase 下已有 completed artifact 的 stage（按 `session.phase` 过滤）；unified 按 milestone 过滤
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
+3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
 6. **终点硬约束**：chain 以 `milestone-complete` 结尾
@@ -743,7 +746,8 @@ decision:post-goal-audit {retry+1}
 - [ ] Phase 先于 position 解析；phase_is_new 标记写入 session
 - [ ] D-007 反查：phase 数字 → `session.milestone`，禁止读 current_milestone；写入 step.milestone_id
 - [ ] phase_is_new=true → lifecycle_position 强制 `analyze`
-- [ ] Intent overrides 识别 brainstorm / blueprint / analyze-macro
+- [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
+- [ ] auto_confirm=true 时 grill stage 跳过（交互式拷问不支持自动模式）
 - [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict，写入 session.scope_verdict + analyze_macro_id
 - [ ] 链路起点 = analyze-macro 时：large→roadmap+analyze+plan(phase)；medium/small→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
 - [ ] post-analyze-scope decision 节点在 macro analyze 之后插入；A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路