maestro-flow 0.5.35 → 0.5.37

package/workflows/grill.md

@@ -451,7 +451,20 @@ Write `{output_dir}/context-package.json`:
 }
 ```
 
-### 7.2: Completion Report
+### 7.2: Domain Knowledge Flow
+
+Grill 产出的领域术语通过以下路径沉淀到项目知识库：
+
+```
+terminology.md (locked terms)  ──→  finish-work Step 3.5  ──→  .workflow/domain/glossary.yaml
+context-package.json#domain.terminology[]  ──→  finish-work Step 3.5  ──→  glossary.yaml
+```
+
+- Grill 期间**不应**直接调用 `maestro domain add` — 术语在 grilling 过程中可能被修改或推翻
+- 所有术语经 Step 5 synthesis 锁定后，由 chain 末尾的 `manage-harvest --auto` 自动触发 finish-work 提取
+- finish-work Step 3.5 的 domain extraction 始终交互确认（`-y` 对 domain 注册无效）
+
+### 7.3: Completion Report
 
 ```
 Grill session {artifact_id} completed.

package/workflows/harvest.md

@@ -1,6 +1,5 @@
 # Harvest Workflow
 
-Extract knowledge from **any workflow artifact** (analysis, brainstorm, debug, lite-plan/fix, scratchpad, sessions) and route into wiki / spec / issue stores.
 
 ---
 
@@ -260,8 +259,6 @@ For each routed item, record in `.workflow/harvest/harvest-log.jsonl`:
 }
 ```
 
-This log prevents duplicate harvesting in future runs.
-
 ---
 
 ## Stage 7: dedup_check

package/workflows/impeccable/audit.md

@@ -1,7 +1,5 @@
 Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.
 
-This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
-
 ## Diagnostic Scan
 
 Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.

package/workflows/impeccable/codex.md

@@ -1,9 +1,5 @@
 # Codex: Visual Direction & Asset Production
 
-This file is loaded by `/maestro-impeccable craft` when the harness has native image generation (currently Codex via `image_gen`). Other harnesses skip it. It covers the two craft steps that depend on real image generation: landing the visual direction, and producing the raster assets the implementation will compose.
-
-Read this *before* generating any images. The order matters, and the per-step user pauses are what keep generated imagery from drifting away from the brief.
-
 ### Four stop points before code
 
 Steps A through D each end with the user. Do not advance past any of them on your own read of the situation.

package/workflows/init.md

@@ -113,6 +113,14 @@ If `.workflow/specs/` does not exist:
    - Skip spec-setup (nothing to scan)
    - Note: Specs will be progressively populated as pipeline stages produce knowledge
 
+## Step 2.5: Domain Init (first-run only)
+
+If `.workflow/domain/` does not exist:
+
+1. Run `Bash("maestro domain init")` — creates `.workflow/domain/glossary.yaml` with empty terms array
+2. If brownfield project (has source files): run `maestro domain discover --auto` to scan codebase for initial term candidates, present top 5 for confirmation
+3. If greenfield project: skip discovery (no codebase to scan); domain terms will be populated by grill/brainstorm sessions via finish-work extraction
+
 
 ---
 
@@ -126,6 +134,7 @@ Verify all required directories and files exist:
   state.json         ✓
   config.json        ✓
   specs/             ✓
+  domain/            ✓ (glossary.yaml)
   research/          ✓ (if research enabled)
   scratch/           ✓ (create empty)
   milestones/        ✓ (create empty)

package/workflows/interview-mechanics.md

@@ -3,5 +3,6 @@
 - **One decision per turn** via AskUserQuestion, 2-4 options, first marked `(Recommended)`. User can redirect via `Other`.
 - **Search-first**: resolve via state.json → session artifacts → `maestro spec/wiki` → Glob/Grep/Read → Agent(Explore) / delegate. Never ask what code can answer.
 - **Writeback**: each decision **immediately written to disk** before the next question. No batching.
-- **Skip**: auto mode (`-y`), resume (`-c`), or unambiguous input → skip entire interview.
-- **Decision table**: `| # | Decision | Choice | Source (user / code / default) |`
+- **Skip**: auto mode (`-y`) → 逐问题 Search-first 代答（不跳过整段 interview）；仅当代码给出高置信答案时跳过该问题。**例外**：broad intent 的边界澄清永不跳过（即使 `-y`）；phase 歧义永不跳过。resume (`-c`) → 跳过已答问题。unambiguous 单一答案输入 → 仅跳过该问题。
+- **Decision table**: `| # | Decision | Choice | Source (user / code / default) | Confidence (high / medium / LOW) |`
+  - `code` source：Search-first 派生（state.json / spec / Glob / Grep）。`code` + 非 broad → 可自动定；`code` + broad → 标 `LOW CONFIDENCE` 需用户确认；`default` source → 一律标 `LOW CONFIDENCE`。

