maestro-flow 0.3.9 → 0.3.11

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

@@ -0,0 +1,335 @@
+---
+name: maestro
+description: Intelligent coordinator — analyze intent, read project state, select chain, execute wave-by-wave via spawn_agents_on_csv. Coordinator only assembles prompts and reads artifacts — never executes skills directly.
+argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--chain <name>]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Wave-based pipeline coordinator. All skill execution happens exclusively in spawned sub-agents
+via `spawn_agents_on_csv` — the coordinator never executes skills directly.
+
+Coordinator loop: classify intent → resolve chain → build wave CSV → spawn → read results →
+(barrier: read artifacts, update context, assemble next skill_call args) → next wave → report.
+
+Each wave = 1 barrier task (solo) or N parallel non-barrier tasks.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/maestro.codex.md — authoritative `detectTaskType`, `detectNextAction`, `chainMap` (35+ intent patterns, 40+ chain types). Read before executing any step.
+</required_reading>
+
+<context>
+$ARGUMENTS — user intent text, or special flags.
+
+**Flags:**
+- `-y, --yes` — Auto mode: skip all prompts; propagate `-y` to each skill
+- `--continue` — Resume latest paused session from last incomplete wave
+- `--dry-run` — Display planned chain without executing
+- `--chain <name>` — Force specific chain (skips intent classification)
+
+**Session state**: `.workflow/.maestro-coordinate/{session-id}/`
+**Core output**: `tasks.csv` (master) + `wave-{N}-results.csv` (per wave) + `context.md` (report)
+</context>
+
+<invariants>
+1. **ALL skills via spawn_agents_on_csv**: Every skill invocation — barrier or non-barrier — MUST go through `spawn_agents_on_csv`. Coordinator NEVER directly executes any skill. No exceptions.
+2. **Coordinator = prompt assembler only**: Classify intent → build CSV → spawn → read results → assemble next CSV. It never runs skill logic itself.
+3. **Barrier ≠ execution**: Barrier designation only means the coordinator **pauses after the wave** to read artifacts and assemble the next wave's prompt args. Coordinator role at barrier: **discover artifacts → read → update context → assemble next skill_call args**. Nothing more.
+4. **Barrier = solo wave**: A barrier skill always executes alone in its wave (wave size = 1).
+5. **Non-barriers can parallel**: Consecutive non-barrier skills grouped into one wave (`max_workers = N`).
+6. **Wave-by-wave**: Never start wave N+1 before wave N results are read and analyzed.
+7. **Coordinator owns context**: Sub-agents never read prior results — coordinator assembles the full `skill_call` with resolved args.
+8. **Simple instruction**: Sub-agent instruction is minimal — just "execute {skill_call}, report result".
+9. **Abort on failure**: Failed step → mark remaining as skipped → report.
+10. **Resume from wave**: `--continue` finds last completed wave, resumes from next pending step.
+</invariants>
+
+<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 |
+</chain_map>
+
+<barrier_skills>
+Skills that produce artifacts the coordinator must read before assembling the next wave.
+After a barrier skill completes **in its spawned sub-agent**, coordinator reads output and updates `state.context`.
+
+| Skill | Artifacts to Read | Context Updates |
+|-------|------------------|-----------------|
+| `maestro-analyze` | `.workflow/.csv-wave/*/context.md`, `state.json` | `gaps`, `phase`, `analysis_dir` |
+| `maestro-plan` | `{phase_dir}/plan.json`, `{phase_dir}/.task/TASK-*.json` | `plan_dir`, `task_count`, `wave_count` |
+| `maestro-brainstorm` | `.workflow/.csv-wave/*/.brainstorming/` | `brainstorm_dir`, `features` |
+| `maestro-spec-generate` | `.workflow/.csv-wave/*/specs/` | `spec_session_id` |
+| `maestro-execute` | `.workflow/.csv-wave/*/results.csv` | `exec_status`, `completed_tasks`, `failed_tasks` |
+
+**Non-barrier skills** (groupable into multi-task waves): `maestro-verify`, `quality-review`, `quality-test`, `quality-debug`, `quality-refactor`, `quality-sync`, `manage-*`
+
+### 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;
+  }
+}
+```
+</barrier_skills>
+
+<execution>
+
+### Phase 1: Resolve Intent and Chain
+
+**`--continue`**: Glob `.workflow/.maestro-coordinate/MCC-*/state.json` sorted desc; load most recent; resume from first pending wave.
+
+**Fresh mode**:
+1. Read `.workflow/state.json` for project context (`current_phase`, `workflow_name`)
+2. If `--chain` given, use directly
+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));
+```
+
+**`--dry-run`**: Display chain with `[BARRIER]` markers, stop.
+
+**User confirmation** (skip if AUTO_YES): Display plan, prompt `Proceed? (yes/no)`.
+
+### 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;
+  }
+}
+```
+
+### 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();
+}
+
+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;
+}
+```
+
+### Sub-Agent Instruction Template
+
+```
+你是 CSV job 子 agent。
+
+先原样执行这一段技能调用：
+{skill_call}
+
+然后基于结果完成这一行任务说明：
+{topic}
+
+限制：
+- 不要修改 .workflow/.maestro-coordinate/ 下的 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 3: Completion Report
+
+```
+=== COORDINATE COMPLETE ===
+Session:  <sessionId>
+Chain:    <chain>
+Waves:    <N> executed
+Steps:    <completed>/<total>
+
+WAVE RESULTS:
+  [W1] $maestro-analyze --gaps  →  ✓  found 3 gaps
+  [W2] $maestro-plan --gaps     →  ✓  12 tasks in 3 waves
+  [W3] $maestro-execute         →  ✓  12/12 tasks done
+  [W4] $maestro-verify          →  ✓  all criteria met
+
+State:    .workflow/.maestro-coordinate/<sessionId>/state.json
+Resume:   $maestro --continue
+```
+</execution>
+
+<csv_schema>
+### wave-{N}.csv (Per-Wave Input)
+
+```csv
+id,skill_call,topic
+"1","$maestro-analyze --gaps \"fix auth\" -y","Chain \"quality-fix\" step 1/4"
+```
+
+| Column | Description |
+|--------|-------------|
+| `id` | Step number from chain (string) |
+| `skill_call` | Full skill invocation assembled by coordinator with resolved context |
+| `topic` | Brief description for the agent |
+
+### tasks.csv (Master State)
+
+```csv
+id,skill,args,wave_n,status,findings,artifacts,error
+```
+
+Accumulated across all waves. Updated after each wave completes.
+</csv_schema>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Intent unclassifiable after clarification | Default to `feature` chain |
+| E002 | error | `--chain` value not in chain map | List valid chains, abort |
+| E003 | error | Wave timeout (max_runtime_seconds) | Mark step `failed`, abort chain |
+| E004 | error | Barrier artifact not found | Retry wave once, then abort |
+| E005 | error | `--continue`: no session found | List sessions, prompt |
+| W001 | warning | Barrier artifact partial | Continue with available context |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent classified and chain resolved (keyword heuristics or `--chain`)
+- [ ] Session dir initialized with `state.json` before first wave
+- [ ] Every skill invocation goes through `spawn_agents_on_csv` — none executed in coordinator
+- [ ] Barrier skills execute solo in their wave; coordinator only reads artifacts afterward
+- [ ] Non-barrier skills grouped into parallel waves where possible
+- [ ] Each wave: CSV built → spawned → results read → state updated
+- [ ] Barrier artifacts read and context updated before assembling next wave's skill_call args
+- [ ] Failed step → remaining marked skipped → abort reported
+- [ ] Completion report with per-wave status written to `context.md`
+- [ ] `--dry-run` shows chain with [BARRIER] markers, no execution
+- [ ] `--continue` resumes from last incomplete wave
+</success_criteria>

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

@@ -1,43 +1,16 @@
 ---
 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
 ---
 
-## Auto Mode
-
-When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive scoping, use defaults for perspectives and depth, auto-deepen for up to 3 rounds.
-
-# Maestro Analyze (CSV Wave)
-
-## Usage
-
-```bash
-$maestro-analyze "3"
-$maestro-analyze -y "microservices vs monolith"
-$maestro-analyze -c 6 "3 -q"
-$maestro-analyze --continue "analyze-microservices-20260318"
-```
-
-**Flags**:
-- `-y, --yes`: Skip all confirmations (auto mode)
-- `-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)
-
-**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)
-
----
-
-## Overview
-
+<purpose>
 Wave-based multi-dimensional analysis using `spawn_agents_on_csv`. Diamond topology: CLI exploration agents gather codebase context (Wave 1), 6-dimension scoring agents evaluate in parallel (Wave 2), then decision synthesis agent compiles final decisions and context.md (Wave 3).
 
 **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).
 
 ```
 +---------------------------------------------------------------------------+
@@ -81,10 +54,30 @@ Wave-based multi-dimensional analysis using `spawn_agents_on_csv`. Diamond topol
 |                                                                           |
 +---------------------------------------------------------------------------+
 ```
