maestro-flow 0.5.46 → 0.5.48

package/.agy/skills/maestro-analyze/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: [phase|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]
+argument-hint: [milestone|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -29,17 +29,17 @@ Multi-dimensional analysis of a proposal, decision, or architecture choice via C
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no args for milestone-wide.
+$ARGUMENTS -- milestone number for micro mode, topic text for macro/adhoc mode, no args for current milestone.
 
 **Dual-layer mode:**
 - **Macro mode** (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with `scope_verdict` to route next step. Use before roadmap or for standalone analysis.
-- **Micro mode** (numeric argument): Phase-level deep analysis within an existing roadmap. Produces fine-grained context for plan consumption. `analyze 1` = Phase 1 of current milestone.
+- **Micro mode** (numeric argument): Milestone-level deep analysis within an existing roadmap. Covers all phases under the milestone. Same analysis depth, broader scope. `analyze 1` = Milestone 1.
 
 **Disambiguation rule (mode selection):**
-- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as phase number)
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as milestone number)
 - First positional arg is non-numeric text (e.g. `auth-refactor`, `improve search`) → **macro mode** (treat as topic)
-- No positional arg → milestone-wide micro mode (when roadmap present) else macro fallback
-- Mixed input like `"1 phase"` is treated as text → macro mode (only bare numerics trigger micro)
+- No positional arg → current milestone micro mode (when roadmap present) else macro fallback
+- Mixed input like `"1 milestone"` is treated as text → macro mode (only bare numerics trigger micro)
 
 **Flags:**
 
@@ -54,9 +54,9 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 **Scope routing:**
 | Input | Mode | Scope |
 |-------|------|-------|
-| Pure digits (e.g. `1`, `42`) | micro | Phase-level deep analysis |
+| Pure digits (e.g. `1`, `42`) | micro | Milestone-level deep analysis |
 | Non-numeric text (e.g. `auth-refactor`) | macro | Topic impact surface |
-| No positional arg + roadmap | micro | Milestone-wide |
+| No positional arg + roadmap | micro | Current milestone |
 | No positional arg + no roadmap | macro | Fallback |
 | `--gaps [ISS-ID]` | gaps | Issue root cause analysis |
 
@@ -81,7 +81,7 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 **Scope guard**: only analyze decisions; do not prejudge plan/execute concerns
 **Writeback target**: discussion.md (top table) + context.md "Interview Decisions"
 **Additional search sources**: issues.jsonl (--gaps mode), roadmap.md
-**Additional skip conditions**: input is already specific (explicit phase number or unambiguous topic)
+**Additional skip conditions**: input is already specific (explicit milestone number or unambiguous topic)
 **Exit condition**: all decision points settled → finalize session metadata
 </interview_protocol>
 
@@ -124,9 +124,9 @@ Status verdicts:
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Phase/Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
-| Phase/Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {phase}` |
-| Phase/Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
+| Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
+| Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {milestone}` |
+| Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
 | Macro/Adhoc, scope_verdict = large | `/maestro-roadmap --from analyze:ANL-xxx` |
 | Macro/Adhoc, scope_verdict = medium/small | `/maestro-plan --from analyze:ANL-xxx` |
 | Need more exploration | `/maestro-analyze {topic} -c` |
@@ -177,7 +177,7 @@ Both modes (full + quick):
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Scope creep redirected to Deferred section
 - [ ] Deferred items auto-created as issues (if any)
