maestro-flow 0.5.2 → 0.5.31

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

@@ -14,200 +14,214 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<purpose>
-Create, revise, or verify an execution plan through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
-
-Supports three modes:
-- **Create** (default): Build plan from analysis context or phase requirements
-- **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
-- **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan
-
-All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting. Scope prefix in directory name (`P{N}` for phase, `M{N}` for milestone, omit for adhoc/standalone) enables fallback identification. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/plan.md
-</required_reading>
-
-<deferred_reading>
-- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
-- [task.json](~/.maestro/templates/task.json) — read when generating task files
-- [state.json](~/.maestro/templates/state.json) — read when registering artifact
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
-
-Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
-
-**Command-level flags** (extensions beyond workflow base):
-- `--from <source>`: Load upstream context directly (bypasses roadmap requirement):
-  - `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
-- `--revise [instructions]` -- See workflow plan.md § Revise Mode
-- `--check <plan-dir>` -- See workflow plan.md § Check Mode
-
-**Upstream context (resolution priority):**
-1. `--from analyze:ANL-xxx` → uses analyze conclusions.implementation_scope directly
-2. `--from blueprint:BLP-xxx` → uses blueprint requirements + architecture
-3. `--dir <path>` → explicit context directory (unchanged)
-4. Numeric arg → scope = "phase", resolve from roadmap (unchanged)
-5. No args + roadmap → scope = "milestone" (unchanged)
-6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone
-
-**Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
-
-**Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".
-
-### Role Knowledge
-`maestro search --category arch` → select relevant → `maestro wiki load`
-</context>
-
-<execution>
-### Pre-flight: team conflict check
-
-Before starting the plan pipeline, run:
-```
-shell("maestro collab preflight --phase <phase-number>")
-```
-If exit code is 1, present warnings and ask whether to proceed.
-
-Follow '~/.maestro/workflows/plan.md' completely.
-
-### Phase Gates (MANDATORY, BLOCKING — Create mode only)
-
-**GATE P1 → P2**: Context collection completed — context files loaded, codebase docs read (if available), wiki searched.
-**GATE P2 → P3**: Clarification completed — ambiguous requirements resolved via ask_user (≤3 rounds).
-**GATE P3 → P4**: Plan generated by planner agent — `plan.json` + `.task/TASK-*.json` files written. Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
-**GATE P4 → P5**: Plan-checker passed (or minor issues acknowledged). Confidence scored. Pressure pass completed on highest-complexity task.
-**GATE P5 → Completion**: User confirmation captured (execute/modify/cancel). PLN artifact registered in state.json.
-
-### 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}" }
-```
-
-This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
-
-### Mode: Revise / Check
-
-Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
-</execution>
-
-<completion>
-### Standalone report
-
-```
-=== PLAN READY ===
-Phase: {phase_name}
-Tasks: {task_count} tasks in {wave_count} waves
-Check: {checker_status} (iteration {check_count}/{max_checks})
-Collision: {collision_status}
-
-Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
-Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
-```
-
-### Ralph-invoked completion
-
-End the step by calling the CLI (no text block output):
-```
-maestro ralph complete <idx> --status {STATUS} [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
-```
-
-Status verdicts:
-- **DONE** — Plan created/revised and confirmed → next step picks up automatically
-- **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
-- **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
-- **BLOCKED** — External hard blocker (e.g., upstream artifact missing, dependency unavailable); pass `--reason "..."`
-
-> Ambiguous requirements are NOT a completion status — resolve them in-place via `ask_user` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.
-
-### Next-step routing
-
-| Condition | Suggestion |
-|-----------|-----------|
-| Plan confirmed for execution | `/maestro-execute` |
-| Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
-| Re-plan with modifications | `/maestro-plan {phase}` |
-</completion>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
-| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-execute first (verification is built-in) |
-| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
-| E005 | error | Plan directory not found (--check) | Check path, use --dir |
-| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
-| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
-| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
-| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
-</error_codes>
-
-<success_criteria>
-- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
-- [ ] .task/TASK-*.json files created for each task
-- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
-- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
-- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
-- [ ] Plan confidence scored in P4 with 5-dimension factor model
-- [ ] Plan readiness gate checked before P4.5 collision detection
-- [ ] Pressure pass completed on highest-complexity task
-- [ ] plan.json includes confidence section (overall, dimensions, pressure_pass)
-- [ ] Collision detection executed against same-milestone plans (non-blocking)
-- [ ] Plan-checker passed (or minor issues acknowledged)
-- [ ] User confirmation captured (execute/modify/cancel) with confidence displayed
-- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
-</success_criteria>
+<purpose>
+Create, revise, or verify execution plans (5-stage pipeline).
+Produces plan.json + TASK files; registers PLN artifact in state.json.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
+- [task.json](~/.maestro/templates/task.json) — read when generating task files
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
+
+Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
+
+**Command-level flags** (extensions beyond workflow base):
+- `--from <source>`: Load upstream context directly (bypasses roadmap requirement):
+  - `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
+- `--revise [instructions]` -- See workflow plan.md § Revise Mode
+- `--check <plan-dir>` -- See workflow plan.md § Check Mode
+
+**Upstream context (resolution priority):**
+1. `--from analyze:ANL-xxx` → uses analyze conclusions.implementation_scope directly
+2. `--from blueprint:BLP-xxx` → uses blueprint requirements + architecture
+3. `--dir <path>` → explicit context directory (unchanged)
+4. Numeric arg → scope = "phase", resolve from roadmap (unchanged)
+5. No args + roadmap → scope = "milestone" (unchanged)
+6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone
+
+**Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
+
+**Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".
+
+### Role Knowledge
+`maestro search --category arch` → select relevant → `maestro wiki load`
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before starting the plan pipeline, run:
+```
+shell("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/plan.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING — Create mode only)
+
+**GATE P1 → P2: Context Collection → Clarification**
+- REQUIRED: Context files loaded (roadmap, analyze artifact, or --from source).
+- REQUIRED: Codebase docs read if available (ARCHITECTURE.md, FEATURES.md).
+- REQUIRED: Wiki searched for prior knowledge related to phase keywords.
+- BLOCKED if missing: no context source found — cannot plan without upstream input (E001).
+
+**GATE P2 → P3: Clarification → Plan Generation**
+- REQUIRED: Ambiguous requirements resolved via ask_user (<=3 rounds).
+- BLOCKED if: unresolved ambiguities remain after 3 clarification rounds — escalate to user before proceeding.
+
+**GATE P3 → P4: Plan Generation → Plan Check**
+- REQUIRED: Plan generated by planner agent — `plan.json` + `.task/TASK-*.json` files written.
+- REQUIRED: Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
+- BLOCKED if missing: plan.json or TASK files not produced by planner agent — do not proceed to checking.
+
+**GATE P4 → P5: Plan Check → User Confirmation**
+- REQUIRED: Plan-checker passed (or minor issues acknowledged).
+- REQUIRED: Confidence scored with 5-dimension factor model.
+- REQUIRED: Pressure pass completed on highest-complexity task.
+- BLOCKED if: plan-checker found critical issues — fix plan before presenting to user.
+
+**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}" }
+```
+
+This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
+
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== PLAN READY ===
+Phase: {phase_name}
+Tasks: {task_count} tasks in {wave_count} waves
+Check: {checker_status} (iteration {check_count}/{max_checks})
+Collision: {collision_status}
+
+Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
+Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
+```
+
+Status verdicts:
+- **DONE** — Plan created/revised and confirmed → next step picks up automatically
+- **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
+- **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
+- **BLOCKED** — External hard blocker (e.g., upstream artifact missing, dependency unavailable); pass `--reason "..."`
+
+> Ambiguous requirements are NOT a completion status — resolve them in-place via `ask_user` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Plan confirmed for execution | `/maestro-execute` |
+| Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
+| Re-plan with modifications | `/maestro-plan {phase}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
+| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-execute first (verification is built-in) |
+| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
+| E005 | error | Plan directory not found (--check) | Check path, use --dir |
+| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
+| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
+| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
+| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
+</error_codes>
+
+<success_criteria>
+- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
+- [ ] .task/TASK-*.json files created for each task
+- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
+- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Plan confidence scored in P4 with 5-dimension factor model
+- [ ] Plan readiness gate checked before P4.5 collision detection
+- [ ] Pressure pass completed on highest-complexity task
+- [ ] plan.json includes confidence section (overall, dimensions, pressure_pass)
+- [ ] Collision detection executed against same-milestone plans (non-blocking)
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel) with confidence displayed
+- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
+</success_criteria>