maestro-flow 0.5.41 → 0.5.43

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

@@ -1,13 +1,14 @@
 ---
 name: maestro-brainstorm
 description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: [topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]
+argument-hint: [topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG] [--review-only] [--from <source>]
 allowed-tools:
   - ask_question
   - define_subagent
   - grep_search
   - invoke_subagent
   - manage_subagents
+  - replace_file_content
   - run_command
   - send_message
   - view_file
@@ -53,6 +54,8 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 | `--skip-questions` | Skip context gathering questions | false |
 | `--include-questions` | Force context gathering even if analysis exists | false |
 | `--style-skill PKG` | Style package for ui-designer role | — |
+| `--review-only` | Run cross-role review on existing analyses without re-running role analysis | false |
+| `--from <source>` | Load upstream context package (grill:ID, blueprint:ID, @file, or path) | — |
 
 ### Pre-load specs
 1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
@@ -92,35 +95,15 @@ These gates apply to Auto mode (full pipeline). Do NOT advance past a gate until
 - BLOCKED if missing: complete all role analyses before spawning cross-role-reviewer.
 
 **GATE 2.5: Cross-Role Review → Boundary Grill** (Step 4.5 → Step 4.6)
-Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-role-reviewer output.
-Input: reviewer findings + role Decision Digests. Scope guard: "only brainstorm decisions; do not pre-resolve roadmap/plan choices".
-IF conflicts → results to `guidance-specification.md` §12.5 + feed into GATE 3. NON-BLOCKING.
+- REQUIRED: Boundary grill executed per workflow boundary-grill.md after cross-role review.
+- NON-BLOCKING: conflicts logged as warnings.
 
 **GATE 3: Cross-Role Review → Completion** (Step 4.5/4.6 → Report)
 - REQUIRED: Cross-role-reviewer output received with `patch_targets[]`.
-- REQUIRED: Boundary grill completed (if conflicts detected, results logged).
-- REQUIRED: If findings > 0, resolutions applied via Edit AND logged in `guidance-specification.md` §12.
-- REQUIRED: If findings == 0, final report explicitly states "No cross-role issues detected".
+- REQUIRED: Boundary grill completed.
+- REQUIRED: Resolutions applied and logged (details in workflow).
 - BLOCKED if missing: complete review synthesis before reporting.
 
-### Artifact Verification (before completion report)
-
-```
-AUTO_MODE_REQUIRED = [
-  "guidance-specification.md",            // Step 1
-  "{role}/analysis.md" (per selected role), // Step 3
-  "{role}/analysis-F-*.md" (per feature),   // Step 3
-]
-```
-If any artifact is missing: DO NOT report completion. Go back and produce the missing artifact.
-
-### Evidence Requirement
-
-Role analysis findings in `{role}/analysis.md` §2 Decision Digest MUST cite concrete evidence:
-- Code references (file:line), API endpoints, data models from the codebase
-- User-provided constraints from interview
-- Cross-role references to other role analyses
-Decisions without evidence are flagged LOW CONFIDENCE.
 </execution>
 
 <completion>

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

@@ -45,6 +45,7 @@ S_CONFIRM         — 展示计划、用户确认（-y 跳过）              PE
 S_FANOUT          — 构建 prompt、并行启动 delegate、STOP       PERSIST: —
 S_COLLECT         — 回调到达、收集结果                          PERSIST: per-tool outputs
 S_CROSS_VERIFY    — 分类发现（共识/冲突/独有）                  PERSIST: —
+S_BOUNDARY_GRILL  — 边界冲突检测与解决                          PERSIST: —
 S_SYNTHESIZE      — 解决冲突、生成 3 个输出文件                 PERSIST: outputs
 S_REGISTER        — 注册 CLB artifact                          PERSIST: state.json
 S_REPORT          — 显示摘要 + next-step routing               PERSIST: —
@@ -86,7 +87,9 @@ S_SYNTHESIZE:
   → S_REGISTER      DO: A_GENERATE_OUTPUTS
 
 S_REGISTER:
-  → S_REPORT        DO: append CLB artifact to state.json (type: collab, scope: adhoc)
+  → S_REPORT        WHEN: user confirms or -y    DO: append CLB artifact to state.json (type: collab, scope: adhoc)
+  → S_REPORT        WHEN: user declines           DO: skip artifact registration, proceed to report
+  GUARD: ask_question "Register collab artifact to state.json?" (skipped if -y)
 
 S_REPORT:
   → END             DO: display summary (requirement, tools, consensus_level, per-tool status, artifact id, output dir)
@@ -98,8 +101,9 @@ S_REPORT:
 ### A_DISCOVER_TOOLS
 
 ```
-run_command("maestro tools list --json 2>/dev/null || cat ~/.maestro/cli-tools.json")
+run_command("maestro tools list --json 2>$null || cat ~/.maestro/cli-tools.json")
 ```
+**Note:** Shell commands MUST use the Bash tool (not PowerShell). Use POSIX syntax within Bash calls.
 Filter: enabled == true. If --mode write: exclude type == "api-endpoint".
 Auto-select (no --tools): first 3 eligible in config order.
 

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

@@ -411,7 +411,10 @@ Collect task outcome data:
 
 ```bash
 # Detect files changed since companion doc creation
-git diff --name-only --since="{companion_created_timestamp}"
+# Use git log --since for time-based filtering, then git diff for the range
+git log --since="{companion_created_timestamp}" --format="%H" -1  # get oldest commit in range
+git diff --name-only {oldest_commit}..HEAD                         # diff from that commit to HEAD
+# Fallback if no commits since timestamp: git diff --name-only HEAD
 ```
 
 Update frontmatter:

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

@@ -125,7 +125,7 @@ Read deferred `node-catalog.md` (fallback to built-in mapping):
 | testing | `quality-test` |
 | review | `quality-review` |
 | brainstorm | `maestro-brainstorm` |
-| analysis | `maestro delegate --role analyze` |
+| analysis | `maestro delegate --to <tool> --mode analysis` |
 | verify | `maestro-execute` |
 | refactor | `quality-refactor` |
 | debug | `quality-debug` |
@@ -155,7 +155,9 @@ Write `nodes.json`. Display resolved node list.
 
 Read deferred `template-schema.md` (fallback to built-in structure).
 Assemble template JSON: template_id, name, nodes, edges, checkpoints, context_schema, execution_mode.
-Write to `~/.maestro/templates/workflows/<slug>.json`. Update index.json.
+**Confirmation gate**: ask_question showing template summary (ID, node count, variables) before writing.
+- User confirms → write to `~/.maestro/templates/workflows/<slug>.json` and update index.json.
+- User cancels → save draft, do not write template or index.
 Display: path, ID, node count, variables, execute/edit commands. Clean up draft dir.
 
 </actions>

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

@@ -39,7 +39,7 @@ $ARGUMENTS — phase number, or no args for milestone-wide execution, with optio
 | `--method agent\|cli\|auto` | Execution method: Agent tool, CLI delegate, or auto-select | `auto` |
 | `--executor <tool>` | Explicit executor tool for CLI delegate mode | First enabled in config |
 | `--dir <path>` | Execute a specific plan directory instead of auto-discovery | — |
-| `-y` / `--yes` | Auto mode — skip interactive questions | false |
+| `-y` / `--yes` | Auto mode — skip ALL interactive questions (executor selection, wave progression, blocked prompts) | false |
 
 ### Scope routing
 
@@ -88,8 +88,14 @@ Follow '~/.maestro/workflows/execute.md' completely.
 - BLOCKED if missing: summary file absent or task status not updated — halt wave progression until evidence is recorded.
 - Do NOT silently skip failed tasks — mark as blocked with reason.
 
+**GATE 2.5: Wave Failure Handling**
+- IF all tasks in a wave failed: halt wave progression, report E005 with per-task failure reasons. Do NOT proceed to next wave — downstream waves depend on current wave outputs.
+- IF cascading failure (wave N fails → wave N+1 has unmet dependencies): mark all dependent tasks in subsequent waves as `blocked` with reason `"upstream_wave_failed"`. Skip blocked waves and proceed to completion with partial results.
+- `-y` mode: auto-skip blocked waves without prompting, log warning W002.
+- Non `-y` mode: `ask_question` with options [retry wave / skip and continue / abort execution].
+
 **GATE 3: All Tasks → Completion**
