maestro-flow 0.3.14 → 0.3.16

package/.claude/commands/wiki-connect.md

@@ -24,121 +24,11 @@ Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, he
 <context>
 Arguments: $ARGUMENTS
 
-**Flags:**
-- `--scope <type>` — Limit analysis to a wiki type (spec, memory, note, lesson, issue). Default: all types.
-- `--min-similarity N` — Minimum similarity score threshold 0.0-1.0 (default: 0.3)
-- `--fix` — Auto-apply the top suggestions by updating wiki entries with new `related` links
-- `--max N` — Maximum number of suggestions to generate (default: 20)
-
-**Storage written:**
-- `.workflow/learning/wiki-connections-{YYYY-MM-DD}.md` — Connection analysis report
-- If `--fix`: wiki entries updated via `maestro wiki update` with new `related` links
-- `.workflow/learning/lessons.jsonl` — Graph structure insights (source: "wiki-connect")
-
-**Storage read (via maestro wiki CLI, offline mode):**
-- `maestro wiki list --json` — All wiki entries
-- `maestro wiki graph` — Full graph structure (forward + backlinks)
-- `maestro wiki health` — Current health score
-- `maestro wiki orphans` — Orphaned entries
-- `maestro wiki hubs` — Hub entries (most referenced)
+Flags, storage paths, and CLI commands defined in workflow wiki-connect.md.
 </context>
 
 <execution>
