maestro-flow 0.3.14 → 0.3.16

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

@@ -53,7 +53,14 @@ $ARGUMENTS — user intent text, or special flags.
 | refactor, cleanup, debt | `quality-refactor` | $quality-refactor |
 | feature, implement, add, build | `feature` | $maestro-plan → $maestro-execute → $maestro-verify |
 | review, check, audit | `quality-review` | $quality-review |
-| deploy, release, ship | `deploy` | $maestro-verify → $maestro-execute |
+| deploy, release, ship | `deploy` | $maestro-verify → $maestro-milestone-release |
+| brainstorm, explore, ideate | `brainstorm-driven` | $maestro-brainstorm → $maestro-plan → $maestro-execute → $maestro-verify |
+| plan, design, architect | `plan` | $maestro-plan |
+| debug, diagnose, troubleshoot | `debug` | $quality-debug |
+| continue, next, go | `state_continue` | (from project state) |
+| status, dashboard | `status` | $manage-status |
+
+Full chain map with 40+ chains: see `@~/.maestro/workflows/maestro.codex.md` §3c
 </chain_map>
 
 <barrier_skills>
@@ -72,36 +79,15 @@ After a barrier skill completes **in its spawned sub-agent**, coordinator reads
 
 ### Barrier Analysis Logic
 
-```javascript
-function analyzeBarrierArtifacts(step, result, ctx) {
-  const artifactPath = result.artifacts;
-  switch (step.skill) {
-    case 'maestro-analyze':
-      const contextMd = Read(`${artifactPath}/context.md`);
-      ctx.analysis_dir = artifactPath;
-      ctx.gaps = extractGaps(contextMd);
-      if (!ctx.phase) ctx.phase = extractPhase(contextMd);
-      break;
-    case 'maestro-plan':
-      const planJson = JSON.parse(Read(`${artifactPath}/plan.json`));
-      ctx.plan_dir = artifactPath;
-      ctx.task_count = planJson.tasks?.length ?? 0;
-      ctx.wave_count = planJson.waves?.length ?? 0;
-      break;
-    case 'maestro-brainstorm':
-      ctx.brainstorm_dir = artifactPath;
-      break;
-    case 'maestro-spec-generate':
-      ctx.spec_session_id = extractSpecId(artifactPath);
-      break;
-    case 'maestro-execute':
-      const execResults = Read(`${artifactPath}/results.csv`);
-      ctx.exec_completed = countStatus(execResults, 'completed');
-      ctx.exec_failed = countStatus(execResults, 'failed');
-      break;
-  }
-}
-```
+After each barrier skill completes, read its artifacts and update `state.context`:
+
+| Barrier Skill | Read | Context Updates |
+|---------------|------|-----------------|
+| `maestro-analyze` | `{artifacts}/context.md` | `analysis_dir`, `gaps` (extracted), `phase` (if unset) |
+| `maestro-plan` | `{artifacts}/plan.json` | `plan_dir`, `task_count`, `wave_count` from plan JSON |
+| `maestro-brainstorm` | `{artifacts}/` | `brainstorm_dir` |
+| `maestro-spec-generate` | `{artifacts}/` | `spec_session_id` (extracted) |
+| `maestro-execute` | `{artifacts}/results.csv` | `exec_completed`, `exec_failed` (counted by status) |
 </barrier_skills>
 
 <execution>