package/workflows/issue-analyze.md

@@ -3,8 +3,6 @@
 > **DEPRECATED**: Superseded by `issue-gaps-analyze.md` which adds batch support and context.md output.
 > Use `maestro-analyze --gaps [ISS-ID]` instead.
 
-This workflow's executable steps have been removed to prevent divergent implementations.
-
 ## Migration
 
 | Old usage | New usage |
@@ -20,6 +18,3 @@ This workflow's executable steps have been removed to prevent divergent implemen
 - `issue-execute.md` — downstream execution after planning
 
 ## Notes
-
-- Issue records analyzed by the new pipeline still write to `.workflow/issues/issues.jsonl` with `analysis` field (root_cause, impact, related_files, confidence, suggested_approach, analyzed_at, analyzed_by).
-- Status is unchanged by analysis (non-destructive enrichment).

package/workflows/issue-discover.md

@@ -178,9 +178,9 @@ Store → .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
 ### Step 9: Gather Codebase Context
 
 ```
-Per dimension:
-  1. Semantic search via {search_tool}(query="{dimension.description}")
-  2. Pattern search via rg for each dimension.search_patterns
+Per dimension (prefer maestro explore over rg):
+  1. maestro explore "{dimension.description}" per dimension, parallel
+  2. Fallback: Semantic search via {search_tool} + rg for dimension.search_patterns
   3. Collect matching files/snippets → {SESSION_ID}/{dimension.name}-context.md
 ```
 
@@ -189,7 +189,7 @@ Per dimension:
 ```
 Up to 3 rounds (exit early if no new gaps/findings):
   Round 1: Analyze context → identify issues + coverage gaps
-  Round 2: Refine patterns for gaps → search adjacent files → merge findings
+  Round 2: maestro explore for gap patterns → search adjacent files → merge findings
   Round 3: Final sweep on uncovered high-severity patterns + cross-module interactions
 
 Log per round → {SESSION_ID}/exploration-log.md:

package/workflows/issue-gaps-analyze.codex.md

@@ -1,11 +1,5 @@
 # Workflow: Issue Gaps Analysis (Codex — CSV Wave)
 
-Root cause analysis for issues via `spawn_agents_on_csv` wave execution.
-Supports single issue (ISS-ID) or batch with classification and parallel analysis.
-Produces analysis records in issues.jsonl and context.md for downstream `plan --gaps`.
-
-**Invoked by**: `maestro-analyze --gaps [ISS-ID]` (codex SKILL.md)
-
 ## Pipeline
 
 ```