+</purpose>
 
----
+<context>
+```bash
+$maestro-analyze "3"
+$maestro-analyze -y "microservices vs monolith"
+$maestro-analyze -c 6 "3 -q"
+$maestro-analyze --continue "analyze-microservices-20260318"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-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.
+
+When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive scoping, use defaults for perspectives and depth, auto-deepen for up to 3 rounds.
+
+**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)
+</context>
 
-## CSV Schema
+<csv_schema>
 
 ### tasks.csv (Master State)
 
@@ -124,9 +117,7 @@ id,title,description,dimension,analysis_type,deps,context_from,wave,status,findi
 
 Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 
----
-
-## Output Artifacts
+### Output Artifacts
 
 | File | Purpose | Lifecycle |
 |------|---------|-----------|
@@ -138,9 +129,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 | `analysis.md` | 6-dimension scoring summary + risk matrix + Go/No-Go | Created in Phase 3 (full mode only) |
 | `conclusions.json` | Structured conclusions with decision trail | Created in Phase 3 (full mode only) |
 
----
-
-## Session Structure
+### Session Structure
 
 ```
 .workflow/.csv-wave/analyze-{slug}-{date}/
@@ -152,10 +141,23 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 +-- conclusions.json
 +-- wave-{N}.csv (temporary)
 ```
+</csv_schema>
 
----
+<invariants>
+1. **Start Immediately**: First action is session initialization, then Phase 1
+2. **Wave Order is Sacred**: Never execute wave 2 before wave 1 completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all state
+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. **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.
+</invariants>
 
-## Implementation
+<execution>
 
 ### Session Initialization
 
@@ -170,10 +172,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 +191,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'
@@ -218,8 +227,6 @@ Bash(`mkdir -p ${sessionFolder}`)
 Bash(`mkdir -p ${scratchDir}`)
 ```
 