-- REQUIRED: All waves executed in dependency order.
+- REQUIRED: All waves executed in dependency order (or explicitly skipped via Gate 2.5).
 - REQUIRED: EXC artifact registered in state.json.
 - BLOCKED if missing: waves incomplete or EXC artifact not registered — do not report execution complete.
 
@@ -102,27 +108,37 @@ Task summaries MUST include:
 
 ### Post-task Knowledge Inquiry
 
-After each task completion, check triggers:
+After each task completion, extract structured fields from the task summary, then check triggers:
+
+**Structured extraction** (from `.summaries/TASK-{NNN}-summary.md`):
+- `deviations[]` — explicit plan deviations (look for "deviated", "changed approach", "instead of", "unlike plan")
+- `design_rationale[]` — explicit design decisions (look for "chose X because", "decided to", "trade-off")
+- `retry_count` — from `.task/TASK-{NNN}.json` status history
 
 | Condition | Ask | Route |
 |-----------|-----|-------|
-| Summary mentions approach change / plan deviation | "Record as arch constraint?" | spec-add arch |
-| retry_count >= 2 | "Document fix pattern?" | spec-add debug |
-| Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
+| `deviations[]` is non-empty | "Record as arch constraint?" | spec-add arch |
+| `retry_count >= 2` | "Document fix pattern?" | spec-add debug |
+| `design_rationale[]` is non-empty | "Record as knowhow?" | spec-add learning |
 
 On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
 Include `--description` with a one-line summary for search result display.
 
 ### Issue Status Sync
 
-On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`.
+
+**Confirmation gate**: Before writing to issues.jsonl, show the proposed status change and ask for confirmation — unless `-y` is active, in which case auto-approve.
 
 ```
 For each completed/failed TASK with issue_id:
   Read issue from issues.jsonl by issue_id
   Collect all task_refs[] statuses for that issue:
-    all task_refs completed → issue.status = "resolved"
-    any task_ref failed    → issue.status = "in_progress"
+    all task_refs completed → proposed issue.status = "resolved"
+    any task_ref failed    → proposed issue.status = "in_progress"
+  IF NOT auto_mode (-y):
+    ask_question: "Update issue {issue_id} status to {proposed_status}?" [Yes / Skip]
+    IF Skip → continue to next task without writing
   Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
   Write updated issue back to issues.jsonl
 ```
@@ -171,7 +187,9 @@ Status verdicts:
 | E002 | error | Plan directory not found | Check --dir path |
 | E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
 | E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
+| E005 | error | All tasks in wave failed — wave progression halted | Review per-task failure reasons; retry wave or abort |
 | W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
+| W002 | warning | Cascading wave failure — downstream waves auto-blocked | Review blocked tasks; re-run after fixing upstream failures |
 </error_codes>
 
 <success_criteria>

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

@@ -55,9 +55,10 @@ Fork and sync algorithm steps are defined in workflow `fork.md`.
 - BLOCKED if missing: worktree creation failed or shared files not copied — do not proceed to artifact scoping.
 
 **GATE 3: Artifact Copy → Completion**
-- REQUIRED: `worktree-scope.json` written with milestone scope.
-- REQUIRED: Scoped `state.json` written (only this milestone's artifacts).
-- REQUIRED: `worktrees.json` registry updated in main worktree.
+- REQUIRED: ask_question confirmation before registry writes — show milestone scope, worktree path, and state entries to be written. User must confirm or abort.
+- REQUIRED: `worktree-scope.json` written with milestone scope (after confirmation).
+- REQUIRED: Scoped `state.json` written (only this milestone's artifacts) (after confirmation).
+- REQUIRED: `worktrees.json` registry updated in main worktree (after confirmation).
 - BLOCKED if missing: scope marker, scoped state, or registry update absent — worktree is unusable without these.
 
 **Sync mode:**

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

@@ -93,22 +93,6 @@ Follow '~/.maestro/workflows/grill.md' completely.
 - REQUIRED: `context-package.json` generated.
 - BLOCKED if any artifact missing: produce it before reporting completion.
 
-### Evidence Requirement
-
-Grill questions MUST reference specific code (`file:line`) when challenging the user's proposal. Generic questions without code grounding are INVALID.
-
-If codebase scan failed (W001): flag ALL subsequent locked decisions as LOW CONFIDENCE.
-
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  "grill-report.md",        // Branch Log + Q&A + synthesis
-  "terminology.md",         // ≥5 terms with code refs
-  "context-package.json"    // Schema "context-package/1.0"
-]
-```
-If any missing: DO NOT report completion. Go back and produce the missing artifact.
 </execution>
 
 <completion>
