maestro-flow 0.3.9 → 0.3.10

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
-description: Multi-dimensional analysis via CSV wave pipeline. Diamond topology — CLI exploration agents (Wave 1), 6-dimension scoring agents (Wave 2), decision synthesis agent (Wave 3). Supports dual depth with -q quick mode. Replaces maestro-analyze command.
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase|topic> [-q|--quick]\""
+description: Multi-dimensional analysis via CSV wave pipeline. Diamond topology — CLI exploration agents (Wave 1), 6-dimension scoring agents (Wave 2), decision synthesis agent (Wave 3). Supports dual depth with -q quick mode and --gaps issue root cause analysis. Replaces maestro-analyze command.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
@@ -25,6 +25,7 @@ $maestro-analyze --continue "analyze-microservices-20260318"
 - `-c, --concurrency N`: Max concurrent agents within each wave (default: 6)
 - `--continue`: Resume existing session
 - `-q, --quick`: Quick mode -- skip exploration + scoring, go straight to decision extraction (Wave 3 only)
+- `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl. Replaces manage-issue-analyze.
 
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
 **Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (decision extraction report) + `analysis.md` (6-dimension scoring summary)
@@ -37,7 +38,7 @@ Wave-based multi-dimensional analysis using `spawn_agents_on_csv`. Diamond topol
 
 **Core workflow**: Parse Subject -> CLI Exploration -> 6-Dimension Scoring -> Decision Synthesis
 
-**Dual depth**: Full mode (all 3 waves) or Quick mode (`-q`, Wave 3 only -- decision extraction from loaded context).
+**Tri-depth**: Full mode (all 3 waves), Quick mode (`-q`, Wave 3 only), or Gaps mode (`--gaps`, issue root cause analysis pipeline).
 
 ```
 +---------------------------------------------------------------------------+
