maestro-flow 0.4.11 → 0.4.12

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

@@ -31,19 +31,23 @@ 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 MUST 通过 `view_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；禁止 `Skill({skill})` 调用
+- `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 +56,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 +129,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 +141,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 全文加载进当前会话
+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
 
-**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 +244,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,67 @@ 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; 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`.
+- 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 `Proceed now`, append the table below to a `Roadmap Decisions` section at the top of `.workflow/roadmap.md`:
+`| # | 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 +100,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/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)

package/.agy/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -75,7 +75,7 @@ After codebase exploration, scan results for context-aware trigger signals (base
 
 ## Phase 4: Context Packaging
 
-1. Write spec-config.json → <session>/spec/
+1. Write blueprint-config.json → <session>/spec/
 2. Write discovery-context.json → <session>/spec/
 3. Inline Discuss (DISCUSS-001):
    - Artifact: <session>/spec/discovery-context.json

package/.agy/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md

@@ -22,7 +22,7 @@
 2. Load quality gate thresholds from specs/quality-gates.md
 3. Score each dimension
 4. Run cross-document validation
-5. Generate readiness-report.md + spec-summary.md
+5. Generate readiness-report.md + blueprint-summary.md
 6. Run DISCUSS-003:
    - Artifact: <session>/spec/readiness-report.md
    - Perspectives: product, technical, quality, risk, coverage
@@ -41,4 +41,4 @@
 
 Write to <session>/artifacts/:
 - readiness-report.md: Dimension scores, issue list, traceability matrix
-- spec-summary.md: Executive summary of all spec docs
+- blueprint-summary.md: Executive summary of all spec docs

package/.agy/skills/team-lifecycle-v4/roles/writer/role.md

@@ -47,7 +47,7 @@ Template-driven document generation with progressive dependency loading.
 
 ### Inputs
 - Template from routing table
-- spec-config.json from <session>/spec/
+- blueprint-config.json from <session>/spec/
 - discovery-context.json from <session>/spec/
 - Prior decisions from context_accumulator (inner loop)
 - Discussion feedback from <session>/discussions/ (if exists)

package/.agy/skills/team-lifecycle-v4/templates/architecture.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
 ---
@@ -246,9 +246,9 @@ date: {timestamp}
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | ADR/requirement number |
 | `{slug}` | Auto-generated | Kebab-case from decision title |
-| `{has_codebase}` | spec-config.json | Whether existing codebase exists |
+| `{has_codebase}` | blueprint-config.json | Whether existing codebase exists |

package/.agy/skills/team-lifecycle-v4/templates/epics.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
   - ../architecture/_index.md
@@ -187,7 +187,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{EPIC}` | Auto-increment | Epic number (3 digits) |

package/.agy/skills/team-lifecycle-v4/templates/product-brief.md

@@ -23,7 +23,7 @@ generated_at: {timestamp}
 stepsCompleted: []
 version: 1
 dependencies:
-  - spec-config.json
+  - blueprint-config.json
 ---
 
 # Product Brief: {product_name}
@@ -117,7 +117,7 @@ dependencies:
 
 ## References
 
-- Derived from: [spec-config.json](spec-config.json)
+- Derived from: [blueprint-config.json](blueprint-config.json)
 - Next: [Requirements PRD](requirements.md)
 ```
 
@@ -125,7 +125,7 @@ dependencies:
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | Seed analysis | Product/feature name |
 | `{executive_summary}` | CLI synthesis | 2-3 sentence summary |

package/.agy/skills/team-lifecycle-v4/templates/requirements.md

@@ -36,7 +36,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
 ---
 
@@ -215,7 +215,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |

package/.claude/agents/cli-explore-agent.md

@@ -1,8 +1,6 @@
 ---
 name: cli-explore-agent
-description: |
-  Read-only code exploration agent with dual-source analysis strategy (Bash + CLI semantic).
-  Orchestrates 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation.
+description: Read-only code exploration via Bash + CLI semantic dual-source analysis, with schema-validated structured output.
 allowed-tools:
   - Read
   - Glob