-- [ ] Artifact registered in state.json with correct scope/milestone/phase
+- [ ] Artifact registered in state.json with correct scope/milestone
 - [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>

package/.agy/skills/maestro-companion/SKILL.md

@@ -46,12 +46,23 @@ $ARGUMENTS — mode + optional flags.
 
 Auto-detection: if `--type` not provided, infer from `--task` description keywords.
 
+**Output boundary**: ALL file writes MUST target `.workflow/.scratchpad/` (companion docs + `.companion-active` pointer) only. Promotion writes (spec/knowhow) are delegated to `spec-add` / `manage-knowhow-capture` skills. NEVER modify source code, `.workflow/state.json`, or files outside `.workflow/.scratchpad/`.
+
 **Companion document:**
 - Path: `.workflow/.scratchpad/companion-{YYYYMMDD-HHmmss}.md`
 - Active doc tracking: `.workflow/.scratchpad/.companion-active` (stores path of current companion doc)
 - Format: YAML frontmatter (rich metadata) + typed sections + timestamped entries
 </context>
 
+<invariants>
+1. **No session creation** — companion NEVER creates workflow sessions, NEVER writes to state.json
+2. **Side-car only** — companion MUST NOT modify source code or execute implementation tasks; it is strictly a knowledge loading + recording utility
+3. **One active doc** — only one `.companion-active` pointer SHALL exist at a time; creating a new companion doc MUST clear any stale pointer
+4. **Append-only entries** — note mode MUST append entries; NEVER overwrite or reorder existing entries
+5. **Promotion via delegation** — spec/knowhow promotion MUST route through `spec-add` / `manage-knowhow-capture` skills; companion NEVER writes directly to `.workflow/specs/` or `.workflow/knowhow/`
+6. **Type-template integrity** — context template sections MUST match the resolved `task_type`; NEVER mix templates from different types
+</invariants>
+
 <state_machine>
 
 <states>

package/.agy/skills/maestro-composer/SKILL.md

@@ -40,8 +40,19 @@ $ARGUMENTS — natural language description, or flags.
 1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
 2. **Coding specs**: Run `maestro load --type spec --category coding` to load coding conventions. Informs executor argument defaults and context injection.
 3. Optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/templates/workflows/` (template JSON + index.json) and `.workflow/templates/design-drafts/` (intermediate drafts) only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
+<invariants>
+1. **Max 20 nodes** — workflow templates MUST NOT exceed 20 nodes; larger workflows MUST be split into sub-workflows
+2. **Acyclic DAG** — generated template MUST be a directed acyclic graph; cycles MUST be detected and rejected before persistence
+3. **No orphan nodes** — every node MUST be reachable from at least one edge; unreachable nodes MUST be flagged
+4. **Confirmation before write** — template JSON MUST be shown to user via ask_question before writing to `~/.maestro/templates/workflows/`; cancellation saves draft only
+5. **Draft preservation** — abandoning at any confirmation gate MUST save current progress to design-drafts directory; NEVER discard user's partial work
+6. **Deferred reading only** — node-catalog and template-schema MUST be read at their designated phases (P2, P5), NEVER loaded eagerly at startup
+</invariants>
+
 <state_machine>
 
 <states>
@@ -142,7 +153,7 @@ Write `nodes.json`. Display resolved node list.
 |------|-----------|
 | Artifact boundary | Source outputs plan/spec/analysis/review |
 | Execution gate | Target contains `execute` |
-| Long-running | Target is maestro-plan, maestro-roadmap --mode full |
+| Long-running | Target is maestro-plan, maestro-blueprint |
 | Post-testing | Source contains `test` or `auto-test` |
 | User-defined | type_hint == checkpoint |
 

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

@@ -30,10 +30,35 @@ $ARGUMENTS — Parse subcommand and optional path argument.
 
 **Enforcement:** The `workflow-guard` hook (PreToolUse on Write/Edit) reads this config
 and blocks operations targeting files outside boundaries. Requires hooks level >= `full`.
+
+**Output boundary**: ALL file writes MUST target `.workflow/config.json` (guard section) only. NEVER modify hook files, `.claude/settings.json`, or source code.
 </context>
 
+<invariants>
+1. **Config-only mutation** — guard MUST only modify the `guard` section of `.workflow/config.json`; NEVER touch other config sections or files
+2. **Non-destructive** — `off` MUST preserve existing paths and mode; NEVER clear the path list when disabling
+3. **Mode switch confirmation** — switching between allow/deny mode MUST require ask_question confirmation when existing paths will be cleared
+4. **Hook dependency** — guard MUST warn when enabled but `workflow-guard` hook is not active (hooks level < full)
+5. **Path normalization** — all paths MUST use forward slashes with trailing slash for directories; NEVER store raw backslash paths
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Config Read**
+- REQUIRED: Subcommand parsed (on/off/status/allow/deny) or defaulted to `status`.
+- BLOCKED if: invalid subcommand provided.
+
+**GATE 2: Config Read → Execute**
+- REQUIRED: `.workflow/config.json` read successfully or initialized with empty guard section.
+- BLOCKED if: file unreadable and cannot be created (E001).
+
+**GATE 3: Execute → Confirm**
+- REQUIRED: Config mutation applied (for on/off/allow/deny) or status displayed (for status).
+- REQUIRED: Mode-switch ask_question answered (for allow↔deny transitions with existing paths).
+- BLOCKED if: user declines mode switch.
+
 **Step 1: Parse subcommand**
 
 Extract from $ARGUMENTS:

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

@@ -295,6 +295,8 @@ Odyssey 长周期循环（独立路径）
 | 长周期改进 | Odyssey 深度循环 | `/odyssey-improve "改进目标"` |
 | 需求迭代 | Odyssey 深度循环 | `/odyssey-planex "需求描述"` |
 
+> 注：Path A/B 中 `analyze 1` / `plan 1` 的数字 `1` 指 **milestone 编号**（第 1 个里程碑），下游以 milestone 为入口。
+
 ## Core Rules
 
 1. **Catalog First**: 先查 catalog.json，再按需读 source 文件

package/.agy/skills/maestro-help/index/catalog.json

@@ -9,8 +9,8 @@
     {"name": "maestro-init", "command": "/maestro-init", "category": "core", "description": "项目初始化 — 创建 .workflow/ 目录结构和状态文件", "source": "../../commands/maestro-init.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-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — 消费上游 context，纯 Milestone > Phase 分解（不做技术探索）", "source": "../../commands/maestro-roadmap.md"},
-    {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
+    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — Milestone > Phase 分解，下游以 milestone 为入口", "source": "../../commands/maestro-roadmap.md"},
+    {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
     {"name": "maestro-overlay", "command": "/maestro-overlay", "category": "core", "description": "Overlay 管理 — 创建、查看、删除命令补丁", "source": "../../commands/maestro-overlay.md"},
     {"name": "maestro-amend", "command": "/maestro-amend", "category": "core", "description": "修正补丁 — 从工作流信号自动生成 overlay", "source": "../../commands/maestro-amend.md"},
     {"name": "maestro-composer", "command": "/maestro-composer", "category": "core", "description": "编排器 — compose + play 工作流组合执行", "source": "../../commands/maestro-composer.md"},
@@ -27,7 +27,7 @@
     {"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-milestone-audit", "command": "/maestro-milestone-audit", "category": "milestone", "description": "里程碑审计 — 检查 Phase 完成度和质量", "source": "../../commands/maestro-milestone-audit.md"},
+    {"name": "maestro-milestone-audit", "command": "/maestro-milestone-audit", "category": "milestone", "description": "里程碑审计 — 检查里程碑完成度和质量", "source": "../../commands/maestro-milestone-audit.md"},
     {"name": "maestro-milestone-complete", "command": "/maestro-milestone-complete", "category": "milestone", "description": "里程碑完成 — 归档里程碑并推进下一个", "source": "../../commands/maestro-milestone-complete.md"},
     {"name": "maestro-milestone-release", "command": "/maestro-milestone-release", "category": "milestone", "description": "里程碑发布 — 生成发布说明和变更日志", "source": "../../commands/maestro-milestone-release.md"},
 
@@ -218,17 +218,17 @@
   ],
   "workflows": {
     "topology": {
-      "hierarchy": "Roadmap > Milestone > Phase > Task",
+      "hierarchy": "Roadmap > Milestone > Phase | Plan > Task > Wave",
       "layers": {
         "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
-        "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
+        "understanding": "analyze 双层: 宏观(文本参数) + 微观(milestone 数字参数)",
         "orchestration": "roadmap (可选，消费上游 context)",
         "execution": ["plan", "execute"]
       }
     },
     "paths": {
-      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute",
-      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute",
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze {milestone} → plan {milestone} → execute",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze {milestone} → plan {milestone} → execute",
       "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute",
       "D_small_fix": "plan → execute",
       "E_spec_only": "blueprint → (供人阅读)",

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

@@ -40,8 +40,18 @@ $ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for aut
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
+
+**Output boundary**: ALL file writes MUST target `.workflow/` (project.md, state.json, config.json, specs/) only. NEVER modify source code or files outside `.workflow/`.
 </context>
 
+<invariants>
+1. **Idempotent init** — re-running init on an already-initialized project MUST detect existing `.workflow/` and warn (E002); NEVER silently overwrite existing state
+2. **Scope guard** — init MUST only make initialization decisions; NEVER prejudge roadmap structure, plan scope, or implementation details
+3. **All artifacts required** — init MUST NOT report completion until project.md, state.json, and config.json all exist; missing artifacts MUST be created before exit
+4. **Template-driven** — deferred templates (project.md, state.json, config.json) MUST be read from `~/.maestro/templates/` and customized; NEVER generate from scratch without template
+5. **Interview writes back** — all interactive decisions MUST be written to project.md/config.json before proceeding to research or completion; NEVER leave decisions unrecorded
+</invariants>
+
 <interview_protocol>
 Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
@@ -54,6 +64,24 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 </interview_protocol>
 
 <execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Pre-flight → Interview**
+- REQUIRED: `.workflow/` existence check completed.
+- REQUIRED: `--from` source validated (if provided).
+- BLOCKED if: E002 (greenfield conflict with existing `.workflow/`) unresolved.
+
+**GATE 2: Interview → Research**
+- REQUIRED: All interview decisions recorded in project.md and config.json.
+- REQUIRED: `.workflow/` directory created with initial structure.
+- BLOCKED if: interview decisions not yet written to files.
+
+**GATE 3: Research → Completion**
+- REQUIRED: All 3 required artifacts exist (project.md, state.json, config.json).
+- REQUIRED: `.workflow/specs/` initialized.
+- BLOCKED if: any artifact missing — write it before reporting completion.
+
 ### Pre-flight
 
 1. Check if `.workflow/` already exists — if so, load state and warn (E002 for greenfield conflicts)
@@ -106,7 +134,7 @@ Status verdicts:
 | Condition | Suggestion |
 |-----------|-----------|
 | Roadmap needed (default light) | `/maestro-roadmap <requirement>` |
-| Full spec package + roadmap | `/maestro-roadmap --mode full <idea>` |
+| Full spec package | `/maestro-blueprint <idea>` |
 | Explore ideas first | `/maestro-brainstorm <topic>` |
 | View project dashboard | `/manage-status` |
 | Quick ad-hoc task | `/maestro-quick <task>` |

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

@@ -58,7 +58,7 @@ Audit checklist steps (phase coverage, ad-hoc completeness, execution completene
 
 **GATE 1: Load → Phase Coverage Check**
 - REQUIRED: state.json loaded with artifacts[] filtered by target milestone.
-- REQUIRED: Milestone phases identified from roadmap (standard) or milestone_obj.phases (adhoc).
+- REQUIRED: Milestone phases identified from the PLN artifact's plan.json (standard) or milestone_obj.phases (adhoc). Phase coverage is verified from the PLN artifact's plan.json, not from roadmap.
 - BLOCKED if no execute artifacts found: error E003.
 
 **GATE 2: Phase Coverage → Integration Check**
@@ -118,7 +118,7 @@ Status verdicts:
 </error_codes>
 
 <success_criteria>
-- [ ] All phases in milestone identified from roadmap (standard) or milestone_obj.phases (adhoc)
+- [ ] All phases in milestone identified from the PLN artifact's plan.json (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)

package/.agy/skills/maestro-milestone-release/SKILL.md

@@ -113,7 +113,7 @@ Status verdicts:
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Release successful, starting next milestone | `/maestro-plan {next_phase}` |
+| Release successful, starting next milestone | `/maestro-plan {next_milestone}` |
 | Want to view project dashboard | `/manage-status` |
 </completion>
 

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

@@ -103,8 +103,8 @@ ls -la .workflow/.maestro/ 2>/dev/null | head -5  # 进行中的 session
 | 无 `.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}` |
+| 有 roadmap，未启动 phase | analyze | `maestro-analyze {milestone}` |
+| 最新 artifact = analyze | plan | `maestro-plan {milestone}` |
 | 最新 artifact = plan | execute | `maestro-execute {phase}` |
 | 最新 artifact = execute | review | `quality-review {phase}` |
 | review verdict=PASS | test-gen | `quality-auto-test {phase}` |

package/.agy/skills/maestro-overlay/SKILL.md

@@ -33,8 +33,19 @@ Turn natural-language instructions into command overlays — JSON patch files th
 **Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.
 
 **Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. Command file patching is handled by `maestro overlay add` — this skill NEVER modifies `.claude/commands/*.md` directly.
 </context>
 
+<invariants>
+1. **Non-invasive** — overlays MUST use hashed HTML-comment markers for injection; NEVER edit command file content directly outside the overlay system
+2. **Idempotent** — re-running `maestro overlay apply` with the same overlay JSON MUST produce no file changes
+3. **Creation only** — this skill MUST only create overlays; listing and removal are handled by `maestro overlay list` (ink TUI)
+4. **Pristine source preferred** — injection point analysis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals) first, fall back to `~/.claude/commands/` only if pristine unavailable
+5. **User approval before write** — overlay JSON MUST be shown and approved via ask_question before writing to disk; NEVER auto-install without confirmation
+6. **Chain skip option mandatory** — if a skill chain is configured, the injected content MUST include a "Skip" option in ask_question; NEVER force the user into a chain
+</invariants>
+
 <execution>
 ### 1. Parse user intent
 

package/.agy/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>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]
+description: Use when creating, revising, or verifying an execution plan for a milestone or task
+argument-hint: [milestone] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -31,9 +31,9 @@ Produces plan.json + TASK files; registers PLN artifact in state.json.
 </deferred_reading>
 
 <context>
-$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
+$ARGUMENTS — milestone number, or no args for current milestone, with optional flags.
 
-Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
+Scope routing, base flags (`--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):
@@ -48,8 +48,8 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 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)
+4. Numeric arg → scope = "milestone", resolve from roadmap
+5. No args + roadmap → scope = "current_milestone"
 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".
@@ -71,6 +71,28 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/plan.md' completely.
 
+### Plan Agent Model
+
+Plan automatically selects agent mode based on milestone scope:
+
+**Single agent mode** (default):
+- Milestone involves ≤3 modules
+- 1 workflow-planner agent, max 8 TASK JSON output
+- Directly produces plan.json
+
+**2+1 agent mode** (auto-triggered):
+- Milestone involves >3 modules
+- 2 parallel workflow-planner agents, each scoped to 2-3 modules
+- Each agent produces max 8 TASK JSON (total max 16)
+- +1 synthesis agent:
+  - Merges TASK JSON from both agents
+  - DAG analysis: dependency correctness, cycle detection, cross-module conflicts
+  - Terminology consistency check
+  - Wave ordering optimization
+  - Produces unified plan.json
+
+Module count is derived from milestone phase definitions and analyze upstream context.
+
 ### Phase Gates (MANDATORY, BLOCKING — Create mode only)
 
 **GATE P1 → P2: Context Collection → Clarification**
@@ -115,7 +137,7 @@ Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These
 
 ```
 === PLAN READY ===
-Phase: {phase_name}
+Milestone: {milestone_name}
 Tasks: {task_count} tasks in {wave_count} waves
 Check: {checker_status} (iteration {check_count}/{max_checks})
 Collision: {collision_status}
@@ -145,13 +167,13 @@ Status verdicts:
 |-----------|-----------|
 | Plan confirmed for execution | `/maestro-execute` |
 | Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
-| Re-plan with modifications | `/maestro-plan {phase}` |
+| Re-plan with modifications | `/maestro-plan {milestone}` |
 </completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
+| E001 | error | No args and no roadmap (cannot determine scope) | Provide milestone number or topic, or create roadmap |
 | E003 | error | --gaps requires prior verification/issues to exist | Run maestro-execute first (verification is built-in) |
 | E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
 | E005 | error | Plan directory not found (--check) | Check path, use --dir |

package/.agy/skills/maestro-player/SKILL.md

@@ -68,8 +68,19 @@ $ARGUMENTS — template slug/path, or flags.
   "last_checkpoint": null
 }
 ```
+
+**Output boundary**: ALL file writes MUST target `.workflow/.maestro/player-*/` (session status.json + step outputs) only. Template files (`~/.maestro/templates/workflows/`) are read-only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
+<invariants>
+1. **Resume-safe** — status.json MUST be updated after every step change; an interrupted session MUST be resumable from the last checkpoint via `-c`
+2. **One step at a time** — execution loop MUST process steps sequentially in topological order; parallel steps share a batch index but NEVER run concurrently within the player
+3. **CLI nodes async** — cli-type nodes MUST use `run_command(run_in_background: true)` + STOP pattern; NEVER block the main thread on delegate execution
+4. **Templates read-only** — player MUST NOT modify template JSON files; runtime state belongs in status.json only
+5. **Failure requires user decision** — on step failure without explicit `on_fail`, player MUST prompt via ask_question (Retry/Skip/Abort); NEVER silently skip or auto-abort
+6. **Reference resolution at runtime** — `{N-xxx.field}` and `{prev_*}` references MUST be resolved at execution time from status.json step results, NEVER pre-resolved during init
+</invariants>
+
 <state_machine>
 
 <states>

package/.agy/skills/maestro-quick/SKILL.md

@@ -41,9 +41,38 @@ Parse for:
    - Browse: `maestro search --category coding`
    - Load task-relevant entries: `maestro load --type knowhow --id <id1> [id2...]`
 3. All are optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/` (task directory, plan.json, summaries) and modified source files as defined in plan.json tasks. State.json scratch entry is implicit workflow tracking.
 </context>
 