@@ -64,7 +58,7 @@ id,title,description,iss_id,group_id,group_label,deps,context_from,wave,status,f
 **Wave 1 rows** — one per issue:
 
 ```csv
-"1","Explore: ISS-xxx {title}","Root cause exploration for ISS-xxx: {description}. Location: {location}. Severity: {severity}. Fix hint: {fix_direction}. Search keywords: {keywords from title+description+components}. TASK: grep keywords → read top matches → trace call chain → identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix. EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }. CONSTRAINTS: Evidence-only, use file reads to verify.","ISS-xxx","G1","src/auth","","","1","","","",""
+"1","Explore: ISS-xxx {title}","Root cause exploration for ISS-xxx: {description}. Location: {location}. Severity: {severity}. Fix hint: {fix_direction}. Search keywords: {keywords from title+description+components}. TASK: maestro explore keywords (preferred) or grep keywords → read top matches → trace call chain → identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix. EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }. CONSTRAINTS: Evidence-only, use file reads to verify.","ISS-xxx","G1","src/auth","","","1","","","",""
 ```
 
 **Wave 2 rows** — one per group:

package/workflows/issue-gaps-analyze.md

@@ -68,10 +68,9 @@ For each group:
   Merge keywords from all issues in group: title, description, location, affected_components.
   Deduplicate keywords.
 
-  Standard depth: grep keywords in source files → top 20 paths, read 10 lines around
-    top 5 matches.
-  Deep depth: standard grep + semantic Agent search (error handling, data flow, deps),
-    merge results.
+  Standard depth: maestro explore per group (keywords as prompt), fallback grep.
+  Deep depth: maestro explore multi-prompt + semantic Agent search (error handling,
+    data flow, deps), merge results.
 
   Build GROUP_CONTEXT: related files, key snippets (max 50 lines), dependency chain.
   Shared context benefits co-located issues — avoids redundant exploration.

package/workflows/knowledge-audit.md

@@ -1,9 +1,5 @@
 # Knowledge Audit Workflow
 
-审查 spec / knowhow / artifact 三大知识存储，识别矛盾、失效、老化、孤儿，通过 keep/deprecate/delete 三态决策淘汰。
-
-与 `harvest.md` 对称：harvest 写入知识 → knowledge-audit 清理知识。与 `harvest --prune`（Stage 9）的区别：prune 做物理 GC（孤儿指针、格式损坏），audit 做语义审查（逻辑矛盾、生命周期决策）。
-
 ---
 
 ## Prerequisites

package/workflows/learn.md

@@ -1,15 +1,9 @@
 # Learn Workflow
 
-Atomic insight capture, search, and retrieval. Lightweight gstack-style "eureka moment" log that complements the retrospective workflow: where retrospective extracts insights from completed phases in bulk, `manage-learn` captures one insight at a time during active work.
-
 Storage:
 - `.workflow/specs/learnings.md` — append-only container of `<spec-entry>` sub-entries (shared with retrospective output)
 - Auto-indexed by WikiIndexer (no manual index required)
 
-**Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
-
-This workflow does NOT spawn sub-agents; it may invoke maestro CLI utilities (e.g. `maestro wiki search`, `maestro wiki list`) for list/search subcommands. The core capture flow is a thin file operation: parse → infer → append → confirm.
-
 ---
 
 ## Prerequisites

package/workflows/maestro.codex.md

@@ -1,9 +1,5 @@
 # Workflow: Maestro (Codex Edition)
 
-CSV wave coordinator version of the intelligent coordinator. Replaces `spawn_agent / wait / close_agent` loop with `spawn_agents_on_csv` (max_workers=1) for sequential pipeline execution. Each chain step is a CSV row with `skill_call` column; agents read prior results from session directory for context propagation.
-
-> Referenced by: `~/.codex/skills/maestro/SKILL.md`
-
 ---
 
 ## Step 1: Parse Arguments

package/workflows/maestro.md

@@ -1,8 +1,7 @@
 # Workflow: maestro
 
 Intelligent coordinator that routes user intent to optimal command chain based on project state.
-Two step types: **Skill** (in-process, synchronous) and **CLI** (via `maestro delegate`, async with role-based tool selection).
-Default `auto` mode selects type based on step complexity. All execution dispatched to unified executor (`maestro-ralph-execute`).
+Builds a `ralph_protocol_version: "1"` session: every executable step carries `skill,args,stage,scope,command_scope,command_path`; every cross-step gate is a `step.decision` node. All execution dispatched to unified executor (`maestro-ralph-execute`); the command body (`.claude/commands/maestro.md`) owns session build + dispatch. `--exec` is legacy input only — recorded to `legacy_options.exec_mode`, never changes execution. This brain is consumed for **classification only** (intent → task_type → chain); it does NOT prescribe execution semantics.
 
 **Prerequisites:**
 - None for initial invocation (can bootstrap)
