Manage Harvest
Documentsmanage-harvestManage Harvest is an Agent Skill for documents published in the catlog22/maestro-flow repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Extract knowledge from artifacts into wiki/spec/issues
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/catlog22/maestro-flow/blob/HEAD/.codex/skills/manage-harvest/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/manage-harvest, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Closed-loop: harvest extracts → stores → downstream consumers (wiki-digest, spec-load, maestro-plan --gaps).
<required_reading>
@/.maestro/workflows/harvest.md
@/.maestro/workflows/run-mode.md
@~/.maestro/workflows/codex-run-mode.md
</required_reading>
Modes:
- No args →
scan: discover all harvestable artifacts, interactive selection <session-id>→session: harvest specific session<path>→path: harvest from explicit directory
Flags:
--to <target>— Force routing: wiki, spec, issue, auto (default: auto)--source <type>— Filter: analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, session, learning, all--recent N— Artifacts within last N days (default: 30)--dry-run— Preview without writing-y— Skip confirmations--min-confidence N— Minimum 0.0-1.0 (default: 0.5)--prune— State hygiene mode: classify artifacts, graduate harvested → knowhow, archive from state.json, prune accumulated_context--age N— Graduation age threshold in days (default: 14). Used with--prune
Output boundary: ALL file writes MUST target .workflow/knowhow/, .workflow/specs/, .workflow/issues/, .workflow/wiki/, .workflow/harvest/, or .workflow/state.json only. NEVER modify source code, source artifacts, or files outside these paths.
Source registry:
| Source | Scan Path | Key Files |
|---|---|---|
| analysis | .workflow/.analysis/ANL-*/ | conclusions.json |
| brainstorm | {run_dir}/outputs/brainstorm-*/ | guidance-specification.md |
| lite-plan | .workflow/.lite-plan/*/ | plan.json |
| lite-fix | .workflow/.lite-fix/*/ | fix-plan.json |
| debug | .workflow/.debug/*/ | debug-log.md |
| scratchpad | {run_dir}/outputs/ | *.md |
| session | .workflow/active/WFS-*/ | workflow-session.json |
| learning | .workflow/specs/ | learnings.md |
Phase Gates (MANDATORY, BLOCKING)
GATE 1: Discovery → Extraction (Stages 1-3 → Stage 4)
- REQUIRED: Source artifacts discovered and mode resolved (scan/session/path).
- REQUIRED: User selected artifact(s) to harvest (or auto-selected via session/path mode, or
-y). - BLOCKED if no harvestable artifacts found (W001) or invalid source (E004/E005).
GATE 2: Extraction → Routing (Stage 4 → Stage 5-6)
- REQUIRED: All files in selected artifacts loaded and parsed.
- REQUIRED: Knowledge fragments extracted with category, confidence, and tags.
- REQUIRED: Fragments filtered by
--min-confidence. - BLOCKED if extraction produces zero fragments.
GATE 3: Routing → Write (Stage 6 → Stage 7-8)
- REQUIRED: Routing classification applied (auto or forced by
--to). - REQUIRED: Dedup check passed against harvest-log.jsonl and existing stores.
- REQUIRED: If
--dry-run: preview displayed, no files written — GATE blocks further writes. - BLOCKED if dedup check fails or store paths unresolvable.
Routing rules:
- Universal design patterns →
codingorarchcategory - Component-level pitfalls →
learningcategory - Quality enforcement rules →
qualitycategory - Wiki:
maestro wiki create --type <type> --slug harvest-<source_type>-<short_id> - Spec:
$spec-add "<category> <content>"(single source of truth — always use spec-add for spec routing; do NOT usemaestro wiki appendfor spec entries) - Issue: append to
issues.jsonlmatching canonical schema, withsource: "harvest"field (distinguishes frommanage-issue-discover, which usessource: "discover"— required for cross-skill dedup when both write concurrently)
Next steps: $manage-wiki health, maestro search --type note, $wiki-connect --fix, $wiki-digest, $manage-issue list --source harvest, $manage-knowledge-audit --scope spec (when specs extracted, check for conflicts)
Prune mode (--prune): Classifies artifacts (active/graduated/stale/protected), graduates harvested artifacts to wiki knowhow, archives from artifacts[] → artifact_archive[], prunes resolved entries from accumulated_context. Files on disk are never deleted. Always backs up state.json before writing.
<error_codes>
| Code | Severity | Condition | Recovery |
|---|---|---|---|
| E001 | error | .workflow/ not initialized | Run $maestro-init |
| E002 | error | Invalid --to target | Valid: wiki, spec, issue, auto |
| E003 | error | Invalid --source type | Display valid types |
| E004 | error | Session ID not found | Show available sessions |
| W001 | warning | No harvestable artifacts in window | Widen --recent |
| W003 | warning | Fragments below threshold | Lower --min-confidence |
| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl |
| </error_codes> |
<success_criteria>
- Mode resolved (scan / session / path)
- Artifacts discovered and parsed
- Fragments extracted with category, confidence, tags
- Dedup check passed against harvest-log.jsonl and stores
- If not dry-run: routed items written to target stores
- harvest-log.jsonl updated with provenance
- harvest-report-{date}.md written
- No source artifacts modified
- If --prune: artifacts classified (active/graduated/stale/protected)
- If --prune: graduated artifacts → knowhow + artifact_archive[]
- If --prune: accumulated_context pruned (resolved deferred/blockers, deduplicated decisions)
- If --prune: state.json backed up before modification </success_criteria>