maestro-flow 0.3.15 → 0.3.16

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

@@ -141,68 +141,31 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Initialization
 
 ```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-// Parse flags
-const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-const continueMode = $ARGUMENTS.includes('--continue')
-const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
-const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 4
-
-// Parse plan-specific flags
-const autoMode = $ARGUMENTS.includes('--auto')
-const gapsMode = $ARGUMENTS.includes('--gaps')
-const dirMatch = $ARGUMENTS.match(/--dir\s+(\S+)/)
-const specMatch = $ARGUMENTS.match(/--spec\s+(SPEC-\S+)/)
-const collabMode = $ARGUMENTS.includes('--collab')
-
-// Clean phase text
-const phaseArg = $ARGUMENTS
-  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--auto|--gaps|--parallel|--collab|--dir\s+\S+|--spec\s+\S+/g, '')
-  .trim()
-
-// Auto-bootstrap state.json if missing
-if (!fileExists('.workflow/state.json')) {
-  Bash('mkdir -p .workflow/scratch/')
-  writeMinimalStateJson()
-}
-
-// Scope determination (per scratch-milestone-architecture)
-const state = JSON.parse(Read('.workflow/state.json'))
-let scope, phaseNum = null, phaseSlug, contextDir
-
-if (dirMatch) {
-  contextDir = dirMatch[1]
-  phaseSlug = contextDir.split('/').pop()
-  // Inherit scope from parent artifact if registered
-  const parentArtifact = state.artifacts.find(a => a.path === contextDir)
-  scope = parentArtifact?.scope || 'standalone'
-} else if (phaseArg === '') {
-  if (state.current_milestone && fileExists('.workflow/roadmap.md')) {
-    scope = 'milestone'
-    phaseSlug = slugify(state.milestones.find(m => m.id === state.current_milestone)?.name || state.current_milestone)
-    // Find latest analyze artifact for this milestone
-    contextDir = state.artifacts.filter(a => a.type === 'analyze' && a.milestone === state.current_milestone && a.status === 'completed').pop()?.path
-  } else {
-    ERROR('E001: No args and no roadmap')
-  }
-} else if (/^\d+$/.test(phaseArg)) {
-  scope = 'phase'
-  phaseNum = parseInt(phaseArg)
-  phaseSlug = resolvePhaseSlugFromRoadmap(phaseNum)
-  contextDir = state.artifacts.filter(a => a.type === 'analyze' && a.milestone === state.current_milestone && a.phase === phaseNum && a.status === 'completed').pop()?.path
-} else {
-  scope = state.current_milestone ? 'adhoc' : 'standalone'
-  phaseSlug = phaseArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
-}
-
-const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `${dateStr}-plan-P${phaseArg}-${phaseSlug}`
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-const scratchDir = `.workflow/scratch/${dateStr}-plan-P${phaseArg}-${phaseSlug}`
-
-Bash(`mkdir -p ${sessionFolder}`)
-Bash(`mkdir -p ${scratchDir}/.task/`)
+// Parse from $ARGUMENTS:
+//   AUTO_YES      <- --yes | -y
+//   continueMode  <- --continue
+//   maxConcurrency <- --concurrency N | -c N  (default: 4)
+//   autoMode      <- --auto
+//   gapsMode      <- --gaps
+//   dirMatch      <- --dir <path>
+//   specMatch     <- --spec SPEC-xxx
+//   collabMode    <- --collab
+//   phaseArg      <- remaining text after stripping all flags
+
+// Auto-bootstrap .workflow/state.json if missing
+
+// Scope determination from state.json (priority order):
+//   --dir given       → scope from parent artifact or 'standalone'
+//   phaseArg empty    → 'milestone' (requires current_milestone + roadmap.md) or ERROR E001
+//   phaseArg is digit → 'phase', resolve slug from roadmap, find latest completed analyze artifact
+//   phaseArg is text  → 'adhoc' (if milestone active) or 'standalone', slugify phaseArg
+
+// Session IDs (UTC+8):
+//   sessionId    = {YYYYMMDD}-plan-P{phaseArg}-{phaseSlug}
+//   sessionFolder = .workflow/.csv-wave/{sessionId}
+//   scratchDir    = .workflow/scratch/{sessionId}
+
+// Create: sessionFolder, scratchDir/.task/
 ```
 
 ### Phase 1: Phase Resolution -> CSV