@@ -110,6 +109,9 @@ Directly match user intent to the best `task_type` (maps to chain in chainMap).
 | `overlay` | Create/edit command overlays |
 | `update` | Update maestro itself |
 | `harvest` | Extract knowledge from artifacts |
+| `domain_add` | Register a domain term into glossary |
+| `domain_list` | List registered domain terms |
+| `domain_discover` | Discover domain term candidates from codebase |
 | `wiki` | Manage wiki graph |
 | `knowhow` | Manage knowhow entries |
 | `impeccable_chain` | UI design — explore, general |
@@ -127,6 +129,9 @@ Directly match user intent to the best `task_type` (maps to chain in chainMap).
 | `team_tech_debt` | Team tech debt remediation |
 | `team_lifecycle` | Team full lifecycle (plan+dev+test+review) |
 | `full-lifecycle` | Complete phase: plan→execute→review→test→audit |
+| `grill` | Stress-test a plan/idea against codebase reality (Socratic; `-y` → Auto mode code-answers, stage NOT skipped) |
+| `blueprint` | Formal spec package — 7-phase spec-generate |
+| `analyze-macro` | Broad/medium intent, no numeric phase — produces scope_verdict for ralph `post-analyze-scope` |
 | `brainstorm-driven` | Start from exploration/brainstorm |
 | `spec-driven` | From spec/requirements (heavy, with init) |
 | `roadmap-driven` | From requirements (light, with init) |
@@ -170,7 +175,7 @@ Display intent analysis: action, object, scope, issue_id, phase_ref, task_type,
 
 **Resolution order:**
 1. `state_continue` → `detectNextAction(projectState)` → `{ chain, argsOverride? }`. Apply argsOverride before template substitution.