@@ -116,23 +102,17 @@ function analyzeBarrierArtifacts(step, result, ctx) {
 3. Otherwise classify intent via keyword heuristics (see chain_map)
 4. No match + not AUTO_YES → one clarifying question via `AskUserQuestion`
 5. Resolve chain's skill list
-6. Write `state.json`:
-
-```javascript
-const sessionId = `MCC-${dateStr}-${timeStr}`;
-const sessionDir = `.workflow/.maestro-coordinate/${sessionId}`;
-
-Write(`${sessionDir}/state.json`, JSON.stringify({
-  id: sessionId, intent, chain: resolvedChain, auto_yes: AUTO_YES,
-  status: "in_progress", started_at: new Date().toISOString(),
-  context: { phase: null, plan_dir: null, analysis_dir: null,
-             brainstorm_dir: null, spec_session_id: null, gaps: null },
-  waves: [],
-  steps: chain.map((skill, i) => ({
-    step_n: i + 1, skill: skill.cmd, args: skill.args ?? '',
-    status: "pending", wave_n: null
-  }))
-}, null, 2));
+6. Create session dir `.workflow/.maestro-coordinate/MCC-{dateStr}-{timeStr}/` and write `state.json`:
+
+```json
+{
+  "id": "MCC-{dateStr}-{timeStr}", "intent": "...", "chain": "...",
+  "auto_yes": false, "status": "in_progress", "started_at": "ISO",
+  "context": { "phase": null, "plan_dir": null, "analysis_dir": null,
+               "brainstorm_dir": null, "spec_session_id": null, "gaps": null },
+  "waves": [],
+  "steps": [{ "step_n": 1, "skill": "...", "args": "", "status": "pending", "wave_n": null }]
+}
 ```
 
 **`--dry-run`**: Display chain with `[BARRIER]` markers, stop.
@@ -141,95 +121,41 @@ Write(`${sessionDir}/state.json`, JSON.stringify({
 
 ### Phase 2: Wave Execution Loop
 
-```javascript
-let waveNum = 0;
-while (state.steps.some(s => s.status === 'pending')) {
-  waveNum++;
-  const waveSteps = buildNextWave(state.steps);
-
-  // Build CSV — coordinator assembles skill_call, sub-agent executes verbatim
-  const csvContent = 'id,skill_call,topic\n' + waveSteps.map(step =>
-    `"${step.step_n}","${buildSkillCall(step, state.context).replace(/"/g, '""')}","Chain \"${state.chain}\" step ${step.step_n}/${state.steps.length}"`
-  ).join('\n');
-  Write(`${sessionDir}/wave-${waveNum}.csv`, csvContent);
-
-  // Spawn — ALL execution via spawn_agents_on_csv, never direct
-  spawn_agents_on_csv({
-    csv_path: `${sessionDir}/wave-${waveNum}.csv`,
-    id_column: "id", instruction: WAVE_INSTRUCTION,
-    max_workers: waveSteps.length > 1 ? waveSteps.length : 1,
-    max_runtime_seconds: 1800,
-    output_csv_path: `${sessionDir}/wave-${waveNum}-results.csv`,
-    output_schema: RESULT_SCHEMA
-  });
-
-  // Read results, update status
-  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.findings; step.wave_n = waveNum;
-  }
-
-  // Barrier: read artifacts, update context (NOT execute — skill already ran in sub-agent)
-  if (isBarrier(waveSteps[0].skill)) {
-    analyzeBarrierArtifacts(waveSteps[0], results[0], state.context);
-  }
-
-  // Persist + abort check
-  state.waves.push({ wave_n: waveNum, steps: waveSteps.map(s => s.step_n), results });
-  Write(`${sessionDir}/state.json`, 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(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
-    break;
-  }
-}
-```
+**While pending steps remain**, increment `waveNum` and repeat:
+
+1. **Build wave**: Select next wave steps via `buildNextWave` (barrier = solo, non-barriers = grouped)
+2. **Write CSV**: `{sessionDir}/wave-{N}.csv` with columns `id,skill_call,topic` — one row per step, skill_call assembled with resolved context
+3. **Spawn**:
+   ```
+   spawn_agents_on_csv({
+     csv_path: "{sessionDir}/wave-{N}.csv",
+     id_column: "id", instruction: WAVE_INSTRUCTION,
+     max_workers: <wave size>, max_runtime_seconds: 1800,
+     output_csv_path: "{sessionDir}/wave-{N}-results.csv",
+     output_schema: RESULT_SCHEMA
+   })
+   ```
+4. **Read results**: Update each step's `status`, `findings`, `wave_n` from results CSV
+5. **Barrier check**: If wave was a barrier skill, run barrier analysis logic (read artifacts, update context)
+6. **Persist**: Append wave to `state.waves[]`, write `state.json`
+7. **Abort on failure**: If any result `status === 'failed'` → mark remaining steps `skipped`, set `state.status = 'aborted'`, break
 
 ### Skill Call Assembly
 
-```javascript
-const BARRIER_SKILLS = new Set([
-  'maestro-analyze', 'maestro-plan', 'maestro-brainstorm',
-  'maestro-spec-generate', 'maestro-execute'
-]);
-const AUTO_FLAG_MAP = {
-  'maestro-analyze': '-y', 'maestro-brainstorm': '-y',
-  'maestro-ui-design': '-y', 'maestro-plan': '--auto',
-  'maestro-spec-generate': '-y', 'quality-test': '--auto-fix',
-  'quality-retrospective': '--auto-yes',
-};
-
-function buildSkillCall(step, ctx) {
-  let args = (step.args ?? '')
-    .replace(/{phase}/g, ctx.phase ?? '')
-    .replace(/{description}/g, state.intent ?? '')
-    .replace(/{issue_id}/g, ctx.issue_id ?? '')
-    .replace(/{plan_dir}/g, ctx.plan_dir ?? '')
-    .replace(/{analysis_dir}/g, ctx.analysis_dir ?? '')
-    .replace(/{brainstorm_dir}/g, ctx.brainstorm_dir ?? '')
-    .replace(/{spec_session_id}/g, ctx.spec_session_id ?? '');
-  if (state.auto_yes) {
-    const flag = AUTO_FLAG_MAP[step.skill];
-    if (flag && !args.includes(flag)) args = args ? `${args} ${flag}` : flag;
-  }
-  return `$${step.skill} ${args}`.trim();
-}
+**Barrier skills**: `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-spec-generate`, `maestro-execute`
 
-function buildNextWave(steps) {
-  const pending = steps.filter(s => s.status === 'pending');
-  if (!pending.length) return [];
-  if (BARRIER_SKILLS.has(pending[0].skill)) return [pending[0]];
-  const wave = [pending[0]];
-  for (let i = 1; i < pending.length; i++) {
-    if (BARRIER_SKILLS.has(pending[i].skill)) break;
-    wave.push(pending[i]);
-  }
-  return wave;
-}
-```
+**Auto-yes flag map** (appended when `state.auto_yes` is true):
+
+| Skill | Flag |
+|-------|------|
+| `maestro-analyze`, `maestro-brainstorm`, `maestro-ui-design`, `maestro-spec-generate` | `-y` |
+| `maestro-plan` | `--auto` |
+| `quality-test` | `--auto-fix` |
+| `quality-retrospective` | `--auto-yes` |
+
+**`buildSkillCall(step, ctx)`**: Replace placeholders `{phase}`, `{description}`, `{issue_id}`, `{plan_dir}`, `{analysis_dir}`, `{brainstorm_dir}`, `{spec_session_id}` in `step.args` with corresponding `ctx` values. Append auto-yes flag if applicable. Return `$<skill> <args>`.
+
+**`buildNextWave(steps)`**: Take first pending step. If it is a barrier skill, return it solo. Otherwise, collect consecutive non-barrier pending steps into one wave (stop at first barrier).
 
 ### Sub-Agent Instruction Template
 
@@ -252,19 +178,7 @@ function buildNextWave(steps) {
 
 ### 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"]
-};
-```
+Object with all fields required: `status` ("completed"|"failed"), `skill_call` (string), `summary` (string), `artifacts` (path or ""), `error` (reason or "").
 
 ### Phase 3: Completion Report
 

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

@@ -161,71 +161,37 @@ 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]) : 6
-
-// Parse analyze-specific flags
-const QUICK_MODE = $ARGUMENTS.includes('-q') || $ARGUMENTS.includes('--quick')
-const GAPS_MODE = $ARGUMENTS.includes('--gaps')
-const gapsIssueMatch = $ARGUMENTS.match(/--gaps\s+(ISS-\S+)/)
-const gapsIssueId = gapsIssueMatch ? gapsIssueMatch[1] : null
-
-// Clean subject text
-const subjectArg = $ARGUMENTS
-  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|-q|--quick|--gaps\s+ISS-\S+|--gaps/g, '')
-  .trim()
-
-// Auto-bootstrap state.json if missing
-if (!fileExists('.workflow/state.json')) {
-  Bash('mkdir -p .workflow/scratch/')
-  writeMinimalStateJson()  // { project: null, status: "active", current_milestone: null, artifacts: [] }
-}
-
-// Scope determination (per scratch-milestone-architecture)
-const state = JSON.parse(Read('.workflow/state.json'))
-let scope, slug, phaseNum = null
-
-if (GAPS_MODE) {
-  // --gaps → issue root cause analysis
-  scope = 'gaps'
-  slug = gapsIssueId ? gapsIssueId.toLowerCase().replace(/[^a-z0-9]+/g, '-') : 'issue-gaps'
-} else if (subjectArg === '') {
-  // No args → milestone-wide
-  if (state.current_milestone && fileExists('.workflow/roadmap.md')) {
-    scope = 'milestone'
-    slug = slugify(state.milestones.find(m => m.id === state.current_milestone)?.name || state.current_milestone)
-  } else {
-    ERROR('E001: No args and no roadmap — provide topic text or create roadmap first')
-  }
-} else if (/^\d+$/.test(subjectArg)) {
-  // Phase number
-  if (state.current_milestone && fileExists('.workflow/roadmap.md')) {
-    scope = 'phase'
-    phaseNum = parseInt(subjectArg)
-    slug = resolvePhaseSlugFromRoadmap(phaseNum)  // parse roadmap.md for phase N slug
-  } else {
-    ERROR('Phase number requires init + roadmap')
-  }
-} else {
-  // Text → adhoc or standalone
-  slug = subjectArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
-  scope = state.current_milestone ? 'adhoc' : 'standalone'
-}
-
-const dateStr = getUtc8ISOString().substring(0, 10)
-const sessionId = `${dateStr}-analyze-${slug}`
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-const scratchDir = `.workflow/scratch/${dateStr}-analyze-${slug}`
-
-Bash(`mkdir -p ${sessionFolder}`)
-Bash(`mkdir -p ${scratchDir}`)
-```
+**Parse from `$ARGUMENTS`**:
+
+| Variable | Source | Default |
+|----------|--------|---------|
+| `AUTO_YES` | `--yes` or `-y` | false |
+| `continueMode` | `--continue` | false |
+| `maxConcurrency` | `--concurrency N` or `-c N` | 6 |
+| `QUICK_MODE` | `-q` or `--quick` | false |
+| `GAPS_MODE` | `--gaps` | false |
+| `gapsIssueId` | `--gaps ISS-{id}` | null |
+| `subjectArg` | remaining text after flag removal | "" |
+
+**Auto-bootstrap**: If `.workflow/state.json` missing, create minimal `{ project: null, status: "active", current_milestone: null, artifacts: [] }`.
+
+**Scope determination** (from `state.json` + `subjectArg`):
+
+| Condition | Scope | Slug |
+|-----------|-------|------|
+| `GAPS_MODE` | `gaps` | `gapsIssueId` slugified or `"issue-gaps"` |
+| Empty subject + milestone + roadmap | `milestone` | milestone name slugified |
+| Empty subject, no roadmap | ERROR: `"E001: No args and no roadmap"` | — |
+| Numeric subject + milestone + roadmap | `phase` | phase slug from roadmap |
+| Numeric subject, no roadmap | ERROR: `"Phase number requires init + roadmap"` | — |
+| Text subject + milestone | `adhoc` | subject slugified (max 40 chars) |
+| Text subject, no milestone | `standalone` | subject slugified (max 40 chars) |
+
+**Session paths** (UTC+8 date prefix):
+- `sessionFolder`: `.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/`
+- `scratchDir`: `.workflow/scratch/{YYYYMMDD}-analyze-{slug}/`
+
+Create both directories.
 
 ### Phase 1: Subject Resolution -> CSV
 
@@ -278,11 +244,7 @@ Available exploration dimensions:
 
 #### Wave 1: CLI Exploration (Parallel) [SKIP in -q mode]
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 1` AND `status == pending`
-3. No prev_context needed (wave 1 has no predecessors)
-4. Write `wave-1.csv`
-5. Execute:
+Filter `wave == 1 && status == pending` from master CSV. No prev_context (no predecessors). Write `wave-1.csv`.
 
 ```javascript
 spawn_agents_on_csv({
@@ -292,43 +254,22 @@ 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" },
-      score: { type: "string" },
-      recommendations: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
+  output_schema: { id, status: ["completed"|"failed"], findings, score, recommendations, error }
+  // required: id, status, findings
 })
 ```
 
