---
name: manage-harvest
description: Extract knowledge from artifacts into wiki/spec/issues
argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
allowed-tools:
  - read_file
  - write_file
  - edit_file
  - shell
  - find_files
  - search
  - delegate_subagent
  - ask_user
---
<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->

<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, source registry (scan paths), and storage locations defined in workflow harvest.md.
</context>

<execution>
Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.

**Key invariants:**
1. **Read-only until Stage 6** — extraction and classification happen in-memory.
2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
3. **Never modify source artifacts** — harvest is purely extractive.
4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.

Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.

**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 --role implement`
- 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>