+<invariants>
+1. **Atomic commits** — each task execution MUST produce a commit with only the files modified by that task; NEVER stage unrelated files
+2. **Evidence-based summaries** — task summaries MUST include concrete evidence (files changed, tests run, commands executed); NEVER accept "task completed successfully" as a summary
+3. **Plan before execute** — plan.json MUST be written before any task execution begins; NEVER skip planning even for single-task workflows
+4. **Scratch isolation** — all workflow artifacts MUST live under `.workflow/scratch/{task-dir}/`; NEVER write workflow metadata outside this directory
+5. **Commit confirmation** — staged files and commit message MUST be shown via ask_question before committing (unless `-y`); NEVER auto-commit without user awareness
+</invariants>
+
 <execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Planning**
+- REQUIRED: Task description parsed and scratch directory created.
+- REQUIRED: Coding specs loaded (optional but attempted).
+- BLOCKED if: no task description (E001) or scratch directory creation failed (E002).
+
+**GATE 2: Planning → Execution**
+- REQUIRED: plan.json written with task definitions.
+- REQUIRED: --discuss decisions extracted and recorded (if flag set).
+- BLOCKED if: plan.json missing or empty.
+
+**GATE 3: Execution → Completion**
+- REQUIRED: All tasks executed with `.summaries/TASK-*-summary.md` written per task.
+- REQUIRED: Each summary contains concrete evidence of completion.
+- REQUIRED: --full verification passed (if flag set).
+- BLOCKED if: any task summary missing or lacking evidence.
+
 Follow '~/.maestro/workflows/quick.md' completely.
 
 ### Artifact Verification (before completion)