----
-
 ### Phase 1: Subject Resolution -> CSV
 
 **Objective**: Parse subject, load context, select dimensions, generate tasks.csv.
@@ -233,10 +240,20 @@ Bash(`mkdir -p ${scratchDir}`)
    - Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context`
    - Find prior analyze artifacts from `state.json.artifacts[]` (type=analyze, same milestone) → load their `context.md`
    - Find brainstorm artifacts from `state.json.artifacts[]` (type=brainstorm, same milestone) → load `guidance-specification.md`
-   - Load project specs: `maestro spec load --category planning`
+   - Load project specs: `maestro spec load --category arch`
 
 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 |
@@ -255,8 +272,6 @@ Available exploration dimensions:
 
 **User validation**: Display task breakdown (skip if AUTO_YES).
 
----
-
 ### Phase 2: Wave Execution Engine
 
 **Objective**: Execute analysis pipeline wave-by-wave via spawn_agents_on_csv.
@@ -386,8 +401,6 @@ Each score MUST include specific evidence (code refs, data points from explorati
 - Generate Locked/Free/Deferred decisions for context.md
 - Build conclusions.json (full mode) with decision trail and recommendations
 
----
-
 ### Phase 3: Results Aggregation
 
 **Objective**: Generate final results and output artifacts.
@@ -498,11 +511,9 @@ IF deferred_items.length > 0:
 8. Copy final outputs (context.md, analysis.md, conclusions.json) from CSV session folder to `scratchDir`
 9. Display summary
 
----
-
-## Shared Discovery Board Protocol
+### Shared Discovery Board Protocol
 
-### Standard Discovery Types
+#### Standard Discovery Types
 
 | Type | Dedup Key | Data Schema | Description |
 |------|-----------|-------------|-------------|
@@ -512,7 +523,7 @@ IF deferred_items.length > 0:
 | `blocker` | `data.issue` | `{issue, severity, impact}` | Blocking issue found |
 | `tech_stack` | singleton | `{framework, language, tools[]}` | Technology stack info |
 
-### Domain Discovery Types
+#### Domain Discovery Types
 
 | Type | Dedup Key | Data Schema | Description |
 |------|-----------|-------------|-------------|
@@ -522,7 +533,7 @@ IF deferred_items.length > 0:
 | `decision_candidate` | `data.area` | `{area, options[], recommendation, classification}` | Gray area for decision |
 | `alternative` | `data.name` | `{name, description, pros[], cons[], fit_score}` | Alternative approach |
 
-### Protocol
+#### Protocol
 
 1. **Read** `{session_folder}/discoveries.ndjson` before own analysis
 2. **Skip covered**: If discovery of same type + dedup key exists, skip
@@ -533,14 +544,15 @@ IF deferred_items.length > 0:
 ```bash
 echo '{"ts":"<ISO>","worker":"{id}","type":"exploration_finding","data":{"file":"src/auth/login.ts","line":42,"snippet":"export async function verifyToken(...)","dimension":"architecture","significance":"Core auth entry point"}}' >> {session_folder}/discoveries.ndjson
 ```
+</execution>
 
----
-
-## Error Handling
+<error_codes>
 
 | 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 |
@@ -551,18 +563,15 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"exploration_finding","data":{"file":
 | CSV parse error | Validate format, show line number |
 | discoveries.ndjson corrupt | Ignore malformed lines |
 | Continue mode: no session found | List available sessions |
-
----
-
-## Core Rules
-
-1. **Start Immediately**: First action is session initialization, then Phase 1
-2. **Wave Order is Sacred**: Never execute wave 2 before wave 1 completes and results are merged
-3. **CSV is Source of Truth**: Master tasks.csv holds all state
-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
-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.
+</error_codes>
+
+<success_criteria>
+- [ ] Session folder created with valid tasks.csv
+- [ ] All waves executed in order (or skipped per mode)
+- [ ] context.md produced (all modes)
+- [ ] analysis.md + conclusions.json produced (full mode only)
+- [ ] Deferred items auto-created as issues
+- [ ] Artifact registered in state.json
+- [ ] Final outputs copied to scratchDir
+- [ ] discoveries.ndjson append-only throughout
+</success_criteria>