maestro-flow 0.5.41 → 0.5.43

package/.agents/skills/maestro-milestone-complete/SKILL.md

@@ -29,6 +29,7 @@ Requires audit PASS; produces milestone archive and learnings.
 
 <context>
 Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+If $ARGUMENTS is empty AND current_milestone is null → raise E001 with message "No milestone specified and no current_milestone set in state.json. Provide a milestone identifier as argument."
 
 **Requires:** `/maestro-milestone-audit` should have passed.
 
@@ -61,7 +62,8 @@ Archive flow steps (validation, directory archival, artifact history, knowhow ex
 - BLOCKED if missing: knowhow extraction not attempted or project.md not updated — state advancement requires completed knowledge capture.
 
 **GATE 4: State Advancement → Completion**
-- REQUIRED: state.json updated — next milestone as current (standard) or current_milestone=null (adhoc).
+- REQUIRED: ask_user confirmation before state.json advancement — show current milestone, next milestone (or null for adhoc), and artifacts to clear. User must confirm or abort.
+- REQUIRED: state.json updated — next milestone as current (standard) or current_milestone=null (adhoc) (after confirmation).
 - REQUIRED: Roadmap snapshot saved (standard only).
 - BLOCKED if missing: state.json not advanced — project remains stuck on completed milestone.
 
@@ -75,9 +77,12 @@ After knowhow extraction (step 4), scan `learnings.md` for promotion candidates:
 2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
    → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
 
-3. **Wiki island check**: Auto-trigger `manage-wiki connect --fix` to link newly extracted knowledge.
+3. **Wiki island check**: ask_user "Run wiki-connect --fix to link newly extracted knowledge?" — execute `manage-wiki connect --fix` only if user confirms.
 
-If user confirms promotion, invoke `invoke_skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
+Each promotion candidate requires explicit user confirmation via ask_user before writing:
+- **"Promote"** → invoke `invoke_skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
+- **"Skip"** → do not promote this candidate; proceed to next.
+- **"Skip all"** → skip remaining candidates.
 
 **Adhoc milestone (D-008):** When completing an adhoc milestone, skip roadmap snapshot and do not advance to next milestone. Set `current_milestone = null`, `status = "idle"`. Adhoc milestones are self-contained — no successor in roadmap chain.
 </execution>

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

@@ -72,10 +72,13 @@ Follow '~/.maestro/workflows/milestone-release.md' completely.
 
 **GATE 3: Changelog → Tag/Push**
 - REQUIRED: CHANGELOG.md entry written with milestone summary + grouped changes.
-- REQUIRED: Release commit created with conventional message.
+- REQUIRED: ask_user confirmation before creating release commit — show version, changelog diff, and files to be committed. User must confirm or abort.
+- REQUIRED: Release commit created with conventional message (after confirmation).
 
-**GATE 4: Tag → Completion**
-- REQUIRED: Annotated git tag created (unless --no-tag).
+**GATE 4: Tag → Push → Completion**
+- REQUIRED: ask_user confirmation before git tag creation — show tag name and annotation (unless --no-tag). User must confirm or abort.
+- REQUIRED: Annotated git tag created (unless --no-tag) (after confirmation).
+- REQUIRED: ask_user confirmation before git push — show remote and refs to push (unless --no-push). User must confirm or abort.
 - REQUIRED: state.json updated with last_release_version + last_release_at.
 
 For `--dry-run`: print computed version, changelog diff, and tag name without side effects.
@@ -134,5 +137,6 @@ Status verdicts:
 - [ ] Release commit created with conventional message
 - [ ] Annotated git tag created (unless `--no-tag`)
 - [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
-- [ ] state.json updated with last_release_version + last_release_at timestamp
+- [ ] User confirmed before each destructive git operation (commit, tag, push) via ask_user
+- [ ] state.json updated with last_release_version + last_release_at timestamp (after ask_user confirmation)
 </success_criteria>

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

@@ -136,6 +136,15 @@ Handoff rules:
 - Support runtime variable placeholders: `{phase}`, `{description}`, `{session_id}`
 - Keep handoff block under 10 lines of markdown
 
+### 3.5. Content approval
+
+Display the full overlay JSON to the user. ask_user:
+- **"Approve & install"** — proceed to installation
+- **"Edit"** — user provides corrections, re-draft
+- **"Cancel"** — discard overlay, do not write
+
+Only write the overlay JSON file to `~/.maestro/overlays/<slug>.json` after user approval.
+
 ### 4. Install via `maestro overlay add`
 
 Run:

package/.agents/skills/maestro-plan/SKILL.md

@@ -40,6 +40,7 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
   - `analyze:ANL-xxx` → CONTEXT_DIR = artifact path, scope = "standalone"
   - `blueprint:BLP-xxx` → CONTEXT_DIR = blueprint path, scope = "standalone"
   - `@file` or `path/` → load context-package.json from path
+- `--tdd` — Enable TDD mode: generate test-first task structure (Red-Green-Refactor). See workflow `plan.md` § TDD Mode for task generation rules.
 - `--revise [instructions]` -- See workflow plan.md § Revise Mode
 - `--check <plan-dir>` -- See workflow plan.md § Check Mode
 
@@ -88,79 +89,22 @@ Follow '~/.maestro/workflows/plan.md' completely.
 - BLOCKED if missing: plan.json or TASK files not produced by planner agent — do not proceed to checking.
 
 **GATE P3.5 → P4: Boundary Grill → Plan Check**
-Run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
-Input: plan.json tasks + convergence criteria + upstream context. Scope guard: "only plan scope; do not re-analyze or re-scope".
-IF conflicts → results to plan.json `boundary_grill` section + affected TASK files. DEC conflicts add `boundary_warning` to confidence.
-NON-BLOCKING: warnings, not hard stops.
+- REQUIRED: Boundary grill executed per workflow boundary-grill.md.
+- NON-BLOCKING: conflicts logged as warnings, not hard stops.
 
 **GATE P4 → P5: Plan Check → User Confirmation**
 - REQUIRED: Plan-checker passed (or minor issues acknowledged).
-- REQUIRED: Boundary grill completed (conflicts resolved or accepted as risks).
+- REQUIRED: Boundary grill completed.
 - REQUIRED: Confidence scored with 5-dimension factor model.
 - REQUIRED: Pressure pass completed on highest-complexity task.
-- REQUIRED: If plan touches UI (检出 `dashboard/` 或 UI 关键词 `landing|page|dashboard|frontend|UI|component|界面`), each delivery wave has ≥1 `[UI-observable]` convergence criterion (vertical-slice delivery, not backend-only).
-- BLOCKED if: plan-checker found critical issues, OR UI plan missing `[UI-observable]` coverage — fix plan before presenting to user.
+- REQUIRED: UI plans have `[UI-observable]` convergence criteria per wave (details in workflow).
+- BLOCKED if: plan-checker found critical issues, OR UI plan missing `[UI-observable]` coverage.
 
 **GATE P5 → Completion: User Confirmation → Done**
 - REQUIRED: User confirmation captured (execute/modify/cancel).
 - REQUIRED: PLN artifact registered in state.json.
 - BLOCKED if missing: no user confirmation — do not register artifact or report completion.
 
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  "plan.json",                    // Task definitions, waves, summary
-  ".task/TASK-*.json" (per task)   // Individual task files with convergence criteria
-]
-```
-Every task MUST have `convergence.criteria[]` with grep-verifiable conditions. If any task lacks verifiable criteria: DO NOT report completion — fix the criteria first.
-
-### P3 Agent Constraint (MANDATORY)
-
-Main flow **MUST** spawn a planner agent (Agent tool) for P3 planning — inline planning by main flow is FORBIDDEN. The agent produces both `plan.json` and `.task/TASK-*.json` files. Main flow only passes context and validates output.
-
-### Codebase Docs Loading (P1 addition)
-
-During P1 Context Collection, after loading context files, load codebase documentation if available:
-
-```
-IF exists(.workflow/codebase/doc-index.json):
-  codebase_ctx = read_file(.workflow/codebase/ARCHITECTURE.md) + read_file(.workflow/codebase/FEATURES.md)
-  Pass codebase_ctx to planner agent as structural context
-ELSE:
-  display "W004: Codebase docs unavailable, continuing with code exploration only"
-```
-
-### Wiki Knowledge Search (P1 addition)
-
-During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
-
-```
-phase_keywords = extract key terms from goal/title (2-5 terms)
-wiki_result = shell("maestro search ${phase_keywords} --json 2>/dev/null")
-
-IF wiki_result exit code != 0 OR empty:
-  display "W003: Wiki search unavailable, continuing without prior knowledge"
-ELSE:
-  entries = JSON.parse(wiki_result).entries (limit to first 10)
-  wiki_context = structured block for downstream stages
-```
-
-### Issue Linkback (--gaps mode)
-
-After plan generation and checking, if `--gaps` mode was used, link TASK files back to issues bidirectionally:
-
-```
-For each created TASK-{NNN}.json that has issue_id:
-  Update corresponding issue in .workflow/issues/issues.jsonl:
-    task_refs: append TASK-{NNN} to array
-    task_plan_dir: relative path to .task/ directory
-    status: "planned"
-    updated_at: now()
-  Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
-```
-
 ### Mode: Revise / Check
 
 Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.

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

@@ -37,7 +37,7 @@ $ARGUMENTS — template slug/path, or flags.
 | skill | `invoke_skill(skill, args)` | sync |
 | command | `invoke_skill(skill, args)` | sync |
 | cli | `maestro delegate --to tool --mode mode` via `shell(run_in_background: true)` | async, STOP + wait |
-| agent | `delegate_subagent(subagent_type, prompt)` | configurable |
+| agent | `delegate_subagent(subagent_type, prompt)` — valid subagent_type: `"task"` (default), `"research"`, `"code"`. Unknown type falls back to `"task"`. | configurable |
 | checkpoint | State save + optional user pause | — |
 
 **Runtime reference resolution** in args_template:
@@ -107,7 +107,7 @@ S_EXEC_LOOP:
   → END           WHEN: checkpoint pause                    DO: set status=paused, display resume command
   → END           WHEN: abort chosen                        DO: set status=aborted, save progress
   GUARD: cli nodes → shell(run_in_background: true) + STOP, wait for callback
-  GUARD: on failure → on_fail: skip (log, advance) | retry (once) | abort (ask_user: Retry/Skip/Abort)
+  GUARD: on failure → on_fail: skip (log, advance) | retry (once) | abort (ask_user: Retry/Skip/Abort). Default on_fail when not specified: `abort` (prompt user via ask_user).
   GUARD: after step 3+ → display context hint "可随时 /maestro-player -c 恢复"
 
 S_COMPLETE:

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-quick
 description: Quick task execution, skip optional agents
-argument-hint: "[description] [--full] [--discuss]"
+argument-hint: "[description] [--full] [--discuss] [-y]"
 allowed-tools:
   - read_file
   - write_file
@@ -17,6 +17,7 @@ allowed-tools:
 <purpose>
 Execute small, ad-hoc tasks with workflow guarantees (atomic commits, state tracking) via a shortened pipeline.
 Flags --discuss and --full enable additional pipeline stages.
+**Implicit write**: state.json scratch task entry is written automatically as part of workflow tracking (no confirmation gate).
 </purpose>
 
 <required_reading>
@@ -29,6 +30,7 @@ $ARGUMENTS
 Parse for:
 - `--full` flag -- Enables plan-checking (max 2 iterations) and post-execution verification
 - `--discuss` flag -- Decision extraction before planning (gray areas, Locked/Free/Deferred classification)
+- `-y` / `--yes` flag -- Auto mode: skip commit confirmation, auto-approve state writes
 - Remaining text as task description
 
 ### Pre-load context
@@ -80,6 +82,6 @@ Task summaries MUST include concrete evidence of completion (files changed, test
 - [ ] Scratch task directory created under .workflow/scratch/
 - [ ] plan.json written with task definitions
 - [ ] All tasks executed with summaries written
-- [ ] state.json updated with scratch task entry
-- [ ] Commit created with task changes
+- [ ] state.json updated with scratch task entry (implicit — part of workflow tracking, no confirmation needed)
+- [ ] Commit created with task changes: stage ONLY files modified by the task (from `.summaries/TASK-*-summary.md` "Files modified" list); confirm with `ask_user` showing staged files and proposed commit message — unless `-y` is active, in which case auto-commit
 </success_criteria>

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

@@ -44,7 +44,7 @@ Remaining     → intent (amend_mode 时为 change_request)
 <invariants>
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
 2. **Handoff via invoke_skill("maestro-ralph-execute")** — 创建 session 后始终自动 handoff；decision 评估后始终 handoff
-3. **Decision delegates read-only** — `maestro delegate --role analyze --mode analysis`
+3. **Decision delegates read-only** — `maestro delegate --to <tool> --mode analysis`
 4. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（详见 invariant 8）
 5. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
 6. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE`（或 DONE_WITH_CONCERNS）写入；CLI 是唯一合法写入路径
@@ -474,11 +474,11 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
    ```
    maestro delegate "PURPOSE: 评估 {decision} 质量门结果
    TASK: 读取结果 | 分析状态 | 评估严重性 | 给出建议
-   EXPECTED: ---VERDICT--- STATUS/REASON/GAP_SUMMARY/CONFIDENCE(high|medium|low)/CONFIDENCE_SCORE(0-100)/WEAKEST_DIMENSION ---END---
+   EXPECTED: ---VERDICT--- STATUS(PASS|FAIL|PARTIAL|BLOCKED)/REASON/GAP_SUMMARY/CONFIDENCE(high|medium|low)/CONFIDENCE_SCORE(0-100)/WEAKEST_DIMENSION ---END---
    CONSTRAINTS: 只评估 | 置信度<60% 倾向 fix | retry {n}/{max} 达上限必须 escalate"
-   --role analyze --mode analysis
+   --to {session.cli_tool} --mode analysis
    ```
-6. On callback: parse verdict; if parse fails → fallback STATUS="fix", BUT MUST set `parse_failed: true` and `confidence_score: 0` in decision log (invariant 13). Subsequent steps inherit LOW CONFIDENCE flag.
+6. On callback: parse verdict block — STATUS must match strict enum `PASS|FAIL|PARTIAL|BLOCKED`; any other value → parse failure. If parse fails → fallback STATUS="fix", BUT MUST set `parse_failed: true` and `confidence_score: 0` in decision log (invariant 13). Subsequent steps inherit LOW CONFIDENCE flag.
 7. Confidence adjustment: <60 + proceed → fix; >95 + fix + retry>0 → suggest proceed
 8. **Decision log**: Append to `{session_dir}/decisions.ndjson`:
    ```json
@@ -547,7 +547,7 @@ Runs only when `task_decomposition` present.
      - 严格按 done_when 判定；evidence 缺失 → unmet
      - 不得建议超出 boundary_contract 的修改
    "
-   --role analyze --mode analysis
+   --to {session.cli_tool} --mode analysis
    ```
 4. On callback: 对每个 met 子目标，set `task_decomposition[i].status="done"` + `completion_confirmed=true` + `completed_at=now`
 5. Append `{session_dir}/decisions.ndjson` with `"type": "goal-gate"`, `unmet_count`, `unmet_ids`
@@ -594,7 +594,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
      - aligned 阈值：≥80% 已完成产出直接服务 intent
      - 单个 step 触碰 out_of_scope → 直接判 drifted
      - goal_changelog 存在 → 以最新 after.goals 为基准"
-   --role analyze --mode analysis
+   --to {session.cli_tool} --mode analysis
    ```
 3. On callback: parse verdict
 4. Append `{session_dir}/decisions.ndjson`：`{ "id": "DEC-{ts}", "type": "reground-gate", "source": "ralph", "node_id": "post-reground", "verdict": "{aligned|drifted}", "confidence_score": {N}, "drift_description": "...", "corrective_action": "..." }`
@@ -679,7 +679,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
 |-------|------|------|
 | 1. 快照 | 读 `task_decomposition` + `boundary_contract` + 已完成 steps 的 `completion_summary` | Display: 目标列表 + 进度 |
 | 2. 解析 | `change_request` 非空 → 直接用；为空 → ask_user（修改/新增/移除/调整边界） | `change_type` + `change_request` |
-| 3. Mini Grill | `maestro delegate --role analyze --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
+| 3. Mini Grill | `maestro delegate --to {session.cli_tool} --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
 | 4. 确认 | ask_user：应用并继续 / 仅改目标 / 取消 | 用户选择 |
 | 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff ralph-execute |
 
@@ -892,7 +892,7 @@ decision:post-goal-audit {retry+1}
 - [ ] planning_mode 显式决定；unified=无 `{phase}`, independent=带 `{phase}`
 - [ ] specs 预检：lifecycle_position 在 init 之后 + `.workflow/specs/` 不存在 → 链路最前面插入 `spec-setup`
 - [ ] Chain 必须以 `milestone-complete` 结尾
-- [ ] Decision nodes 由 maestro delegate --role analyze 评估
+- [ ] Decision nodes 由 maestro delegate --to {session.cli_tool} --mode analysis 评估
 - [ ] Ralph 不执行 step，只 evaluate；invoke_skill("maestro-ralph-execute") handoff
 - [ ] Phase-level deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
 - [ ] Phase-level plan step 运行时获得 `--from analyze:{phase_analyze_id}`（由 ralph-execute 从 state.json 查找注入）