-6. Read `wave-1-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-1.csv`
+Merge results into master `tasks.csv`, delete `wave-1.csv`.
 
-**Exploration agent responsibilities**:
-- 3-layer exploration per dimension:
-  - Layer 1: Module Discovery (breadth) -- search by topic keywords, identify relevant files, map module boundaries
-  - Layer 2: Structure Tracing (depth) -- top 3-5 key files: trace call chains 2-3 levels deep, identify data flow
-  - Layer 3: Code Anchor Extraction (detail) -- each key finding: extract code snippet (20-50 lines) with file:line
+**Exploration agent responsibilities** (3-layer per dimension):
+1. **Module Discovery** (breadth) -- keyword search, relevant files, module boundaries
+2. **Structure Tracing** (depth) -- top 3-5 files: call chains 2-3 levels, data flow
+3. **Code Anchor Extraction** (detail) -- code snippet (20-50 lines) with file:line per finding
 - Share findings via discovery board
 
 #### Wave 2: 6-Dimension Scoring (Parallel) [SKIP in -q mode]
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 2` AND `status == pending`
-3. Build `prev_context` from wave 1 findings:
-   ```
-   [Task 1: Explore Architecture] Module boundaries: src/auth/, src/api/, src/core/. Key pattern: repository layer...
-   [Task 2: Explore Implementation] Error handling: Result type pattern. Type coverage: 85%...
-   [Task 3: Explore Performance] Hot path: request handler chain (3 middleware). No async bottlenecks...
-   ```
-4. Write `wave-2.csv` with `prev_context` column
-5. Execute:
+Filter `wave == 2 && status == pending` from master CSV. Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per exploration task). Write `wave-2.csv` with `prev_context` column.
 
 ```javascript
 spawn_agents_on_csv({
@@ -338,23 +279,12 @@ spawn_agents_on_csv({
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 600,
   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" },
-      score: { type: "string" },
-      recommendations: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings", "score"]
-  }
+  output_schema: { id, status: ["completed"|"failed"], findings, score, recommendations, error }
+  // required: id, status, findings, score
 })
 ```
 
-6. Read `wave-2-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-2.csv`
+Merge results into master `tasks.csv`, delete `wave-2.csv`.
 
 **Scoring agent responsibilities** (6 dimensions):
 
@@ -371,22 +301,13 @@ Each score MUST include specific evidence (code refs, data points from explorati
 
 #### Wave 3: Decision Synthesis (Single Agent)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 3` (or wave 1 in quick mode) AND `status == pending`
-3. For full mode: check deps -- if all wave 2 tasks failed, use available exploration context
-4. Build `prev_context`:
-   - Full mode: from wave 2 scoring findings
-     ```
-     [Task 4: Score Feasibility] Score: 75. Moderate difficulty, existing patterns support...
-     [Task 5: Score Impact] Score: 90. High user value, significant DX improvement...
-     [Task 6: Score Risk] Score: 40. Main risk: auth regression. Mitigation: incremental rollout...
-     ...
-     ```
-   - Quick mode: from loaded project context (project.md, roadmap, brainstorm artifacts)
-5. Write `wave-3.csv` (or `wave-1.csv` in quick mode) with `prev_context` column
-6. Execute `spawn_agents_on_csv` for synthesis agent
-7. Merge results into master `tasks.csv`
-8. Delete temporary CSV
+Filter `wave == 3` (or wave 1 in quick mode) `&& status == pending`. If full mode and all wave 2 failed, fall back to available exploration context.
+
+**prev_context source**:
+- Full mode: wave 2 scoring findings (format: `[Task N: Score Dim] Score: X. summary...`)
+- Quick mode: loaded project context (project.md, roadmap, brainstorm artifacts)
+
+Write wave CSV with `prev_context`, execute `spawn_agents_on_csv` for synthesis agent, merge results, delete temp CSV.
 
 **Synthesis agent responsibilities**:
 - Compile dimension scores into analysis.md (full mode):
@@ -486,28 +407,9 @@ Each score MUST include specific evidence (code refs, data points from explorati
 }
 ```
 
-6. **Auto-create issues from Deferred items**:
-
-```
-deferred_items = decisions.filter(d => d.classification == "Deferred")
-
-IF deferred_items.length > 0:
-  mkdir -p ".workflow/issues"
-  FOR each item IN deferred_items:
-    Append issue to .workflow/issues/issues.jsonl
-  Print: "Created {N} deferred issues for tracking"
-```
+6. **Auto-create issues from Deferred items**: Filter decisions with `classification == "Deferred"`, append each as issue to `.workflow/issues/issues.jsonl`.
 
-7. **Register artifact in state.json**:
-   ```
-   Read .workflow/state.json
-   next_id = max ANL-NNN + 1 (or 1 if none)
-   Push artifact: { id: "ANL-{next_id}", type: "analyze", milestone: current_milestone,
-     phase: phaseNum, scope: scope, path: scratchDir (relative to .workflow/),
-     status: "completed", depends_on: null, harvested: false,
-     created_at: session_start, completed_at: now() }
-   Write state.json (atomic)
-   ```
+7. **Register artifact in state.json**: Append `{ id: "ANL-{next_id}", type: "analyze", milestone, phase, scope, path: scratchDir, status: "completed", depends_on: null, harvested: false, created_at, completed_at }`.
 8. Copy final outputs (context.md, analysis.md, conclusions.json) from CSV session folder to `scratchDir`
 9. Display summary