maestro-flow 0.4.12 → 0.4.14

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

@@ -14,7 +14,7 @@ allowed-tools:
   - write_to_file
 ---
 <purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/brainstorm-{slug}-{date}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
 </purpose>
 
 <required_reading>
@@ -32,7 +32,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
 **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
 **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 **Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).
@@ -64,14 +64,15 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `--yes/-y`, `--skip-questions`, `--session` (existing session), or input is already specific.
 
-- One decision per turn via ask_question with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
-- Never ask what code can verify — resolve via `state.json`, the session directory, `maestro spec load`, or `maestro wiki search`.
+- One decision per turn via ask_question with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each time a decision settles, immediately append/update its row in `guidance-specification.md` §11 (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
 - Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
 
 Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
 
-Exit: on consensus or `Proceed now`, write the table below into `guidance-specification.md` §11 and session metadata:
+Exit: on consensus or explicit user signal to proceed, finalize session metadata. The §11 table (already populated incrementally) uses this schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 

package/.agy/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/.agy/skills/maestro-guard/SKILL.md

@@ -77,10 +77,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/.agy/skills/maestro-impeccable/SKILL.md

@@ -75,6 +75,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 |
@@ -182,17 +184,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}
    ```
@@ -206,9 +208,9 @@ Before reading any command workflow:
      "gate_history": [], "loop_count": 0, "status": "running" }
    ```
 4. **TodoWrite 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**: TodoWrite marks current step in_progress

package/.agy/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/.agy/skills/maestro-plan/SKILL.md

@@ -56,7 +56,9 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 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" 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".
+**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`

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

@@ -15,10 +15,12 @@ Closed-loop decision engine for the maestro workflow lifecycle.
 Reads project state → infers position → builds adaptive chain → delegates execution.
 
 Entry points:
-- **`/maestro-ralph "intent"`** — New session: infer → decompose → build → execute
-- **`/maestro-ralph continue`** — Resume via maestro-ralph-execute
+- **`/maestro-ralph "intent"`** — New session: infer → decompose → build → (decomposition → emit /goal prompt, STOP；否则 dispatch ralph-execute)
+- **`/maestro-ralph continue`** — Wrapper; dispatches to ralph-execute（首选直接 `/maestro-ralph-execute` 推进 step）
 - **`/maestro-ralph status`** — Display session progress
 
+> 推进规则：**step 推进由 `/maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `Skill("maestro-ralph")` handoff，无需用户手动切换。
+
 Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
 
 Node types:
@@ -66,15 +68,16 @@ Remaining     → intent
 
 <invariants>
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
-2. **Handoff via Skill("maestro-ralph-execute")** — at session creation and after decision evaluation
+2. **Handoff via Skill("maestro-ralph-execute")** — 仅当 session 无 `task_decomposition` 时在创建后自动 handoff；decomposition 路径 STOP 等用户输入。decision 评估后始终 handoff
 3. **Decision delegates read-only** — `maestro delegate --role analyze --mode analysis`
 4. **Default type = internal** — `external` 仅显式标注时出现，build 不默认生成
 5. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
 6. **每个 step 必须 `completion_confirmed: true`** — 基于 `--- COMPLETION STATUS ---` 的 `STATUS: DONE`；缺失则视为未完成
 7. **command_path 在 A_BUILD_STEPS 解析** — 全局优先 `~/.claude/commands/{name}.md`，fallback 项目 `.claude/commands/{name}.md`，写入 status.json
-8. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 只发提示词
-9. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
-10. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
+8. **Internal step 加载契约** — ralph-execute 读 `command_path` 后，必须解析并加载该命令 `<required_reading>` 引用的所有文件（"入口 + workflow"形式的核心），并把 `<deferred_reading>` 路径记录到 `step.deferred_reads`；加载完成后输出 `✓ skill {name} 加载完成`。ralph 在 build 阶段只解析路径，不读 .md 内容
+9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 只发提示词后 STOP，等用户输入
+10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 </invariants>
 
 <state_machine>
@@ -144,8 +147,9 @@ S_BUILD_CHAIN:
   → S_CREATE_SESSION DO: A_BUILD_STEPS
 
 S_CREATE_SESSION:
-  → S_CONFIRM       WHEN: not auto_confirm                  DO: A_CREATE_SESSION
-  → S_DISPATCH      WHEN: auto_confirm                      DO: A_CREATE_SESSION
+  → END             WHEN: task_decomposition present        DO: A_CREATE_SESSION (emits Goal Prompt → STOP，等用户输入 /goal 后手动 /maestro-ralph-execute)
+  → S_CONFIRM       WHEN: not auto_confirm AND no decomposition DO: A_CREATE_SESSION
+  → S_DISPATCH      WHEN: auto_confirm AND no decomposition  DO: A_CREATE_SESSION
 
 S_CONFIRM:
   → S_DISPATCH      WHEN: user selects "Proceed"
@@ -409,7 +413,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
    - 全局优先：`~/.claude/commands/{name}.md` 存在 → `command_scope = "global"`
    - Fallback：`.claude/commands/{name}.md` 存在 → `command_scope = "project"`
    - 两者都缺 → `command_scope = "missing"`, `command_path = null`，A_CREATE_SESSION 报错 E006
-10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`
+   - **不在 build 阶段读取 .md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 ralph-execute A_EXEC_INTERNAL 负责（保持入口/工作流分离）
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`
 11. **scope_verdict gating**（仅当 chain 起点 = `analyze-macro`）：
     - `scope_verdict ∈ {medium, small}` → 跳过 `roadmap` + `analyze` 两 stage；`plan` 选 standalone 列（`--from analyze:{analyze_macro_id}`），不带 `{phase}`
     - `scope_verdict == large` → 保留 `roadmap` + `analyze`；`plan` 选 phase 列（`{phase}`）
@@ -427,7 +432,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 1. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E006 + 列出缺失 skill
 2. Write `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json` (Appendix: Session Schema)
 3. Display chain overview：每步显示 `{index}. {skill} [{type}] [{command_scope}]`
-4. If `task_decomposition` present: display the **Goal Prompt block** (Appendix: Goal Prompt Template)
+4. If `task_decomposition` present: display **Goal Prompt block** (Appendix) → STOP，等用户输入 `/goal`（auto_confirm 也不跳过）
 
 ### A_DELEGATE_EVALUATE
 
@@ -616,7 +621,8 @@ Runs only when `task_decomposition` present.
     "completion_confirmed": false,
     "completion_status": null,
     "completion_evidence": null,
-    "completed_at": null
+    "completed_at": null,
+    "deferred_reads": []          // 由 ralph-execute A_EXEC_INTERNAL 解析 .md 时填充
   }],
   "waves": [], "current_step": 0,
 
@@ -700,11 +706,9 @@ decision:post-goal-audit {retry+1}
 链路概览后逐字显示（仅当 decomposition 已产出）：
 
 ```
-📋 任务分解完成。复制下面一行设定目标，会话在子目标全部达成前不停：
-
-/goal 目标达成条件: {session_dir}/status.json 中 task_decomposition[*].status == "done" 且 task_decomposition[*].completion_confirmed == true 且 steps[*].completion_confirmed == true。未达成时：阅读 {session_dir}/status.json 取得 execution_criteria / boundary_contract / task_decomposition / steps 作为行动手册，调用 /maestro-ralph continue 推进；严禁手动执行 skill 或越界修改 status.json.boundary_contract.out_of_scope。
+📋 任务分解完成。复制以下 /goal 设定终止条件，随后运行 /maestro-ralph-execute：
 
-随后运行 /maestro-ralph continue 立即开始执行。
+/goal 直到 {session_dir}/status.json 的 task_decomposition[*] 与 steps[*] 全部 completion_confirmed=true 才停。每轮以 status.json 为唯一行动手册，通过 /maestro-ralph-execute 推进 step；decision 节点由其自动 handoff 回 ralph 评估。禁止手动执行 skill 或修改 boundary_contract.out_of_scope。
 ```
 
 `/goal` 由用户输入；ralph 只输出此提示词。判据以 status.json 为权威。
@@ -740,7 +744,8 @@ decision:post-goal-audit {retry+1}
 - [ ] Decomposition: broad intent ≤3 question clarify；narrow auto-derive
 - [ ] status.json 唯一真源：boundary_contract + execution_criteria + task_decomposition；无外部清单
 - [ ] 每个 step 默认 `type: "internal"`，含 `command_scope` + `command_path`（全局优先 fallback 项目）
