maestro-flow

<purpose> Single-entry skill packaging all 49 Maestro workflow commands (Codex variant). Two execution modes: 1. **Router** (default): Analyze intent -> decompose (broad intents) -> match chain -> create session -> sequential step execution 2. **Direct** (`--cmd <name> <args>`): Load and execute a specific command inline Execution invokes each step DIRECTLY in coordinator context (no agent spawning). Step lifecycle managed by `maestro-flow next/done` CLI. Commands loaded via `maestro-flow resolve`. Goal tracking via built-in `create_goal` / `update_plan` / `update_goal`. Session path: `.workflow/.maestro/flow-{YYYYMMDD-HHmmss}/status.json` </purpose> <context> $ARGUMENTS -- intent text, flags, or special keywords. **Skill directory structure** (relative to this SKILL.md): ``` maestro-flow/ SKILL.md <- this file (router + sequential executor) commands/ lifecycle/ <- 17 commands: init, analyze, plan, execute, verify, ... quality/ <- 7 commands: debug, review, test, auto-test, ... manage/ <- 10 commands: status, issue, wiki, harvest, ... learn/ <- 5 commands: decompose, follow, investigate, ... milestone/ <- 3 commands: audit, complete, release spec/ <- 4 commands: add, load, remove, setup wiki/ <- 2 commands: connect, digest chains/ templates.json <- 14 chain templates + decision types ``` **State files:** - `.workflow/state.json` -- project artifact registry (optional) - `.workflow/.maestro/flow-*/status.json` -- flow session state **CLI prerequisite:** `maestro-flow` command must be globally available (`npm install -g maestro-flow-one`) </context> <invariants> 1. **Steps invoked DIRECTLY in-context** -- coordinator runs `$maestro-flow --cmd <skill> <args>` itself, sequentially. NO spawn_agents_on_csv, NO wave, NO CSV. 2. **Coordinator owns the loop** -- classify -> decompose -> build -> for each step: resolve args -> invoke -> read result -> persist -> next. 3. **Decision nodes evaluate, never execute** -- quality-gate via `maestro delegate --role analyze`; goal-gate audits sub-goals; structural evaluated directly. 4. **Goal is tool-created** -- broad intents call `create_goal` with sub-goal success criteria; `update_goal` on convergence. 5. **task_decomposition drives DYNAMIC step growth** -- sub-goals are the convergence spec; `steps[]` is a living array. `post-goal-audit` re-checks the checklist and inserts scoped steps for unmet sub-goals. 6. **Status JSON: schema-additive + step-dynamic** -- decomposition fields OPTIONAL (absent -> old behavior); `steps[]` grown at runtime; `goal_ref` traces dynamically-added steps. Never remove/rename existing fields. 7. **Sequential execution** -- one step at a time in index order; each step's result read before the next starts. </invariants> <execution> ## Step 1: Parse & Route ``` Parse $ARGUMENTS: --cmd <name> <remaining-args> -> Step 1a: Direct Command Execution -> End. list -> Bash: maestro-flow list. End. status [session-id] -> Bash: maestro-flow status [session-id]. End. chains -> Bash: maestro-flow chains. End. execute | continue -> Phase 2 (Sequential Execution Loop) --chain <name> [-y] <remaining> -> Force chain selection (skip intent analysis), go to Step 4 -y / --yes -> auto_confirm = true Other text -> intent = remaining text -> Step 2 ``` ### Step 1a: Direct Command Execution (--cmd) Entry point for single-command execution. ``` 1. Bash: maestro-flow resolve <name> -> absolute path to command .md 2. If NOT_FOUND -> Error. End. 3. Read() the command .md file 4. Set $ARGUMENTS = <remaining-args> 5. Follow the command's <execution> section completely End. ``` --- ## Step 2: Read Project State (optional) ``` If .workflow/state.json exists: Read -> extract: current_milestone, milestones, artifacts If not: state_summary = "Project not initialized" ``` ## Step 3: Intent Analysis & Chain Matching ``` Bash: maestro-flow suggest "{intent}" -> parse suggested chains Display top 3 chain options AskUserQuestion: select chain / single command / Cancel If auto_confirm: pick highest scoring chain If single command: --cmd -> Step 1a If chain selected: -> Step 3.5 ``` --- ## Step 3.5: Task Decomposition (broad lifecycle intents) Shares the decomposition contract with maestro-ralph `A_DECOMPOSE_TASKS` — reference that spec; do not duplicate. ``` Classify intent breadth: broad = 重构/全面/重写/重做/整体/迁移 · overhaul/migrate/rewrite/revamp narrow = single file/function/bug, "fix X", "add Y to Z" other = medium Skip decomposition (-> Step 4 directly) WHEN: narrow intent OR single-command chain OR chain ∈ {status, init, quick} Else (broad MUST clarify even if auto_confirm; medium clarify unless auto_confirm): AskUserQuestion ≤3 rounds (options pre-filled from intent + quick Glob/Grep of target module): 1. Scope -> in_scope / out_of_scope 2. Constraints -> constraints + execution_criteria (compat/API/perf/test bar) 3. Done -> definition_of_done Derive: execution_criteria = 3-6 imperative rules every step obeys task_decomposition = outcome sub-goals; each: { id:"G1", goal, boundary, done_when, evidence, lifecycle:[...], status:"pending" } RULE: done_when objectively verifiable, mapped to a ralph evidence artifact (verification.json | review.json | uat.md | <test path>) Write {session_dir}/goal-checklist.md (template below) with ALL_GOALS_DONE sentinel. Register goal via built-in tool: create_goal({ objective: "Flow {chain}: {intent} — converge {N} sub-goals within boundary", success_criteria: task_decomposition.map(g => `${g.id}: ${g.done_when}`), constraints: [...execution_criteria, "stay within boundary_contract"] }) Stage additive block + goal_checklist_path for Step 4. ``` **goal-checklist.md template:** ```markdown # Flow Goal Checklist — {session_id} > Intent: {intent} ## 执行准则 / Execution Criteria - {criterion} ## 边界契约 / Boundary Contract - In scope / Out of scope / Constraints / Definition of Done ## 子目标 / Sub-goals - [ ] G1: {goal} — done when: {done_when} (evidence: {evidence}) <!-- executor flips [ ]→[x] when evidence confirms; appends ALL_GOALS_DONE when all [x] --> ``` --- ## Step 4: Build Session ### 4.1: Load template & build steps ``` Bash: maestro-flow chain {template_name} -> parse step list Build session steps[] from template. Each step type ∈ {internal, external, decision}. Decision steps get extra fields: decision, retry_count, max_retries. ``` ### 4.2: Create session ``` session_id = "flow-{YYYYMMDD-HHmmss}" session_dir = .workflow/.maestro/{session_id}/ Write {session_dir}/status.json: { "session_id": "{session_id}", "source": "flow", "created_at": "{ISO}", "updated_at": "{ISO}", "intent": "{intent}", "status": "running", "chain_name": "{template_name}", "task_type": "{category}", "phase": {phase}, "milestone": "{current_milestone}", "auto_mode": {auto_confirm}, "quality_mode": "standard", "passed_gates": [], "context": { "scratch_dir": null, "plan_dir": null, "analysis_dir": null }, "steps": [ { ..., "goal_ref": null } ], "waves": [], "current_step": 0, "_comment": "↓ OPTIONAL additive block — present only if Step 3.5 ran; absent = flat-chain behavior", "boundary_contract": {}, "execution_criteria": [], "task_decomposition": [], "goal_checklist_path": "" } If Step 3.5 produced a decomposition: - Fill the additive block (never remove/rename existing fields) - Append a decision step { "cmd":"decision:post-goal-audit", "type":"decision", "decision":"post-goal-audit", "retry_count":0, "max_retries":2 } as the FINAL node — after the last evidence-producing step (verify/review/test), before a milestone-complete/close-out step if the chain ends with one - update_plan({ plan: steps.map(s => ({ step: s.cmd, status: "pending" })) }) Else: - create_goal({ objective: "Flow {chain}: {N} steps" }) - update_plan({ plan: steps.map(s => ({ step: s.cmd, status: "pending" })) }) ``` ### 4.3: Display + confirm ``` ============================================================ MAESTRO FLOW SESSION ============================================================ Session: {session_id} Chain: {chain_name} ({total} steps) Sub-goals: {n if decomposed} Phase: {phase} [ ] 0. maestro-plan {phase} [ ] 1. maestro-execute {phase} [ ] 2. maestro-verify {phase} [ ] 3. > post-goal-audit [decision] ... ============================================================ If auto_confirm: proceed directly Else: AskUserQuestion -> Execute / Cancel ``` Fall through to Phase 2. --- ## Phase 2: Sequential Execution Loop Core loop: `maestro-flow next` -> route by type -> execute directly -> `maestro-flow done` -> self-invoke. ### 2.1: Load next step ``` Bash: maestro-flow next [session-id] Parse: "NO_SESSION" -> "No running flow session." End. "SESSION_COMPLETE" -> Phase 3. Else: STEP / TYPE / SKILL / ARGS DECISION / RETRY (decision only) PATH (internal/external only) ---COMMAND--- + content (internal/external only) Display banner: [{idx}/{total}] {SKILL} [{TYPE}] Args: {ARGS} Route: TYPE == "decision" -> Step 2.2 TYPE == "internal" -> Step 2.3 (direct) TYPE == "external" -> Step 2.4 (direct) ``` ### 2.2: Decision Evaluation ``` Route by decision class: decision == "post-milestone" -> Structural (2.2d) decision == "post-goal-audit" -> Goal-gate (2.2g) otherwise -> Quality-gate (2.2a) ``` Resolve `artifact_dir`: read state.json, filter artifacts by session.milestone+phase, latest; fallback glob `.workflow/scratch/*-P{phase}-*/`. #### 2.2a: Quality-gate delegate assessment ``` Result file mapping: post-verify -> {artifact_dir}/verification.json post-business-test -> {artifact_dir}/business-test-results.json post-review -> {artifact_dir}/review.json post-test -> {artifact_dir}/uat.md, {artifact_dir}/.tests/test-results.json Bash({ command: `maestro delegate "PURPOSE: evaluate ${decision} quality gate TASK: read result files | analyze pass/fail | assess severity | recommend MODE: analysis CONTEXT: @${result_files} EXPECTED: