maestro-flow 0.2.2 → 0.3.0

package/.claude/agents/team-worker.md

@@ -80,6 +80,10 @@ Follow the instructions loaded from the role_spec body. This contains the domain
 - Use CLI tools (`maestro cli`) or direct tools (Read, Grep, Glob) for analysis — see @~/.maestro/templates/search-tools.md for tool selection
 - If agent delegation is needed, send a request to the coordinator via SendMessage
 
+### Context-Aware Signal Emission (Optional)
+
+During Phase 2-4 execution, if you detect codebase signals relevant to specialist injection (SQL usage, auth modules, ML imports, performance-sensitive code, etc.), include `tech_profile` in your Phase 5 state_update data. This enables the coordinator to evaluate specialist injection for the pipeline.
+
 ### 6. Publish Results
 
 After execution, publish contributions:
@@ -172,14 +176,14 @@ Determine report variant based on loop state:
 
 **Loop continuation** (inner_loop=true AND more same-prefix tasks pending):
 1. `TaskUpdate` -- mark current task `completed`
-2. Log `state_update` via `team_msg` with task results
+2. Log `state_update` via `team_msg` with task results and optional `tech_profile` (if codebase signals detected in Phase 2-4)
 3. Accumulate summary to in-memory `context_accumulator`
 4. Interrupt check: consensus_blocked HIGH or errors >= 3 -- SendMessage and STOP
 5. Return to step 3 (Task Discovery)
 
 **Final report** (no more same-prefix tasks OR inner_loop=false):
 1. `TaskUpdate` -- mark current task `completed`
-2. Log `state_update` via `team_msg`
+2. Log `state_update` via `team_msg` (include `tech_profile` if codebase signals detected)
 3. Compile and send final report via SendMessage to coordinator:
    - Tasks completed (count + list)
    - Artifacts produced (paths)

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