@@ -169,7 +153,7 @@ Status verdicts:
 - [ ] Risk register captures all unresolved tensions
 - [ ] `context-package.json` generated with schema "context-package/1.0"
 - [ ] Artifact registered in state.json (type=grill, id=GRL-xxx)
-- [ ] Session sealed via finish-work
+- [ ] Session sealed via finish-work (finish-work.md includes ask_question confirmation before state.json artifact registration and optional spec/knowhow extraction)
 </success_criteria>
 
 <on_complete>

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

@@ -64,14 +64,14 @@ Read `.workflow/config.json`. If file missing, initialize with empty guard secti
 
 **`allow <path>`:**
 - Normalize path to forward slashes, ensure trailing slash for directories
-- If `guard.mode` is `deny`, switch to `allow` and clear paths with warning
+- If `guard.mode` is `deny`, ask_question: "Switching from deny to allow mode will clear existing paths ({N} paths). Continue?" — abort if user declines.
 - Add path to `guard.paths` (deduplicate)
 - Set `guard.enabled = true` if not already
 - Write config
 
 **`deny <path>`:**
 - Normalize path to forward slashes, ensure trailing slash for directories
-- If `guard.mode` is `allow`, switch to `deny` and clear paths with warning
+- If `guard.mode` is `allow`, ask_question: "Switching from allow to deny mode will clear existing paths ({N} paths). Continue?" — abort if user declines.
 - Set `guard.mode = "deny"`
 - Add path to `guard.paths` (deduplicate)
 - Set `guard.enabled = true` if not already (symmetric with `allow`: adding a deny path auto-enables the guard)

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

@@ -203,7 +203,8 @@ Before reading any command workflow:
    - `↺` marks refine loop with max iteration count
    - Conditional steps show trigger condition
    - Skipped conditional steps marked `(skipped)`
-3. Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
+3. **Confirm chain session**: ask_question "Create chain session for '{chain_type}' targeting '{target}'?" — proceed only if user confirms. On decline, abort chain.
+   Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
    ```json
    { "chain_type": "...", "target": "...", "steps": [...], "current_step": 0,
      "gate_history": [], "loop_count": 0, "status": "running" }

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-init
 description: Initialize project with auto state detection
-argument-hint: [-y] [--from <source>]
+argument-hint: [-y] [--from <source>] [--from-brainstorm SESSION-ID]
 allowed-tools:
   - ask_question
   - define_subagent

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

@@ -54,7 +54,18 @@ Follow '~/.maestro/workflows/merge.md' completely.
 <completion>
 ### Knowledge inquiry
 
-After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `Skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
+After successful merge, use `ask_question` to confirm knowledge persistence:
+
+```
+question: "Merge 完成。是否记录里程碑经验教训？"
+options:
+  - label: "记录经验"
+    description: "通过 spec-add 持久化此次里程碑的关键洞察"
+  - label: "跳过"
+    description: "不记录，直接完成"
+```
+
+User selects "记录经验" → prompt for title/insight, then persist via `Skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`. User selects "跳过" → proceed to next-step routing.
 
 ### Next-step routing
 

package/.agy/skills/maestro-milestone-audit/SKILL.md

