maestro-flow 0.3.10 → 0.3.11

package/.claude/commands/learn-follow.md

@@ -1,167 +1,167 @@
----
-name: learn-follow
-description: Guided follow-along reading of code or wiki entries, extracting patterns and building understanding
-argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Guided reading experience for code files, wiki entries, or topics. Instead of just reading code, this command walks through content section by section using forcing questions (inspired by gstack `/office-hours` brainstorming) to extract patterns, identify assumptions, and build a structured understanding map.
-
-Outputs reading notes with extracted patterns, open questions, and connection points. Insights persist to `lessons.jsonl` and optionally become wiki note entries for the knowledge graph.
-</purpose>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Target resolution (auto-detected from first argument):**
-- File path (e.g., `src/commands/wiki.ts`) → Read source file
-- Wiki ID (e.g., `spec-auth`, `phase-planning`) → Fetch via `maestro wiki get`
-- Topic string (e.g., `"authentication flow"`) → Search via `maestro wiki search`, use top result
-
-**Flags:**
-- `--depth shallow` — Quick pass: key patterns and structure only (default)
-- `--depth deep` — Thorough: every function, every branch, every assumption
-- `--save-wiki` — Create a wiki note entry with the reading notes via `maestro wiki create --type note`
-
-**Storage written:**
-- `.workflow/learning/follow-{slug}-{YYYY-MM-DD}.md` — Reading notes with understanding map
-- `.workflow/learning/lessons.jsonl` — Appended pattern/technique insights
-- `.workflow/learning/learning-index.json` — Updated index
-- If `--save-wiki`: new wiki note entry
-
-**Storage read:**
-- Target source file or wiki entry
-- `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
-- `.workflow/specs/coding-conventions.md` — Convention reference for pattern matching
-- `.workflow/learning/lessons.jsonl` — Prior insights for dedup and cross-reference
-</context>
-
-<execution>
-
-### Stage 1: Resolve Target
-- If argument looks like a file path (contains `/` or `\`, or matches a glob): verify file exists via Read
-- If argument matches wiki ID pattern (`<type>-<slug>`): fetch via `maestro wiki get <id>` (offline mode)
-- Otherwise: treat as topic string, run `maestro wiki search "<topic>"`, take the top result. If no result, fall back to Grep across `src/` for the topic.
-- If target cannot be resolved, AskUserQuestion with suggestions.
-
-### Stage 2: Load Context Web
-For the resolved target, build a 1-hop context neighborhood:
-
-**If wiki entry:**
-- `maestro wiki forward <id>` — What this entry references
-- `maestro wiki backlinks <id>` — What references this entry
-- Read the body of top 3 related entries for context
-
-**If code file:**
-- Parse imports/requires to identify dependency files
-- Grep for exports used by other files (reverse dependencies)
-- Read the first 50 lines of top 3 dependent files for context
-
-**If directory:**
-- List files, identify entry points (index.ts, main.ts, cli.ts)
-- Build reading order: entry point → core modules → utilities → tests
-
-### Stage 3: Build Reading Order
-- For a single file: split into logical sections (function boundaries, class boundaries, export groups)
-- For a wiki entry: split by markdown headings
-- For a directory: order files by dependency (entry points first, leaf modules last)
-- For `--depth shallow`: limit to top-level structure (function signatures, section headers)
-- For `--depth deep`: include every function body, every branch
-
-### Stage 4: Guided Reading with Forcing Questions
-Walk through each section in reading order. For each section, apply 4 forcing questions:
-
-1. **"What pattern is being used here?"** — Identify design patterns, idioms, conventions. Compare against `coding-conventions.md`.
-2. **"Why this approach instead of alternatives?"** — What trade-offs were made? What was the simpler approach not chosen?
-3. **"What assumption does this depend on?"** — What must be true for this code/content to be correct? External state? Input shape? Ordering?
-4. **"What would break if this changed?"** — Fragility analysis. What downstream effects would a change have?
-
-Record answers as structured annotations per section.
-
-### Stage 5: Extract Patterns
-From the forcing question answers, extract:
-- **Design patterns**: named patterns with code anchors (file:line)
-- **Naming conventions**: how things are named and why
-- **Error handling approach**: how errors flow through this code/content
-- **Data flow**: how data enters, transforms, and exits
-- **Assumptions**: explicit and implicit assumptions identified
-
-Cross-reference each pattern against existing `coding-conventions.md` entries:
-- Already documented → note as "confirmed convention"
-- Not documented → flag as "undocumented pattern" (candidate for `spec-add`)
-
-### Stage 6: Produce Understanding Map
-Build a structured summary document:
-
-```markdown
-# Follow-Along: {target name}
-
-## Key Concepts
-- {concept}: {one-line explanation}
-
-## Patterns Identified
-| Pattern | Location | Convention Status |
-|---------|----------|-------------------|
-| {name} | {file:line} | documented / undocumented |
-
-## Assumptions
-- {assumption}: {what depends on it}
-
-## Open Questions
-- {question}: {why it matters}
-
-## Connections
-- Links to: {forward link entries}
-- Referenced by: {backlink entries}
-- Related lessons: {matching lessons.jsonl entries}
-```
-
-### Stage 7: Persist
-1. Write `.workflow/learning/follow-{slug}-{date}.md` with the understanding map
-2. Append each new pattern/technique as an insight to `lessons.jsonl`:
-   - `source: "follow"`, `category: "pattern"` or `"technique"`
-   - Tags: `["follow", "{target-slug}"]`
-   - Stable INS-id from `hash("follow" + target + pattern_name)`
-3. Update `learning-index.json`
-4. If `--save-wiki`: run `maestro wiki create --type note --slug follow-{slug} --title "Follow-Along: {target}" --body-file .workflow/learning/follow-{slug}-{date}.md`
-5. Display summary with key findings and next steps
-
-**Next-step routing:**
-- Deep dive into a discovered pattern → `/learn-decompose <path>`
-- Add undocumented pattern to specs → `/spec-add pattern <description>`
-- Get second opinion on a finding → `/learn-second-opinion <file>`
-- Browse related wiki entries → `/wiki-digest <topic>`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target not resolvable (file not found, wiki ID not found, search returned 0) | Check path/ID, or rephrase topic for search |
-| E002 | error | `.workflow/` not initialized | Run `/maestro-init` first |
-| W001 | warning | Wiki graph unavailable (no .workflow/ wiki entries) — skipping context web | Proceed with code-only context (imports/exports) |
-| W002 | warning | coding-conventions.md not found — skipping convention comparison | Patterns flagged as "unknown convention status" |
-| W003 | warning | Target is very large (>1000 lines) — auto-switching to shallow depth | Use --depth deep to override |
-</error_codes>
-
-<success_criteria>
-- [ ] Target resolved to concrete content (file, wiki entry, or search result)
-- [ ] Context web loaded (forward/backlinks for wiki, imports/exports for code)
-- [ ] Reading order established (sections/files ordered logically)
-- [ ] All 4 forcing questions applied per section
-- [ ] Patterns extracted with file:line anchors
-- [ ] Convention comparison performed against coding-conventions.md
-- [ ] Understanding map produced with: concepts, patterns, assumptions, questions, connections
-- [ ] `follow-{slug}-{date}.md` written
-- [ ] `lessons.jsonl` appended with discovered patterns (stable INS-ids)
-- [ ] `learning-index.json` updated
-- [ ] If --save-wiki: wiki note entry created
-- [ ] No files modified outside `.workflow/learning/` (and optionally wiki)
-- [ ] Summary displayed with next-step routing
-</success_criteria>
+---
+name: learn-follow
+description: Guided follow-along reading of code or wiki entries, extracting patterns and building understanding
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Guided reading experience for code files, wiki entries, or topics. Instead of just reading code, this command walks through content section by section using forcing questions (inspired by gstack `/office-hours` brainstorming) to extract patterns, identify assumptions, and build a structured understanding map.
+
+Outputs reading notes with extracted patterns, open questions, and connection points. Insights persist to `lessons.jsonl` and optionally become wiki note entries for the knowledge graph.
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Target resolution (auto-detected from first argument):**
+- File path (e.g., `src/commands/wiki.ts`) → Read source file
+- Wiki ID (e.g., `spec-auth`, `phase-planning`) → Fetch via `maestro wiki get`
+- Topic string (e.g., `"authentication flow"`) → Search via `maestro wiki search`, use top result
+
+**Flags:**
+- `--depth shallow` — Quick pass: key patterns and structure only (default)
+- `--depth deep` — Thorough: every function, every branch, every assumption
+- `--save-wiki` — Create a wiki note entry with the reading notes via `maestro wiki create --type note`
+
+**Storage written:**
+- `.workflow/learning/follow-{slug}-{YYYY-MM-DD}.md` — Reading notes with understanding map
+- `.workflow/learning/lessons.jsonl` — Appended pattern/technique insights
+- `.workflow/learning/learning-index.json` — Updated index
+- If `--save-wiki`: new wiki note entry
+
+**Storage read:**
+- Target source file or wiki entry
+- `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
+- `.workflow/specs/coding-conventions.md` — Convention reference for pattern matching
+- `.workflow/learning/lessons.jsonl` — Prior insights for dedup and cross-reference
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target
+- If argument looks like a file path (contains `/` or `\`, or matches a glob): verify file exists via Read
+- If argument matches wiki ID pattern (`<type>-<slug>`): fetch via `maestro wiki get <id>` (offline mode)
+- Otherwise: treat as topic string, run `maestro wiki search "<topic>"`, take the top result. If no result, fall back to Grep across `src/` for the topic.
+- If target cannot be resolved, AskUserQuestion with suggestions.
+
+### Stage 2: Load Context Web
+For the resolved target, build a 1-hop context neighborhood:
+
+**If wiki entry:**
+- `maestro wiki forward <id>` — What this entry references
+- `maestro wiki backlinks <id>` — What references this entry
+- Read the body of top 3 related entries for context
+
+**If code file:**
+- Parse imports/requires to identify dependency files
+- Grep for exports used by other files (reverse dependencies)
+- Read the first 50 lines of top 3 dependent files for context
+
+**If directory:**
+- List files, identify entry points (index.ts, main.ts, cli.ts)
+- Build reading order: entry point → core modules → utilities → tests
+
+### Stage 3: Build Reading Order
+- For a single file: split into logical sections (function boundaries, class boundaries, export groups)
+- For a wiki entry: split by markdown headings
+- For a directory: order files by dependency (entry points first, leaf modules last)
+- For `--depth shallow`: limit to top-level structure (function signatures, section headers)
+- For `--depth deep`: include every function body, every branch
+
+### Stage 4: Guided Reading with Forcing Questions
+Walk through each section in reading order. For each section, apply 4 forcing questions:
+
+1. **"What pattern is being used here?"** — Identify design patterns, idioms, conventions. Compare against `coding-conventions.md`.
+2. **"Why this approach instead of alternatives?"** — What trade-offs were made? What was the simpler approach not chosen?
+3. **"What assumption does this depend on?"** — What must be true for this code/content to be correct? External state? Input shape? Ordering?
+4. **"What would break if this changed?"** — Fragility analysis. What downstream effects would a change have?
+
+Record answers as structured annotations per section.
+
+### Stage 5: Extract Patterns
+From the forcing question answers, extract:
+- **Design patterns**: named patterns with code anchors (file:line)
+- **Naming conventions**: how things are named and why
+- **Error handling approach**: how errors flow through this code/content
+- **Data flow**: how data enters, transforms, and exits
+- **Assumptions**: explicit and implicit assumptions identified
+
+Cross-reference each pattern against existing `coding-conventions.md` entries:
+- Already documented → note as "confirmed convention"
+- Not documented → flag as "undocumented pattern" (candidate for `spec-add`)
+
+### Stage 6: Produce Understanding Map
+Build a structured summary document:
+
+```markdown
+# Follow-Along: {target name}
+
+## Key Concepts
+- {concept}: {one-line explanation}
+
+## Patterns Identified
+| Pattern | Location | Convention Status |
+|---------|----------|-------------------|
+| {name} | {file:line} | documented / undocumented |
+
+## Assumptions
+- {assumption}: {what depends on it}
+
+## Open Questions
+- {question}: {why it matters}
+
+## Connections
+- Links to: {forward link entries}
+- Referenced by: {backlink entries}
+- Related lessons: {matching lessons.jsonl entries}
+```
+
+### Stage 7: Persist
+1. Write `.workflow/learning/follow-{slug}-{date}.md` with the understanding map
+2. Append each new pattern/technique as an insight to `lessons.jsonl`:
+   - `source: "follow"`, `category: "pattern"` or `"technique"`
+   - Tags: `["follow", "{target-slug}"]`
+   - Stable INS-id from `hash("follow" + target + pattern_name)`
+3. Update `learning-index.json`
+4. If `--save-wiki`: run `maestro wiki create --type note --slug follow-{slug} --title "Follow-Along: {target}" --body-file .workflow/learning/follow-{slug}-{date}.md`
+5. Display summary with key findings and next steps
+
+**Next-step routing:**
+- Deep dive into a discovered pattern → `/learn-decompose <path>`
+- Add undocumented pattern to specs → `/spec-add coding <description>`
+- Get second opinion on a finding → `/learn-second-opinion <file>`
+- Browse related wiki entries → `/wiki-digest <topic>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable (file not found, wiki ID not found, search returned 0) | Check path/ID, or rephrase topic for search |
+| E002 | error | `.workflow/` not initialized | Run `/maestro-init` first |
+| W001 | warning | Wiki graph unavailable (no .workflow/ wiki entries) — skipping context web | Proceed with code-only context (imports/exports) |
+| W002 | warning | coding-conventions.md not found — skipping convention comparison | Patterns flagged as "unknown convention status" |
+| W003 | warning | Target is very large (>1000 lines) — auto-switching to shallow depth | Use --depth deep to override |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete content (file, wiki entry, or search result)
+- [ ] Context web loaded (forward/backlinks for wiki, imports/exports for code)
+- [ ] Reading order established (sections/files ordered logically)
+- [ ] All 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors
+- [ ] Convention comparison performed against coding-conventions.md
+- [ ] Understanding map produced with: concepts, patterns, assumptions, questions, connections
+- [ ] `follow-{slug}-{date}.md` written
+- [ ] `lessons.jsonl` appended with discovered patterns (stable INS-ids)
+- [ ] `learning-index.json` updated
+- [ ] If --save-wiki: wiki note entry created
+- [ ] No files modified outside `.workflow/learning/` (and optionally wiki)
+- [ ] Summary displayed with next-step routing
+</success_criteria>

package/.claude/commands/learn-retro.md

@@ -145,7 +145,7 @@ git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
 ```
 
 Also read:
-- `.workflow/specs/architecture-constraints.md` — grep for `### [decision]` blocks
+- `.workflow/specs/architecture-constraints.md` — grep for `<spec-entry category="arch"` blocks
 - `.workflow/phases/*/context.md` — scan for "Locked:", "Deferred:" sections
 - `.workflow/learning/lessons.jsonl` — filter `category == "decision"`
 

package/.claude/commands/maestro-coordinate.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-coordinate
 description: CLI-based coordinator - analyze intent → select command chain → execute sequentially via maestro delegate with auto-confirm
-argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>] [--tool <tool>]"
+argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>]"
 allowed-tools:
   - Read
   - Write
