maestro-flow 0.3.9 → 0.3.11

package/.codex/skills/learn-decompose/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: learn-decompose
+description: 4-dimension parallel pattern extraction via CSV wave pipeline. Structural, behavioral, data, and error dimension agents scan in parallel (Wave 1), cross-reference agent deduplicates and catalogs (Wave 2). Outputs pattern catalog to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
+scan a module, then a cross-reference agent deduplicates against existing patterns and
+produces a catalog. Discovered patterns persist to `lessons.jsonl` and optionally to
+specs (via `spec-add`) and wiki.
+
+```
+Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
+```
+</purpose>
+
+<context>
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution:**
+- File path → analyze that file
+- Directory path → all source files in it
+- Module name → Glob `src/**/{module}*`
+
+**Flags:**
+- `-y, --yes`: Skip confirmations
+- `-c, --concurrency N`: Max concurrent agents (default: 4)
+- `--continue`: Resume existing session
+- `--patterns <list>`: Comma-separated pattern names to focus on
+- `--save-spec`: Invoke `spec-add` for each new pattern
+- `--save-wiki`: Create wiki note entries per dimension group
+
+**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/learning/decompose-{slug}-{date}.md`
+</context>
+
+<invariants>
+1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
+2. **Evidence required**: Every finding must have file:line anchors
+3. **Dedup before persist**: Cross-reference against existing specs + lessons
+4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
+5. **No files modified outside** `.workflow/learning/` (and optionally specs/wiki)
+</invariants>
+
+<execution>
+
+### Phase 1: Session Init + Target Resolution
+
+```javascript
+const AUTO_YES = $ARGUMENTS.includes('-y') || $ARGUMENTS.includes('--yes')
+const patternsMatch = $ARGUMENTS.match(/--patterns\s+(\S+)/)
+const patternFilter = patternsMatch ? patternsMatch[1].split(',') : null
+const SAVE_SPEC = $ARGUMENTS.includes('--save-spec')
+const SAVE_WIKI = $ARGUMENTS.includes('--save-wiki')
+const target = $ARGUMENTS.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--patterns\s+\S+|--save-spec|--save-wiki/g, '').trim()
+```
+
+Resolve target to file list. Load existing patterns from `coding-conventions.md` + `lessons.jsonl` for dedup set.
+
+### Phase 2: Wave 1 — Parallel Dimension Scans
+
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
+
+| id | dimension | focus |
+|----|-----------|-------|
+| 1 | structural | Class hierarchy, composition, DI, factories, exports |
+| 2 | behavioral | Events, middleware, observer, command, state machines |
+| 3 | data | Repository, DTO, caching, serialization, validation |
+| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
+| 5 | cross-ref | Dedup + catalog from wave 1 findings |
+
+Each dimension agent returns:
+```json
+[{
+  "name": "pattern name",
+  "dimension": "structural|behavioral|data|error",
+  "confidence": "high|medium|low",
+  "anchors": ["file:line"],
+  "description": "what it does",
+  "rationale": "why this approach",
+  "tradeoffs": "what was given up"
+}]
+```
+
+### Phase 3: Wave 2 — Cross-Reference + Catalog
+
+Single agent receives all wave 1 findings via `prev_context`. Tasks:
+- Match against dedup set → mark as `documented`, `known`, or `new`
+- Merge duplicates across dimensions (same pattern found by multiple agents)
+- Flag contradictions with documented conventions
+- Build pattern catalog grouped by dimension
+
+### Phase 4: Persist
+
+1. Write `decompose-{slug}-{date}.md` with full catalog
+2. Append each **new** pattern to `lessons.jsonl` (source: "decompose", category: "pattern")
+3. If `--save-spec`: invoke `spec-add` per new pattern
+4. If `--save-wiki`: create wiki note per dimension group
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target path not found | Check path or use module name |
+| E002 | error | No source files in target | Check target has .ts/.js files |
+| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
+| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete file list
+- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
+- [ ] Each finding has: name, dimension, confidence, anchors, description
+- [ ] Cross-reference performed (documented / known / new)
+- [ ] Pattern catalog written to `decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
+- [ ] If --save-spec / --save-wiki: entries created
+</success_criteria>