@@ -266,21 +229,13 @@ spawn_agents_on_csv({
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
+  output_schema: { // required: id, status, findings
+    id: "string", status: "completed|failed", findings: "string", error: "string"
   }
 })
 ```
 
-6. Read `wave-1-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-1.csv`
+6. Merge `wave-1-results.csv` into master `tasks.csv`, delete `wave-1.csv`
 
 #### Wave 2: Plan Generation (Sequential)
 
@@ -303,123 +258,44 @@ spawn_agents_on_csv({
   instruction: buildPlanningInstruction(sessionFolder, phaseDir, {
     contextMd, indexJson, specRef, docIndex, designRef, gapsContext
   }),
-  max_concurrency: 1,  // Sequential — single planning agent
+  max_concurrency: 1,  // Single planning agent
   max_runtime_seconds: 900,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
+  output_schema: { // required: id, status, findings
+    id: "string", status: "completed|failed", findings: "string", error: "string"
   }
 })
 ```
 
-6. Merge results into master `tasks.csv`
-7. Delete `wave-2.csv`
+6. Merge `wave-2-results.csv` into master `tasks.csv`, delete `wave-2.csv`
 
 **Planning agent responsibilities** (embedded in instruction):
-- Decompose phase goal into concrete tasks (TASK-001, TASK-002, ...)
-- Determine dependencies and group into execution waves
-- Apply Deep Work Rules:
-  - Every task has `read_first[]` with file being modified + source of truth files
-  - Every task has `convergence.criteria[]` with grep-verifiable conditions
-  - Every `action` has concrete values (never "align X with Y")
-  - Every `implementation` step has specific values
-- Write `plan.json` to `{PHASE_DIR}/plan.json`
-- Write `.task/TASK-{NNN}.json` files to `{PHASE_DIR}/.task/`
-- If `--gaps`: create fix tasks from gap context, link to issues
-- If `--collab`: pre-allocate ID ranges for parallel planners
+- Decompose phase goal → TASK-001..N with dependencies grouped into execution waves
+- Apply Deep Work Rules: `read_first[]` includes modified file + source of truth; `convergence.criteria[]` are grep-verifiable; all actions/steps have concrete values
+- Write `plan.json` to `{PHASE_DIR}/plan.json` and `.task/TASK-{NNN}.json` to `{PHASE_DIR}/.task/`
+- `--gaps`: create fix tasks from gap context, link to issues; `--collab`: pre-allocate ID ranges
 
 ### Phase 3: Plan Checking + Confirmation
 
 **Objective**: Validate plan quality, revise if needed, present to user.
 
 1. **Plan checking** (inline, not a separate wave):
-   - Read generated `plan.json` + all `.task/TASK-*.json`
-   - Validate dimensions:
-
-| Check | Criteria |
-|-------|----------|
-| Requirements coverage | Every success_criterion maps to at least one task |
-| Feasibility | Referenced files exist or can be created |
-| Dependency correctness | No circular deps, deps exist, wave ordering valid |
-| Convergence criteria quality | Grep-verifiable, no subjective language |
-| read_first completeness | Every task has read_first[] with modified file |
-| Action concreteness | No vague "align X with Y" |
-| Wave structure | Parallel tasks have no conflicting file modifications |
+   Read `plan.json` + all `.task/TASK-*.json`. Validate: requirements coverage, file feasibility, dependency correctness (no cycles, valid wave order), grep-verifiable convergence criteria, read_first completeness, action concreteness, no parallel file conflicts.
 
 2. **Revision loop** (max 3 rounds): If critical issues found, regenerate affected tasks.
 
 3. **Export results**:
    - Export `results.csv` from master `tasks.csv`
-   - Generate `context.md`:
-
-```markdown
-# Plan Report -- Phase {phase}
-
-## Summary
-- Phase: {phase_name}
-- Tasks: {task_count} in {wave_count} waves
-- Complexity: {complexity}
-- Explorations: {exploration_count} angles explored
-
-## Exploration Findings
+   - Generate `context.md`: summary (phase, task count, wave count, complexity, exploration count), exploration findings per angle, plan overview (approach, task IDs, waves), next steps
 
-### {angle}: {title}
-{findings}
-
-## Plan Overview
-- Approach: {plan.approach}
-- Task IDs: {task_ids}
-- Waves: {wave_structure}
-
-## Next Steps
-{suggested actions}
-```
-
-4. **Update index.json**:
-   ```json
-   {
-     "status": "planning",
-     "plan": {
-       "task_ids": ["TASK-001", "TASK-002"],
-       "task_count": N,
-       "complexity": "moderate",
-       "waves": [[...], [...]]
-     },
-     "updated_at": "<ISO>"
-   }
-   ```
+4. **Update index.json**: set `status: "planning"`, `plan: { task_ids, task_count, complexity, waves }`, `updated_at`
 
 5. **Issue linking** (if --gaps):
-   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 bidirectional issue <-> TASK traceability for dashboard display.
+   For each TASK with `issue_id`: update issue in `issues.jsonl` (`task_refs` += TASK-NNN, `task_plan_dir`, `status: "planned"`, `updated_at`) + append history entry. Ensures bidirectional issue-TASK traceability.
 
 6. **Display summary + options** (skip options if AUTO_YES):