-2. Task-type aliases → named chain: `spec_generate`→`spec-driven`, `brainstorm`→`brainstorm-driven`, `issue_execute`→`issue-full`
+2. Task-type aliases → named chain: `spec_generate`→`spec-driven`, `brainstorm`→`brainstorm-driven`, `grill`→`grill-driven`, `blueprint`→`blueprint-driven`, `analyze_macro`→`analyze-plan-execute`, `issue_execute`→`issue-full`
 3. `chainMap[taskType]` → direct lookup
 
 Full `chainMap` and `detectNextAction` are in the [Reference Data](#reference-data) section.
@@ -210,9 +215,9 @@ When executing issue chains, replace `{issue_id}` in step args with resolved ID.
 **If not `autoYes`:** Confirm with user — show numbered steps, offer: Execute / Execute from step N / Cancel.
 If user chooses "Execute from step N": set `$START_STEP = N` (used in 3f to set `current_step`).
 
-### 3e: Step-level type selection
+### 3e: Step-level command resolution (v1)
 
-Step type is selected **per step**, not per chain. Pre-compute and write to each step's `type` field in status.json (executor reads this, does not re-compute).
+> **Superseded by `ralph_protocol_version: "1"`.** The command body resolves `command_scope`/`command_path` per execution step via `maestro ralph skills --platform claude --json --quiet`; cross-step gates carry `step.decision`. Do NOT write a per-step `type` field (legacy skill/cli). `--exec` is recorded to `legacy_options.exec_mode` only — it never changes execution. FSM owns step ordering + decision evaluation (control-plane precedence, see command-body invariant 15).
 
 ```
 If execMode is 'cli' or 'internal' → force that type for all steps ("cli" or "skill").
@@ -287,7 +292,7 @@ status.json already created in Step 3g, TodoWrite initialized in Step 3h.
 Skill({ skill: "maestro-ralph-execute" })
 ```
 
-The unified executor discovers the latest running session from `.workflow/.maestro/*/status.json` and executes steps sequentially. For maestro sessions (source: "maestro"), there are no decision nodes — execution is purely sequential.
+The unified executor discovers the latest running session from `.workflow/.maestro/*/status.json` and executes steps in order. maestro sessions (source: "maestro") are `ralph_protocol_version: "1"`: execution steps load via `maestro ralph next`; any `step.decision` node hands off to `Skill("maestro-ralph")` for evaluation (same mechanism as ralph sessions). Decision nodes ARE supported in maestro sessions.
 
 ---
 
@@ -300,6 +305,9 @@ const chainMap = {
   // ── Single-step ──
   'status':             [{ cmd: 'manage-status' }],
   'init':               [{ cmd: 'maestro-init' }],
+  'grill':              [{ cmd: 'maestro-grill', args: '"{description}"' }],
+  'blueprint':          [{ cmd: 'maestro-blueprint', args: '"{description}"' }],
+  'analyze-macro':      [{ cmd: 'maestro-analyze', args: '"{description}"' }],
   'analyze':            [{ cmd: 'maestro-analyze', args: '{phase}' }],
   'analyze-quick':      [{ cmd: 'maestro-analyze', args: '{phase} -q' }],
   'ui_design':          [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }],
@@ -327,6 +335,9 @@ const chainMap = {
   'spec_add':           [{ cmd: 'spec-add', args: '"{description}"' }],
   'spec_load':          [{ cmd: 'spec-load' }],
   'spec_map':           [{ cmd: 'manage-codebase-rebuild' }],
+  'domain_add':         [{ cmd: 'domain-add', args: '"{description}"' }],
+  'domain_list':        [{ cmd: 'domain-list' }],
+  'domain_discover':    [{ cmd: 'domain-discover' }],
   'knowhow_capture':     [{ cmd: 'manage-knowhow-capture', args: '"{description}"' }],
   'issue':              [{ cmd: 'manage-issue', args: '"{description}"' }],
   'issue_discover':     [{ cmd: 'manage-issue-discover', args: '"{description}"' }],
@@ -349,20 +360,22 @@ const chainMap = {
   'team_tech_debt':     [{ cmd: 'team-tech-debt', args: '"{description}"' }],
 
   // ── Multi-step chains ──
-  'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }],
-  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
+  'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'grill-driven':         [{ cmd: 'maestro-grill', args: '"{description}"' }, { cmd: 'maestro-brainstorm', args: '"{description}" --from grill:{grill_id}' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'blueprint-driven':     [{ cmd: 'maestro-init' }, { cmd: 'maestro-blueprint', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
   'brainstorm_visualize': [{ cmd: 'brainstorm-visualize', args: '"{description}"' }],
   'impeccable-build':       [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'impeccable-driven':      [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }],
+  'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }, { cmd: 'manage-harvest', args: '--auto' }],
   'quality-loop':         [{ cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-auto-test', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'quality-debug', args: '--from-uat {phase}' }, { cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'milestone-close':      [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
   'next-milestone':       [{ cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'review-fix':           [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }],
   'quality-loop-partial': [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'issue-full':           [{ cmd: 'maestro-analyze', args: '--gaps {issue_id}' }, { cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
+  'issue-full':           [{ cmd: 'maestro-analyze', args: '--gaps {issue_id}' }, { cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }, { cmd: 'manage-harvest', args: '--auto' }],
   'issue-quick':          [{ cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
   'milestone-release':    [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-release' }],
 
@@ -417,19 +430,19 @@ detectNextAction(state):
 
 | Chain | Steps | Use Case |
 |-------|-------|----------|
-| `full-lifecycle` | plan → execute → review → test → audit | Full milestone completion |
-| `blueprint-driven` | init → blueprint → plan → execute | From idea/requirements (heavy) |
-| `roadmap-driven` | init → roadmap → plan → execute | From requirements (light) |
-| `brainstorm-driven` | brainstorm → plan → execute | From exploration |
+| `full-lifecycle` | plan → execute → review → test → audit → harvest | Full milestone completion |
+| `blueprint-driven` | init → blueprint → plan → execute → harvest | From idea/requirements (heavy) |
+| `roadmap-driven` | init → roadmap → plan → execute → harvest | From requirements (light) |
+| `brainstorm-driven` | brainstorm → plan → execute → harvest | From exploration |
 | `impeccable-build` | impeccable --chain build → plan → execute | From design system generation |
-| `analyze-plan-execute` | analyze -q → plan --dir → execute --dir | Fast track (scratch mode) |
+| `analyze-plan-execute` | analyze -q → plan --dir → execute --dir → harvest | Fast track (scratch mode) |
 | `review-fix` | plan --gaps → execute → review | Fix review-blocked issues |
 | `quality-loop` | review → test-gen → test → debug → plan --gaps → execute | Fix quality issues |
 | `quality-loop-partial` | plan --gaps → execute | Partial quality fix cycle |
 | `milestone-close` | audit → complete | Close a milestone |
 | `milestone-release` | audit → release | Release with version tag |
 | `next-milestone` | roadmap → plan → execute | Next milestone (auto-loads deferred) |
-| `issue-full` | analyze → plan → execute → review → close | Issue with quality gate |
+| `issue-full` | analyze → plan → execute → review → close → harvest | Issue with quality gate |
 | `issue-quick` | plan → execute → close | Issue fast path |
 
 ### Pipeline Examples

package/workflows/merge.md

@@ -1,9 +1,5 @@
 # Workflow: merge
 
-Two-phase merge of a completed milestone worktree branch back into main. Phase 1: git merge (source code). Phase 2: artifact sync (workflow state). Artifact sync only proceeds after successful git merge.
-
-Merges operate at the **milestone level** — one worktree per milestone, all phases merged together.
-
 ---
 
 ## Step 1: Parse Arguments and Flags

package/workflows/milestone-complete.md

@@ -1,7 +1,5 @@
 # Workflow: milestone-complete
 
-Archive completed milestone, move artifacts to history, and prepare for next.
-
 ---
 
 ## Step 1: Validation
@@ -167,5 +165,3 @@ Next steps:
   /maestro-analyze              -- Start next milestone (standard only)
   /manage-status                -- View project state
 ```
-
-**Adhoc milestone note:** When completing an adhoc milestone, the "Next steps" section omits "Start next milestone" since adhoc milestones have no successor in a roadmap chain.

package/workflows/overlays.md

@@ -1,7 +1,5 @@
 # Command Overlays — Format & Contract
 
-Overlays are non-invasive patches for `.claude/commands/*.md` files. They let users and operators inject additional steps, reading requirements, or gating rules into any slash command without editing the pristine source files shipped by the `maestro` package. Every `maestro install` run reapplies them automatically.
-
 ## File format
 
 Each overlay is a JSON file at `~/.maestro/overlays/<name>.json`:
@@ -83,10 +81,6 @@ On apply, each patch's `content` is wrapped in hashed markers:
 2. Restore `.md.disabled` state from the prior install
 3. **Apply overlays** — reads `~/.maestro/overlays/*.json`, applies each enabled one to the just-installed commands, writes `~/.maestro/manifests/overlays-<scope>.json`
 
-Because step 1 always overwrites commands with pristine content, the apply in step 3 is always clean — no drift, no stacking across reinstalls.
-
-Users can also run `maestro overlay apply` standalone between installs — it's idempotent and safe to call any number of times.
-
 ## CLI reference
 
 ```bash
@@ -96,10 +90,6 @@ maestro overlay add <file.json>             # validate, install, apply
 maestro overlay remove <name>               # strip markers, delete overlay file
 ```
 
-## Authoring via the `/maestro-overlay` skill
-
-Users rarely write overlay JSON by hand. The `/maestro-overlay` skill takes natural-language intent, reads the pristine target command to find the right section, drafts the overlay JSON, and runs `maestro overlay add` for you. See `.claude/commands/maestro-overlay.md`.
-
 ## Edge cases
 
 - **Disabled targets** (`.md.disabled`) are skipped silently.

package/workflows/plan.md

@@ -76,8 +76,6 @@ When plan resolves to `scope == "standalone"` AND `state.json.current_milestone
 5. Use this milestone ID for artifact registration (P5 Step 4)
 ```
 
-This ensures downstream commands (verify, milestone-audit, milestone-complete) have a valid milestone context without requiring roadmap.
-
 **Backward compatibility:** If `state.json.milestones[]` already has entries with `current_milestone != null`, skip creation (existing milestone takes precedence). Missing `type` field on legacy milestones defaults to `"standard"`.
 
 ---

package/workflows/roadmap-common.md

@@ -1,7 +1,5 @@
 # Workflow: Roadmap Common
 
-Shared logic for roadmap generation — used by roadmap.md.
-
 ---
 
 ## Worktree Guard
@@ -18,8 +16,6 @@ Block if `.workflow/worktree-scope.json` exists — must run from main worktree.
 specs_content = maestro spec load --category arch
 ```
 
-Ensure phases respect architectural constraints.
-
 ### Load Project History (if `.workflow/` exists)
 
 Read project artifacts to understand what has already been built:

package/workflows/tdd.md

@@ -1,7 +1,5 @@
 # TDD Workflow
 
-Test-Driven Development discipline for plan generation and execution. Invoked when `maestro-plan --tdd` is used. Transforms feature requirements into RED-GREEN-REFACTOR task chains that `maestro-execute` can consume.
-
 ---
 
 ## Iron Law

package/workflows/tools-spec.md

@@ -1,14 +1,8 @@
 # Tool Spec Reference
 
-<reference>
-Tool specs are a **subtype of knowhow** (`tool: true` frontmatter on knowhow documents). For the full knowhow data model, lifecycle, and management commands, see `knowhow.md`. This file documents only the tool-specific subset.
-</reference>
-
-Shared reference for tool spec registration and execution commands.
-
 ## Storage
 
-Tool specs are stored as knowhow documents in `.workflow/knowhow/` with `tool: true` in YAML frontmatter. Tool registration creates new knowhow files or promotes existing ones (via frontmatter update). The `category` field determines which `spec load --category` queries match this tool.
+Path: `.workflow/knowhow/` with `tool: true` in YAML frontmatter.
 
 ## Entry Format
 

package/workflows/ui-codify-extract.md

@@ -1,7 +1,5 @@
 # UI Codify: Phase 2 — Parallel Agent Extraction
 
-从源代码文件中提取设计系统 token，通过 3 个并行 Agent 分析。
-
 ## Overview
 
 - 3 个 Agent 并行运行：Style、Animation、Layout

package/workflows/ui-codify-package.md

@@ -1,7 +1,5 @@
 # UI Codify: Phase 3 — Reference Package Generation
 
-将提取结果转换为可分享的参考包，包含交互式预览页面。
-
 ## Prerequisites
 
 来自前序 Phase 的变量：

package/chains/singles/spec-generate.json

@@ -1,31 +0,0 @@
-{
-  "$schema": "../chain-graph.schema.json",
-  "id": "singles/roadmap-full",
-  "name": "Spec Generate",
-  "description": "Generate specification package through 7-phase document chain",
-  "version": "1.0.0",
-  "tags": [
-    "maestro",
-    "spec"
-  ],
-  "entry": "spec_generate",
-  "inputs": {
-    "description": {
-      "type": "string"
-    }
-  },
-  "nodes": {
-    "spec_generate": {
-      "type": "command",
-      "cmd": "maestro-roadmap",
-      "next": "done",
-      "analyze": false,
-      "args": "--mode full \"{description}\"",
-      "description": "Generate specification package through 7-phase document chain"
-    },
-    "done": {
-      "type": "terminal",
-      "status": "success"
-    }
-  }
-}