maestro-flow-one 0.1.0

package/codex/maestro-flow/commands/lifecycle/player.md

@@ -0,0 +1,323 @@
+---
+name: maestro-player
+description: Workflow template player — load JSON template, bind variables, execute DAG nodes wave-by-wave via spawn_agents_on_csv, persist state at checkpoints, support resume. Coordinator assembles skill_call from template nodes — never executes skills directly.
+argument-hint: "<template-slug|path> [--context key=value...] [-c [session-id]] [--list] [--dry-run]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Wave-based template executor using `spawn_agents_on_csv`. Loads a workflow template
+(produced by maestro-composer), binds context variables, converts DAG nodes into
+CSV waves via topological sort, executes wave-by-wave with barrier/non-barrier grouping.
+
+Aligned with maestro codex coordinator pattern:
+- ALL skill execution via `spawn_agents_on_csv` — coordinator never executes directly
+- Barrier nodes (checkpoints + artifact-producing skills) execute solo
+- Non-barrier nodes grouped into parallel waves
+- Session state at `.workflow/.maestro/{session-id}/`
+- Resume from last completed wave via `-c`
+
+```
+Load Template → Bind Variables → Build Wave CSV → spawn → read results →
+(barrier: read artifacts, update context) → next wave → report
+```
+</purpose>
+
+<invariants>
+1. **ALL skills via spawn_agents_on_csv**: Every node execution goes through spawn. Coordinator NEVER directly executes any skill.
+2. **Coordinator = prompt assembler only**: Load template → resolve refs → build CSV → spawn → read results → assemble next CSV.
+3. **Barrier = solo wave**: Checkpoint nodes and artifact-producing skills execute alone (wave size = 1).
+4. **Non-barriers can parallel**: Consecutive non-barrier nodes grouped into one wave.
+5. **Wave-by-wave**: Never start wave N+1 before wave N results are read and analyzed.
+6. **Coordinator owns context**: Sub-agents never read prior results — coordinator assembles full `skill_call` with resolved args.
+7. **Resume from wave**: `-c` finds last completed wave, resumes from next pending step.
+</invariants>
+
+<context>
+$ARGUMENTS — template slug/path, or flags.
+
+**Flags:**
+- `--context key=value` — Bind context variables (repeatable)
+- `-c` / `--continue [session-id]` — Resume paused/interrupted session
+- `--list` — List available templates
+- `--dry-run` — Show wave plan without executing
+
+**Entry routing:**
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| List | `--list` | handleList |
+| Resume | `-c [session-id]` | Phase 0: Resume |
+| Dry run | `--dry-run` | Phase 1 + 2, print plan, exit |
+| Normal | Template slug/path | Phase 1 |
+| No args | Empty | handleList + AskUserQuestion |
+
+**Session tracking (aligned with maestro codex):**
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `MCP` (Maestro Composer Player) |
+| Session dir | `.workflow/.maestro/MCP-<YYYYMMDD>-<HHmmss>/` |
+| State file | `state.json` |
+| Wave CSV | `wave-{N}.csv` |
+| Wave results | `wave-{N}-results.csv` |
+| Template dir | `~/.maestro/templates/workflows/` |
+| Template index | `~/.maestro/templates/workflows/index.json` |
+
+**Barrier nodes** (solo wave, coordinator reads artifacts after):
+
+| Node type | Artifacts to Read | Context Updates |
+|-----------|------------------|-----------------|
+| `checkpoint` | — (state save only) | `last_checkpoint` |
+| `maestro-plan` | `plan.json`, `.task/TASK-*.json` | `plan_dir`, `task_count` |
+| `maestro-execute` | `results.csv` | `exec_status`, `completed_tasks` |
+| `maestro-analyze` | `context.md` | `analysis_dir`, `gaps`, `phase` |
+| `maestro-brainstorm` | `.brainstorming/` | `brainstorm_dir` |
+| `maestro-roadmap` | `specs/` | `spec_session_id` |
+
+All other skill nodes are **non-barrier** (groupable into parallel waves).
+
+**state.json schema:**
+
+```json
+{
+  "id": "MCP-<YYYYMMDD>-<HHmmss>",
+  "intent": "<template_name> with context",
+  "chain": "<template_id>",
+  "template_path": "~/.maestro/templates/workflows/<slug>.json",
+  "template_name": "<name>",
+  "auto_yes": false,
+  "status": "in_progress | paused | completed | aborted",
+  "started_at": "<ISO>",
+  "context": {
+    "goal": "...", "scope": "...",
+    "phase": null, "plan_dir": null, "analysis_dir": null,
+    "last_checkpoint": null
+  },
+  "waves": [],
+  "steps": [
+    {
+      "step_n": 1, "node_id": "N-001",
+      "skill": "<executor>", "args": "<args_template>",
+      "type": "skill | cli | checkpoint",
+      "is_barrier": true,
+      "status": "pending | completed | failed | skipped",
+      "wave_n": null, "findings": null, "artifacts": null
+    }
+  ]
+}
+```
+</context>
+
+<execution>
+
+### handleList
+
+Scan `~/.maestro/templates/workflows/index.json`. Display:
+```
+Available workflow templates:
+  feature-tdd-review    [feature, complex]   3 work nodes, 2 checkpoints
+  quick-bugfix          [bugfix, simple]     2 work nodes, 1 checkpoint
+
+Run: $maestro-player <slug> --context goal="..."
+```
+
+If not found: "No templates. Create with $maestro-composer"
+
+---
+
+### Phase 0: Resume
+
+**Trigger**: `-c [session-id]`
+
+Load session state by explicit ID or most recent `MCP-*/state.json` with `status = "in_progress" | "paused"`. Error E005 if none found. Resume from next pending step after last completed wave → jump to Phase 3.
+
+---
+
+### Phase 1: Load & Bind
+
+1. **Resolve template**: absolute path → as-is, slug → lookup in `~/.maestro/templates/workflows/index.json`, partial → confirm, not found → show `--list`
+2. **Parse** `--context key=value` pairs into `bound_context`
+3. **Load and validate** template JSON
+4. **Collect missing** required variables via AskUserQuestion
+5. **Bind** `{variable_name}` in all `args_template` strings. Leave `{N-xxx.field}` and `{prev_*}` unresolved (runtime Phase 3)
+6. If `--dry-run`: print wave plan and exit
+
+---
+
+### Phase 2: Init Session & Build Wave Plan
+
+1. Generate session ID: `MCP-<YYYYMMDD>-<HHmmss>`
+2. Topological sort (Kahn's algorithm) on template nodes + edges
+3. Classify barrier vs non-barrier: barriers = checkpoint nodes + `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-roadmap`, `maestro-execute`
+4. Group into waves: barrier nodes → solo wave, non-barrier nodes → accumulate into parallel wave
+5. Build steps array from waves, write `state.json`
+
+**Step 2.6** — Display start banner:
+```
+============================================================
+  MAESTRO PLAYER
+============================================================
+  Template: <template.name>
+  Session:  <session_id>
+  Context:  goal="<value>"
+
+  Wave Plan:
+    [W1] N-001 maestro-plan          "{goal}"       [BARRIER]
+    [W2] N-002 maestro-execute       {phase}        [BARRIER]
+    [W3] N-003 quality-test          {phase}
+         N-004 quality-review        {phase}
+============================================================
+```
+
+**`--dry-run`**: Display above and exit.
+
+---
+
+### Phase 3: Wave Execution Loop
+
+Loop while any step has `status === 'pending'`:
+
+**3a. Resolve runtime references** in each step's args:
+- `{key}` → lookup from `context[key]`
+- `{N-xxx.field}` → lookup from completed step with matching `node_id`
+- `{prev_field}` → lookup from most recently completed non-checkpoint step
+
+**3b. Handle checkpoint nodes** (no CSV spawn needed):
+- Save checkpoint snapshot to `checkpoints/{node_id}.json` (session state + context)
+- Update `context.last_checkpoint`, mark completed
+- If `auto_continue === false`: prompt user (Continue / Pause / Abort)
+
+**3c. Build wave CSV** for skill nodes:
+Write `wave-{N}.csv` with columns `id,skill_call,topic`. Each row: resolved `$${step.skill} ${args}`.
+
+**3d. Spawn agents**:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionDir}/wave-${waveNum}.csv`,
+  id_column: "id",
+  instruction: PLAYER_INSTRUCTION,
+  max_workers: waveSteps.length,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionDir}/wave-${waveNum}-results.csv`,
+  output_schema: RESULT_SCHEMA
+})
+```
+
+**3e. Read results**: Map each result row back to its step — update status, findings, artifacts, wave_n.
+
+**3f. Barrier analysis**: If barrier wave, read artifacts and update context (see barrier node table in `<context>`).
+
+**3g. Persist + abort check**: Append wave record to `state.waves[]`, persist `state.json`. If any result failed → set `state.status = 'aborted'`, mark remaining steps as skipped.
+
+### Sub-Agent Instruction Template
+
+```
+你是 CSV job 子 agent。
+
+先原样执行这一段技能调用：
+{skill_call}
+
+然后基于结果完成这一行任务说明：
+{topic}
+
+限制：
+- 不要修改 .workflow/.maestro/ 下的 state 文件
+- skill 内部有自己的 session 管理，按 skill SKILL.md 执行即可
+
+最后必须调用 `report_agent_job_result`，返回 JSON：
+{"status":"completed|failed","skill_call":"{skill_call}","summary":"一句话结果","artifacts":"产物路径或空字符串","error":"失败原因或空字符串"}
+```
+
+### Result Schema
+
+```javascript
+const RESULT_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["completed", "failed"] },
+    skill_call: { type: "string" },
+    summary: { type: "string" },
+    artifacts: { type: "string" },
+    error: { type: "string" }
+  },
+  required: ["status", "skill_call", "summary", "artifacts", "error"]
+};
+```
+
+---
+
+### Phase 4: Completion Report
+
+```
+============================================================
+  MAESTRO PLAYER SESSION COMPLETE
+============================================================
+  Session:   <session_id>
+  Template:  <template_name> (<template_id>)
+  Waves:     <N> executed
+  Steps:     <completed>/<total>
+  Context:   goal="<value>"
+
+  WAVE RESULTS:
+    [W1] $maestro-plan "{goal}"         →  ✓  plan created
+    [W2] $maestro-execute {phase}       →  ✓  12/12 tasks
+    [W3] $quality-test {phase}          →  ✓  all tests pass
+         $quality-review {phase}        →  ✓  no issues
+
+  State:    .workflow/.maestro/<session_id>/state.json
+  Resume:   $maestro-player -c
+============================================================
+```
+
+Update `state.status = "completed"`, write final `state.json`.
+</execution>
+
+<csv_schema>
+### wave-{N}.csv (Per-Wave Input)
+
+```csv
+id,skill_call,topic
+"1","$maestro-plan \"implement user auth\"","Template \"feature-plan-test\" step 1/5"
+```
+
+| Column | Description |
+|--------|-------------|
+| `id` | Step number (string) |
+| `skill_call` | Full skill invocation with resolved context args |
+| `topic` | Brief description for the agent |
+
+### wave-{N}-results.csv (Per-Wave Output)
+
+Written by `spawn_agents_on_csv`. Contains result per agent.
+</csv_schema>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Template not found | Show --list, suggest closest match |
+| E002 | error | Template JSON invalid | Point to file for fix |
+| E003 | error | Required variable missing, user declined | Cannot proceed |
+| E004 | error | DAG cycle in template | Suggest $maestro-composer --edit |
+| E005 | error | Resume session not found | List sessions |
+| E006 | error | Wave timeout | Mark failed, abort chain |
+| E007 | error | Barrier artifact not found | Retry wave once, then abort |
+| W001 | warning | Runtime reference resolved to empty | Log, continue |
+| W002 | warning | Barrier artifact partial | Continue with available context |
+</error_codes>
+
+<success_criteria>
+- [ ] Template loaded from `~/.maestro/templates/workflows/` and validated
+- [ ] All required context variables bound
+- [ ] Session dir at `.workflow/.maestro/MCP-*/` with `state.json`
+- [ ] DAG nodes converted to waves (barrier=solo, non-barrier=parallel)
+- [ ] Every skill invocation goes through `spawn_agents_on_csv` — none in coordinator
+- [ ] Checkpoint nodes handled inline (state save, optional user pause)
+- [ ] Barrier artifacts read and context updated before next wave
+- [ ] Runtime references ({N-xxx.field}, {prev_*}) resolved before each wave CSV
+- [ ] Failed step → remaining marked skipped → abort reported
+- [ ] `--dry-run` shows wave plan with [BARRIER] markers, no execution
+- [ ] `-c` resumes from last completed wave
+- [ ] Completion report with per-wave status
+</success_criteria>

package/codex/maestro-flow/commands/lifecycle/quick.md

@@ -0,0 +1,124 @@
+---
+name: maestro-quick
+description: Fast-track single task execution with workflow guarantees — analyze, plan, execute in one pass
+argument-hint: "\"task description\" [--discuss] [--full]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+---
+
+<purpose>
+Shortened pipeline for well-understood tasks. Creates a scratch directory, runs quick analysis, generates a plan, executes tasks, and optionally verifies results. Single agent, sequential flow — no CSV waves needed.
+
+**Pipeline**: `[discuss] → analyze-q → plan → execute → [verify]`
+
+Quick tasks default to minimal interaction. `--discuss` adds a decision extraction step. `--full` adds plan-checking and post-execution verification.
+</purpose>
+
+<context>
+
+```bash
+$maestro-quick "add rate limiting to /api/auth endpoints"
+$maestro-quick "refactor user service to use repository pattern" --discuss
+$maestro-quick "fix memory leak in WebSocket handler" --full
+$maestro-quick "add dark mode toggle to settings page" --discuss --full
+```
+
+**Flags**:
+- `--discuss`: Decision extraction before planning (Locked/Free/Deferred classification)
+- `--full`: Enable plan-checking (max 2 iterations) and post-execution verification
+
+**Output**: `.workflow/scratch/{slug}/` with plan.json, execution results, optional verification
+
+</context>
+
+<invariants>
+1. **Speed over ceremony** — minimal overhead, get to implementation fast
+2. **Follow existing patterns** — grep for 3+ similar implementations before writing new code
+3. **Atomic commits** — one commit per quick task, descriptive message
+4. **Scratch isolation** — all metadata stays in .workflow/scratch/{slug}/
+5. **Works without init** — quick tasks function even without full .workflow/ setup
+</invariants>
+
+<execution>
+
+### Step 1: Parse Arguments
+
+Extract from arguments:
+- `--discuss` flag
+- `--full` flag
+- Remaining text as task description (required — E001 if empty)
+
+### Step 2: Load Project Context
+
+Read `.workflow/state.json` and `.workflow/project.md` if they exist. If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
+
+### Step 3: Create Scratch Directory
+
+Generate slug from task description (lowercase, hyphens, max 40 chars). Create `.workflow/scratch/{slug}/`. Write `config.json` with: `task`, `flags` (discuss, full), `created_at` (ISO), `status` ("active").
+
+### Step 4: Discussion Phase (if --discuss)
+
+**Only when `--discuss` is set.**
+
+Analyze the task for gray areas and ambiguities:
+1. Identify decision points in the task
+2. Classify each as: **Locked** (clear from context), **Free** (implementation choice), **Deferred** (need user input)
+3. For Deferred items: ask user for decisions
+4. Write `context.md` to scratch directory with all decisions
+
+### Step 5: Quick Analysis
+
+Rapid codebase exploration focused on the task:
+1. Search for related files using Grep/Glob
+2. Identify existing patterns to follow
+3. Map dependencies and integration points
+4. Write analysis findings to `context.md` (append if --discuss created it)
+
+### Step 6: Generate Plan
+
+Create `plan.json` in scratch directory:
+- Decompose task into subtasks (typically 1-5 for quick tasks)
+- Each task has: id, title, description, scope, convergence_criteria, files
+- Assign single wave (sequential execution)
+
+**If `--full`**: Present plan for review, allow up to 2 revision iterations.
+
+### Step 7: Execute Tasks
+
+For each task in plan.json (sequential):
+1. Read task definition
+2. Implement changes following existing patterns
+3. Run any specified verification commands
+4. Write task summary with files_modified, status
+
+Update plan.json task statuses as completed.
+
+### Step 8: Verification (if --full)
+
+**Only when `--full` is set.** Run convergence criteria checks for each task via grep/test commands. If gaps found (W001): attempt single fix iteration, then report remaining gaps.
+
+### Step 9: Commit and Report
+
+Commit all changes: `git add -A && git commit -m "quick: {slug} - {short description}"`. Update `.workflow/state.json` scratch task entry (if state.json exists).
+
+Display report: task description, scratch path, status (completed/completed-with-gaps), tasks completed/total, files modified count. If `--full`: include verification result (PASS/GAPS).
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Task description required | Ask user for description |
+| E002 | error | Scratch directory creation failed | Check permissions |
+| W001 | warning | Verification found minor gaps | Report gaps, continue |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Scratch directory created with config.json
+- [ ] Analysis completed and context.md written
+- [ ] Plan generated with subtasks
+- [ ] All tasks executed and statuses updated
+- [ ] Changes committed with descriptive message
+- [ ] Completion report displayed
+</success_criteria>