-   ```
-   === PLAN READY ===
-   Phase: {phase_name}
-   Tasks: {task_count} tasks in {wave_count} waves
-   Check: {checker_status}
-
-   Plan: {scratch_dir}/plan.json
-   Tasks: {scratch_dir}/.task/TASK-*.json
-
-   Next steps:
-     Skill({ skill: "maestro-execute", args: "{phase}" })  -- Execute the plan
-     Skill({ skill: "maestro-plan", args: "{phase}" })     -- Re-plan with modifications
-   ```
+   Show phase name, task/wave counts, checker status, output file paths.
+   Next steps: `maestro-execute "{phase}"` (execute) or `maestro-plan "{phase}"` (re-plan).
 
 ### Shared Discovery Board Protocol
 

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

@@ -130,75 +130,28 @@ If not found: "No templates. Create with $maestro-composer"
 
 **Trigger**: `-c [session-id]`
 
-1. If session-id given: load `.workflow/.maestro-coordinate/<session-id>/state.json`
-2. If no session-id: Glob `.workflow/.maestro-coordinate/MCP-*/state.json` sorted desc, find `status = "in_progress" | "paused"`
-3. None found → error E005
-4. Identify last completed wave, resume from next pending step
-5. Jump to Phase 3 (Wave Execution)
+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
 
-**Step 1.1** — Resolve template path:
-1. Absolute path → use as-is
-2. Slug → look up in `~/.maestro/templates/workflows/index.json`
-3. Partial match → confirm with user
-4. Not found → show `--list`, AskUserQuestion
-
-**Step 1.2** — Parse `--context key=value` pairs into `bound_context`.
-
-**Step 1.3** — Load and validate template JSON.
-
-**Step 1.4** — Collect missing required variables via AskUserQuestion.
-
-**Step 1.5** — Bind `{variable_name}` in all `args_template` strings. Leave `{N-xxx.field}` and `{prev_*}` unresolved (runtime Phase 3).
-
-**Step 1.6** — If `--dry-run`: print wave plan and exit (see Phase 2 output).
+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
 
-**Step 2.1** — Generate session ID: `MCP-<YYYYMMDD>-<HHmmss>`.
-
-**Step 2.2** — Topological sort (Kahn's algorithm) on template nodes + edges.
-
-**Step 2.3** — Classify barrier vs non-barrier per node:
-
-```javascript
-const BARRIER_SKILLS = new Set([
-  'maestro-analyze', 'maestro-plan', 'maestro-brainstorm',
-  'maestro-spec-generate', 'maestro-execute'
-]);
-
-function isBarrier(node) {
-  if (node.type === 'checkpoint') return true;
-  return BARRIER_SKILLS.has(node.executor);
-}
-```
-
-**Step 2.4** — Group into waves:
-
-```javascript
-function buildWaves(sortedNodes) {
-  const waves = [];
-  let currentWave = [];
-  for (const node of sortedNodes) {
-    if (isBarrier(node)) {
-      if (currentWave.length > 0) waves.push(currentWave);
-      waves.push([node]); // barrier = solo wave
-      currentWave = [];
-    } else {
-      currentWave.push(node);
-    }
-  }
-  if (currentWave.length > 0) waves.push(currentWave);
-  return waves;
-}
-```
-
-**Step 2.5** — Build steps array from waves. Write `state.json` to `.workflow/.maestro-coordinate/<session-id>/`.
+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-spec-generate`, `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:
 ```
@@ -223,69 +176,20 @@ function buildWaves(sortedNodes) {
 
 ### Phase 3: Wave Execution Loop
 
-```javascript
-let waveNum = 0;
-while (state.steps.some(s => s.status === 'pending')) {
-  waveNum++;
-  const waveSteps = getNextWave(state.steps);
-```
+Loop while any step has `status === 'pending'`:
 
 **3a. Resolve runtime references** in each step's args:
-
-```javascript
-function resolveArgs(args, steps, context) {
-  return args
-    .replace(/{(\w+)}/g, (_, key) => context[key] ?? '')
-    .replace(/{N-(\d+)\.(\w+)}/g, (_, id, field) => {
-      const step = steps.find(s => s.node_id === `N-${id}`);
-      return step?.[field] ?? '';
-    })
-    .replace(/{prev_(\w+)}/g, (_, field) => {
-      const prev = [...steps].reverse().find(s =>
-        s.status === 'completed' && s.type !== 'checkpoint');
-      return prev?.[field] ?? '';
-    });
-}
-```
+- `{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):
-
-```javascript
-if (waveSteps[0].type === 'checkpoint') {
-  const cp = waveSteps[0];
-  // Save checkpoint snapshot
-  Write(`${sessionDir}/checkpoints/${cp.node_id}.json`, JSON.stringify({
-    session_id: state.id, checkpoint_id: cp.node_id,
-    saved_at: new Date().toISOString(),
-    steps_snapshot: state.steps, context: state.context
-  }, null, 2));
-
-  state.context.last_checkpoint = cp.node_id;
-  cp.status = 'completed'; cp.wave_n = waveNum;
-
-  // If auto_continue == false: pause for user
-  if (!cp.auto_continue) {
-    AskUserQuestion: Continue / Pause / Abort
-    on Pause: state.status = 'paused', save, exit
-    on Abort: state.status = 'aborted', skip remaining, exit
-  }
-
-  Write(stateFile, JSON.stringify(state, null, 2));
-  continue;
-}
-```
+- 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:
-
-```javascript
-const csvContent = 'id,skill_call,topic\n' + waveSteps.map(step => {
-  const resolvedArgs = resolveArgs(step.args, state.steps, state.context);
-  const skillCall = `$${step.skill} ${resolvedArgs}`.trim();
-  return `"${step.step_n}","${skillCall.replace(/"/g, '""')}","Template \"${state.template_name}\" step ${step.step_n}/${state.steps.length}"`;
-}).join('\n');
-
-Write(`${sessionDir}/wave-${waveNum}.csv`, csvContent);
-```
+Write `wave-{N}.csv` with columns `id,skill_call,topic`. Each row: resolved `$${step.skill} ${args}`.
 
 **3d. Spawn agents**:
 
