maestro-flow 0.4.11 → 0.4.13

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

@@ -31,19 +31,24 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 
 | Type | Execution | Flow after |
 |------|-----------|------------|
-| decision (ralph-only) | `Skill("maestro-ralph")` — ralph re-evaluates | Execution ends here |
-| internal | `Skill({ skill, args })` — synchronous | Self-invoke next |
-| external | `maestro delegate --to claude --mode write` | STOP → callback → self-invoke |
-
-HARD RULE: External nodes ALWAYS append `-y` to skill args inside the prompt — delegate sessions are non-interactive.
-HARD RULE: External nodes ALWAYS delegate to `claude` — only Claude Code can execute slash-command skills.
+| decision (ralph-only) | `Skill("maestro-ralph")` | Execution ends here |
+| internal (default) | `view_file({file_path: step.command_path})` + 内联解释执行 | Self-invoke next |
+| external (opt-in) | `maestro delegate --to claude --mode write` (STOP → callback) | Self-invoke next |
+
+HARD RULES:
+- internal step：优先通过 `view_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；不要对 internal step 使用 `Skill({skill})` 调用
+- 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
 </context>
 
 <invariants>
-1. **Every step via Skill() or delegate** — never simulate or inline a skill's work
-2. **External → claude only** — `session.cli_tool` is for analysis delegates, NOT execution
-3. **Self-invocation chain** — continues until all steps complete or session paused
-4. **Status.json updated after every change** — resume-safe
+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
 </invariants>
 
 <state_machine>
@@ -52,8 +57,8 @@ HARD RULE: External nodes ALWAYS delegate to `claude` — only Claude Code can e
 S_LOCATE        — 定位 session + 找下一个 pending step   PERSIST: —
 S_RESOLVE_ARGS  — 解析占位符 + 丰富参数                  PERSIST: step.args (enriched)
 S_EXECUTE       — 执行当前 step                          PERSIST: step.status = "running", session.current_step
-S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.status, session.context
-S_HANDLE_FAIL   — 处理失败（重试/跳过/中止）              PERSIST: step.status, session.status
+S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.completion_*, step.status, session.context
+S_HANDLE_FAIL   — 处理失败                               PERSIST: step.status, session.status
 S_COMPLETE      — 所有 step 完成                         PERSIST: session.status = "completed"
 S_FALLBACK      — 无 session 可执行                      PERSIST: —
 </states>
@@ -125,9 +130,9 @@ S_FALLBACK:
 | maestro-brainstorm | topic | `"{intent}"` |
 | maestro-roadmap | description | `"{intent}"` |
 | maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
-| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` if standalone |
-| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` if standalone |
-| quality-debug | gap context | Read previous step's error/gap from artifact dir |
+| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| quality-debug | gap context | Read previous step's error/gap |
 | quality-* | phase | `{phase}` |
 
 **Artifact dir resolution for --dir:**
@@ -137,91 +142,97 @@ plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
 execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
 ```
 
-Write enriched args back to status.json (resume-safe).
+Write enriched args back to status.json.
 
 ### A_EXEC_DECISION
 
 1. Mark step running, write status.json
-2. Display: `[{index}/{total}] ◆ {skill} [decision] Retry: {retry}/{max}`
-3. `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph/SKILL.md") + execute inline` — ralph detects running decision → evaluates → handoff
-4. **This execution ends here** — ralph handles the handoff back
+2. Display: `[{index}/{total}] ◆ {decision} Retry: {retry}/{max}`
+3. `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph/SKILL.md") + execute inline` — ralph 评估 + handoff
+4. 执行在此结束
 
 ### A_EXEC_INTERNAL
 
-1. Mark step running, write status.json
-2. Display: `[{index}/{total}] {skill} [internal]`
-3. Resolve auto flag: `auto ? (flag_map[skill] || "") : ""`
-4. `Skill({ skill: next.skill, args: effective_args })`
-5. Return success/failure
+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 全文加载进当前会话（prefer Read over Skill for internal steps；decision 节点另行使用 Skill 见 A_EXEC_DECISION）
+5. 解析 frontmatter `argument-hint` 与 `<purpose>/<state_machine>/<actions>` 等指令块
+6. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
+7. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate
+8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
+9. Return success / failure
 