-- [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence`（初始 false/null）
+- [ ] Ralph build 阶段只解析路径，不读 .md 内容；`<required_reading>` 加载由 ralph-execute A_EXEC_INTERNAL 完成
+- [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence` + `deferred_reads`（初始 false/null/[]）
 - [ ] 每个 sub-goal 含 `completion_confirmed`（初始 false）
 - [ ] post-goal-audit decision 仅在 decomposed 时插入，位于 milestone-complete 之前
 - [ ] Unmet sub-goals 动态 grow steps[]（goal_ref tagged）；max retries → escalate

package/.agy/skills/maestro-ralph-execute/SKILL.md

@@ -36,7 +36,9 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 | external (opt-in) | `maestro delegate --to claude --mode write` (STOP → callback) | Self-invoke next |
 
 HARD RULES:
-- internal step MUST 通过 `view_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；禁止 `Skill({skill})` 调用
+- internal step：优先通过 `view_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；不要对 internal step 使用 `Skill({skill})` 调用
+- **必须遵循 `<required_reading>` / `<deferred_reading>` 标签**：命令 .md 通常采用"入口 + workflow"形式，主体逻辑放在 workflow 文件中并通过 `<required_reading>` 引用；不加载 required_reading 会导致命令执行不完整
+- decision 节点例外：A_EXEC_DECISION 必须使用 `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph/SKILL.md") + execute inline` 进行 handoff（这是 decision 节点的唯一允许用法）
 - `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json；ralph-execute 不再自行解析（缺失 → 报错 E002）
 - external 仅在 `step.type == "external"` 显式声明时使用，并 always append `-y` 到 prompt args
 - 每个 step 必须产出 `--- COMPLETION STATUS ---` 块，否则视为 NEEDS_RETRY
@@ -44,10 +46,13 @@ HARD RULES:
 
 <invariants>
 1. **Internal = Read + inline** — 通过 Read 读取 `step.command_path`，按其指令在当前 session 内执行
-2. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
-3. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
-4. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
-5. **status.json 每步骤后写盘** — resume-safe
+2. **Required reading must be loaded** — 命令 .md 中的 `<required_reading>` 引用的所有文件必须立即 Read；缺一 → 视为加载失败，pause session（E007）
+3. **Deferred reading recorded only** — `<deferred_reading>` 列出的文件路径需记录，执行过程按需 Read；不在加载阶段读取
+4. **Skill loaded confirmation** — 所有 required_reading 加载完成后必须输出一行确认：`✓ skill {step.skill} 加载完成 (required: N, deferred: M)`
+5. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
+6. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
+7. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
+8. **status.json 每步骤后写盘** — resume-safe
 </invariants>
 
 <state_machine>
@@ -155,12 +160,21 @@ Write enriched args back to status.json.
 1. Validate `step.command_path != null`；否则 raise E002，pause session
 2. Mark step running, write status.json
 3. Display: `[{index}/{total}] {step.skill} [internal · {step.command_scope}]`
-4. `view_file({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话
-5. 解析 frontmatter `argument-hint` 与 `<purpose>/<state_machine>/<actions>` 等指令块
-6. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
-7. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 Skill() 或 delegate
-8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
-9. Return success / failure
+4. `view_file({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话（prefer Read over Skill for internal steps；decision 节点另行使用 Skill 见 A_EXEC_DECISION）
+5. **解析 reading 标签**（"入口 + workflow"形式核心步骤）：
+   - 抽取 frontmatter `argument-hint` / `allowed-tools`
+   - 抽取 `<required_reading>` 块的所有 `@path` 引用 → 立刻 `view_file({ file_path: <expanded path> })` 加载（`~/` / `@~/` 展开为用户主目录）；任一文件缺失或读取失败 → raise E007，pause session
+   - 抽取 `<deferred_reading>` 块的所有路径 → 仅记录到 `step.deferred_reads = [...]`，执行阶段按需 Read
+   - 抽取 `<purpose>/<context>/<state_machine>/<execution>/<actions>` 等指令块
+6. **加载完成确认**：required_reading 全部成功 Read 后，输出一行：
+   ```
+   ✓ skill {step.skill} 加载完成 (required: {N}, deferred: {M})
+   ```
+   其中 N = required_reading 引用数，M = deferred_reading 路径数（缺省块按 0 计）
+7. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
+8. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate；执行过程中如触发 deferred_reading 引用的资源 → 按需 Read
+9. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
+10. Return success / failure
 
 **Auto flag map**: 所有 lifecycle skill → `-y`; `quality-test` → `-y --auto-fix`; 未列出 → 无 flag
 
@@ -248,7 +262,9 @@ Write enriched args back to status.json.
 | E003 | error | status.json corrupt | Show path, manual check |
 | E004 | error | Delegate failed + user abort | Mark paused, suggest resume |
 | E005 | error | COMPLETION STATUS block missing | Trigger NEEDS_RETRY |
+| E007 | error | required_reading file 缺失或读取失败 | List missing paths, pause session |
 | W001 | warning | Step completed with concerns | Log and continue |
+| W002 | warning | command .md 无 `<required_reading>` 标签 | 直接执行 .md 主体，跳过加载阶段 |
 
 ### Success Criteria
 
@@ -257,6 +273,9 @@ Write enriched args back to status.json.
 - [ ] Placeholders resolved；per-skill enrichment 正确
 - [ ] Decision 节点 Skill("maestro-ralph") handoff
 - [ ] Internal 节点通过 view_file({step.command_path}) 内联执行，禁止 Skill()
+- [ ] Internal 节点 Read 后必须解析并加载 `<required_reading>` 引用的文件；缺失 → E007 pause
+- [ ] `<deferred_reading>` 仅记录路径到 `step.deferred_reads`，执行阶段按需 Read
+- [ ] required_reading 加载完成后输出 `✓ skill {name} 加载完成 (required: N, deferred: M)`
 - [ ] External 仅在显式声明时走 delegate，prompt 必带 `-y`
 - [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
 - [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置

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

@@ -71,14 +71,15 @@ maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c/--continue`, or input is already specific (clear requirement + mode).
 
-- One decision per turn via ask_question with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
-- Never ask what code can verify — resolve via `state.json`, existing `roadmap.md`, `project.md`, or `maestro spec load`.
+- One decision per turn via ask_question with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
 
 Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
 
-Exit: on consensus or `Proceed now`, append the table below to a `Roadmap Decisions` section at the top of `.workflow/roadmap.md`:
+Exit: on consensus or explicit user signal to proceed, finalize the `Roadmap Decisions` section (rows already populated incrementally). Schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 

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

@@ -21,7 +21,7 @@ Verify execution results through three complementary methods:
 3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
 
 Supports dual-level verification:
-- **Single plan**: `verify --dir scratch/plan-xxx` — verifies one plan, writes `verification.json` into plan dir
+- **Single plan**: `verify --dir scratch/{YYYYMMDD}-plan-xxx` — verifies one plan, writes `verification.json` into plan dir
 - **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 Registers VRF artifact in state.json on completion.

package/.agy/skills/manage-harvest/SKILL.md

@@ -49,6 +49,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
 1. **Read-only until Stage 6** — extraction and classification happen in-memory.
 2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
 3. **Never modify source artifacts** — harvest is purely extractive.
+4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 

package/.agy/skills/manage-issue-discover/SKILL.md

@@ -48,7 +48,7 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 - `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
 
 **State files:**
-- `.workflow/issues/issues.jsonl` -- issues appended here
+- `.workflow/issues/issues.jsonl` -- issues appended here (set `source: "discover"` on each row so concurrent writers like `manage-harvest` with `source: "harvest"` can be distinguished and deduplicated)
 - `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
 
 ### Pre-load specs

package/.agy/skills/manage-knowhow/SKILL.md

@@ -52,7 +52,7 @@ Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | No memory stores found — run `/manage-knowhow-capture` or create MEMORY.md | resolve_paths |
+| E001 | error | No memory stores found — for workflow store run `/manage-knowhow-capture`; for system store create `~/.claude/projects/{project}/memory/MEMORY.md` manually | resolve_paths |
 | E002 | error | Entry ID or filename not found | execute_view, execute_delete |
 | E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
 | E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |

package/.agy/skills/manage-learn/SKILL.md

@@ -29,7 +29,7 @@ Arguments: $ARGUMENTS
 - `"<insight text>"` (or any non-keyword text) → insight capture mode
 - `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
 - `list` → list recent entries (default 20)
-- `search <query>` → `maestro spec load --category learning` or text search across `specs/learnings.md`
+- `search <query>` → `maestro spec load --category learning` or text search across `.workflow/specs/learnings.md`
 - `show <INS-id>` → full detail with phase context
 - empty → ask_question to prompt for text
 
@@ -46,19 +46,19 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
 | E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in `specs/learnings.md` | show |
+| E004 | error | Insight id not found in `.workflow/specs/learnings.md` | show |
 | W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
 </error_codes>
 
 <success_criteria>
 - [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `<spec-entry>` block appended to `specs/learnings.md` with all required fields
+- [ ] Capture: `<spec-entry>` block appended to `.workflow/specs/learnings.md` with all required fields
 - [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
 - [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/knowhow/`
+- [ ] No file modifications outside `.workflow/specs/learnings.md` and `.workflow/knowhow/`
 - [ ] Confirmation banner displayed with INS-id and next-step hints
 - [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
 </success_criteria>

package/.agy/skills/quality-auto-test/SKILL.md

@@ -39,13 +39,13 @@ Phase or task: $ARGUMENTS (required — phase number)
 
 **Intelligent routing** (auto-detected from project state):
 
-| Priority | Condition | Route | Equivalent to |
-|----------|-----------|-------|---------------|
+| Priority | Condition | Route | Reference skill |
+|----------|-----------|-------|-----------------|
 | 1 | Active session exists (state.json status=running) | Resume | — |
 | 2 | --re-run flag + previous failures | Re-run | — |
-| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test |
-| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen |
-| 5 | Default | code | quality-integration-test |
+| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test (separate skill) |
+| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen (separate skill) |
+| 5 | Default | code | quality-integration-test (separate skill) |
 
 Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
 

package/.agy/skills/quality-refactor/SKILL.md

@@ -48,7 +48,7 @@ After successful refactoring, ask user once: "Record refactoring pattern as codi
 
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)
-- Test failures after refactor → `/quality-debug {scope}`
+- Test failures after refactor → `/quality-debug "test failures after refactor in {scope}"`
 - No test suite available → `/quality-auto-test {phase}`
 </execution>
 

package/.agy/skills/quality-retrospective/SKILL.md

@@ -15,7 +15,7 @@ allowed-tools:
   - write_to_file
 ---
 <purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
 </purpose>
 
 <required_reading>
@@ -72,7 +72,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `view_file(AbsolutePath="<agy-skills-dir>/manage-learn/SKILL.md") + execute inline (args: "tip ...")`
-- [ ] `specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
+- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
 - [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library

package/.agy/skills/security-audit/SKILL.md

@@ -18,6 +18,10 @@ Systematic security audit covering OWASP Top 10, dependency supply chain, secret
 CI/CD pipeline review, and optional STRIDE threat modeling. Three tiers control depth vs speed.
 </purpose>
 
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
 <context>
 $ARGUMENTS — Parse tier and scope:
 - Tier: `quick` (default) | `standard` | `deep`
@@ -145,6 +149,26 @@ CONCERNS: {count} critical findings require immediate action
 NEXT: /quality-review
 --- END STATUS ---
 ```
+
+**Register artifact on completion** (so retrospective/harvest can trace this audit):
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // RVW-NNN (security-audit reuses review type)
+  type: "review",
+  subtype: "security-audit",
+  milestone: current_milestone || null,
+  phase: target_phase || null,
+  scope: target_phase ? "phase" : "standalone",
+  path: "scratch/{YYYYMMDD}-security-audit-{tier}-{slug}",
+  status: critical_count == 0 ? "completed" : "completed_with_concerns",
+  tier: tier,                              // quick|standard|deep
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+Write findings report to the same `path` (severity matrix, file:line refs, remediation).
 </execution>
 
 <success_criteria>

package/.agy/skills/spec-remove/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: <entry-id>
+argument-hint: <entry-id> [--cascade]
 allowed-tools:
   - ask_question
   - grep_search
@@ -25,6 +25,9 @@ $ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-con
 **Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
 
 **Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+
+**Flags:**
+- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
 </context>
 
 <execution>
@@ -46,5 +49,6 @@ Follow '~/.maestro/workflows/specs-remove.md' completely.
 - [ ] User confirmed removal (unless -y flag)
 - [ ] Entry removed from container file via `maestro wiki remove-entry`
 - [ ] Wiki index auto-updated
-- [ ] Confirmation displayed with removed entry details
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
 </success_criteria>

package/.claude/agents/role-design-author.md

@@ -17,9 +17,9 @@ You produce a set of analysis files for one role in a brainstorm session, organi
 | Field | Required | Notes |
 |---|---|---|
 | `role_name` | yes | kebab-case slug, e.g. `system-architect` |
-| `role_template_path` | yes | `~/.maestro/templates/planning-roles/{role}.md` |
-| `guidance_path` | yes | path to `guidance-specification.md` |
-| `output_dir` | yes | absolute path to role folder — `{session_dir}/{role}/` |
+| `role_template_path` | yes | **absolute** path to `planning-roles/{role}.md` (orchestrator MUST expand `~/`) |
+| `guidance_path` | yes | **absolute** path to `guidance-specification.md` |
+| `output_dir` | yes | **absolute** path to role folder — `{session_dir}/{role}/`. If you receive a relative path or a literal `{output_dir}` placeholder, fail fast with `TASK BLOCKED: output_dir is not absolute`. |
 | `feature_list` | optional | F-id + slug + title rows; if missing, fall back to non-feature organization |
 | `design_research` | optional | external research markdown to integrate as evidence |
 | `project_specs` | optional | pre-loaded `maestro spec load` output |
@@ -28,7 +28,9 @@ You produce a set of analysis files for one role in a brainstorm session, organi
 
 ## Output Contract
 
-Write files to `output_dir/`. Do NOT write files anywhere else.
+Write files to `output_dir/` using the Write tool. Do NOT write files anywhere else. Do NOT return analysis as chat text — files on disk are the only valid deliverable. After writing, verify with Glob that `analysis.md` exists; if any Write call fails (e.g. relative path rejected), fail fast with `TASK BLOCKED`.
+
+**Authority note**: This Output Contract is authoritative for file layout. The role template at `role_template_path` may contain a legacy "## Brainstorming Analysis Structure" section describing a single-file layout — ignore it for file structure. Use the role template ONLY to source §3 subsection headings (via its "## MUST-Have Sections (Brainstorming)" block when present).
 
 ### File Structure
 

package/.claude/commands/learn-decompose.md

@@ -25,8 +25,8 @@ $ARGUMENTS — target path/module and optional flags.
 - `--save-spec`: `Skill("spec-add")` for each new pattern
 - `--save-wiki`: create wiki note per dimension group
 
-**Storage read**: target files + `coding-conventions.md` + `specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `specs/learnings.md`
+**Storage read**: target files + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
 </context>
 
 <state_machine>
@@ -47,7 +47,7 @@ S_RESOLVE:
   → S_RESOLVE     WHEN: unresolvable                     DO: AskUserQuestion
 
 S_DEDUP:
-  → S_ANALYZE     DO: read coding-conventions.md + specs/learnings.md → build known pattern set
+  → S_ANALYZE     DO: read coding-conventions.md + .workflow/specs/learnings.md → build known pattern set
 
 S_ANALYZE:
   → S_CROSSREF    DO: A_PARALLEL_DIMENSION_ANALYSIS
@@ -59,7 +59,7 @@ S_CATALOG:
   → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
 
 S_PERSIST:
-  → END           DO: append specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
+  → END           DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
 
 </transitions>
 
@@ -86,7 +86,7 @@ For each finding, match against known pattern set:
 | Status | Condition |
 |--------|-----------|
 | documented | Already in coding-conventions.md |
-| known | In specs/learnings.md |
+| known | In .workflow/specs/learnings.md |
 | new | Not seen before |
 
 Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).
@@ -106,7 +106,7 @@ Flag contradictions (finding conflicts with documented convention). Merge duplic
 <success_criteria>
 - [ ] 4 dimension agents spawned in parallel, findings with anchors
 - [ ] Cross-reference: documented/known/new status assigned
-- [ ] Pattern catalog written + specs/learnings.md appended
+- [ ] Pattern catalog written + .workflow/specs/learnings.md appended
 </success_criteria>
 
 <next_step_routing>