maestro-flow 0.4.10 → 0.4.12

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

@@ -0,0 +1,182 @@
+---
+name: maestro-plan
+description: Use when creating, revising, or verifying an execution plan for a phase or task
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- 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" 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".
+
+### Role Knowledge
+`maestro wiki list --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.
+
+### 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 wiki 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.
+
+**Report format on completion:**
+
+```
+=== 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
+
+Next steps:
+  /maestro-execute              -- Execute the plan
+  /maestro-execute --dir {dir}  -- Execute specific plan
+  /maestro-plan {phase}         -- Re-plan with modifications
+```
+
+**Completion status:**
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|NEEDS_CONTEXT
+CONCERNS: {description if applicable}
+NEXT: /maestro-execute
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — Plan created/revised and confirmed → NEXT: /maestro-execute
+- **NEEDS_CONTEXT** — Ambiguous requirements, insufficient context to produce plan
+
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<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-verify first |
+| 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>

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

@@ -0,0 +1,177 @@
+---
+name: maestro-player
+description: Play workflow templates with checkpoint resume
+argument-hint: "<template-slug|path> [--context key=value...] [-c [session-id]] [--list] [--dry-run]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+  - invoke_skill
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Load workflow template (from maestro-composer) → bind context variables → execute DAG nodes in topological order → persist state at checkpoints → support resume.
+
+Session: `.workflow/.maestro/player-{YYYYMMDD-HHmmss}/status.json`
+</purpose>
+
+<context>
+$ARGUMENTS — template slug/path, or flags.
+
+**Flags**:
+- `--context key=value`: Bind context variables (repeatable)
+- `-c [session-id]`: Resume paused/interrupted session
+- `--list`: List available templates from index.json
+- `--dry-run`: Show execution plan without executing
+
+**Node execution mechanisms**:
+
+| Node type | Mechanism | Blocking |
+|-----------|-----------|----------|
+| 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 |
+| checkpoint | State save + optional user pause | — |
+
+**Runtime reference resolution** in args_template:
+
+| Reference | Resolves to |
+|-----------|-------------|
+| `{variable}` | session context[variable] |
+| `{N-001.session_id}` | node's session_id |
+| `{N-001.output_path}` | node's output_path |
+| `{prev_session_id}` | previous non-checkpoint node's session_id |
+| `{prev_output_path}` | previous non-checkpoint node's output_path |
+
+**Session schema** (status.json — must align with maestro.md tracking):
+```json
+{
+  "session_id": "player-<YYYYMMDD>-<HHmmss>",
+  "status": "running|paused|completed|failed|aborted",
+  "template_id": "wft-<slug>-<date>",
+  "template_path": "<path>",
+  "auto_mode": false,
+  "context": { "goal": "..." },
+  "steps": [{
+    "index": 0, "node_id": "N-001", "skill": "<executor>",
+    "args": "<resolved>", "type": "skill|cli|agent|checkpoint",
+    "status": "pending|running|completed|skipped|failed",
+    "session_id": null, "output_path": null, "artifacts": []
+  }],
+  "current_step": 0,
+  "last_checkpoint": null
+}
+```
+</context>
+
+<state_machine>
+
+<states>
+S_ROUTE        — 入口路由（list/resume/dry-run/normal）     PERSIST: —
+S_RESUME       — 恢复已暂停 session                         PERSIST: —
+S_LOAD         — 加载模板、收集变量、绑定引用                 PERSIST: —
+S_INIT         — 创建 session、拓扑排序、初始化 steps         PERSIST: status.json
+S_EXEC_LOOP    — 逐步执行（核心循环）                        PERSIST: status.json (每步更新)
+S_COMPLETE     — 标记完成、输出摘要                           PERSIST: status.json (final)
+</states>
+
+<transitions>
+
+S_ROUTE:
+  → handleList    WHEN: --list                              DO: scan index.json, display templates
+  → S_RESUME      WHEN: -c flag
+  → S_LOAD        WHEN: template slug/path provided
+  → handleList    WHEN: no args                             DO: display templates + ask_user
+
+S_RESUME:
+  → S_EXEC_LOOP   WHEN: session found                      DO: A_RESUME_SESSION
+  → ERROR(E004)   WHEN: no session found
+
+S_LOAD:
+  → S_INIT        DO: A_LOAD_AND_BIND
+
+S_INIT:
+  → END           WHEN: --dry-run                           DO: display execution plan
+  → S_EXEC_LOOP   DO: A_INIT_SESSION (topological sort → steps[], write status.json, display banner)
+
+S_EXEC_LOOP:
+  → S_EXEC_LOOP   WHEN: step completed, more steps          DO: A_EXECUTE_STEP → advance current_step
+  → S_COMPLETE     WHEN: all steps completed
+  → 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: after step 3+ → display context hint "可随时 /maestro-player -c 恢复"
+
+S_COMPLETE:
+  → END           DO: A_COMPLETE_SESSION
+
+</transitions>
+
+<actions>
+
+### A_RESUME_SESSION
+
+1. If session-id: load status.json. If none: scan player-*/status.json for running|paused.
+2. Reset any "running" steps to "pending" (interrupted mid-execution)
+3. Set current_step to resume point after last_checkpoint
+4. Enter S_EXEC_LOOP
+
+### A_LOAD_AND_BIND
+
+1. Resolve template: absolute path → as-is; relative → from cwd; slug → index.json lookup
+2. Parse `--context key=value` pairs
+3. Validate template (template_id, nodes, edges, context_schema required)
+4. Collect missing required variables via ask_user
+5. Bind {variable} placeholders (leave {N-xxx.field} and {prev_*} for runtime)
+
+### A_INIT_SESSION
+
+1. Generate session_id: player-{YYYYMMDD-HHmmss}
+2. Topological sort (Kahn's algorithm) → flatten to steps[] (parallel nodes share batch index)
+3. All steps status: "pending"
+4. Write status.json
+
+### A_EXECUTE_STEP
+
+1. Resolve runtime references ({N-xxx.field}, {prev_*}) in args
+2. Set step status="running", write status.json
+3. Execute by type:
+   - **skill/command**: `invoke_skill(skill, resolved_args)` → extract session_id, output_path, artifacts
+   - **cli**: `shell(run_in_background: true)` → STOP, wait for callback → `maestro delegate output <id>`
+   - **agent**: `delegate_subagent(subagent_type, resolved_args)`
+   - **checkpoint**: write checkpoint snapshot. If auto_continue==false: ask_user (Continue/Pause/Abort)
+4. Set step status="completed" (or "skipped"/"failed"), write status.json
+
+### A_COMPLETE_SESSION
+
+Set status="completed", completed_at. Display summary: session, template, steps completed, context, per-step results, artifacts, session dir.
+ask_user: Keep session / Run again / Done.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | Template not found | Show --list, suggest closest match |
+| E002 | Template JSON invalid (missing template_id/nodes/edges) | Point to template file for fix |
+| E004 | Resume session not found | List available player-*/ sessions |
+| E005 | DAG cycle in template | Point to template, suggest --edit |
+| E006 | Node execution failed + abort chosen | Save state, suggest `-c` resume |
+</error_codes>
+
+<success_criteria>
+- [ ] Template loaded, variables bound, session created with topological steps
+- [ ] status.json written after every step change (resume-safe)
+- [ ] CLI nodes use shell(run_in_background) + STOP pattern
+- [ ] Checkpoints saved, resume via -c works
+</success_criteria>

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

@@ -0,0 +1,67 @@
+---
+name: maestro-quick
+description: Quick task execution, skip optional agents
+argument-hint: "[description] [--full] [--discuss]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Execute small, ad-hoc tasks with workflow guarantees (atomic commits, state tracking) using a shortened pipeline. Invoked for tasks that are well-understood and do not require full phase-level planning. Produces scratch task directory with plan, execution results, and optional verification. Flags --discuss and --full enable additional pipeline stages.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/quick.md
+</required_reading>
+
+<context>
+$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)
+- Remaining text as task description
+
+### Pre-load context
+
+1. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions and discoverable tools. Apply to implementation.
+2. **UI specs (conditional)**: If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro spec load --category ui`.
+3. **Role Knowledge**:
+   - Browse: `maestro wiki list --category coding`
+   - Load task-relevant entries: `maestro wiki load <id1> [id2...]`
+3. All are optional — proceed without if unavailable.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/quick.md' completely.
+
+**Next-step routing on completion:**
+- Task done, --full verification passed → /manage-status
+- Task done, verification found gaps → /quality-debug {issue}
+- Task done, want to sync docs → /quality-sync
+- Need a full phase workflow instead → /maestro-plan {phase}
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Task description required (no text provided) | Check arguments format, re-run with correct input |
+| E002 | error | Scratch directory creation failed | Check disk space and .workflow/ permissions |
+| W001 | warning | Verification found minor gaps | Review gaps and determine if they need fixing |
+</error_codes>
+
+<success_criteria>
+- [ ] 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
+</success_criteria>