-**Auto flag map:** all lifecycle skills → `-y`; `quality-test` → `-y --auto-fix`; unlisted internal → no flag
+**Auto flag map**: 所有 lifecycle skill → `-y`; `quality-test` → `-y --auto-fix`; 未列出 → 无 flag
 
 ### A_EXEC_EXTERNAL
 
+仅当 `step.type == "external"` 时使用（默认链路不产生）。
+
 1. Mark step running, write status.json
-2. Display: `[{index}/{total}] ⚡ {skill} [external]`
-3. Always append `-y` to skill args (delegates are non-interactive): `flag = flag_map[skill] || "-y"`
+2. Display: `[{index}/{total}] ⚡ {step.skill} [external]`
+3. 始终在 prompt 内追加 `-y`（delegate session 非交互）：`flag = flag_map[step.skill] || "-y"`
 4. Execute:
    ```
    run_command({
-     command: `maestro delegate "/${skill} ${effective_args}" --to claude --mode write`,
+     command: `maestro delegate "/${step.skill} ${effective_args}" --to claude --mode write`,
      run_in_background: true, timeout: 600000
    })
    STOP — wait for callback.
    ```
-5. On callback: retrieve output → S_POST_EXEC or S_HANDLE_FAIL
+5. On callback: 把回调输出视为 step 的执行结果 → S_POST_EXEC / S_HANDLE_FAIL
 
 ### A_MARK_COMPLETE
 
-1. `step.status = "completed"`, `step.completed_at = now`
-2. Scan output for context signals:
-   - `PHASE: N` → session.phase
-   - `scratch_dir: path` → context.scratch_dir
-   - `SPEC-xxx` → context.spec_session_id
-3. Scan output for `--- COMPLETION STATUS ---` block. If found, parse and map:
-   - `STATUS: DONE` → `step.status = "completed"`
-   - `STATUS: DONE_WITH_CONCERNS` → `step.status = "completed"`, `step.concerns = CONCERNS value`
-   - `STATUS: NEEDS_RETRY` → trigger retry: set `step.status = "pending"`, `step.retried = true` → S_HANDLE_FAIL
-   - `STATUS: BLOCKED` → `session.status = "paused"`, display blocker reason from CONCERNS
-   - `STATUS: NEEDS_CONTEXT` → `session.status = "paused"`, display context gap from CONCERNS
-   - If no `--- COMPLETION STATUS ---` block found → fall back to existing heuristic (backward compatible)
-4. Write status.json
-5. Display: `[{index}/{total}] ✓ {skill} completed`
+1. 从 step 输出中提取 `--- COMPLETION STATUS ---` 块（required）
+2. 解析并写入：
+   - `STATUS: DONE` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE"`
+   - `STATUS: DONE_WITH_CONCERNS` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE_WITH_CONCERNS"`, `step.concerns = <CONCERNS>`
+   - `STATUS: NEEDS_RETRY` → `step.status = "pending"`, `step.retried = true`, `step.completion_confirmed = false`, → S_HANDLE_FAIL
+   - `STATUS: BLOCKED` / `NEEDS_CONTEXT` → `session.status = "paused"`, `step.completion_status` 记录原因, `step.completion_confirmed = false`
+   - 缺失 `--- COMPLETION STATUS ---` 块 → 视为 NEEDS_RETRY（不允许 heuristic fallback）
+3. 写入 `step.completion_evidence`（artifact 路径 / 关键输出节选）
+4. 扫描输出抓取 context 信号：`PHASE: N` → session.phase；`scratch_dir: path` → context.scratch_dir；`BLP-xxx` → context.blueprint_session_id
+5. `step.completed_at = now`，写 status.json
+6. **Sub-goal evidence 校验**（task_decomposition 存在时）：若 `step.goal_ref` 对应子目标的 `lifecycle` 覆盖当前 stage 且 evidence artifact 已生成 → 暂不直接置 done，仍交由 post-goal-audit 决策；仅在 step 显式确认时更新 `task_decomposition[*].completion_confirmed = false` 占位（保持 pending）
+7. Display: `[{index}/{total}] ✓ {step.skill} completed (confirmed)`
 
 ### A_RETRY
 
-1. `step.retried = true`, `step.status = "pending"`, `step.error = null`
+1. `step.retried = true`, `step.status = "pending"`, `step.error = null`, `step.completion_confirmed = false`
 2. Write status.json
 
 ### A_SKIP_STEP
 
-1. `step.status = "skipped"`
+1. `step.status = "skipped"`, `step.completion_confirmed = false`
 2. Write status.json
 
 ### A_PAUSE_SESSION
 
 1. `session.status = "paused"`, write status.json
-2. Display: `[{index}/{total}] ✗ {skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
+2. Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
 
 ### A_COMPLETE_SESSION
 
-1. `session.status = "completed"`, write status.json
-2. Display completion report:
+1. 校验：所有 step `completion_confirmed == true`（除 skipped）；task_decomposition 存在时校验 `task_decomposition_all_done == true`
+2. 任一校验失败 → 不标 completed，回 S_LOCATE 或 pause
+3. `session.status = "completed"`, write status.json
+4. Display completion report:
    ```
    ============================================================
      SESSION COMPLETE
    ============================================================
      Session:  {session_id} [{source}]
-     Steps:    {completed}/{total}
+     Steps:    {completed}/{total}   confirmed: {confirmed}/{completed}
 
-     [✓] 0.   maestro-plan 1            [internal]
-     [✓] 1. ⚡ maestro-execute 1         [external]
-     [✓] 2.   maestro-verify 1          [internal]
+     [✓] 0.   maestro-plan 1            [internal · global]
+     [✓] 1.   maestro-execute 1         [internal · project]
+     [✓] 2.   maestro-verify 1          [internal · global]
      [✓] 3. ◆ post-verify               [decision]
      ...
    ============================================================
    ```
-   Icons: `✓` completed, `—` skipped, `✗` failed, `◆` decision, `⚡` external
+   Icons: `✓` confirmed, `—` skipped, `✗` failed, `◆` decision, `⚡` external
 
 </actions>
 
@@ -234,22 +245,26 @@ Write enriched args back to status.json (resume-safe).
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
 | E001 | error | No running session found | Suggest /maestro or /maestro-ralph |
-| E002 | error | status.json corrupt | Show path, suggest manual check |
-| E003 | error | Delegate failed + user abort | Mark paused, suggest resume |
-| W001 | warning | Step completed with warnings | Log and continue |
+| E002 | error | step.command_path missing for internal step | Pause, ask ralph to rebuild step |
+| 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 |
+| W001 | warning | Step completed with concerns | Log and continue |
 
 ### Success Criteria
 
-- [ ] Session discovery covers both maestro-* and ralph-*
-- [ ] `-y` parsed from args OR inherited from session.auto_mode
-- [ ] Placeholders resolved from session context
-- [ ] Per-skill enrichment provides correct args
-- [ ] Decision nodes hand off to maestro-ralph via Skill()
-- [ ] Internal nodes execute via Skill() with auto flag
-- [ ] External nodes delegate to claude with `-y` in prompt args, run_in_background + STOP
-- [ ] Context signals propagate to status.json
-- [ ] Auto mode: retry once then pause
-- [ ] Interactive: ask_question retry/skip/abort
-- [ ] Self-invocation continues until complete or paused
+- [ ] Session discovery covers maestro-* and ralph-*
+- [ ] `-y` parsed from args 或 session.auto_mode
+- [ ] Placeholders resolved；per-skill enrichment 正确
+- [ ] Decision 节点 Skill("maestro-ralph") handoff
+- [ ] Internal 节点通过 view_file({step.command_path}) 内联执行，禁止 Skill()
+- [ ] External 仅在显式声明时走 delegate，prompt 必带 `-y`
+- [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
+- [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置
+- [ ] step.completion_evidence 记录 artifact path / 输出节选
+- [ ] Context signals 传播 status.json
+- [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
+- [ ] 自调用持续到全部 completion_confirmed 或 paused
+- [ ] A_COMPLETE_SESSION 校验全部 step confirmed + sub-goal all_done
 
 </appendix>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-roadmap
-description: Generate roadmap from requirements (light or full mode)
-argument-hint: <requirement> [--mode light|full] [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]
+description: Generate roadmap with milestone/phase structure from requirements or upstream context
+argument-hint: <requirement> [-y] [-c] [-m progressive|direct|auto] [--from <source>] [--revise [instructions]] [--review]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -15,16 +15,14 @@ allowed-tools:
   - write_to_file
 ---
 <purpose>
-Unified roadmap generation with two execution paths:
+Generate a milestone/phase roadmap from requirements or upstream context. Produces `.workflow/roadmap.md` with Milestone > Phase hierarchy ready for maestro-analyze and maestro-plan.
 
-- **Light mode** (default): Directly from requirements to roadmap. No specification documents.
-- **Full mode** (`--mode full`): 7-phase document chain (Product Brief → PRD → Architecture → Epics → Roadmap) producing a complete specification package in `.workflow/.spec/` plus `.workflow/roadmap.md`.
-
-Additional operation modes (light mode only):
+Operation modes:
+- **Create** (default): Build roadmap from requirements or upstream context
 - **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
 - **Review** (`--review`): Health assessment of current roadmap (read-only)
 
-Both modes produce `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
+For formal specification documents (Product Brief, PRD, Architecture, Epics), use `/maestro-blueprint` instead.
 </purpose>
 
 <required_reading>