@@ -298,43 +202,14 @@ spawn_agents_on_csv({
   max_runtime_seconds: 1800,
   output_csv_path: `${sessionDir}/wave-${waveNum}-results.csv`,
   output_schema: RESULT_SCHEMA
-});
-```
-
-**3e. Read results, update state**:
-
-```javascript
-const results = readCSV(`${sessionDir}/wave-${waveNum}-results.csv`);
-for (const row of results) {
-  const step = state.steps.find(s => s.step_n === parseInt(row.id));
-  step.status = row.status;
-  step.findings = row.summary;
-  step.artifacts = row.artifacts;
-  step.wave_n = waveNum;
-}
+})
 ```
 
-**3f. Barrier analysis** (if barrier wave):
+**3e. Read results**: Map each result row back to its step — update status, findings, artifacts, wave_n.
 
-```javascript
-if (isBarrier(waveSteps[0])) {
-  analyzeBarrierArtifacts(waveSteps[0], results[0], state.context);
-}
-```
-
-**3g. Persist + abort check**:
+**3f. Barrier analysis**: If barrier wave, read artifacts and update context (see barrier node table in `<context>`).
 
-```javascript
-state.waves.push({ wave_n: waveNum, steps: waveSteps.map(s => s.step_n) });
-Write(stateFile, JSON.stringify(state, null, 2));
-
-if (results.some(r => r.status === 'failed')) {
-  state.status = 'aborted';
-  state.steps.filter(s => s.status === 'pending').forEach(s => s.status = 'skipped');
-  Write(stateFile, JSON.stringify(state, null, 2));
-  break;
-}
-```
+**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
 

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

@@ -49,30 +49,11 @@ Extract from arguments:
 
 ### Step 2: Load Project Context
 
-```bash
-cat .workflow/state.json 2>/dev/null
-cat .workflow/project.md 2>/dev/null
-```
-
-If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
+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).
-
-```bash
-mkdir -p .workflow/scratch/{slug}
-```
-
-Write `config.json` with task metadata:
-```json
-{
-  "task": "<description>",
-  "flags": { "discuss": false, "full": false },
-  "created_at": "<ISO timestamp>",
-  "status": "active"
-}
-```
+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)
 
@@ -113,37 +94,13 @@ Update plan.json task statuses as completed.
 
 ### Step 8: Verification (if --full)
 
-**Only when `--full` is set.**
-
-Run convergence criteria checks:
-```bash
-# For each task, verify convergence_criteria via grep/test commands
-```
-
-If gaps found (W001): attempt single fix iteration, then report remaining gaps.
+**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
 
-```bash
-git add -A
-git commit -m "quick: {slug} - {short description}"
-```
-
-Update `.workflow/state.json` scratch task entry (if state.json exists).
+Commit all changes: `git add -A && git commit -m "quick: {slug} - {short description}"`. Update `.workflow/state.json` scratch task entry (if state.json exists).
 
-```
-=== QUICK TASK COMPLETE ===
-Task:    {description}
-Scratch: .workflow/scratch/{slug}/
-Status:  {completed|completed-with-gaps}
-
-Tasks: {completed}/{total}
-Files modified: {count}
-
-{if --full}
-Verification: {PASS|GAPS}
-{endif}
-```
+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>