maestro-flow 0.4.12 → 0.4.14

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

@@ -40,7 +40,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 通过 `read_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；禁止 `invoke_skill({skill})` 调用
+- internal step：优先通过 `read_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；不要对 internal step 使用 `invoke_skill({skill})` 调用
+- **必须遵循 `<required_reading>` / `<deferred_reading>` 标签**：命令 .md 通常采用"入口 + workflow"形式，主体逻辑放在 workflow 文件中并通过 `<required_reading>` 引用；不加载 required_reading 会导致命令执行不完整
+- decision 节点例外：A_EXEC_DECISION 必须使用 `invoke_skill({ skill: "maestro-ralph" })` 进行 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
@@ -48,10 +50,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>
@@ -159,12 +164,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. `read_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. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 invoke_skill() 或 delegate
-8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
-9. Return success / failure
+4. `read_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` 引用 → 立刻 `read_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
 
@@ -252,7 +266,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
 
@@ -261,6 +277,9 @@ Write enriched args back to status.json.
 - [ ] Placeholders resolved；per-skill enrichment 正确
 - [ ] Decision 节点 invoke_skill("maestro-ralph") handoff
 - [ ] Internal 节点通过 read_file({step.command_path}) 内联执行，禁止 invoke_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/.agents/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_user 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_user 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 `delegate_subagent(subagent_type: Explore)` / `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/.agents/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/.agents/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/.agents/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/.agents/skills/manage-knowhow/SKILL.md

@@ -55,7 +55,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/.agents/skills/manage-learn/SKILL.md

@@ -32,7 +32,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_user to prompt for text
 
@@ -49,19 +49,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/.agents/skills/quality-auto-test/SKILL.md

@@ -42,13 +42,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/.agents/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/.agents/skills/quality-retrospective/SKILL.md

@@ -15,7 +15,7 @@ allowed-tools:
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
 <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 `invoke_skill({ skill: "manage-learn", 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/.agents/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/.agents/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:
   - read_file
   - write_file
@@ -28,6 +28,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>
@@ -49,5 +52,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/.agy/agents/role-design-author.md

@@ -16,9 +16,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 |
@@ -27,7 +27,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/.agy/skills/learn-decompose/SKILL.md

@@ -27,8 +27,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>
@@ -49,7 +49,7 @@ S_RESOLVE:
   → S_RESOLVE     WHEN: unresolvable                     DO: ask_question
 
 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
@@ -61,7 +61,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>
 
@@ -88,7 +88,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).
@@ -108,7 +108,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>

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

@@ -14,7 +14,7 @@ allowed-tools:
   - write_to_file
 ---
 <purpose>
-Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
+Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -32,8 +32,8 @@ $ARGUMENTS — target and optional flags.
 - `--depth deep`: every function, every branch, every assumption
 - `--save-wiki`: create wiki note entry with reading notes
 
-**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `specs/learnings.md`
+**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
 </context>
 
 <state_machine>
@@ -66,7 +66,7 @@ S_EXTRACT:
   → S_PERSIST     DO: A_EXTRACT_PATTERNS
 
 S_PERSIST:
-  → END           DO: write KNW-follow + append specs/learnings.md [+ wiki note if --save-wiki]
+  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
 
 </transitions>
 

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

@@ -30,9 +30,9 @@ $ARGUMENTS — question text and optional flags.
 - `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
 - `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — evolving understanding
 - `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
-- `specs/learnings.md` — appended `<spec-entry>` blocks
+- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
 
-**Storage read**: source files in scope + `maestro wiki search` + `specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
+**Storage read**: source files in scope + `maestro wiki search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
 </context>
 
 <state_machine>
@@ -45,7 +45,7 @@ S_HYPOTHESIZE    — 生成假设列表                                PERSIST:
 S_CLI_EXPLORE    — CLI 辅助探索（可选）                         PERSIST: evidence.ndjson (append)
 S_TEST           — 逐假设测试                                  PERSIST: evidence.ndjson + understanding.md
 S_ESCALATE       — 3-strike 升级                               PERSIST: —
-S_REPORT         — 综合报告 + persist                          PERSIST: report.md + specs/learnings.md
+S_REPORT         — 综合报告 + persist                          PERSIST: report.md + .workflow/specs/learnings.md
 </states>
 
 <transitions>
@@ -57,7 +57,7 @@ S_EVIDENCE:
   → S_PATTERN     DO: A_COLLECT_EVIDENCE
 
 S_PATTERN:
-  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + specs/learnings.md patterns
+  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns
 
 S_HYPOTHESIZE:
   → S_CLI_EXPLORE WHEN: CLI tools enabled AND hypotheses non-trivial    DO: A_FORM_HYPOTHESES
@@ -85,7 +85,7 @@ S_REPORT:
 ### A_FRAME_QUESTION
 
 1. Parse question, generate slug, create KNW-investigate-{slug}/
-2. Search prior knowledge: `maestro wiki search "<question>"` + search specs/learnings.md + read debug-notes.md
+2. Search prior knowledge: `maestro wiki search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
 3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
 
 ### A_COLLECT_EVIDENCE
@@ -126,7 +126,7 @@ For each hypothesis (rank order):
 ### A_SYNTHESIZE_REPORT
 
 Write report.md: Answer (or INCONCLUSIVE), Evidence Trail table, Hypotheses Tested table, Key Learnings, Open Questions.
-Append to specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
+Append to .workflow/specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
 
 </actions>
 

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

@@ -16,7 +16,7 @@ allowed-tools:
 <purpose>
 Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
 
-All insights persist to `specs/learnings.md` as `<spec-entry>` blocks.
+All insights persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -30,9 +30,9 @@ $ARGUMENTS — lens selection and scope flags.
 **Storage write**:
 - `.workflow/knowhow/KNW-retro-{date}.md` — unified report
 - `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
-- `specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
+- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
 
-**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
+**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `.workflow/specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
 </context>
 
 <state_machine>
@@ -42,7 +42,7 @@ S_PARSE       — 解析 lens + flags                           PERSIST: —
 S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
 S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
 S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
-S_PERSIST     — 写 spec-entry 块                             PERSIST: specs/learnings.md
+S_PERSIST     — 写 spec-entry 块                             PERSIST: .workflow/specs/learnings.md
 </states>
 
 <transitions>
@@ -62,7 +62,7 @@ S_REPORT:
   → S_PERSIST     DO: write KNW-retro-{date}.md + .json
 
 S_PERSIST:
-  → END           DO: append insights to specs/learnings.md via `maestro spec add learning`
+  → END           DO: append insights to .workflow/specs/learnings.md via `maestro spec add learning`
   RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
 
 </transitions>
@@ -104,7 +104,7 @@ maestro wiki search "decision" --json
 maestro wiki list --type spec --json
 git log --oneline --all --grep="decision\|chose\|decided" -20
 ```
-Plus: architecture-constraints.md, phase context Locked/Deferred sections, specs/learnings.md.
+Plus: architecture-constraints.md, phase context Locked/Deferred sections, .workflow/specs/learnings.md.
 Apply --phase/--tag/--id filters.
 
 **Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
@@ -148,7 +148,7 @@ Apply --phase/--tag/--id filters.
 - [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
 - [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
 - [ ] Unified report + structured JSON written
-- [ ] specs/learnings.md appended with stable INS-ids
+- [ ] .workflow/specs/learnings.md appended with stable INS-ids
 </success_criteria>
 
 <next_step_routing>

package/.agy/skills/learn-second-opinion/SKILL.md

@@ -19,7 +19,7 @@ Structured second-opinion on code, decisions, or plans. Three modes:
 - **challenge**: single adversarial agent — break assumptions, propose alternatives
 - **consult**: interactive Q&A — agent studies target, answers your questions
 
-Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
+Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -47,7 +47,7 @@ S_RESOLVE    — 解析 target                          PERSIST: —
 S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
 S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
 S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
-S_PERSIST    — 写文件、append specs/learnings.md      PERSIST: knowhow files
+S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: knowhow files
 </states>
 
 <transitions>
@@ -68,7 +68,7 @@ S_SYNTHESIZE:
   → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
 
 S_PERSIST:
-  → END           DO: write KNW-opinion + append <spec-entry> blocks to specs/learnings.md
+  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
 
 </transitions>
 
@@ -114,7 +114,7 @@ Interactive loop:
 <success_criteria>
 - [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
 - [ ] Synthesis with agreements, disagreements, verdict
-- [ ] Report written + findings appended to specs/learnings.md
+- [ ] Report written + findings appended to .workflow/specs/learnings.md
 </success_criteria>
 
 <next_step_routing>

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

@@ -147,6 +147,7 @@ On validation failure: fix JSON, retry (max 2).
 | Code | Condition | Recovery |
 |------|-----------|----------|
 | E001 | No signals from any source | Verify artifact paths or provide description |
+| E002 | Signal source path invalid or unreadable | Check `--from-*` path; ensure artifact exists |
 | E003 | All signals are code bugs, not command gaps | Use /maestro-quick or /maestro-plan --gaps |
 | E004 | Overlay validation failed after 2 retries | Review JSON manually |
 | W001 | Some signals skipped (code bugs) | Route to appropriate fix command |

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

@@ -40,6 +40,12 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 - **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.
 
+**Disambiguation rule (mode selection):**
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as phase 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)
+
 **Flags:**
 - `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
 - `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
@@ -56,14 +62,15 @@ Scope routing, output directory format, artifact registration schema, and output
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (explicit phase number or unambiguous topic).
 
-- One decision per turn via ask_question with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option so the user can end the interview at any time.
-- Never ask what code can verify — resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, or Read.
+- 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`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, 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 `discussion.md` (top table) and mirrored into `context.md` "Interview Decisions". Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.
 - Scope guard: only ask about decisions owned by `analyze`. Do not prejudge plan/execute concerns.
 
 Decision points: scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold.
 
-Exit: on `Proceed now` or when all decision points are settled, write the table below to the top of `discussion.md` and mirror it into `context.md` under an `Interview Decisions` section:
+Exit: when all decision points are settled (or user explicitly signals to proceed), finalize session metadata. The decision table (populated incrementally during interview) uses this schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 

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

@@ -66,14 +66,15 @@ maestro-analyze → maestro-roadmap → maestro-plan
 <interview_protocol>
 Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
 
-- Ask one question per turn via ask_question and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total, and a `Proceed now` option.
-- Never ask what code can verify — resolve via `state.json`, existing artifacts, `maestro spec load`, or direct codebase exploration (Glob/Grep/Read) instead of prompting.
+- Ask one question per turn via ask_question and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. 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 artifacts, `maestro spec load`, direct codebase exploration (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 persisted into `blueprint-config.json` before the next question. Do NOT batch writeback to the end — partial decisions must already be on disk.
 - Walk the decision dependency tree depth-first: scope → spec type → focus areas → requirement priorities. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the specification. Do not pre-resolve roadmap phases or plan tasks — those belong to downstream commands.
 
 Decision points: scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration.
 
-Exit: on consensus or `Proceed now`, persist decisions in blueprint-config.json and proceed to Phase 1.
+Exit: on consensus or explicit user signal to proceed, finalize blueprint-config.json (decisions already written incrementally) and proceed to Phase 1.
 </interview_protocol>
 
 <execution>