maestro-flow 0.1.4 → 0.2.1

package/.claude/commands/learn-follow.md

@@ -0,0 +1,167 @@
+---
+name: learn-follow
+description: Guided follow-along reading of code or wiki entries, extracting patterns and building understanding
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Guided reading experience for code files, wiki entries, or topics. Instead of just reading code, this command walks through content section by section using forcing questions (inspired by gstack `/office-hours` brainstorming) to extract patterns, identify assumptions, and build a structured understanding map.
+
+Outputs reading notes with extracted patterns, open questions, and connection points. Insights persist to `lessons.jsonl` and optionally become wiki note entries for the knowledge graph.
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Target resolution (auto-detected from first argument):**
+- File path (e.g., `src/commands/wiki.ts`) → Read source file
+- Wiki ID (e.g., `spec-auth`, `phase-planning`) → Fetch via `maestro wiki get`
+- Topic string (e.g., `"authentication flow"`) → Search via `maestro wiki search`, use top result
+
+**Flags:**
+- `--depth shallow` — Quick pass: key patterns and structure only (default)
+- `--depth deep` — Thorough: every function, every branch, every assumption
+- `--save-wiki` — Create a wiki note entry with the reading notes via `maestro wiki create --type note`
+
+**Storage written:**
+- `.workflow/learning/follow-{slug}-{YYYY-MM-DD}.md` — Reading notes with understanding map
+- `.workflow/learning/lessons.jsonl` — Appended pattern/technique insights
+- `.workflow/learning/learning-index.json` — Updated index
+- If `--save-wiki`: new wiki note entry
+
+**Storage read:**
+- Target source file or wiki entry
+- `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
+- `.workflow/specs/coding-conventions.md` — Convention reference for pattern matching
+- `.workflow/learning/lessons.jsonl` — Prior insights for dedup and cross-reference
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target
+- If argument looks like a file path (contains `/` or `\`, or matches a glob): verify file exists via Read
+- If argument matches wiki ID pattern (`<type>-<slug>`): fetch via `maestro wiki get <id>` (offline mode)
+- Otherwise: treat as topic string, run `maestro wiki search "<topic>"`, take the top result. If no result, fall back to Grep across `src/` for the topic.
+- If target cannot be resolved, AskUserQuestion with suggestions.
+
+### Stage 2: Load Context Web
+For the resolved target, build a 1-hop context neighborhood:
+
+**If wiki entry:**
+- `maestro wiki forward <id>` — What this entry references
+- `maestro wiki backlinks <id>` — What references this entry
+- Read the body of top 3 related entries for context
+
+**If code file:**
+- Parse imports/requires to identify dependency files
+- Grep for exports used by other files (reverse dependencies)
+- Read the first 50 lines of top 3 dependent files for context
+
+**If directory:**
+- List files, identify entry points (index.ts, main.ts, cli.ts)
+- Build reading order: entry point → core modules → utilities → tests
+
+### Stage 3: Build Reading Order
+- For a single file: split into logical sections (function boundaries, class boundaries, export groups)
+- For a wiki entry: split by markdown headings
+- For a directory: order files by dependency (entry points first, leaf modules last)
+- For `--depth shallow`: limit to top-level structure (function signatures, section headers)
+- For `--depth deep`: include every function body, every branch
+
+### Stage 4: Guided Reading with Forcing Questions
+Walk through each section in reading order. For each section, apply 4 forcing questions:
+
+1. **"What pattern is being used here?"** — Identify design patterns, idioms, conventions. Compare against `coding-conventions.md`.
+2. **"Why this approach instead of alternatives?"** — What trade-offs were made? What was the simpler approach not chosen?
+3. **"What assumption does this depend on?"** — What must be true for this code/content to be correct? External state? Input shape? Ordering?
+4. **"What would break if this changed?"** — Fragility analysis. What downstream effects would a change have?
+
+Record answers as structured annotations per section.
+
+### Stage 5: Extract Patterns
+From the forcing question answers, extract:
+- **Design patterns**: named patterns with code anchors (file:line)
+- **Naming conventions**: how things are named and why
+- **Error handling approach**: how errors flow through this code/content
+- **Data flow**: how data enters, transforms, and exits
+- **Assumptions**: explicit and implicit assumptions identified
+
+Cross-reference each pattern against existing `coding-conventions.md` entries:
+- Already documented → note as "confirmed convention"
+- Not documented → flag as "undocumented pattern" (candidate for `spec-add`)
+
+### Stage 6: Produce Understanding Map
+Build a structured summary document:
+
+```markdown
+# Follow-Along: {target name}
+
+## Key Concepts
+- {concept}: {one-line explanation}
+
+## Patterns Identified
+| Pattern | Location | Convention Status |
+|---------|----------|-------------------|
+| {name} | {file:line} | documented / undocumented |
+
+## Assumptions
+- {assumption}: {what depends on it}
+
+## Open Questions
+- {question}: {why it matters}
+
+## Connections
+- Links to: {forward link entries}
+- Referenced by: {backlink entries}
+- Related lessons: {matching lessons.jsonl entries}
+```
+
+### Stage 7: Persist
+1. Write `.workflow/learning/follow-{slug}-{date}.md` with the understanding map
+2. Append each new pattern/technique as an insight to `lessons.jsonl`:
+   - `source: "follow"`, `category: "pattern"` or `"technique"`
+   - Tags: `["follow", "{target-slug}"]`
+   - Stable INS-id from `hash("follow" + target + pattern_name)`
+3. Update `learning-index.json`
+4. If `--save-wiki`: run `maestro wiki create --type note --slug follow-{slug} --title "Follow-Along: {target}" --body-file .workflow/learning/follow-{slug}-{date}.md`
+5. Display summary with key findings and next steps
+
+**Next-step routing:**
+- Deep dive into a discovered pattern → `Skill({ skill: "learn-decompose", args: "<path>" })`
+- Add undocumented pattern to specs → `Skill({ skill: "spec-add", args: "pattern <description>" })`
+- Get second opinion on a finding → `Skill({ skill: "learn-second-opinion", args: "<file>" })`
+- Browse related wiki entries → `Skill({ skill: "wiki-digest", args: "<topic>" })`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable (file not found, wiki ID not found, search returned 0) | Check path/ID, or rephrase topic for search |
+| E002 | error | `.workflow/` not initialized | Run `Skill({ skill: "maestro-init" })` first |
+| W001 | warning | Wiki graph unavailable (no .workflow/ wiki entries) — skipping context web | Proceed with code-only context (imports/exports) |
+| W002 | warning | coding-conventions.md not found — skipping convention comparison | Patterns flagged as "unknown convention status" |
+| W003 | warning | Target is very large (>1000 lines) — auto-switching to shallow depth | Use --depth deep to override |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete content (file, wiki entry, or search result)
+- [ ] Context web loaded (forward/backlinks for wiki, imports/exports for code)
+- [ ] Reading order established (sections/files ordered logically)
+- [ ] All 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors
+- [ ] Convention comparison performed against coding-conventions.md
+- [ ] Understanding map produced with: concepts, patterns, assumptions, questions, connections
+- [ ] `follow-{slug}-{date}.md` written
+- [ ] `lessons.jsonl` appended with discovered patterns (stable INS-ids)
+- [ ] `learning-index.json` updated
+- [ ] If --save-wiki: wiki note entry created
+- [ ] No files modified outside `.workflow/learning/` (and optionally wiki)
+- [ ] Summary displayed with next-step routing
+</success_criteria>

package/.claude/commands/learn-investigate.md

@@ -0,0 +1,195 @@
+---
+name: learn-investigate
+description: Systematic question investigation with hypothesis testing, evidence logging, and 3-strike escalation
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Systematic investigation workflow for understanding questions (not bug-fixing). Inspired by gstack `/investigate` with its 4-phase approach, scope lock, and 3-strike escalation rule.
+
+Unlike `quality-debug` which is designed for fixing bugs during execution phases, this command is for answering "how does X work?", "why does Y happen?", "what would happen if Z?" questions. It produces structured evidence trails and understanding documents that persist to the learning system.
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Target:** First argument is the question or topic to investigate (quoted string or keywords).
+
+**Flags:**
+- `--scope <path>` — Restrict investigation to files under this directory (default: entire project)
+- `--max-hypotheses N` — Maximum hypotheses to test before escalating (default: 3)
+
+**Storage written:**
+- `.workflow/learning/investigate-{slug}/evidence.ndjson` — Structured evidence log (one JSON line per evidence)
+- `.workflow/learning/investigate-{slug}/understanding.md` — Evolving understanding document
+- `.workflow/learning/investigate-{slug}/report.md` — Final investigation report
+- `.workflow/learning/lessons.jsonl` — Investigation findings as insights (source: "investigate")
+- `.workflow/learning/learning-index.json` — Updated index
+
+**Storage read:**
+- Source files within scope
+- `maestro wiki search "<question>"` — Prior knowledge about the topic
+- `.workflow/learning/lessons.jsonl` — Prior related investigations
+- `.workflow/specs/debug-notes.md` — Known gotchas and patterns
+- `.workflow/codebase/architecture.md` — Structural context (if exists)
+</context>
+
+<execution>
+
+### Stage 1: Frame the Question
+- Parse question from arguments
+- Determine scope (--scope or full project)
+- Generate investigation slug from question keywords
+- Create `.workflow/learning/investigate-{slug}/` directory
+- Search prior knowledge:
+  - `maestro wiki search "<question>"` for related entries
+  - Grep `lessons.jsonl` for related insights
+  - Read `debug-notes.md` for known gotchas
+
+Write initial `understanding.md`:
+```markdown
+# Investigation: {question}
+## Initial Understanding
+- Prior knowledge: {summary of wiki/lessons findings}
+- Scope: {path or "full project"}
+- Started: {timestamp}
+```
+
+### Stage 2: Evidence Collection
+Systematically gather evidence related to the question:
+
+1. **Code search**: Grep for keywords from the question across the scoped files
+2. **File inspection**: Read the most relevant files identified by search
+3. **Import/dependency tracing**: Follow imports to understand the dependency chain
+4. **Git history**: `git log --oneline -10 -- <relevant-files>` for recent changes
+
+For each piece of evidence, append to `evidence.ndjson`:
+```json
+{"ts": "ISO", "type": "code|git|search|doc", "source": "file:line", "relevance": "high|medium|low", "content": "...", "note": "why this matters"}
+```
+
+### Stage 3: Pattern Matching
+Compare collected evidence against known patterns:
+- Check `debug-notes.md` entries for matching situations
+- Check `lessons.jsonl` for related technique/pattern/gotcha entries
+- Identify: does this match a documented pattern, or is it novel?
+
+Update `understanding.md` with pattern analysis section.
+
+### Stage 4: Hypothesis Formation
+From evidence and patterns, generate ranked hypotheses:
+- Each hypothesis: a specific, testable claim about "how/why"
+- Rank by plausibility (evidence strength)
+- Write hypotheses to `understanding.md`
+
+```markdown
+## Hypotheses
+1. **[HIGH]** {hypothesis 1} — Evidence: {refs}
+2. **[MEDIUM]** {hypothesis 2} — Evidence: {refs}
+3. **[LOW]** {hypothesis 3} — Evidence: {refs}
+```
+
+### Stage 5: Hypothesis Testing
+For each hypothesis (in rank order):
+
+1. **Design test**: What specific evidence would confirm or disprove this?
+2. **Execute test**: Code trace, targeted search, data inspection, or experiment
+3. **Record result**: Append to `evidence.ndjson` with `type: "test"`
+4. **Update understanding**: Mark hypothesis as confirmed / disproved / inconclusive
+
+```markdown
+## Test Results
+### Hypothesis 1: {claim}
+- Test: {what was done}
+- Result: CONFIRMED / DISPROVED / INCONCLUSIVE
+- Evidence: {file:line references}
+```
+
+### Stage 6: 3-Strike Escalation
+If `--max-hypotheses` hypotheses all fail:
+
+1. **Broaden scope**: If scope was restricted, suggest expanding. AskUserQuestion:
+   ```
+   {N} hypotheses tested, none confirmed.
+   A) Broaden scope to full project
+   B) I have a new hypothesis: [user provides]
+   C) Escalate — this needs deeper investigation
+   ```
+2. **Search wiki for clues**: `maestro wiki search` with alternative keywords
+3. **If still stuck**: Mark as INCONCLUSIVE with what was learned and what remains unknown
+
+### Stage 7: Synthesize & Report
+Write final `report.md`:
+
+```markdown
+# Investigation Report: {question}
+
+## Answer
+{confirmed understanding or "INCONCLUSIVE: ..."}
+
+## Evidence Trail
+| # | Type | Source | Relevance | Finding |
+|---|------|--------|-----------|---------|
+| 1 | code | file:line | high | ... |
+
+## Hypotheses Tested
+| Hypothesis | Result | Key Evidence |
+|-----------|--------|-------------|
+| ... | confirmed/disproved | file:line |
+
+## Key Learnings
+- {learning 1}
+- {learning 2}
+
+## Open Questions
+- {what remains unknown}
+```
+
+### Stage 8: Persist
+1. Append findings to `lessons.jsonl`:
+   - Confirmed hypotheses → `category: "technique"` or `"pattern"`
+   - Disproved hypotheses → `category: "gotcha"` (what looked true but wasn't)
+   - `source: "investigate"`, tags: `["investigate", "{question-slug}"]`
+   - Stable INS-id from `hash("investigate" + question + finding_title)`
+2. Update `learning-index.json`
+3. Display summary with answer and next steps
+
+**Next-step routing:**
+- Save finding to specs → `Skill({ skill: "spec-add", args: "debug <finding>" })`
+- Follow-along on discovered code → `Skill({ skill: "learn-follow", args: "<path>" })`
+- Decompose patterns found → `Skill({ skill: "learn-decompose", args: "<module>" })`
+- Create wiki entry for understanding → `maestro wiki create --type note`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No question provided | Provide a question as the first argument |
+| E002 | error | Scope path does not exist | Check --scope path is valid |
+| W001 | warning | No prior knowledge found in wiki/lessons | Proceed with fresh investigation |
+| W002 | warning | Evidence collection found very few matches (<3) | Broaden search terms or expand scope |
+| W003 | warning | All hypotheses inconclusive — escalating | Investigation marked INCONCLUSIVE |
+</error_codes>
+
+<success_criteria>
+- [ ] Question parsed and investigation slug generated
+- [ ] Investigation directory created under `.workflow/learning/`
+- [ ] Prior knowledge loaded from wiki and lessons
+- [ ] Evidence collected and logged to `evidence.ndjson` (structured NDJSON)
+- [ ] Pattern matching performed against debug-notes and lessons
+- [ ] At least 1 hypothesis formed and tested
+- [ ] `understanding.md` tracks evolving understanding with timestamps
+- [ ] `report.md` written with answer, evidence trail, hypothesis results
+- [ ] Findings appended to `lessons.jsonl` with stable INS-ids
+- [ ] `learning-index.json` updated
+- [ ] 3-strike escalation triggered if all hypotheses fail
+- [ ] No files modified outside `.workflow/learning/`
+- [ ] Summary displayed with answer and next-step routing
+</success_criteria>

package/.claude/commands/learn-retro-decision.md

@@ -0,0 +1,198 @@
+---
+name: learn-retro-decision
+description: Decision trace and evaluation with multi-perspective analysis and lifecycle classification
+argument-hint: "[--phase N] [--tag <tag>] [--id <decision-id>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Decision retrospective that traces architectural and design decisions across wiki, specs, phase contexts, and git history. Evaluates each decision from 3 perspectives (technical soundness, cost assessment, alternative hindsight) and classifies its lifecycle status.
+
+Inspired by gstack's cross-functional review pipeline (CEO/Eng/Design perspectives). Unlike `quality-retrospective` which reviews completed phases holistically, this command focuses specifically on decision quality and evolution.
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Scope:**
+- No arguments → scan all sources for decisions, prompt for selection
+- `--phase N` → decisions from phase N's context and related specs
+- `--tag <tag>` → decisions tagged with specific tag in wiki/specs
+- `--id <id>` → single decision by wiki ID or lessons.jsonl INS-id
+
+**Storage written:**
+- `.workflow/learning/retro-decision-{YYYY-MM-DD}.md` — Decision evaluation report
+- `.workflow/learning/lessons.jsonl` — Decision evaluation insights (source: "retro-decision")
+- `.workflow/learning/learning-index.json` — Updated index
+
+**Storage read:**
+- `maestro wiki list --type spec --json` — Spec entries (many contain decisions)
+- `maestro wiki search "decision"` — Decision-tagged entries
+- `.workflow/specs/architecture-constraints.md` — Documented architectural decisions
+- `.workflow/phases/*/context.md` — Phase context with Locked/Free/Deferred decisions (if exists)
+- `.workflow/learning/lessons.jsonl` — Entries with `category: "decision"`
+- Git log — Implementation evidence for decision tracing
+</context>
+
+<execution>
+
+### Stage 1: Collect Decisions
+Gather decisions from all sources in parallel:
+
+```bash
+# Wiki decisions
+maestro wiki search "decision" --json
+maestro wiki list --type spec --json  # specs often contain decision entries
+
+# Git evidence
+git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
+```
+
+Also read:
+- `.workflow/specs/architecture-constraints.md` — grep for `### [decision]` heading blocks
+- `.workflow/phases/*/context.md` — scan for "Locked:", "Deferred:" sections
+- `.workflow/learning/lessons.jsonl` — filter entries where `category == "decision"`
+
+Apply scope filter (--phase, --tag, --id) to reduce the set.
+
+If no decisions found, AskUserQuestion: "No decisions found in wiki/specs. Would you like to: A) Scan git commit messages for implicit decisions, B) Provide a specific decision to evaluate"
+
+### Stage 2: Build Decision Registry
+For each decision, build a structured record:
+
+```json
+{
+  "id": "decision source id",
+  "title": "what was decided",
+  "source": "wiki|spec|phase-context|lesson|git",
+  "date": "when decided",
+  "rationale": "why (if documented)",
+  "alternatives": "what was considered (if documented)",
+  "phase": "which phase",
+  "tags": ["related tags"],
+  "implementation_evidence": ["file paths from git that implement this"]
+}
+```
+
+For implementation evidence: search git log for commits that reference the decision topic, and grep source files for patterns consistent with the decision.
+
+### Stage 3: Multi-Perspective Evaluation
+Spawn 3 Agents in a single message, each evaluating all decisions from one perspective:
+
+**Agent 1 — Technical Soundness:**
+- Does the implementation match the stated intent?
+- Are there code-level violations of the decision?
+- Has the technical context changed since the decision was made?
+- Grade: sound / degraded / violated
+
+**Agent 2 — Cost Assessment:**
+- What complexity did this decision add?
+- How many files/modules are affected?
+- Is the decision creating coupling or technical debt?
+- Grade: low-cost / acceptable / expensive / debt-creating
+
+**Agent 3 — Alternative Hindsight:**
+- With what we know now, was this the right call?
+- What alternative would we choose today?
+- Would reversing this decision be feasible?
+- Grade: confirmed / questionable / should-revisit
+
+Each agent receives the full decision registry and returns evaluations per decision.
+
+### Stage 4: Classify Decision Lifecycle
+Based on the 3 perspectives, classify each decision:
+
+| Status | Criteria |
+|--------|---------|
+| **Validated** | Sound + Low/Acceptable cost + Confirmed | 
+| **Aging** | Sound but Expensive + Confirmed (still right but costly) |
+| **Questionable** | Degraded or Violated + Any cost + Questionable |
+| **Stale** | Any soundness + Any cost + Should-revisit |
+| **Reversed** | Evidence in code contradicts the decision |
+
+### Stage 5: Generate Recommendations
+For each non-Validated decision:
+- **Aging**: flag for tech debt review, suggest cost reduction
+- **Questionable**: create issue for investigation, suggest brainstorm
+- **Stale**: suggest decision refresh (re-evaluate with current context)
+- **Reversed**: suggest documenting the reversal and updating specs/wiki
+
+### Stage 6: Write Report
+`.workflow/learning/retro-decision-{date}.md`:
+
+```markdown
+# Decision Retrospective: {scope}
+**Date:** {date} | **Decisions evaluated:** {count}
+
+## Decision Health Dashboard
+| Status | Count | Decisions |
+|--------|-------|-----------|
+| Validated | N | {list} |
+| Aging | N | {list} |
+| Questionable | N | {list} |
+| Stale | N | {list} |
+
+## Per-Decision Evaluation
+
+### {Decision Title}
+**Source:** {wiki/spec/phase} | **Date:** {when} | **Status:** {lifecycle}
+
+| Perspective | Grade | Assessment |
+|------------|-------|-----------|
+| Technical | sound/degraded/violated | {one-line} |
+| Cost | low/acceptable/expensive | {one-line} |
+| Hindsight | confirmed/questionable/revisit | {one-line} |
+
+**Implementation evidence:** {file references}
+**Recommendation:** {action if non-validated}
+
+## Recommended Actions
+1. {action}: {reason}
+```
+
+### Stage 7: Persist
+1. Write report file
+2. Append decision evaluation insights to `lessons.jsonl`:
+   - `source: "retro-decision"`, `category: "decision"`
+   - Tags: `["retro-decision", "{lifecycle-status}"]`
+   - One insight per non-Validated decision with the recommendation
+3. Update `learning-index.json`
+4. Optionally: update wiki entries with evaluation metadata via `maestro wiki update`
+5. Display health dashboard summary
+
+**Next-step routing:**
+- Create issue for questionable decision → `Skill({ skill: "manage-issue", args: "create ..." })`
+- Brainstorm alternatives → `Skill({ skill: "maestro-brainstorm", args: "<decision topic>" })`
+- Investigate stale decision → `Skill({ skill: "learn-investigate", args: "<question>" })`
+- Update spec → `Skill({ skill: "spec-add", args: "decision <updated rationale>" })`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No decisions found in any source | Check wiki/specs content, or provide --id |
+| E002 | error | --id not found in wiki or lessons | Verify the decision ID exists |
+| W001 | warning | One perspective agent failed — partial evaluation | Proceed with available perspectives, note gap |
+| W002 | warning | No git implementation evidence found for a decision | Decision evaluation is theoretical only |
+| W003 | warning | Phase context files not found | Skip phase-context decisions, proceed with wiki/spec sources |
+</error_codes>
+
+<success_criteria>
+- [ ] Decisions collected from all available sources (wiki, specs, phase-context, lessons, git)
+- [ ] Scope filter applied correctly (--phase, --tag, or --id)
+- [ ] Decision registry built with structured records
+- [ ] 3 perspective agents spawned in parallel
+- [ ] Each decision classified: Validated / Aging / Questionable / Stale / Reversed
+- [ ] Recommendations generated for non-Validated decisions
+- [ ] Report written to `retro-decision-{date}.md` with health dashboard
+- [ ] Insights appended to `lessons.jsonl` (source: "retro-decision")
+- [ ] `learning-index.json` updated
+- [ ] No files modified outside `.workflow/learning/`
+- [ ] Health dashboard displayed with next-step routing
+</success_criteria>