-
-### Stage 1: Load Wiki State
-Run these `maestro wiki` commands in parallel:
-
-```bash
-maestro wiki list --json
-maestro wiki health
-maestro wiki orphans
-maestro wiki hubs --top 10
-```
-
-Parse results:
-- Entry count, type distribution
-- Baseline health score (from `wiki health`)
-- Orphan list (entries with 0 in-degree and 0 out-degree)
-- Hub list (most-referenced entries)
-
-Apply `--scope` filter if provided.
-
-### Stage 2: Identify Connection Candidates
-For each entry, compute potential connections:
-
-**2a. Orphan Rescue:**
-For each orphan entry, search for related entries using:
-- `maestro wiki search "<orphan title>"` — BM25 match by title
-- Tag overlap: entries sharing 2+ tags with the orphan
-- Same category: entries with matching `category`
-
-**2b. Missing Bidirectional Links:**
-For entries that have forward links but no corresponding backlink (A links to B, but B doesn't link to A), suggest adding the reverse link.
-
-**2c. Transitive Closure:**
-If A → B and B → C, but A has no link to C, and A and C share tags or category, suggest A → C.
-
-**2d. Type Bridge:**
-Entries of different types that reference the same concept (e.g., a `spec-auth` and a `lesson-auth-gotcha`) but aren't linked.
-
-### Stage 3: Score Candidates
-For each candidate connection (source → target), compute similarity:
-
-```
-score = 0.4 × tag_overlap_ratio
-      + 0.3 × title_bm25_similarity
-      + 0.2 × same_category_bonus
-      + 0.1 × type_bridge_bonus
-```
-
-- `tag_overlap_ratio`: shared_tags / max(source_tags, target_tags)
-- `title_bm25_similarity`: normalized BM25 score from wiki search
-- `same_category_bonus`: 1.0 if same category, else 0.0
-- `type_bridge_bonus`: 1.0 if different types, else 0.0
-
-Filter by `--min-similarity`, rank descending, limit to `--max`.
-
-### Stage 4: Present Suggestions
-Display ranked connection suggestions:
-
-```
-== Wiki Connection Suggestions ==
-Baseline health: 72/100 | Orphans: 8 | Broken links: 3
-
-#  Score  Source              → Target              Reason
-1  0.85   memory-auth-flow    → spec-auth           tag overlap (auth, security) + same phase
-2  0.71   note-cache-pattern  → spec-performance    title BM25 match + type bridge
-3  0.65   lesson-retry-fix    → spec-error-handling  tag overlap (error, retry)
-...
-
-Projected health after fix: 81/100 (+9)
-```
-
-If NOT `--fix`: display and exit.
-If `--fix`: proceed to Stage 5.
-
-### Stage 5: Apply Connections (--fix only)
-For each accepted suggestion:
-1. Get current entry: `maestro wiki get <source-id> --json`
-2. Extract existing `related` list from frontmatter
-3. Append target-id to `related` if not already present
-4. Update: `maestro wiki update <source-id> --frontmatter "related: [existing..., new-target]"`
-5. Log success/failure
-
-After all updates:
-- Re-run `maestro wiki health` to get new health score
-- Report delta
-
-### Stage 6: Persist & Report
-1. Write `.workflow/learning/wiki-connections-{date}.md` with:
-   - Baseline and final health scores
-   - All suggestions (applied and unapplied)
-   - Orphan rescue results
-   - Graph structure observations (hub concentration, type distribution)
-2. Append graph insights to `lessons.jsonl`:
-   - `source: "wiki-connect"`, `category: "technique"`
-   - e.g., "Auth-related entries are poorly connected", "Phase 3 has 5 orphaned notes"
-3. Display summary
+Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
 
 **Next-step routing:**
 - Generate knowledge digest → `/wiki-digest <topic>`

package/.claude/commands/wiki-digest.md

@@ -28,150 +28,11 @@ Unlike `maestro wiki list` which shows raw entries, this command synthesizes and
 <context>
 Arguments: $ARGUMENTS
 
-**Scope resolution (auto-detected):**
-- `<topic>` — Search wiki for entries matching the topic via `maestro wiki search`
-- `--recent N` — Entries updated in the last N days
-- `--type <type>` — Filter by wiki type (spec, memory, note, lesson, issue)
-- No arguments — digest of the entire wiki
-
-**Flags:**
-- `--format brief` — Compact summary, one paragraph per theme (default)
-- `--format full` — Detailed digest with per-entry summaries and full gap analysis
-- `--create-issues` — Auto-create `type: "knowledge-gap"` entries in `.workflow/issues/issues.jsonl` for each identified gap (closes the discovery→action loop)
-
-**Storage written:**
-- `.workflow/learning/digest-{slug}-{YYYY-MM-DD}.md` — Digest document
-- `.workflow/learning/lessons.jsonl` — Meta-insights about knowledge structure (source: "wiki-digest")
-- `.workflow/issues/issues.jsonl` — Knowledge-gap issues (only when `--create-issues`)
-
-**Storage read (via maestro wiki CLI, offline mode):**
-- `maestro wiki list --json` — All entries (or filtered)
-- `maestro wiki search <topic>` — Topic-scoped entries
-- `maestro wiki get <id>` — Entry bodies for summarization
-- `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
-- `maestro wiki health` — Overall graph health
-- `.workflow/learning/lessons.jsonl` — Cross-reference for unlinked insights
+Flags, scope resolution, storage paths, and CLI commands defined in workflow wiki-digest.md.
 </context>
 
 <execution>
-
-### Stage 1: Scope & Load
-- Parse arguments to determine scope:
-  - Topic: `maestro wiki search "<topic>" --json` → matching entries
-  - Recent N: `maestro wiki list --json` → filter by `updated` within N days
-  - Type: `maestro wiki list --type <type> --json`
-  - All: `maestro wiki list --json`
-- Load entry metadata (id, title, tags, status, type, related, summary)
-- For `--format full`: also load entry bodies via `maestro wiki get <id>` for top entries
-- Run `maestro wiki health` for baseline metrics
-
-### Stage 2: Theme Clustering
-Group entries into 3-5 semantic themes using:
-
-1. **Tag co-occurrence**: entries sharing 2+ tags belong to the same theme
-2. **Title similarity**: BM25-based grouping (entries whose titles match each other's keywords)
-3. **Relationship proximity**: entries connected by `related` links cluster together
-4. **Type grouping**: if entries are all same type, sub-cluster by content
-
-For each theme:
-- Name: most common tag or dominant keyword
-- Entry count
-- Type distribution within theme
-- Status distribution (draft/active/completed/archived)
-
-### Stage 3: Per-Theme Analysis
-For each theme, produce:
-
-**Summary paragraph**: synthesize the key knowledge in this theme area (what do these entries collectively say?)
-
-**Key entries**: top 3-5 most important entries (by hub score / backlink count)
-
-**Gap detection**:
-- Broken links: `[[references]]` that don't resolve within the theme
-- Orphans: entries in this theme with no connections
-- Questions: entries with `?` in title or "TODO" / "TBD" markers in body
-- Missing perspectives: if theme has specs but no lessons, or issues but no decisions
-
-**Health**: per-theme health score (adapted from wiki health formula)
-
-### Stage 4: Cross-Reference with Lessons
-- Search `lessons.jsonl` for insights related to each theme
-- Identify unlinked insights: lessons that match a theme but are not referenced by any wiki entry in that theme
-- Flag these as "knowledge not yet connected to the graph"
-
-### Stage 5: Coverage Heatmap
-Build a matrix showing knowledge density by type × theme:
-
-```
-              Theme 1    Theme 2    Theme 3    Theme 4    Theme 5
-spec          ███░░      ░░░░░      █████      ██░░░      ░░░░░
-memory        ░░░░░      ████░      ██░░░      ░░░░░      ███░░
-lesson        █░░░░      ██░░░      ████░      █░░░░      ░░░░░
-issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
-
-Legend: █ = entries exist, ░ = sparse/missing
-```
-
-Identify: which theme × type cells are empty? These are knowledge gaps.
-
-### Stage 6: Write Digest
-Produce `.workflow/learning/digest-{slug}-{date}.md`:
-
-```markdown
-# Knowledge Digest: {scope description}
-**Generated:** {date} | **Entries:** {count} | **Health:** {score}/100
-
-## Themes
-
-### 1. {Theme Name} ({N} entries)
-{summary paragraph}
-
-**Key entries:** {linked entry IDs}
-**Gaps:** {list of missing knowledge}
-**Health:** {score}/100
-
-### 2. {Theme Name} ...
-
-## Coverage Heatmap
-{matrix}
-
-## Knowledge Gaps
-| Gap | Theme | Type Missing | Suggested Action |
-|-----|-------|-------------|-----------------|
-| No lessons for auth patterns | Security | lesson | Run /learn-decompose on src/auth/ |
-
-## Unlinked Insights
-{lessons.jsonl entries not connected to wiki graph}
-
-## Recommended Actions
-1. {action}: {reason}
-2. ...
-```
-
-### Stage 7: Gap → Issue Routing (if --create-issues)
-For each knowledge gap identified in Stage 5:
-1. Check `.workflow/issues/issues.jsonl` for existing gap with same theme + type
-2. If not duplicate, append to `issues.jsonl` using the canonical schema from `~/.maestro/workflows/issue.md` Step 4:
-   - `id`: `ISS-XXXXXXXX-NNN` format (8 hex hash + sequence)
-   - `title`: "Knowledge gap: {gap description}"
-   - `type`: "knowledge-gap"
-   - `status`: "open"
-   - `severity`: "low"
-   - `priority`: "low"
-   - `source`: "wiki-digest"
-   - `description`: "Theme: {theme}, Missing type: {type}. Suggested action: {action}"
-   - `tags`: ["knowledge-gap", "{theme-slug}"]
-   - `created`: ISO date
-   - `issue_history`: initial entry with `action: "created"`, `by: "wiki-digest"`, `timestamp`
-3. Report created issue count
-
-### Stage 8: Persist
-1. Write digest file
-2. Append meta-insights to `lessons.jsonl`:
-   - `source: "wiki-digest"`, `category: "technique"`
-   - e.g., "Auth knowledge is concentrated in specs but lacks lessons", "Security category has no decision entries"
-3. Update `learning-index.json`
-4. Display summary with key findings
+Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
 
 **Next-step routing:**
 - Deep dive on a theme → `/learn-follow <wiki-id>`

package/.claude/skills/skill-iter-tune/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: skill-iter-tune
+description: Iterative skill tuning via execute-evaluate-improve feedback loop. Uses ccw cli Claude to execute skill, Gemini to evaluate quality, and Agent to apply improvements. Iterates until quality threshold or max iterations. Triggers on "skill iter tune", "iterative skill tuning", "tune skill".
+allowed-tools: Skill, Agent, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Skill Iter Tune
+
+Iterative skill refinement through execute-evaluate-improve feedback loops. Each iteration runs the skill via Claude, evaluates output via Gemini, and applies improvements via Agent.
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Skill Iter Tune Orchestrator (SKILL.md)                                 │
+│  → Parse input → Setup workspace → Iteration Loop → Final Report         │
+└────────────────────────────┬─────────────────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────────────────────┐
+         ↓                   ↓                                   ↓
+    ┌──────────┐      ┌─────────────────────────────┐     ┌──────────┐
+    │ Phase 1  │      │  Iteration Loop (2→3→4)     │     │ Phase 5  │
+    │ Setup    │      │  ┌─────┐  ┌─────┐  ┌─────┐ │     │ Report   │
+    │          │─────→│  │ P2  │→ │ P3  │→ │ P4  │ │────→│          │
+    │ Backup + │      │  │Exec │  │Eval │  │Impr │ │     │ History  │
+    │ Init     │      │  └─────┘  └─────┘  └─────┘ │     │ Summary  │
+    └──────────┘      │       ↑               │     │     └──────────┘
+                      │       └───────────────┘     │
+                      │    (if score < threshold    │
+                      │     AND iter < max)         │
+                      └─────────────────────────────┘
+```
+
+### Chain Mode Extension
+
+```
+Chain Mode (execution_mode === "chain"):
+
+Phase 2 runs per-skill in chain_order:
+  Skill A → ccw cli → artifacts/skill-A/
+       ↓ (artifacts as input)
+  Skill B → ccw cli → artifacts/skill-B/
+       ↓ (artifacts as input)
+  Skill C → ccw cli → artifacts/skill-C/
+
+Phase 3 evaluates entire chain output + per-skill scores
+Phase 4 improves weakest skill(s) in chain
+```
+
+## Key Design Principles
+
+1. **Iteration Loop**: Phases 2-3-4 repeat until quality threshold, max iterations, or convergence
+2. **Two-Tool Pipeline**: Claude (write/execute) + Gemini (analyze/evaluate) = complementary perspectives
+3. **Pure Orchestrator**: SKILL.md coordinates only — execution detail lives in phase files
+4. **Progressive Phase Loading**: Phase docs read only when that phase executes
+5. **Skill Versioning**: Each iteration snapshots skill state before execution
+6. **Convergence Detection**: Stop early if score stalls (no improvement in 2 consecutive iterations)
+
+## Interactive Preference Collection
+
+```javascript
+// ★ Auto mode detection
+const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
+
+if (autoYes) {
+  workflowPreferences = {
+    autoYes: true,
+    maxIterations: 5,
+    qualityThreshold: 80,
+    executionMode: 'single'
+  }
+} else {
+  const prefResponse = AskUserQuestion({
+    questions: [
+      {
+        question: "选择迭代调优配置：",
+        header: "Tune Config",
+        multiSelect: false,
+        options: [
+          { label: "Quick (3 iter, 70)", description: "快速迭代，适合小幅改进" },
+          { label: "Standard (5 iter, 80) (Recommended)", description: "平衡方案，适合多数场景" },
+          { label: "Thorough (8 iter, 90)", description: "深度优化，适合生产级 skill" }
+        ]
+      }
+    ]
+  })
+
+  const configMap = {
+    "Quick": { maxIterations: 3, qualityThreshold: 70 },
+    "Standard": { maxIterations: 5, qualityThreshold: 80 },
+    "Thorough": { maxIterations: 8, qualityThreshold: 90 }
+  }
+  const selected = Object.keys(configMap).find(k =>
+    prefResponse["Tune Config"].startsWith(k)
+  ) || "Standard"
+  workflowPreferences = { autoYes: false, ...configMap[selected] }
+
+  // ★ Mode selection: chain vs single
+  const modeResponse = AskUserQuestion({
+    questions: [{
+      question: "选择调优模式：",
+      header: "Tune Mode",
+      multiSelect: false,
+      options: [
+        { label: "Single Skill (Recommended)", description: "独立调优每个 skill，适合单一 skill 优化" },
+        { label: "Skill Chain", description: "按链序执行，前一个 skill 的产出作为后一个的输入" }
+      ]
+    }]
+  });
+  workflowPreferences.executionMode = modeResponse["Tune Mode"].startsWith("Skill Chain")
+    ? "chain" : "single";
+}
+```
+
+## Input Processing
+
+```
+$ARGUMENTS → Parse:
+  ├─ Skill path(s): first arg, comma-separated for multiple
+  │   e.g., ".claude/skills/my-skill" or "my-skill" (auto-prefixed)
+  │   Chain mode: order preserved as chain_order
+  ├─ Test scenario: --scenario "description" or remaining text
+  └─ Flags: --max-iterations=N, --threshold=N, -y/--yes
+```
+
+## Execution Flow
+
+> **⚠️ COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
+> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
+> Only compress phases marked `completed` or `pending`.
+
+### Phase 1: Setup (one-time)
+
+Read and execute: `Ref: phases/01-setup.md`
+
+- Parse skill paths, validate existence
+- Create workspace at `.workflow/.scratchpad/skill-iter-tune-{ts}/`
+- Backup original skill files
+- Initialize iteration-state.json
+
+Output: `workDir`, `targetSkills[]`, `testScenario`, initialized state
+
+### Iteration Loop
+
+```javascript
+// Orchestrator iteration loop
+while (true) {
+  // Increment iteration
+  state.current_iteration++;
+  state.iterations.push({
+    round: state.current_iteration,
+    status: 'pending',
+    execution: null,
+    evaluation: null,
+    improvement: null
+  });
+
+  // Update TodoWrite
+  TaskUpdate(iterationTask, {
+    subject: `Iteration ${state.current_iteration}/${state.max_iterations}`,
+    status: 'in_progress',
+    activeForm: `Running iteration ${state.current_iteration}`
+  });
+
+  // === Phase 2: Execute ===
+  // Read: phases/02-execute.md
+  // Single mode: one ccw cli call for all skills
+  // Chain mode: sequential ccw cli per skill in chain_order, passing artifacts
+  // Snapshot skill → construct prompt → ccw cli --tool claude --mode write
+  // Collect artifacts
+
+  // === Phase 3: Evaluate ===
+  // Read: phases/03-evaluate.md
+  // Construct eval prompt → ccw cli --tool gemini --mode analysis
+  // Parse score → write iteration-N-eval.md → check termination
+
+  // Check termination
+  if (shouldTerminate(state)) {
+    break;  // → Phase 5
+  }
+
+  // === Phase 4: Improve ===
+  // Read: phases/04-improve.md
+  // Agent applies suggestions → write iteration-N-changes.md
+
+  // Update TodoWrite with score
+  // Continue loop
+}
+```
+
+### Phase 2: Execute Skill (per iteration)
+
+Read and execute: `Ref: phases/02-execute.md`
+
+- Snapshot skill → `iteration-{N}/skill-snapshot/`
+- Build execution prompt from skill content + test scenario
+- Execute: `ccw cli -p "..." --tool claude --mode write --cd "${iterDir}/artifacts"`
+- Collect artifacts
+
+### Phase 3: Evaluate Quality (per iteration)
+
+Read and execute: `Ref: phases/03-evaluate.md`
+
+- Build evaluation prompt with skill + artifacts + criteria + history
+- Execute: `ccw cli -p "..." --tool gemini --mode analysis`
+- Parse 5-dimension score (Clarity, Completeness, Correctness, Effectiveness, Efficiency)
+- Write `iteration-{N}-eval.md`
+- Check termination: score >= threshold | iter >= max | convergence | error limit
+
+### Phase 4: Apply Improvements (per iteration, skipped on termination)
+
+Read and execute: `Ref: phases/04-improve.md`
+
+- Read evaluation suggestions
+- Launch general-purpose Agent to apply changes
+- Write `iteration-{N}-changes.md`
+- Update state
+
+### Phase 5: Final Report (one-time)
+
+Read and execute: `Ref: phases/05-report.md`
+
+- Generate comprehensive report with score progression table
+- Write `final-report.md`
+- Display summary to user
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose | Compact |
+|-------|----------|---------|---------|
+| 1 | [phases/01-setup.md](phases/01-setup.md) | Initialize workspace and state | TodoWrite 驱动 |
+| 2 | [phases/02-execute.md](phases/02-execute.md) | Execute skill via ccw cli Claude | TodoWrite 驱动 + 🔄 sentinel |
+| 3 | [phases/03-evaluate.md](phases/03-evaluate.md) | Evaluate via ccw cli Gemini | TodoWrite 驱动 + 🔄 sentinel |
+| 4 | [phases/04-improve.md](phases/04-improve.md) | Apply improvements via Agent | TodoWrite 驱动 + 🔄 sentinel |
+| 5 | [phases/05-report.md](phases/05-report.md) | Generate final report | TodoWrite 驱动 |
+
+**Compact Rules**:
+1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
+2. **TodoWrite `completed`** → 可压缩为摘要
+3. **🔄 sentinel fallback** → 若 compact 后仅存 sentinel 而无完整 Step 协议，立即 `Read()` 恢复
+
+## Core Rules
+
+1. **Start Immediately**: First action is preference collection → Phase 1 setup
+2. **Progressive Loading**: Read phase doc ONLY when that phase is about to execute
+3. **Snapshot Before Execute**: Always snapshot skill state before each iteration
+4. **Background CLI**: ccw cli runs in background, wait for hook callback before proceeding
+5. **Parse Every Output**: Extract structured JSON from CLI outputs for state updates
+6. **DO NOT STOP**: Continuous iteration until termination condition met
+7. **Single State Source**: `iteration-state.json` is the only source of truth
+
+## Data Flow
+
+```
+User Input (skill paths + test scenario)
+    ↓ (+ execution_mode + chain_order if chain mode)
+    ↓
+Phase 1: Setup
+    ↓ workDir, targetSkills[], testScenario, iteration-state.json
+    ↓
+┌─→ Phase 2: Execute (ccw cli claude)
+│   ↓ artifacts/ (skill execution output)
+│   ↓
+│   Phase 3: Evaluate (ccw cli gemini)
+│   ↓ score, dimensions[], suggestions[], iteration-N-eval.md
+│   ↓
+│   [Terminate?]─── YES ──→ Phase 5: Report → final-report.md
+│   ↓ NO
+│   ↓
+│   Phase 4: Improve (Agent)
+│   ↓ modified skill files, iteration-N-changes.md
+│   ↓
+└───┘ next iteration
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initial state
+TaskCreate({ subject: "Phase 1: Setup workspace", activeForm: "Setting up workspace" })
+TaskCreate({ subject: "Iteration Loop", activeForm: "Running iterations" })
+TaskCreate({ subject: "Phase 5: Final Report", activeForm: "Generating report" })
+
+// Chain mode: create per-skill tracking tasks
+if (state.execution_mode === 'chain') {
+  for (const skillName of state.chain_order) {
+    TaskCreate({
+      subject: `Chain: ${skillName}`,
+      activeForm: `Tracking ${skillName}`,
+      description: `Skill chain member position ${state.chain_order.indexOf(skillName) + 1}`
+    })
+  }
+}
+
+// During iteration N
+// Single mode: one score per iteration (existing behavior)
+// Chain mode: per-skill status updates
+if (state.execution_mode === 'chain') {
+  // After each skill executes in Phase 2:
+  TaskUpdate(chainSkillTask, {
+    subject: `Chain: ${skillName} — Iter ${N} executed`,
+    activeForm: `${skillName} iteration ${N}`
+  })
+  // After Phase 3 evaluates:
+  TaskUpdate(chainSkillTask, {
+    subject: `Chain: ${skillName} — Score ${chainScores[skillName]}/100`,
+    activeForm: `${skillName} scored`
+  })
+} else {
+  // Single mode (existing)
+  TaskCreate({
+    subject: `Iteration ${N}: Score ${score}/100`,
+    activeForm: `Iteration ${N} complete`,
+    description: `Strengths: ... | Weaknesses: ... | Suggestions: ${count}`
+  })
+}
+
+// Completed — collapse
+TaskUpdate(iterLoop, {
+  subject: `Iteration Loop (${totalIters} iters, final: ${finalScore})`,
+  status: 'completed'
+})
+```
+
+## Termination Logic
+
+```javascript
+function shouldTerminate(state) {
+  // 1. Quality threshold met
+  if (state.latest_score >= state.quality_threshold) {
+    return { terminate: true, reason: 'quality_threshold_met' };
+  }
+  // 2. Max iterations reached
+  if (state.current_iteration >= state.max_iterations) {
+    return { terminate: true, reason: 'max_iterations_reached' };
+  }
+  // 3. Convergence: ≤2 points improvement over last 2 iterations
+  if (state.score_trend.length >= 3) {
+    const last3 = state.score_trend.slice(-3);
+    if (last3[2] - last3[0] <= 2) {
+      state.converged = true;
+      return { terminate: true, reason: 'convergence_detected' };
+    }
+  }
+  // 4. Error limit
+  if (state.error_count >= state.max_errors) {
+    return { terminate: true, reason: 'error_limit_reached' };
+  }
+  return { terminate: false };
+}
+```
+
+## Error Handling
+
+| Phase | Error | Recovery |
+|-------|-------|----------|
+| 2: Execute | CLI timeout/crash | Retry once with simplified prompt, then skip |
+| 3: Evaluate | CLI fails | Retry once, then use score 50 with warning |
+| 3: Evaluate | JSON parse fails | Extract score heuristically, save raw output |
+| 4: Improve | Agent fails | Rollback from `iteration-{N}/skill-snapshot/` |
+| Any | 3+ consecutive errors | Terminate with error report |
+
+**Error Budget**: Each phase gets 1 retry. 3 consecutive failed iterations triggers termination.
+
+## Coordinator Checklist
+
+### Pre-Phase Actions
+- [ ] Read iteration-state.json for current state
+- [ ] Verify workspace directory exists
+- [ ] Check error count hasn't exceeded limit
+
+### Per-Iteration Actions
+- [ ] Increment current_iteration in state
+- [ ] Create iteration-{N} subdirectory
+- [ ] Update TodoWrite with iteration status
+- [ ] After Phase 3: check termination before Phase 4
+- [ ] After Phase 4: write state, proceed to next iteration
+
+### Post-Workflow Actions
+- [ ] Execute Phase 5 (Report)
+- [ ] Display final summary to user
+- [ ] Update all TodoWrite tasks to completed