package/.codex/skills/learn-follow/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: learn-follow
+description: Guided follow-along reading of code or wiki entries. Section-by-section walk-through with 4 forcing questions, pattern extraction, and understanding map generation. Persists insights to lessons.jsonl.
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Guided reading experience for code files, wiki entries, or topics. Walks through content
+section by section using 4 forcing questions to extract patterns, identify assumptions,
+and build a structured understanding map. Insights persist to `lessons.jsonl`.
+
+Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
+deep reading that builds understanding incrementally.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → Read source file
+- Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
+- Topic string → Search via `maestro wiki search`, use top result
+
+**Flags:**
+- `--depth shallow` — Key patterns and structure only (default)
+- `--depth deep` — Every function, branch, assumption
+- `--save-wiki` — Create wiki note with reading notes
+
+**Output**: `.workflow/learning/follow-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target + Load Context Web
+- File: verify exists, parse imports for dependency files
+- Wiki ID: fetch + load forward/backlinks
+- Topic: search wiki, take top result
+- Build 1-hop context neighborhood (imports/exports or wiki links)
+
+### Stage 2: Build Reading Order
+- Single file: split into logical sections (function/class boundaries)
+- Directory: entry point → core modules → utilities → tests
+- `--depth shallow`: top-level structure only
+- `--depth deep`: every function body, every branch
+
+### Stage 3: Guided Reading (4 Forcing Questions per Section)
+1. **"What pattern is being used here?"** — design patterns, idioms, conventions
+2. **"Why this approach instead of alternatives?"** — trade-offs made
+3. **"What assumption does this depend on?"** — external state, input shape, ordering
+4. **"What would break if this changed?"** — fragility, downstream effects
+
+### Stage 4: Extract Patterns + Produce Understanding Map
+From forcing question answers, extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+
+Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
+
+### Stage 5: Persist
+1. Write `follow-{slug}-{date}.md` with understanding map
+2. Append new patterns to `lessons.jsonl` (source: "follow", stable INS-ids)
+3. If `--save-wiki`: create wiki note entry
+
+**Next steps:** `/learn-decompose <path>`, `/spec-add coding ...`, `/learn-second-opinion <file>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Check path/ID or rephrase topic |
+| W001 | warning | Wiki graph unavailable | Proceed with code-only context |
+| W002 | warning | coding-conventions.md not found | Patterns flagged "unknown status" |
+| W003 | warning | Large target (>1000 lines) | Auto-switch to shallow depth |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete content
+- [ ] Context web loaded (imports/exports or wiki links)
+- [ ] All 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors
+- [ ] Understanding map produced with concepts, patterns, assumptions, questions
+- [ ] `follow-{slug}-{date}.md` written
+- [ ] `lessons.jsonl` appended with stable INS-ids
+</success_criteria>