@@ -25,6 +25,7 @@ Produces audit-report.md with PASS/FAIL verdict.
 
 <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:** All phases in the milestone should have completed execute artifacts.
 
@@ -71,21 +72,6 @@ Audit checklist steps (phase coverage, ad-hoc completeness, execution completene
 - REQUIRED: Clear PASS/FAIL verdict determined with evidence for each check.
 - BLOCKED if missing: integration check not completed — do not write report without cross-artifact verification.
 
-### Artifact Verification (before completion)
-
-```
-REQUIRED_ARTIFACTS = [
-  ".workflow/milestones/{milestone}/audit-report.md"  // Clear PASS/FAIL verdict
-]
-```
-If missing: DO NOT report completion. Write the audit report first.
-
-### Evidence Requirement
-
-Every audit check result MUST cite what was examined and what was found:
-- PASS: "Phase 1 chain complete: ANL-001 → PLN-001 → EXC-001, all tasks completed"
-- FAIL: "Phase 2 missing EXC artifact — PLN-002 exists but no execution found"
-- Do NOT mark checks as PASS without verifying the actual artifact exists and contains expected content.
 </execution>
 
 <completion>

package/.agy/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_question 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_question "Run wiki-connect --fix to link newly extracted knowledge?" — execute `manage-wiki connect --fix` only if user confirms.
 
-If user confirms promotion, invoke `view_file(AbsolutePath="<agy-skills-dir>/spec-add/SKILL.md") + execute inline (args: "<category> <content>")` with promoted content, preserving original date and source traceability.
+Each promotion candidate requires explicit user confirmation via ask_question before writing:
+- **"Promote"** → invoke `view_file(AbsolutePath="<agy-skills-dir>/spec-add/SKILL.md") + execute inline (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/.agy/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_question 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_question 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_question 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_question
+- [ ] state.json updated with last_release_version + last_release_at timestamp (after ask_question confirmation)
 </success_criteria>

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

@@ -133,6 +133,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_question:
+- **"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/.agy/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 = view_file(.workflow/codebase/ARCHITECTURE.md) + view_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 = run_command("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/.agy/skills/maestro-player/SKILL.md

@@ -36,7 +36,7 @@ $ARGUMENTS — template slug/path, or flags.
 | skill | `Skill(skill, args)` | sync |
 | command | `Skill(skill, args)` | sync |
 | cli | `maestro delegate --to tool --mode mode` via `run_command(run_in_background: true)` | async, STOP + wait |
-| agent | `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` | configurable |
+| agent | `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` — 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:
@@ -106,7 +106,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 → run_command(run_in_background: true) + STOP, wait for callback
-  GUARD: on failure → on_fail: skip (log, advance) | retry (once) | abort (ask_question: Retry/Skip/Abort)
+  GUARD: on failure → on_fail: skip (log, advance) | retry (once) | abort (ask_question: Retry/Skip/Abort). Default on_fail when not specified: `abort` (prompt user via ask_question).
   GUARD: after step 3+ → display context hint "可随时 /maestro-player -c 恢复"
 
 S_COMPLETE:

package/.agy/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:
   - ask_question
   - define_subagent
@@ -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_question` showing staged files and proposed commit message — unless `-y` is active, in which case auto-commit
 </success_criteria>

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

@@ -40,7 +40,7 @@ Remaining     → intent (amend_mode 时为 change_request)
 <invariants>
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
 2. **Handoff via 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 是唯一合法写入路径
@@ -470,11 +470,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
@@ -543,7 +543,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`
@@ -590,7 +590,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": "..." }`
@@ -675,7 +675,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
 |-------|------|------|
 | 1. 快照 | 读 `task_decomposition` + `boundary_contract` + 已完成 steps 的 `completion_summary` | Display: 目标列表 + 进度 |
 | 2. 解析 | `change_request` 非空 → 直接用；为空 → ask_question（修改/新增/移除/调整边界） | `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_question：应用并继续 / 仅改目标 / 取消 | 用户选择 |
 | 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff ralph-execute |
 
@@ -888,7 +888,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；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 查找注入）