@@ -33,73 +31,68 @@ Both modes produce `.workflow/roadmap.md` with milestone/phase structure ready f
 </required_reading>
 
 <deferred_reading>
-- [roadmap.md](~/.maestro/workflows/roadmap.md) — read when mode is light (default)
-- [spec-generate.md](~/.maestro/workflows/spec-generate.md) — read when mode is full
-- [spec-config.json](~/.maestro/templates/spec-config.json) — read when initializing spec configuration (full mode)
+- [roadmap.md](~/.maestro/workflows/roadmap.md) — read for roadmap generation workflow
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- requirement text, @file reference, or brainstorm session reference.
+$ARGUMENTS -- requirement text, @file reference, or upstream context source.
 
-**Flags (shared):**
-- `--mode light|full`: Execution path (default: light)
+**Flags:**
 - `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
 - `-c` / `--continue`: Resume from last checkpoint
-- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
-
-**Flags (light mode only):**
 - `-m progressive|direct|auto`: Decomposition strategy (default: auto)
+- `--from <source>`: Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json
+- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
 - `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress.
 - `--review`: Roadmap health assessment (read-only)
 
 **Input types:**
 - Direct text: `"Implement user authentication system with OAuth and 2FA"`
 - File reference: `@requirements.md`
-- Brainstorm import: `--from-brainstorm WFS-xxx`
+- Context import: `--from brainstorm:BRN-001` or `--from analyze:ANL-xxx` or `--from blueprint:BLP-xxx`
 - No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`
 
 **Pipeline position:**
 ```
-maestro-brainstorm (optional upstream)
-        ↓ guidance-specification.md
-maestro-init (project setup)
-        ↓ project.md, state.json, config.json
-maestro-roadmap [--mode light]     → roadmap.md directly
-maestro-roadmap --mode full        → spec package + roadmap.md
+maestro-brainstorm ─┐
+maestro-blueprint  ─┤ (optional upstream, parallel)
+maestro-analyze    ─┘ context-package.json
+        ↓
+maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
         ↓
-maestro-plan → maestro-execute → maestro-verify
+maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
 ```
 
-**Note (full mode):** `maestro-init` MUST run before `--mode full`. It creates the `.workflow/` directory and project context.
-
 ### Pre-load specs
 1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for phase decomposition — ensures roadmap respects documented decisions and boundaries.
 2. Optional — proceed without if unavailable.
 </context>
 
-<execution>
+<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).
 
-### Mode routing
+- 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`.
 
-1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
-2. Parse `--mode` flag:
-   - `light` or omitted → read `@~/.maestro/workflows/roadmap.md`, follow its process
-   - `full` → read `@~/.maestro/workflows/spec-generate.md`, follow its process
-3. If `--revise` or `--review` present → force light mode (these are light-mode-only operations)
+Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
 
-### Light mode (default)
+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>
 
-Follow `~/.maestro/workflows/roadmap.md` completely.
+<execution>
+
+1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
+2. Read `@~/.maestro/workflows/roadmap.md`, follow its process
 
 Sub-modes:
-- **Create** (default): Build roadmap from requirements
+- **Create** (default): Build roadmap from requirements or upstream context
 - **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
 - **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
 
-### Full mode (`--mode full`)
-
-Follow `~/.maestro/workflows/spec-generate.md` completely.
-
 ### Next-step routing on completion
 
 | Condition | Suggestion |
@@ -108,63 +101,32 @@ Follow `~/.maestro/workflows/spec-generate.md` completely.
 | Simple project, ready to plan | /maestro-plan 1 |
 | Need UI design first | /maestro-impeccable build |
 | View project dashboard | /manage-status |
-| Need project setup (full mode) | /maestro-init |
+| Need formal spec documents | /maestro-blueprint |
 </execution>
 
 <error_codes>
-
-**Shared:**
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Requirement/idea text or @file required | Prompt user for input |
-| E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
-| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
-| W005 | warning | External research agent failed | Continue without apiResearchContext |
-
-**Light mode:**
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
+| E002 | error | Context source not found (--from / --from-brainstorm) | Show available sessions/sources |
 | E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
 | E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
 | E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
 | W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
-
-**Full mode:**
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E006 | error | `.workflow/` not initialized | Run maestro-init first |
-| E007 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
-| W002 | warning | Codebase exploration failed | Continue without codebase context |
-| W003 | warning | Glossary has < 5 terms | Note in readiness check |
-| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
 </error_codes>
 
 <success_criteria>
-
-**Light mode:**
+- [ ] Interactive mode: interview decision table appended to `.workflow/roadmap.md` "Roadmap Decisions" section
 - [ ] Requirement parsed with goal, constraints, stakeholders
+- [ ] Milestones defined with deliverable targets and version tags
 - [ ] Decomposition strategy selected (progressive or direct)
-- [ ] Phases defined with success criteria, dependencies, and requirement mappings
+- [ ] Phases defined within milestones with success criteria, dependencies, and requirement mappings
 - [ ] Every Active requirement from project.md mapped to exactly one phase
 - [ ] No circular dependencies in phase ordering
 - [ ] User approved roadmap (or auto-approved with -y)
-- [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
+- [ ] `.workflow/roadmap.md` written with Milestone > Phase hierarchy, scope decisions, and progress table
 - [ ] No phase directories created (phases are labels in roadmap, not directories)
-
-**Full mode (in addition to light mode criteria for roadmap):**
-- [ ] `spec-config.json` created with session metadata and phase tracking
-- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
-- [ ] `glossary.json` with 5+ core terms for cross-document consistency
-- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
-- [ ] All requirements have RFC 2119 keywords and acceptance criteria
-- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
-- [ ] Architecture includes state machine, config model, error handling, observability (service type)
-- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
-- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
-- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
-- [ ] `spec-summary.md` with one-page executive summary
-- [ ] All documents have valid YAML frontmatter with session_id
-- [ ] Glossary terms used consistently across all documents
-- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
-- [ ] `.workflow/roadmap.md` written
+- [ ] Artifact registered in state.json with milestone entries
 </success_criteria>

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

@@ -14,7 +14,7 @@ allowed-tools:
 Run unified automated testing via CSV layer pipeline. Reads project state to auto-select the optimal scenario source — PRD specs (when spec package exists), coverage gaps (when Nyquist audit found gaps), or code exploration (default). All sources converge into a CSV pipeline: discover infrastructure → plan → build scenarios.csv → write tests per layer (spawn_agents_on_csv parallel) → execute → diagnose failures (spawn_agents_on_csv parallel) → iterate → report.
 
 Key mechanisms:
-- **Intelligent routing**: Reads `.tests/`, `.workflow/.spec/`, `verification.json` to auto-select source — no mode flag needed
+- **Intelligent routing**: Reads `.tests/`, `.workflow/blueprint/`, `verification.json` to auto-select source — no mode flag needed
 - **CSV parallel test writing**: Per-layer `spawn_agents_on_csv` — each agent writes one test file independently
 - **CSV parallel failure diagnosis**: Failed scenarios dispatched via `spawn_agents_on_csv` for classification + fix
 - **Unified iteration engine**: Nested inner loop (fix test_defects via diagnosis CSV, max 3/layer) + outer loop (adaptive strategy, max N iterations)
@@ -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>