package/.codex/skills/learn-investigate/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: learn-investigate
+description: Systematic question investigation with hypothesis testing, evidence logging, and 3-strike escalation. 4-phase pipeline — evidence collection, pattern matching, hypothesis testing, synthesis. Persists findings to lessons.jsonl.
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Systematic investigation for understanding questions (not bug-fixing). 4-phase approach
+with scope lock and 3-strike escalation. Produces structured evidence trails and
+understanding documents that persist to the learning system.
+
+Unlike `quality-debug` (fixing bugs during execution), this answers "how does X work?",
+"why does Y happen?", "what would happen if Z?" questions.
+</purpose>
+
+<context>
+$ARGUMENTS — question text and optional flags.
+
+**Flags:**
+- `--scope <path>` — Restrict to files under this directory (default: entire project)
+- `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
+
+**Output**: `.workflow/learning/investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
+</context>
+
+<execution>
+
+### Stage 1: Frame the Question
+- Parse question, generate slug, create investigation directory
+- Search prior knowledge: wiki search, grep lessons.jsonl, read debug-notes.md
+- Write initial `understanding.md`
+
+### Stage 2: Evidence Collection
+1. **Code search**: Grep keywords across scoped files
+2. **File inspection**: Read most relevant files
+3. **Import tracing**: Follow dependency chain
+4. **Git history**: `git log --oneline -10 -- <relevant-files>`
+
+Each evidence item → `evidence.ndjson`:
+```json
+{"ts":"ISO","type":"code|git|search|doc","source":"file:line","relevance":"high|medium|low","content":"...","note":"..."}
+```
+
+### Stage 3: Hypothesis Formation + Testing
+Generate ranked hypotheses from evidence. For each (in rank order):
+1. Design test: what evidence would confirm/disprove?
+2. Execute test: code trace, targeted search, experiment
+3. Record result in `evidence.ndjson` (type: "test")
+4. Update `understanding.md`: confirmed / disproved / inconclusive
+
+### Stage 4: 3-Strike Escalation
+If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark INCONCLUSIVE.
+
+### Stage 5: Synthesize + Persist
+1. Write `report.md` with answer, evidence trail, hypothesis results
+2. Append to `lessons.jsonl`:
+   - Confirmed → category: "technique" / "pattern"
+   - Disproved → category: "gotcha"
+3. Display summary with next-step routing
+
+**Next steps:** `/spec-add debug <finding>`, `/learn-follow <path>`, `/learn-decompose <module>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No question provided | Provide question as first argument |
+| E002 | error | Scope path does not exist | Check --scope path |
+| W001 | warning | No prior knowledge found | Proceed with fresh investigation |
+| W002 | warning | Very few evidence matches (<3) | Broaden search terms |
+| W003 | warning | All hypotheses inconclusive | Marked INCONCLUSIVE |
+</error_codes>
+
+<success_criteria>
+- [ ] Question parsed and investigation directory created
+- [ ] Evidence collected and logged to evidence.ndjson
+- [ ] At least 1 hypothesis formed and tested
+- [ ] understanding.md tracks evolving understanding
+- [ ] report.md written with answer and evidence trail
+- [ ] Findings appended to lessons.jsonl with stable INS-ids
+- [ ] 3-strike escalation triggered if all hypotheses fail
+</success_criteria>

package/.codex/skills/learn-retro/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: learn-retro
+description: Unified retrospective via CSV wave pipeline. Git lens (commit metrics, session detection, hotspots) and decision lens (multi-perspective evaluation via 3 parallel agents) with lens-based selection. Persists insights to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--compare]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Unified retrospective combining git activity analysis and decision quality evaluation.
+Two lenses, usable independently or together:
+- **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trends
+- **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation via 3 parallel agents
+
+Works on raw git history and wiki/spec data — does not require completed phase artifacts.
+</purpose>
+
+<context>
+$ARGUMENTS — lens selection and scope flags.
+
+**Lens:** `--lens git` | `--lens decision` | `--lens all` (default)
+
+**Git flags:** `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare`
+**Decision flags:** `--phase N`, `--tag <tag>`, `--id <id>`
+
+**Output**: `.workflow/learning/retro-{date}.md` + `retro-{date}.json`
+</context>
+
+<execution>
+
+### Phase 1: Parse + Select Lenses
+
+### Phase 2: Git Lens (skip if --lens decision)
+**Sequential data gathering** (parallel git commands):
+- Commit stats with shortstat
+- Per-commit numstat for test/production LOC split
+- Timestamps for session detection (>2hr gap clustering)
+- File hotspots (most frequently changed)
+- Per-author commit counts
+
+**Compute**: commits, LOC, test ratio, churn rate, active days, sessions, per-author breakdown.
+**Trend comparison** if prior `retro-*.json` exists.
+
+### Phase 3: Decision Lens (skip if --lens git)
+**3a: Collect decisions** from wiki, specs, git log, phase context, lessons.jsonl.
+**3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
+
+**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents):
+
+| id | perspective | focus |
+|----|------------|-------|
+| 1 | technical | Implementation vs intent, context drift. Grade: sound/degraded/violated |
+| 2 | cost | Complexity added, coupling, tech debt. Grade: low-cost/acceptable/expensive |
+| 3 | hindsight | Right call with current knowledge? Grade: confirmed/questionable/should-revisit |
+
+**3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
+
+### Phase 4: Unified Report
+Write `retro-{date}.md` + `retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
+
+### Phase 5: Persist
+Append insights to `lessons.jsonl` (source: "retro-git" or "retro-decision"). Display summary.
+
+**Next steps:** `/learn-follow <path>`, `/quality-test-gen <area>`, `/learn-investigate <question>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Not inside git repo (git lens) | Navigate to git repo |
+| E002 | error | No commits in time window | Increase --days |
+| E003 | error | No decisions found (decision lens) | Check wiki/specs content |
+| W001 | warning | .workflow/learning/ not found | Auto-bootstrap |
+| W002 | warning | No prior retro for comparison | First retro establishes baseline |
+| W003 | warning | Decision perspective agent failed | Proceed with partial evaluation |
+</error_codes>
+
+<success_criteria>
+- [ ] Lens selection parsed correctly
+- [ ] Git lens: metrics computed, sessions detected, hotspots identified
+- [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
+- [ ] Unified report written to retro-{date}.md + retro-{date}.json
+- [ ] lessons.jsonl appended with insights (stable INS-ids)
+</success_criteria>

package/.codex/skills/learn-second-opinion/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: learn-second-opinion
+description: Multi-perspective analysis via CSV wave pipeline. Review mode spawns 3 parallel persona agents (pragmatist, purist, strategist), then synthesis agent merges verdicts. Also supports challenge and consult modes. Persists findings to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency 3] [--continue] \"<target> [--mode review|challenge|consult]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Structured second-opinion for code, decisions, or plans. Three modes:
+- **review** (default): 3 parallel persona agents independently assess target via spawn_agents_on_csv
+- **challenge**: single adversarial agent via spawn_agents_on_csv (1 worker)
+- **consult**: interactive Q&A (no CSV wave — direct orchestration)
+
+Findings persist to `lessons.jsonl`. Decoupled from phase lifecycle.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → analyze file content
+- Wiki ID (`type-slug`) → fetch via `maestro wiki get`
+- `HEAD` / `staged` → analyze git diff
+- Phase number → analyze phase plan
+
+**Flags:**
+- `--mode review` — 3-persona parallel review (default)
+- `--mode challenge` — Adversarial single-agent analysis
+- `--mode consult` — Interactive Q&A session
+
+**Output**: `.workflow/learning/opinion-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Phase 1: Resolve Target + Load Context
+Resolve target to content. Load specs, wiki search, prior lessons for context brief.
+
+### Phase 2: Execute Mode
+
+#### Review Mode (spawn_agents_on_csv)
+
+| id | persona | focus | grading |
+|----|---------|-------|---------|
+| 1 | pragmatist | Simplicity, YAGNI, maintenance cost, readability | complexity score, abstraction depth |
+| 2 | purist | Correctness, type safety, edge cases, error handling | error paths, type completeness |
+| 3 | strategist | Scalability, extensibility, architecture alignment | coupling, cohesion |
+| 4 | synthesis | Merge verdicts → agreements, disagreements, top 3 recommendations | combined verdict |
+
+Wave 1: 3 persona agents in parallel. Wave 2: synthesis agent with wave 1 findings as prev_context.
+
+Each persona returns: `{ persona, verdict: approve|concern|reject, confidence, findings: [{severity, description, location, suggestion}], summary }`
+
+#### Challenge Mode
+Single agent via spawn_agents_on_csv (1 worker). Adversarial analysis with forcing questions:
+- "What assumption would invalidate this entire approach?"
+- "What's the simplest thing that breaks this?"
+- "What's the implicit contract that isn't enforced?"
+
+#### Consult Mode
+Interactive loop via AskUserQuestion. Agent studies target, answers questions with code references. Compile Q&A into report on exit.
+
+### Phase 3: Persist
+1. Write `opinion-{slug}-{date}.md` with per-persona findings + synthesis
+2. Append non-trivial findings to `lessons.jsonl` (source: "second-opinion")
+3. Display summary with verdict and next steps
+
+**Next steps:** `/manage-issue create`, `/learn-decompose <path>`, `/learn-follow <path>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Verify path/ID |
+| E002 | error | Unknown --mode value | Use: review, challenge, consult |
+| W001 | warning | Persona agent failed — partial perspectives | Proceed with available agents |
+| W003 | warning | Git diff empty for HEAD/staged | Use file path instead |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved and context loaded
+- [ ] Mode executed: review (3 parallel agents), challenge (adversarial), or consult (interactive)
+- [ ] Synthesis produced with agreements, disagreements, verdict
+- [ ] Report written to `opinion-{slug}-{date}.md`
+- [ ] Non-trivial findings appended to `lessons.jsonl`
+</success_criteria>