@@ -36,7 +36,6 @@ $ARGUMENTS — user intent text, or special keywords (`continue`/`next`/`status`
 - `-c` / `--continue` — Resume previous session
 - `--dry-run` — Show planned chain without executing
 - `--chain <name>` — Force a specific chain
-- `--tool <tool>` — CLI tool override (default: claude)
 </context>
 
 <execution>
@@ -50,7 +49,6 @@ Follow '~/.maestro/workflows/maestro-coordinate.md' completely.
 | E002 | error | Clarity too low after 2 rounds | Ask to rephrase |
 | E003 | error | Step failed + abort | Suggest resume with -c |
 | E004 | error | Resume session not found | Show available sessions |
-| E005 | error | CLI tool unavailable | Try fallback tool |
 </error_codes>
 
 <success_criteria>

package/.claude/commands/manage-harvest.md

@@ -1,131 +1,131 @@
----
-name: manage-harvest
-description: Extract knowledge from workflow artifacts and route to wiki / spec / issue stores
-argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
-
-Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
-
-**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/harvest.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
-- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Modes (auto-detected):**
-- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
-- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
-- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
-
-**Flags:**
-- `--to <target>` — Force routing: `wiki`, `spec`, `issue`, `auto` (default: `auto`)
-- `--source <type>` — Filter source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `learning`, `all` (default: `all`)
-- `--recent N` — Only artifacts updated within last N days (default: 30)
-- `--dry-run` — Preview extraction and routing without writing
-- `-y` / `--yes` — Skip confirmation prompts
-- `--min-confidence N` — Minimum extraction confidence 0.0-1.0 (default: 0.5)
-
-**Source registry (scan paths):**
-| Source Type | Scan Path | Key Files |
-|-------------|-----------|-----------|
-| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` |
-| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md` |
-| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` |
-| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
-| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` |
-| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` |
-| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` |
-| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md` |
-
-**Storage written:**
-- `.workflow/harvest/harvest-log.jsonl` — provenance log (prevents duplicate harvesting)
-- `.workflow/harvest/harvest-report-{date}.md` — per-run report
-- Wiki entries via `maestro wiki create`
-- Spec entries via `Skill({ skill: "spec-add" })`
-- Issue entries appended to `.workflow/issues/issues.jsonl`
-
-**Storage read (never modified):**
-- All artifact source files (read-only until routing stage)
-- `.workflow/harvest/harvest-log.jsonl` (dedup check)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
-
-1. **Read-only until Stage 6** — Stages 1–5 must not write anything. All extraction and classification happens in-memory.
-2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
-3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
-4. **Reuse existing routing infrastructure**:
-   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
-   - Spec: `Skill({ skill: "spec-add", args: "<type> <content>" })`
-   - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
-5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.
-6. **Confidence filtering** — fragments below `--min-confidence` are logged but not routed.
-7. **Provenance tracking** — every routed item logged to `harvest-log.jsonl` with fragment_id, source reference, and target reference.
-
-**Fragment extraction uses source-specific parsing** (see harvest.md Stage 3b for per-source patterns). The agent should read each artifact file and identify discrete knowledge items: findings, decisions, patterns, bugs, risks, tasks, lessons, recommendations.
-
-**Classification uses category-to-target mapping** (see harvest.md Stage 4). Override with `--to` flag if user wants all items in one store.
-
-**Next-step routing on completion:**
-- Review wiki entries → `maestro wiki list --type note`
-- Connect wiki graph → `/wiki-connect --fix`
-- Triage issues → `/manage-issue list --source harvest`
-- View specs → `/spec-load --category general`
-- Full retrospective → `/quality-retrospective`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
-| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
-| E003 | error | Invalid `--source` type | Display valid source types from registry |
-| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
-| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
-| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
-| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
-| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
-| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
-| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly resolved (scan / session / path)
-- [ ] Source artifacts discovered and listed with metadata
-- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
-- [ ] All files in selected artifacts loaded and parsed
-- [ ] Knowledge fragments extracted with category, confidence, tags
-- [ ] Fragments filtered by `--min-confidence`
-- [ ] Routing classification applied (auto or forced by `--to`)
-- [ ] Dedup check passed against harvest-log.jsonl and existing stores
-- [ ] If `--dry-run`: preview displayed, no files written
-- [ ] If not dry-run: all routed items written to target stores
-- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
-- [ ] Spec entries added via `spec-add` mechanism
-- [ ] Issue entries appended to `issues.jsonl` with canonical schema
-- [ ] `harvest-log.jsonl` updated with provenance for each routed item
-- [ ] `harvest-report-{date}.md` written with full summary
-- [ ] No source artifacts modified
-- [ ] Summary displayed with counts and next-step routing
-</success_criteria>
+---
+name: manage-harvest
+description: Extract knowledge from workflow artifacts and route to wiki / spec / issue stores
+argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
+
+Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
+
+**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
+- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected):**
+- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
+- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
+- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
+
+**Flags:**
+- `--to <target>` — Force routing: `wiki`, `spec`, `issue`, `auto` (default: `auto`)
+- `--source <type>` — Filter source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `learning`, `all` (default: `all`)
+- `--recent N` — Only artifacts updated within last N days (default: 30)
+- `--dry-run` — Preview extraction and routing without writing
+- `-y` / `--yes` — Skip confirmation prompts
+- `--min-confidence N` — Minimum extraction confidence 0.0-1.0 (default: 0.5)
+
+**Source registry (scan paths):**
+| Source Type | Scan Path | Key Files |
+|-------------|-----------|-----------|
+| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` |
+| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md` |
+| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` |
+| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
+| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` |
+| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` |
+| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` |
+| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md` |
+
+**Storage written:**
+- `.workflow/harvest/harvest-log.jsonl` — provenance log (prevents duplicate harvesting)
+- `.workflow/harvest/harvest-report-{date}.md` — per-run report
+- Wiki entries via `maestro wiki create`
+- Spec entries via `Skill({ skill: "spec-add" })`
+- Issue entries appended to `.workflow/issues/issues.jsonl`
+
+**Storage read (never modified):**
+- All artifact source files (read-only until routing stage)
+- `.workflow/harvest/harvest-log.jsonl` (dedup check)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
+
+1. **Read-only until Stage 6** — Stages 1–5 must not write anything. All extraction and classification happens in-memory.
+2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
+3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
+4. **Reuse existing routing infrastructure**:
+   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
+   - Spec: `Skill({ skill: "spec-add", args: "<category> <content>" })`
+   - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
+5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.
+6. **Confidence filtering** — fragments below `--min-confidence` are logged but not routed.
+7. **Provenance tracking** — every routed item logged to `harvest-log.jsonl` with fragment_id, source reference, and target reference.
+
+**Fragment extraction uses source-specific parsing** (see harvest.md Stage 3b for per-source patterns). The agent should read each artifact file and identify discrete knowledge items: findings, decisions, patterns, bugs, risks, tasks, lessons, recommendations.
+
+**Classification uses category-to-target mapping** (see harvest.md Stage 4). Override with `--to` flag if user wants all items in one store.
+
+**Next-step routing on completion:**
+- Review wiki entries → `maestro wiki list --type note`
+- Connect wiki graph → `/wiki-connect --fix`
+- Triage issues → `/manage-issue list --source harvest`
+- View specs → `/spec-load --category learning`
+- Full retrospective → `/quality-retrospective`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
+| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
+| E003 | error | Invalid `--source` type | Display valid source types from registry |
+| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
+| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
+| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
+| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
+| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
+| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / session / path)
+- [ ] Source artifacts discovered and listed with metadata
+- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
+- [ ] All files in selected artifacts loaded and parsed
+- [ ] Knowledge fragments extracted with category, confidence, tags
+- [ ] Fragments filtered by `--min-confidence`
+- [ ] Routing classification applied (auto or forced by `--to`)
+- [ ] Dedup check passed against harvest-log.jsonl and existing stores
+- [ ] If `--dry-run`: preview displayed, no files written
+- [ ] If not dry-run: all routed items written to target stores
+- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
+- [ ] Spec entries added via `spec-add` mechanism
+- [ ] Issue entries appended to `issues.jsonl` with canonical schema
+- [ ] `harvest-log.jsonl` updated with provenance for each routed item
+- [ ] `harvest-report-{date}.md` written with full summary
+- [ ] No source artifacts modified
+- [ ] Summary displayed with counts and next-step routing
+</success_criteria>