maestro-flow 0.3.38 → 0.3.40

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

@@ -1,83 +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>
+---
+name: learn-investigate
+description: Investigate questions with hypothesis testing and evidence logging
+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

@@ -1,83 +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-auto-test <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>
+---
+name: learn-retro
+description: Retrospective of git activity and decision quality
+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-auto-test <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

@@ -1,86 +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>
+---
+name: learn-second-opinion
+description: Get alternative perspectives -- review, challenge, or consult
+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>