@@ -0,0 +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, manage-issue-plan).
+</purpose>
+
+<required_reading>
+@workflows/harvest.md
+</required_reading>
+
+<deferred_reading>
+- @workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
+- @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 '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 → `Skill({ skill: "wiki-connect", args: "--fix" })`
+- Triage issues → `Skill({ skill: "manage-issue", args: "list --source harvest" })`
+- View specs → `Skill({ skill: "spec-load", args: "--category general" })`
+- Full retrospective → `Skill({ skill: "quality-retrospective" })`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` not initialized | Run `Skill({ skill: "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>

package/.claude/skills/team-coordinate/specs/role-spec-template.md

@@ -122,6 +122,12 @@ Quality thresholds from [specs/quality-gates.md](quality-gates.md):
 - Review 60-79%: report completed with warnings
 - Fail < 60%: retry Phase 3 (max 2)
 
+### Tech Profile Injection
+
+When generating role-specs for analysis or exploration roles, append a Tech Profile Scan instruction after their Phase 3:
+- Instruct the role to scan analysis results for codebase signals relevant to its domain
+- Include `tech_profile` in state_update data for coordinator specialist injection evaluation
+
 ### Error Protocol
 
 - Primary approach fails → try alternative (different CLI tool / different tool)

package/.claude/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -59,6 +59,22 @@ CONTEXT: @**/*
 EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis`, run_in_background: false })
 ```
 
+### Tech Profile Scan
+
+After codebase exploration, scan results for context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check imports/dependencies → framework signals (`sql_detected`, `auth_detected`, `ml_detected`, `frontend_framework`)
+2. Check file patterns → infrastructure signals (`devops_detected`, `data_migration`, `realtime_detected`)
+3. Check code patterns → risk signals (`perf_sensitive`, `crypto_usage`, `legacy_patterns`, `test_gap`)
+4. Include `tech_profile` in Phase 5 state_update data:
+   ```json
+   "tech_profile": {
+     "signals": ["<detected signals>"],
+     "evidence": { "<signal>": ["<file paths>"] },
+     "confidence": "high|medium|low"
+   }
+   ```
+
 ## Phase 4: Context Packaging
 
 1. Write spec-config.json → <session>/spec/

package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md

@@ -31,14 +31,63 @@ Worker completed. Process and advance.
 4. Completion -> mark task done
    - Resident agent (supervisor) -> keep in active_workers (stays alive for future checkpoints)
    - Standard worker -> remove from active_workers
+4.5. **evaluateSpecialistInjection** (based on detected codebase characteristics):
+   - If callback from analyst, planner, or executor role:
+     a. `get_state(role=<callback_role>)` → extract `tech_profile.signals`
+     b. Merge with previously collected signals from other roles
+     c. Evaluate against trigger matrix (§4)
+     d. P0 matches → TaskCreate with blockedBy on current stage, blocks downstream
+     e. P1 matches → TaskCreate parallel with REVIEW/TEST stage
+     f. Log: `team_msg(type="specialist_injection", data={ specialist, signals, priority, evidence })`
+     g. Dedup: skip if same specialist already injected this session
 5. Check for checkpoints:
    - CHECKPOINT-* with verdict "block" -> AskUserQuestion: Override / Revise upstream / Abort
    - CHECKPOINT-* with verdict "warn" -> log risks to wisdom, proceed normally
    - CHECKPOINT-* with verdict "pass" -> proceed normally
    - QUALITY-001 -> display quality gate, pause for user commands
-   - PLAN-001 -> read plan.json complexity, create dynamic IMPL tasks per specs/pipelines.md routing
+   - PLAN-001 -> dynamicImplDispatch (see below)
 6. -> handleSpawnNext
 
+### dynamicImplDispatch (PLAN-001 callback)
+
+When PLAN-001 completes, coordinator creates IMPL tasks based on complexity:
+
+1. Read `<session>/plan/plan.json` → extract `complexity`, `tasks[]`
+2. Route by complexity (per specs/pipelines.md §6):
+
+| Complexity | Action |
+|------------|--------|
+| Low (1-2 modules) | Create single IMPL-001, blockedBy: [PLAN-001], InnerLoop: true |
+| Medium (3-4 modules) | Create IMPL-{1..N}, each blockedBy: [PLAN-001] only, InnerLoop: false |
+| High (5+ modules) | Create IMPL-{1..N} with DAG deps from plan.json, InnerLoop per dispatch rules |
+
+3. For each IMPL task: TaskCreate with structured description (dispatch.md template)
+4. Set blockedBy:
+   - **Parallel tasks**: blockedBy: [PLAN-001] (or [CHECKPOINT-003] if supervision enabled)
+   - **Serial chain within DAG**: blockedBy includes upstream IMPL task IDs
+5. Update team-session.json: `pipeline.tasks_total`, `pipeline.impl_topology: "single"|"parallel"|"dag"`
+6. Log via team_msg: `{ type: "state_update", data: { impl_count: N, topology: "..." } }`
+
+### dynamicImplDispatch (PLAN-001 callback)
+
+When PLAN-001 completes, coordinator creates IMPL tasks based on complexity:
+
+1. Read `<session>/plan/plan.json` → extract `complexity`, `tasks[]`
+2. Route by complexity (per specs/pipelines.md §6):
+
+| Complexity | Action |
+|------------|--------|
+| Low (1-2 modules) | Create single IMPL-001, blockedBy: [PLAN-001], InnerLoop: true |
+| Medium (3-4 modules) | Create IMPL-{1..N}, each blockedBy: [PLAN-001] only, InnerLoop: false |
+| High (5+ modules) | Create IMPL-{1..N} with DAG deps from plan.json, InnerLoop per dispatch rules |
+
+3. For each IMPL task: TaskCreate with structured description (dispatch.md template)
+4. Set blockedBy:
+   - **Parallel tasks**: blockedBy: [PLAN-001] (or [CHECKPOINT-003] if supervision enabled)
+   - **Serial chain within DAG**: blockedBy includes upstream IMPL task IDs
+5. Update team-session.json: `pipeline.tasks_total`, `pipeline.impl_topology: "single"|"parallel"|"dag"`
+6. Log via team_msg: `{ type: "state_update", data: { impl_count: N, topology: "..." } }`
+
 ## handleCheck
 
 Read-only status report, then STOP.

package/.claude/skills/team-lifecycle-v4/roles/planner/role.md

@@ -41,6 +41,15 @@ Codebase-informed implementation planning with complexity assessment.
    ```
 4. Store results in <session>/explorations/
 
+### Secondary Signal Scan
+
+After exploration, supplement upstream tech_profile with planning-phase signals (based on detected codebase characteristics):
+
+1. Check plan complexity → `scaling_concern` if O(n^2)+ patterns found
+2. Check scope → `breaking_change` if public API modifications planned
+3. Check data → `data_migration` if schema changes identified
+4. Include `tech_profile` in Phase 5 state_update (merge with any upstream signals)
+
 ## Phase 3: Plan Generation
 
 Generate plan.json + .task/TASK-*.json:

package/.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md

@@ -53,7 +53,8 @@ Sent via `team_msg(type="state_update")` on task completion.
   "files_modified": [
     "path/to/file.ts"
   ],
-  "verification": "self-validated | peer-reviewed | tested"
+  "verification": "self-validated | peer-reviewed | tested",
+  "tech_profile": "<optional, from Phase 2-4 if codebase signals detected>"
 }
 ```
 
@@ -63,6 +64,7 @@ Sent via `team_msg(type="state_update")` on task completion.
 - `decisions`: Include rationale, not just the choice
 - `files_modified`: Only for implementation tasks
 - `verification`: One of `self-validated`, `peer-reviewed`, `tested`
+- `tech_profile`: Optional. Codebase signals for context-aware specialist injection. Schema: `{ signals: string[], evidence: { signal: filePaths[] }, confidence: "high|medium|low" }`
 
 **Supervisor-specific extensions** (CHECKPOINT tasks only):
 

package/.claude/skills/team-lifecycle-v4/specs/pipelines.md

@@ -107,19 +107,34 @@ PLAN-001 outputs a complexity assessment that determines the impl topology.
 | TEST-001 | tester | validation | IMPL-* | - | P0 |
 | REVIEW-001 | reviewer | review | IMPL-* | - | P0 |
 
-## 8. Dynamic Specialist Injection
+## 8. Context-Aware Specialist Injection
 
-When task content or user request matches trigger keywords, inject a specialist task.
+Specialists are injected based on **codebase signals** detected by explorer/analyst/planner workers, not keyword matching. The coordinator evaluates signals emitted in worker state updates against a trigger matrix to determine when specialist roles are needed.
 
-| Trigger Keywords | Specialist Role | Task Prefix | Priority | Insert After |
-|------------------|----------------|-------------|----------|--------------|
-| security, vulnerability, OWASP | security-expert | SECURITY-* | P0 | PLAN |
-| performance, optimization, latency | performance-optimizer | PERF-* | P1 | IMPL |
-| data, pipeline, ETL, migration | data-engineer | DATA-* | P0 | parallel with IMPL |
-| devops, CI/CD, deployment, infra | devops-engineer | DEVOPS-* | P1 | IMPL |
-| ML, model, training, inference | ml-engineer | ML-* | P0 | parallel with IMPL |
+### Signal Flow
 
-**Injection rules**:
-- Specialist tasks inherit the session context and wisdom
+```
+analyst (RESEARCH-001) emits tech_profile in state_update
+  → coordinator evaluateSpecialistInjection (in handleCallback)
+  → signal combination matches trigger matrix
+  → P0: TaskCreate blocking downstream | P1: TaskCreate parallel with REVIEW/TEST
+```
+
+### Common Trigger Examples
+
+| Signal Combination | Specialist | Priority |
+|-------------------|-----------|----------|
+| `sql_detected` + `auth_detected` | security-expert (SECURITY-*) | P0 |
+| `perf_sensitive` + `scaling_concern` | performance-optimizer (PERF-*) | P0 |
+| `ml_detected` | ml-engineer (ML-*) | P0 |
+| `data_migration` | data-engineer (DATA-*) | P0 |
+| `devops_detected` + CI config changes | devops-engineer (DEVOPS-*) | P1 |
+
+
+
+### Injection Rules
+
+- Specialist tasks inherit session context and wisdom
 - They publish state_update on completion like any other task
 - P0 specialists block downstream tasks; P1 run in parallel
+- Same specialist is only injected once per session (dedup)

package/.claude/skills/team-quality-assurance/roles/analyst/role.md

@@ -62,6 +62,14 @@ TASK: Classify defects by root cause, identify high-density files, analyze cover
 MODE: analysis
 ```
 
+### Tech Profile Scan
+
+After quality analysis, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check defect patterns → signals (`injection_risk`, `auth_detected`, `sql_detected`)
+2. Check coverage data → risk signals (`test_gap`, `perf_sensitive`, `legacy_patterns`)
+3. Include `tech_profile` in Phase 5 state_update data
+
 ## Phase 4: Report Generation & Output
 
 1. Generate quality report markdown with: score, defect patterns, coverage analysis, test effectiveness, quality trend, recommendations

package/.claude/skills/team-quality-assurance/roles/scout/role.md

@@ -58,6 +58,14 @@ After all perspectives complete:
 - Compare against known defect patterns from .msg/meta.json
 - Rank by severity: critical > high > medium > low
 
+### Tech Profile Scan
+
+After scanning, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check scan findings → signals (`sql_detected`, `auth_detected`, `injection_risk`, `eval_usage`)
+2. Check quality issues → risk signals (`test_gap`, `legacy_patterns`, `perf_sensitive`)
+3. Include `tech_profile` in Phase 5 state_update data
+
 ## Phase 4: Result Aggregation
 
 1. Build `discoveredIssues` array from critical + high findings (with id, severity, perspective, file, line, description)

package/.claude/skills/team-review/roles/scanner/role.md

@@ -61,6 +61,14 @@ Build prompt with target file patterns, toolchain dedup summary, and per-dimensi
 
 Execute via `maestro cli --tool gemini --mode analysis --rule analysis-review-code-quality` (fallback: qwen -> codex). Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.
 
+### Tech Profile Scan
+
+After scan execution, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check security findings → signals (`injection_risk`, `eval_usage`, `sql_detected`, `auth_detected`)
+2. Check quality findings → risk signals (`legacy_patterns`, `test_gap`, `perf_sensitive`)
+3. Include `tech_profile` in Phase 5 state_update data
+
 ## Phase 4: Aggregate & Output
 
 1. Merge toolchain + semantic findings, deduplicate (same file + line + dimension = duplicate)

package/.claude/skills/team-tech-debt/roles/assessor/role.md

@@ -61,6 +61,14 @@ Quantitative evaluator for tech debt items. Score each debt item on business imp
 
 For CLI mode, prompt gemini with full debt summary requesting JSON array of `{id, impact_score, cost_score, risk_if_unfixed, priority_quadrant}`. Unevaluated items fall back to heuristic scoring.
 
+### Tech Profile Scan
+
+After assessment, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check debt items → signals (`legacy_patterns`, `perf_sensitive`, `test_gap`)
+2. Check code patterns → risk signals (`sql_detected`, `auth_detected`, `scaling_concern`)
+3. Include `tech_profile` in Phase 5 state_update data
+
 ## Phase 4: Generate Priority Matrix
 
 1. Build matrix structure: evaluation_date, total_items, by_quadrant (grouped), summary (counts per quadrant)

package/.claude/skills/team-tech-debt/roles/scanner/role.md

@@ -74,6 +74,14 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch
 | `suggestion` | Fix suggestion |
 | `estimated_effort` | small, medium, large, unknown |
 
+### Tech Profile Scan
+
+After multi-dimension scan, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check debt dimensions → signals (`legacy_patterns`, `test_gap`, `perf_sensitive`)
+2. Check detected patterns → risk signals (`sql_detected`, `auth_detected`, `scaling_concern`, `injection_risk`)
+3. Include `tech_profile` in Phase 5 state_update data
+
 ## Phase 4: Aggregate & Save
 
 1. Deduplicate findings across Fan-out layers (file:line key), merge cross-references

package/.claude/skills/team-testing/roles/analyst/role.md

@@ -79,6 +79,14 @@ Glob("<session>/tests/**/*")
 
 Write report to `<session>/analysis/quality-report.md`
 
+### Tech Profile Scan
+
+After test analysis, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check test findings → signals (`test_gap`, `perf_sensitive`)
+2. Check tested code → risk signals (`sql_detected`, `auth_detected`, `injection_risk`)
+3. Include `tech_profile` in Phase 5 state_update data
+
 ## Phase 4: Trend Analysis & State Update
 
 **Historical comparison** (if multiple sessions exist):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/workflows/harvest.md

@@ -0,0 +1,420 @@
+# Harvest Workflow
+
+Extract knowledge from workflow artifacts and route into wiki / spec / issue stores.
+
+Unlike `retrospective.md` which is phase-scoped and post-execution, harvest operates on **any workflow session artifact** — analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, and completed workflow sessions.
+
+---
+
+## Prerequisites
+
+- `.workflow/` initialized (`.workflow/state.json` exists)
+- At least one artifact source present (analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, or active session)
+- For wiki routing: `maestro wiki` CLI available
+
+---
+
+## Argument Shape
+
+```
+/manage-harvest                                      → scan all sources, interactive selection
+/manage-harvest <session-id>                         → harvest specific session (ANL-*, WFS-*, etc.)
+/manage-harvest <path>                               → harvest from explicit directory or file
+/manage-harvest --recent 7                           → harvest from artifacts updated in last 7 days
+/manage-harvest --source analysis                    → harvest only from analysis sessions
+/manage-harvest <target> --to wiki                   → force all findings to wiki
+/manage-harvest <target> --to spec                   → force all findings to spec
+/manage-harvest <target> --to issue                  → force all findings to issue
+/manage-harvest <target> --to auto                   → auto-classify routing (default)
+/manage-harvest <target> --dry-run                   → preview without writing
+```
+
+| Flag | Effect |
+|------|--------|
+| `--to <target>` | Force routing target: `wiki`, `spec`, `issue`, `auto` (default: auto) |
+| `--source <type>` | Filter by source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `all` |
+| `--recent N` | Only scan artifacts updated within last N days (default: 30) |
+| `--dry-run` | Preview extracted items without writing to any store |
+| `-y` / `--yes` | Skip confirmation prompts, accept all routing |
+| `--min-confidence N` | Minimum extraction confidence 0.0-1.0 (default: 0.5) |
+
+---
+
+## Stage 1: parse_input
+
+```
+1. Verify .workflow/ exists; else error E001.
+2. Tokenize $ARGUMENTS:
+   - First non-flag token: session ID, path, or empty (scan mode)
+   - Flags: --to, --source, --recent, --dry-run, -y, --min-confidence
+3. Build:
+     mode = "scan" | "session" | "path"
+     target_filter = "auto" | "wiki" | "spec" | "issue"
+     source_filter = "all" | specific source type
+     recent_days = 30 (or --recent value)
+     dry_run = false
+     auto_yes = false
+     min_confidence = 0.5
+4. Validate --to value. Unknown target → error E002.
+5. Validate --source value. Unknown source → error E003.
+```
+
+---
+
+## Stage 2: discover_artifacts
+
+Scan `.workflow/` for harvestable artifacts. Each source type has a known structure:
+
+### Source Registry
+
+| Source Type | Scan Path | Key Files | ID Pattern |
+|-------------|-----------|-----------|------------|
+| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` | `ANL-*` |
+| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md`, `brainstorm-*.md` | directory name |
+| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` | directory name |
+| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` | directory name |
+| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` | directory name |
+| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` | filename |
+| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` | `WFS-*` |
+| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md`, `*.md` | filename |
+
+```
+candidates = []
+FOR each source_type in source_registry:
+  IF source_filter != "all" AND source_filter != source_type: SKIP
+  Glob for directories/files matching scan_path
+  FOR each match:
+    stat = file modification time
+    IF stat.mtime < (now - recent_days): SKIP
+    Read key files, extract:
+      - session_id or directory name
+      - title (from JSON title field or markdown H1)
+      - created_at / updated_at
+      - summary (first paragraph or JSON summary field)
+      - file_count (number of artifact files)
+    candidates.push({ source_type, id, path, title, updated_at, summary, file_count })
+```
+
+### Display candidates
+
+```
+=== HARVESTABLE ARTIFACTS ===
+
+  #  Source       ID                    Title                    Updated       Files
+  ─  ──────────  ────────────────────  ─────────────────────── ────────────  ─────
+  1  analysis    ANL-auth-20260410     Auth vulnerability scan  2026-04-10      4
+  2  brainstorm  brainstorm-cache      Cache strategy options   2026-04-08      3
+  3  lite-fix    rate-limit-20260405   Rate limiter edge case   2026-04-05      2
+  4  debug       debug-memory-leak     Memory leak in worker    2026-04-03      5
+
+  Found: 4 artifacts (filtered by: last 30 days)
+```
+
+### Selection logic
+
+| Mode | Action |
+|------|--------|
+| `scan`, 0 candidates | Print "No harvestable artifacts found", exit 0 |
+| `scan`, ≥1 candidates | AskUserQuestion: select one, multiple (comma-separated), or "all" |
+| `session` | Find matching session ID in candidates; error E004 if not found |
+| `path` | Validate path exists; auto-detect source type from structure |
+
+---
+
+## Stage 3: load_and_extract (per selected artifact)
+
+For each selected artifact, load all files and extract knowledge fragments.
+
+### 3a. Load artifact content
+
+Read all relevant files in the artifact directory. Build a content bundle:
+
+```
+bundle = {
+  source_type: "analysis" | "brainstorm" | ...,
+  id: session_id,
+  path: artifact_directory,
+  files: [{ name, content, type: "json"|"md" }],
+  metadata: extracted from key files (conclusions.json, plan.json, etc.)
+}
+```
+
+### 3b. Extract knowledge fragments
+
+Parse content to identify discrete knowledge items. Each source type has specific extraction patterns:
+
+**Analysis (`conclusions.json` + markdown):**
+- `findings[]` → each finding is a fragment
+- `recommendations[]` → each recommendation is a fragment
+- `risks[]` → each risk is a fragment
+- Markdown sections with `## ` headings → section-level fragments
+
+**Brainstorm (`guidance-specification.md` + notes):**
+- `## Options` or `## Approaches` → each option is a fragment
+- `## Decision` or `## Recommendation` → decision fragment
+- `## Trade-offs` → trade-off fragments
+- Action items (lines starting with `- [ ]` or `TODO`) → task fragments
+
+**Lite-plan (`plan.json`):**
+- `tasks[]` → each with rationale → decision fragments
+- `dependencies[]` → architectural constraint fragments
+- `risks[]` → risk fragments
+
+**Lite-fix (`fix-plan.json`):**
+- `root_cause` → bug fragment
+- `fix_strategy` → pattern fragment
+- `verification` → test/validation fragment
+
+**Debug (`debug-log.md`, `hypothesis-*.md`):**
+- Final diagnosis → bug fragment
+- Verified hypothesis → pattern/lesson fragment
+- Rejected hypotheses with reasoning → lesson fragment
+
+**Scratchpad (*.md):**
+- Markdown sections → generic fragments
+- Code blocks with explanations → pattern fragments
+
+**Session (`workflow-session.json`):**
+- `completed_tasks[].summary` → pattern/decision fragments
+- `key_decisions[]` → decision fragments
+- `deferred_items[]` → issue fragments
+
+**Learning (`lessons.jsonl`):**
+- Each lesson line → lesson fragment (check if already routed to wiki/spec/issue)
+
+Each fragment gets:
+```
+fragment = {
+  id: "HRV-{8 hex}" from hash(source_id + content_hash),
+  source_type: ...,
+  source_id: ...,
+  title: extracted or inferred,
+  content: raw text,
+  tags: extracted from context,
+  category: "finding" | "decision" | "pattern" | "bug" | "risk" | "task" | "lesson" | "recommendation",
+  confidence: 0.0-1.0 (based on specificity and actionability)
+}
+```
+
+Filter by `--min-confidence`.
+
+---
+
+## Stage 4: classify_routing
+
+For each fragment, determine the best routing target (unless `--to` forces a specific target).
+
+### Classification Rules
+
+| Category | Default Target | Rationale |
+|----------|---------------|-----------|
+| `finding` | wiki (note) | Observations go to knowledge graph |
+| `decision` | wiki (spec) or spec (decision) | Architectural decisions → spec ADR or wiki spec entry |
+| `pattern` | spec (pattern) | Reusable code patterns → coding conventions |
+| `bug` | issue or spec (bug) | Active bugs → issue; fixed bugs → spec learnings |
+| `risk` | issue | Unmitigated risks → trackable issues |
+| `task` | issue | Unfinished work → trackable issues |
+| `lesson` | wiki (lesson) | Generalizable insights → wiki knowledge |
+| `recommendation` | wiki (note) or issue | Actionable recommendations → issue; informational → wiki |
+
+### Override with `--to`
+
+If `--to wiki`: all fragments → wiki entries
+If `--to spec`: all fragments → spec entries
+If `--to issue`: all fragments → issue entries
+If `--to auto`: use classification rules above
+
+### Build routing plan
+
+```
+routing_plan = {
+  wiki: [{ fragment, wiki_type, slug, title, tags, body }],
+  spec: [{ fragment, spec_type, content }],
+  issue: [{ fragment, title, severity, description }]
+}
+```
+
+---
+
+## Stage 5: preview_and_confirm
+
+Display the routing plan:
+
+```
+=== HARVEST PLAN ===
+Source: ANL-auth-20260410 (analysis)
+Fragments extracted: 8 (filtered from 12 by confidence ≥ 0.5)
+
+  → Wiki (3 entries):
+    [note]   "SQL injection vector in user input"     tags: security, sql
+    [lesson] "Parameterized queries prevent injection" tags: security, pattern
+    [spec]   "Auth token rotation policy"              tags: auth, security
+
+  → Spec (2 entries):
+    [pattern] "Always use parameterized queries for user input"
+    [decision] "JWT refresh tokens over session cookies"
+
+  → Issue (3 entries):
+    [high]   "Unvalidated redirect in OAuth callback"
+    [medium] "Missing rate limit on token refresh endpoint"
+    [low]    "Inconsistent error messages leak internal state"
+
+  Total: 3 wiki + 2 spec + 3 issue = 8 routed items
+```
+
+If `--dry-run`: display and exit.
+If NOT `--dry-run` AND NOT `-y`:
+  AskUserQuestion: "Apply this routing plan? (yes/edit/skip)" with options.
+  - `edit`: re-display with per-item accept/reject
+  - `skip`: exit without writing
+
+---
+
+## Stage 6: route_outputs
+
+Execute the routing plan. Each target uses existing infrastructure:
+
+### 6a. Wiki routing
+
+For each wiki item:
+```bash
+maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id> \
+  --title "<title>" --tags "<tags>" --body "<body>"
+```
+
+Wiki types mapping:
+- `note` → `--type note`
+- `lesson` → `--type lesson`
+- `spec` → `--type spec`
+
+If `maestro wiki create` fails, fall back to writing `.workflow/harvest/wiki-pending-{id}.md` with frontmatter.
+
+### 6b. Spec routing
+
+For each spec item, use the same mechanism as `quality-retrospective` Stage 6:
+
+```
+Skill({ skill: "spec-add", args: "<spec_type> <content>" })
+```
+
+Where `spec_type` maps from fragment category:
+- `pattern` → `pattern`
+- `decision` → `decision`
+- `bug` → `bug`
+- `lesson` → `rule` (if it prescribes a rule)
+
+### 6c. Issue routing
+
+For each issue item, append to `.workflow/issues/issues.jsonl` using the canonical schema from `workflows/issue.md`:
+
+```json
+{
+  "id": "ISS-{YYYYMMDD}-{NNN}",
+  "title": "<title>",
+  "description": "<description>",
+  "severity": "<high|medium|low>",
+  "status": "open",
+  "source": "harvest",
+  "source_ref": "<source_id>",
+  "tags": [],
+  "created_at": "<ISO timestamp>",
+  "issue_history": [{ "action": "created", "timestamp": "<ISO>", "by": "harvest", "detail": "Extracted from <source_type> <source_id>" }]
+}
+```
+
+### 6d. Track harvest provenance
+
+For each routed item, record in `.workflow/harvest/harvest-log.jsonl`:
+
+```json
+{
+  "fragment_id": "HRV-...",
+  "source_type": "analysis",
+  "source_id": "ANL-auth-20260410",
+  "routed_to": "wiki|spec|issue",
+  "target_id": "note-harvest-analysis-abc123|ISS-20260413-001|...",
+  "timestamp": "<ISO>",
+  "title": "<title>",
+  "confidence": 0.85
+}
+```
+
+This log prevents duplicate harvesting in future runs.
+
+---
+
+## Stage 7: dedup_check
+
+Before writing any item in Stage 6, check for duplicates:
+
+1. **harvest-log.jsonl**: Has this fragment_id already been routed?
+2. **Wiki**: `maestro wiki search "<title>"` — does a similar entry exist?
+3. **Issues**: Search `issues.jsonl` for matching title/description
+4. **Specs**: Search `learnings.md` for similar content
+
+If duplicate found:
+- Skip with `[SKIP-DUP]` marker
+- Log to harvest report
+
+---
+
+## Stage 8: report
+
+Write `.workflow/harvest/harvest-report-{date}.md`:
+
+```markdown
+# Harvest Report — {date}
+
+## Source
+- Type: {source_type}
+- ID: {source_id}
+- Path: {path}
+
+## Extraction Summary
+- Fragments found: {total}
+- Filtered by confidence: {filtered_count}
+- Duplicates skipped: {dup_count}
+
+## Routing Results
+
+### Wiki ({N} entries)
+| # | Type | Slug | Title | Status |
+|---|------|------|-------|--------|
+| 1 | note | harvest-analysis-abc | SQL injection vector | CREATED |
+| 2 | lesson | harvest-analysis-def | Parameterized queries | CREATED |
+
+### Spec ({N} entries)
+| # | Type | Content (truncated) | Status |
+|---|------|---------------------|--------|
+| 1 | pattern | Always use parameterized queries... | ADDED |
+
+### Issue ({N} entries)
+| # | Severity | Title | ID | Status |
+|---|----------|-------|-----|--------|
+| 1 | high | Unvalidated redirect in OAuth... | ISS-20260413-001 | CREATED |
+
+## Skipped
+| Fragment | Reason |
+|----------|--------|
+| HRV-abc123 | Duplicate: existing wiki entry note-sql-injection |
+```
+
+Display summary:
+
+```
+=== HARVEST COMPLETE ===
+Source: ANL-auth-20260410 (analysis)
+
+  Wiki:  3 created, 0 skipped
+  Spec:  2 added, 0 skipped
+  Issue: 3 created, 1 skipped (dup)
+
+  Report: .workflow/harvest/harvest-report-2026-04-13.md
+  Log:    .workflow/harvest/harvest-log.jsonl
+
+Next:
+  → Review wiki entries: maestro wiki list --type note
+  → Triage issues: Skill({ skill: "manage-issue", args: "list --source harvest" })
+  → Connect wiki graph: Skill({ skill: "wiki-connect", args: "--fix" })
+  → View specs: Skill({ skill: "spec-load", args: "--category general" })
+```