@@ -170,10 +171,13 @@ 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/g, '')
+  .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
@@ -186,7 +190,11 @@ if (!fileExists('.workflow/state.json')) {
 const state = JSON.parse(Read('.workflow/state.json'))
 let scope, slug, phaseNum = null
 
-if (subjectArg === '') {
+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'
@@ -237,6 +245,16 @@ Bash(`mkdir -p ${scratchDir}`)
 
 3. **Quick mode routing**: If QUICK_MODE, generate only wave 3 (synthesis/decide) task in CSV. Skip exploration and scoring.
 
+3b. **Gaps mode routing** (if GAPS_MODE):
+   - Load issues from `.workflow/issues/issues.jsonl`
+   - If `gapsIssueId`: load single issue, validate existence
+   - If no ISS-ID: filter `status == "open" || status == "registered"`
+   - For each issue, generate an exploration task (wave 1) focused on issue context
+   - Generate a synthesis task (wave 2) that writes analysis records back to issues.jsonl
+   - Skip standard dimension scoring (wave 2 in normal mode)
+   - Pipeline: Load Issues → CLI Exploration per issue → Root Cause Synthesis → Write issue.analysis → Output context.md
+   - On completion: append history entry `{ action: "analyzed", at: <ISO>, by: "maestro-analyze --gaps" }` per issue
+
 4. **Dimension and perspective selection** (full mode):
 
 | Depth | Exploration Dimensions | Scoring Dimensions |
@@ -540,7 +558,9 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"exploration_finding","data":{"file":
 
 | Error | Resolution |
 |-------|------------|
-| Subject argument missing | Abort with error: "Analysis subject required (phase number or topic text)" |
+| Subject argument missing (non-gaps) | Abort with error: "Analysis subject required (phase number or topic text)" |
+| --gaps but no issues found | Abort with error: "No open/registered issues in issues.jsonl" |
+| --gaps ISS-ID not found | Abort with error: "Issue {ISS-ID} not found — run manage-issue list" |
 | Phase directory not found | List available phases, abort with error |
 | No prior context for quick mode | Warn: limited context, proceed with available information |
 | Exploration agent timeout | Mark as failed, continue with remaining exploration agents |
@@ -562,7 +582,8 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"exploration_finding","data":{"file":
 4. **Context Propagation**: prev_context built from master CSV, not from memory
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
 6. **Quick Mode Shortcut**: With -q flag, generate only wave 3 task, skip exploration and scoring
+6b. **Gaps Mode Pipeline**: With --gaps flag, load issues, explore per issue, write analysis records back to issues.jsonl, output context.md for plan --gaps
 7. **Skip on Failure**: Degrade gracefully -- missing exploration reduces scoring quality, missing scoring reduces synthesis quality
 8. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 9. **DO NOT STOP**: Continuous execution until all waves complete
-10. **Dual Output**: context.md is ALWAYS produced (both modes). analysis.md + conclusions.json are full-mode only.
+10. **Tri-Output**: context.md is ALWAYS produced (all modes). analysis.md + conclusions.json are full-mode only. Gaps mode writes analysis records to issues.jsonl + context.md for plan --gaps.

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

@@ -0,0 +1,248 @@
+---
+name: maestro-chain
+description: Flat chain coordinator — resolve intent, build single CSV with all steps, execute via spawn_agents_on_csv (max_workers=1). Sub-agents self-discover context from prior results. No coordinator-side artifact analysis. Simpler than maestro but requires skills to be self-discovering.
+argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--chain <name>]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `-y` or `--yes`: Skip clarification and confirmation prompts. Pass `-y` through to each step's skill invocation.
+
+# Maestro Chain (Flat)
+
+## Usage
+
+```bash
+$maestro-chain "implement user authentication with JWT"
+$maestro-chain -y "refactor the payment module"
+$maestro-chain --continue
+$maestro-chain --dry-run "add rate limiting to API endpoints"
+$maestro-chain --chain feature "add dark mode toggle"
+```
+
+**Flags**:
+- `-y, --yes` — Auto mode: skip all prompts; propagate `-y` to each skill
+- `--continue` — Resume latest paused session (re-run from first failed/pending step)
+- `--dry-run` — Display planned chain without executing
+- `--chain <name>` — Force a specific chain (skips intent classification)
+
+**Session state**: `.workflow/.maestro-chain/{session-id}/`
+**Core Output**: `tasks.csv` + `results.csv` + `state.json`
+
+---
+
+## Overview
+
+Flat sequential chain execution — one CSV, one `spawn_agents_on_csv` call, done. Each skill is self-discovering: it reads `.workflow/state.json`, globs for latest artifacts, and resolves its own inputs. The coordinator only assembles initial args and launches.
+
+```
+Intent → Resolve Chain → Build tasks.csv → spawn_agents_on_csv(max_workers=1) → Read results → Report
+                           (all steps)       step 1 → step 2 → … → step N
+                                             (each skill self-discovers context)
+```
+
+**When to use this vs `$maestro`**:
+- Use `$maestro-chain` when all skills in the chain are self-discovering (read state.json, glob artifacts)
+- Use `$maestro` when you need coordinator-side artifact analysis between steps (dynamic arg resolution)
+
+---
+
+## Chain Map
+
+| Intent keywords | Chain | Steps (skills, in order) |
+|----------------|-------|--------------------------|
+| fix, bug, error, broken, crash | `quality-fix` | $maestro-analyze --gaps → $maestro-plan --gaps → $maestro-execute → $maestro-verify |
+| test, spec, coverage | `quality-test` | $quality-test |
+| 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 |
+
+---
+
+## Implementation
+
+> **Full chain map reference**: `~/.maestro/workflows/maestro.codex.md` — read for 35+ intent patterns and 40+ chain definitions.
+
+### Phase 1: Resolve Intent and Chain
+
+1. Parse arguments: extract `AUTO_YES`, `RESUME`, `DRY_RUN`, `forceChain`, `intent`
+2. Read `.workflow/state.json` for project context
+3. Classify intent → select chain (same logic as `$maestro`)
+4. If unclear and not AUTO_YES: ask one clarifying question
+5. Resolve phase from intent or state
+
+**`--continue` mode**: Load latest `state.json` from `.workflow/.maestro-chain/`, rebuild CSV from first pending step.
+
+**`--dry-run`**: Display chain and stop.
+
+---
+
+### Phase 2: Build CSV and Execute
+
+#### Assemble skill_call
+
+```javascript
+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) {
+  let args = (step.args ?? '')
+    .replace(/{phase}/g, resolvedPhase ?? '')
+    .replace(/{description}/g, intent ?? '')
+    .replace(/{issue_id}/g, resolvedIssueId ?? '');
+
+  if (AUTO_YES) {
+    const flag = AUTO_FLAG_MAP[step.cmd];
+    if (flag && !args.includes(flag)) args = args ? `${args} ${flag}` : flag;
+  }
+  return `$${step.cmd} ${args}`.trim();
+}
+```
+
+#### Generate tasks.csv
+
+```csv
+id,skill_call,topic
+"1","$maestro-analyze --gaps \"fix auth\" -y","Chain quality-fix step 1/4"
+"2","$maestro-plan --gaps -y","Chain quality-fix step 2/4"
+"3","$maestro-execute -y","Chain quality-fix step 3/4"
+"4","$maestro-verify -y","Chain quality-fix step 4/4"
+```
+
+#### Write state.json
+
+```javascript
+const sessionId = `MC-${dateStr}-${timeStr}`;
+const sessionDir = `.workflow/.maestro-chain/${sessionId}`;
+Bash(`mkdir -p ${sessionDir}`);
+
+Write(`${sessionDir}/state.json`, JSON.stringify({
+  id: sessionId,
+  intent,
+  chain: chainName,
+  auto_yes: AUTO_YES,
+  status: "running",
+  started_at: new Date().toISOString(),
+  steps: chain.map((s, i) => ({
+    step_n: i + 1,
+    cmd: s.cmd,
+    skill_call: buildSkillCall(s),
+    status: "pending"
+  }))
+}, null, 2));
+```
+
+#### Execute
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionDir}/tasks.csv`,
+  id_column: "id",
+  instruction: INSTRUCTION,
+  max_workers: 1,
+  max_runtime_seconds: 1800,
+  output_csv_path: `${sessionDir}/results.csv`,
+  output_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"]
+  }
+})
+```
+
+---
+
+### Instruction Template
+
+```
+你是 CSV job 子 agent。
+
+先原样执行这一段技能调用：
+{skill_call}
+
+然后基于结果完成这一行任务说明：
+{topic}
+
+限制：
+- skill 内部自己管理 session 和产物发现
+- 不要修改 .workflow/.maestro-chain/ 下的 state 文件
+
+最后必须调用 `report_agent_job_result`，返回 JSON：
+{"status":"completed|failed","skill_call":"{skill_call}","summary":"一句话结果","artifacts":"产物路径或空字符串","error":"失败原因或空字符串"}
+```
+
+---
+
+### Phase 3: Report
+
+Read `results.csv`, update `state.json`:
+
+```javascript
+const results = parseCSV(Read(`${sessionDir}/results.csv`));
+const done = results.filter(r => r.status === 'completed').length;
+const failed = results.filter(r => r.status === 'failed').length;
+
+state.status = failed > 0 ? 'completed_with_errors' : 'completed';
+state.completed_at = new Date().toISOString();
+for (const row of results) {
+  const step = state.steps[parseInt(row.id) - 1];
+  step.status = row.status;
+  step.summary = row.summary;
+  step.artifacts = row.artifacts;
+  step.error = row.error;
+}
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+```
+
+Display:
+
+```
+=== CHAIN COMPLETE ===
+Session:  <sessionId>
+Chain:    <chain>
+Steps:    <done>/<total>
+
+RESULTS:
+  [1] $maestro-analyze --gaps  →  ✓  <summary>
+  [2] $maestro-plan --gaps     →  ✓  <summary>
+  [3] $maestro-execute         →  ✓  <summary>
+  [4] $maestro-verify          →  ✓  <summary>
+
+State:  .workflow/.maestro-chain/<sessionId>/state.json
+Resume: $maestro-chain --continue
+```
+
+---
+
+## Error Handling
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | Intent unclassifiable | Default to `feature` chain |
+| E002 | `--chain` not in map | List valid chains, abort |
+| E003 | Step timeout | Mark `failed` in results (subsequent steps still attempt) |
+| E004 | `--continue`: no session | List sessions, prompt |
+
+---
+
+## Core Rules
+
+1. **One CSV, one call**: Entire chain is a single `spawn_agents_on_csv` invocation
+2. **max_workers=1**: Strict sequential — step N finishes before step N+1 starts
+3. **Skills self-discover**: Each skill reads `.workflow/state.json` and globs for latest artifacts — no coordinator-side analysis needed
+4. **Simple instruction**: Sub-agent just executes `{skill_call}` verbatim and reports
+5. **Args resolved once**: All `{phase}`, `{description}` resolved at CSV build time — no dynamic updates mid-chain
+6. **Abort tolerance**: A failed step doesn't auto-skip subsequent steps — each skill decides independently whether to proceed
+7. **Resume = rebuild CSV**: `--continue` rebuilds CSV from first pending/failed step