maestro-flow 0.5.2 → 0.5.31

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

@@ -1,152 +1,151 @@
----
-name: learn-investigate
-description: Investigate questions with hypothesis testing and evidence logging
-argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Systematic investigation for understanding questions (not bug-fixing). 4-phase scientific method with scope lock and 3-strike escalation. Produces evidence trails and understanding docs that persist to the learning system.
-
-Unlike `quality-debug` (fix bugs during execution), this answers "how does X work?", "why does Y happen?", "what if Z?".
-</purpose>
-
-<context>
-$ARGUMENTS — question text and optional flags.
-
-**Flags**:
-- `--scope <path>`: Restrict to files under this dir (default: entire project)
-- `--max-hypotheses N`: Max hypotheses before escalation (default: 3)
-
-**Storage write**:
-- `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
-- `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — evolving understanding
-- `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
-- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
-
-**Storage read**: source files in scope + `maestro search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
-</context>
-
-<state_machine>
-
-<states>
-S_FRAME          — 解析问题、确定 scope、搜索先验知识          PERSIST: understanding.md (initial)
-S_EVIDENCE       — 系统收集证据                                PERSIST: evidence.ndjson
-S_PATTERN        — 比对已知模式                                PERSIST: understanding.md (patterns)
-S_HYPOTHESIZE    — 生成假设列表                                PERSIST: understanding.md (hypotheses)
-S_CLI_EXPLORE    — CLI 辅助探索（可选）                         PERSIST: evidence.ndjson (append)
-S_TEST           — 逐假设测试                                  PERSIST: evidence.ndjson + understanding.md
-S_ESCALATE       — 3-strike 升级                               PERSIST: —
-S_REPORT         — 综合报告 + persist                          PERSIST: report.md + .workflow/specs/learnings.md
-</states>
-
-<transitions>
-
-S_FRAME:
-  → S_EVIDENCE    DO: A_FRAME_QUESTION
-
-S_EVIDENCE:
-  → S_PATTERN     DO: A_COLLECT_EVIDENCE
-
-S_PATTERN:
-  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns
-
-S_HYPOTHESIZE:
-  → S_CLI_EXPLORE WHEN: CLI tools enabled AND hypotheses non-trivial    DO: A_FORM_HYPOTHESES
-  → S_TEST        WHEN: no CLI tools OR trivial hypotheses              DO: A_FORM_HYPOTHESES
-
-S_CLI_EXPLORE:
-  → S_TEST        DO: A_CLI_SUPPLEMENT (maestro delegate --role explore --mode analysis, run_in_background, STOP)
-
-S_TEST:
-  → S_REPORT      WHEN: hypothesis confirmed                  DO: A_TEST_HYPOTHESIS
-  → S_REPORT      WHEN: all hypotheses tested (some confirmed) DO: A_TEST_HYPOTHESIS
-  → S_ESCALATE    WHEN: max_hypotheses all failed              DO: A_TEST_HYPOTHESIS
-
-S_ESCALATE:
-  → S_HYPOTHESIZE WHEN: user broadens scope or provides new hypothesis   DO: AskUserQuestion
-  → S_REPORT      WHEN: user selects "Escalate" or still stuck          DO: mark INCONCLUSIVE
-
-S_REPORT:
-  → END           DO: A_SYNTHESIZE_REPORT
-
-</transitions>
-
-<actions>
-
-### A_FRAME_QUESTION
-
-1. Parse question, generate slug, create KNW-investigate-{slug}/
-2. Search prior knowledge: `maestro search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
-3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
-
-### A_COLLECT_EVIDENCE
-
-Parallel evidence gathering:
-1. Code search: Grep keywords from question
-2. File inspection: Read most relevant files
-3. Import tracing: follow dependency chain
-4. Git history: `git log --oneline -10 -- <relevant-files>`
-
-Each item → append evidence.ndjson: `{ts, type (code|git|search|doc), source (file:line), relevance (high|medium|low), content, note}`
-
-### A_FORM_HYPOTHESES
-
-Generate ranked hypotheses: each is specific, testable claim about "how/why".
-Rank by plausibility (evidence strength). Write to understanding.md:
-- `[HIGH]` hypothesis — Evidence: {refs}
-- `[MEDIUM]` hypothesis — Evidence: {refs}
-
-### A_CLI_SUPPLEMENT
-
-```
-maestro delegate "PURPOSE: Gather evidence for hypotheses
-TASK: Trace call chains and data flows per hypothesis | Find corroborating/contradicting patterns
-EXPECTED: JSON [{hypothesis_rank, evidence: [{file, line, supports: bool, explanation}]}]
-" --role explore --mode analysis
-```
-Run_in_background, STOP, wait. On callback: append to evidence.ndjson.
-
-### A_TEST_HYPOTHESIS
-
-For each hypothesis (rank order):
-1. Design test: what evidence would confirm/disprove?
-2. Execute: code trace, targeted search, data inspection
-3. Record: append evidence.ndjson with type: "test"
-4. Update: mark hypothesis confirmed / disproved / inconclusive
-
-### A_SYNTHESIZE_REPORT
-
-Write report.md: Answer (or INCONCLUSIVE), Evidence Trail table, Hypotheses Tested table, Key Learnings, Open Questions.
-Append to .workflow/specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
-
-</actions>
-
-</state_machine>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| E002 | --scope path not found | Check path |
-| W002 | Very few evidence matches (<3) | Broaden search terms or expand scope |
-| W003 | All hypotheses inconclusive | Investigation marked INCONCLUSIVE |
-</error_codes>
-
-<success_criteria>
-- [ ] Evidence collected and logged to evidence.ndjson (structured NDJSON)
-- [ ] At least 1 hypothesis formed and tested
-- [ ] 3-strike escalation triggered if all fail
-- [ ] Report + spec-entry blocks written
-</success_criteria>
-
-<next_step_routing>
-- Save to specs → `/spec-add debug <finding>`
-- Follow code → `/learn-follow <path>`
-- Decompose patterns → `/learn-decompose <module>`
-</next_step_routing>
+---
+name: learn-investigate
+description: Investigate questions with hypothesis testing and evidence logging
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Systematic investigation for understanding questions (not bug-fixing).
+4-phase scientific method with scope lock, 3-strike escalation, and evidence persistence.
+</purpose>
+
+<context>
+$ARGUMENTS — question text and optional flags.
+
+**Flags**:
+- `--scope <path>`: Restrict to files under this dir (default: entire project)
+- `--max-hypotheses N`: Max hypotheses before escalation (default: 3)
+
+**Storage write**:
+- `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
+- `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — evolving understanding
+- `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
+- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
+
+**Storage read**: source files in scope + `maestro search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
+</context>
+
+<state_machine>
+
+<states>
+S_FRAME          — 解析问题、确定 scope、搜索先验知识          PERSIST: understanding.md (initial)
+S_EVIDENCE       — 系统收集证据                                PERSIST: evidence.ndjson
+S_PATTERN        — 比对已知模式                                PERSIST: understanding.md (patterns)
+S_HYPOTHESIZE    — 生成假设列表                                PERSIST: understanding.md (hypotheses)
+S_CLI_EXPLORE    — CLI 辅助探索（可选）                         PERSIST: evidence.ndjson (append)
+S_TEST           — 逐假设测试                                  PERSIST: evidence.ndjson + understanding.md
+S_ESCALATE       — 3-strike 升级                               PERSIST: —
+S_REPORT         — 综合报告 + persist                          PERSIST: report.md + .workflow/specs/learnings.md
+</states>
+
+<transitions>
+
+S_FRAME:
+  → S_EVIDENCE    DO: A_FRAME_QUESTION
+
+S_EVIDENCE:
+  → S_PATTERN     DO: A_COLLECT_EVIDENCE
+
+S_PATTERN:
+  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns
+
+S_HYPOTHESIZE:
+  → S_CLI_EXPLORE WHEN: CLI tools enabled AND hypotheses non-trivial    DO: A_FORM_HYPOTHESES
+  → S_TEST        WHEN: no CLI tools OR trivial hypotheses              DO: A_FORM_HYPOTHESES
+
+S_CLI_EXPLORE:
+  → S_TEST        DO: A_CLI_SUPPLEMENT (maestro delegate --role explore --mode analysis, run_in_background, STOP)
+
+S_TEST:
+  → S_REPORT      WHEN: hypothesis confirmed                  DO: A_TEST_HYPOTHESIS
+  → S_REPORT      WHEN: all hypotheses tested (some confirmed) DO: A_TEST_HYPOTHESIS
+  → S_ESCALATE    WHEN: max_hypotheses all failed              DO: A_TEST_HYPOTHESIS
+
+S_ESCALATE:
+  → S_HYPOTHESIZE WHEN: user broadens scope or provides new hypothesis   DO: AskUserQuestion
+  → S_REPORT      WHEN: user selects "Escalate" or still stuck          DO: mark INCONCLUSIVE
+
+S_REPORT:
+  → END           DO: A_SYNTHESIZE_REPORT
+
+</transitions>
+
+<actions>
+
+### A_FRAME_QUESTION
+
+1. Parse question, generate slug, create KNW-investigate-{slug}/
+2. Search prior knowledge: `maestro search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
+3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
+
+### A_COLLECT_EVIDENCE
+
+Parallel evidence gathering:
+1. Code search: Grep keywords from question
+2. File inspection: Read most relevant files
+3. Import tracing: follow dependency chain
+4. Git history: `git log --oneline -10 -- <relevant-files>`
+
+Each item → append evidence.ndjson: `{ts, type (code|git|search|doc), source (file:line), relevance (high|medium|low), content, note}`
+
+### A_FORM_HYPOTHESES
+
+Generate ranked hypotheses: each is specific, testable claim about "how/why".
+Rank by plausibility (evidence strength). Write to understanding.md:
+- `[HIGH]` hypothesis — Evidence: {refs}
+- `[MEDIUM]` hypothesis — Evidence: {refs}
+
+### A_CLI_SUPPLEMENT
+
+```
+maestro delegate "PURPOSE: Gather evidence for hypotheses
+TASK: Trace call chains and data flows per hypothesis | Find corroborating/contradicting patterns
+EXPECTED: JSON [{hypothesis_rank, evidence: [{file, line, supports: bool, explanation}]}]
+" --role explore --mode analysis
+```
+Run_in_background, STOP, wait. On callback: append to evidence.ndjson.
+
+### A_TEST_HYPOTHESIS
+
+For each hypothesis (rank order):
+1. Design test: what evidence would confirm/disprove?
+2. Execute: code trace, targeted search, data inspection
+3. Record: append evidence.ndjson with type: "test"
+4. Update: mark hypothesis confirmed / disproved / inconclusive
+
+### A_SYNTHESIZE_REPORT
+
+Write report.md: Answer (or INCONCLUSIVE), Evidence Trail table, Hypotheses Tested table, Key Learnings, Open Questions.
+Append to .workflow/specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | --scope path not found | Check path |
+| W002 | Very few evidence matches (<3) | Broaden search terms or expand scope |
+| W003 | All hypotheses inconclusive | Investigation marked INCONCLUSIVE |
+</error_codes>
+
+<success_criteria>
+- [ ] Evidence collected and logged to evidence.ndjson (structured NDJSON)
+- [ ] At least 1 hypothesis formed and tested
+- [ ] 3-strike escalation triggered if all fail
+- [ ] Report + spec-entry blocks written
+</success_criteria>
+
+<next_step_routing>
+- Save to specs → `/spec-add debug <finding>`
+- Follow code → `/learn-follow <path>`
+- Decompose patterns → `/learn-decompose <module>`
+</next_step_routing>

package/.claude/commands/learn-second-opinion.md

@@ -1,122 +1,118 @@
----
-name: learn-second-opinion
-description: Get alternative perspectives — review, challenge, or consult
-argument-hint: "<target> [--mode review|challenge|consult]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Structured second-opinion on code, decisions, or plans. Three modes:
-- **review** (default): 3 parallel agents (pragmatist, purist, strategist)
-- **challenge**: single adversarial agent — break assumptions, propose alternatives
-- **consult**: interactive Q&A — agent studies target, answers your questions
-
-Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
-</purpose>
-
-<context>
-$ARGUMENTS — target and optional mode flag.
-
-**Target resolution** (auto-detected):
-| Input | Resolution |
-|-------|-----------|
-| File path | Read file content |
-| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
-| `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
-| Phase number | Resolve via state.json.artifacts[] → plan.json |
-
-**Flags**: `--mode review|challenge|consult` (default: review)
-
-**Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
-
-**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
-</context>
-
-<state_machine>
-
-<states>
-S_RESOLVE    — 解析 target                          PERSIST: —
-S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
-S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
-S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
-S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: knowhow files
-</states>
-
-<transitions>
-
-S_RESOLVE:
-  → S_CONTEXT     WHEN: target resolved                DO: read target content
-  → S_RESOLVE     WHEN: unresolvable                   DO: AskUserQuestion for clarification
-
-S_CONTEXT:
-  → S_EXECUTE     DO: load specs + wiki search (optional, proceed without)
-
-S_EXECUTE:
-  → S_SYNTHESIZE  WHEN: mode == review                 DO: A_REVIEW
-  → S_SYNTHESIZE  WHEN: mode == challenge              DO: A_CHALLENGE
-  → S_SYNTHESIZE  WHEN: mode == consult                DO: A_CONSULT
-
-S_SYNTHESIZE:
-  → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
-
-S_PERSIST:
-  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
-
-</transitions>
-
-<actions>
-
-### A_REVIEW
-Spawn 3 Agents in single message:
-
-| Agent | Focus | Question |
-|-------|-------|----------|
-| Pragmatist | simplicity, YAGNI, maintenance | "Simplest thing that works? Maintenance burden?" |
-| Purist | correctness, edge cases, type safety | "What assumptions can be violated?" |
-| Strategist | scalability, architecture alignment | "Supports future growth? Fits architecture?" |
-
-Each returns: persona, verdict (approve/concern/reject), confidence, findings[{severity, description, location, suggestion}], summary.
-
-### A_CHALLENGE
-Spawn 1 adversarial Agent:
-- Find weakest assumption
-- Propose concrete breaking scenario
-- Identify single biggest risk
-- Suggest alternative approach
-- Apply forcing questions: "What invalidates this?", "Simplest thing that breaks this?", "What would you regret in 6 months?", "What implicit contract isn't enforced?"
-
-### A_CONSULT
-Interactive loop:
-1. Agent studies target
-2. Display "Target loaded. What would you like to know?"
-3. AskUserQuestion → Agent answers with code refs → repeat until "done"
-4. Compile Q&A into report
-
-</actions>
-
-</state_machine>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| E002 | Unknown --mode value | Use: review, challenge, or consult |
-| W001 | One review agent failed | Proceed with available perspectives |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
-- [ ] Synthesis with agreements, disagreements, verdict
-- [ ] Report written + findings appended to .workflow/specs/learnings.md
-</success_criteria>
-
-<next_step_routing>
-- Create issue → `/manage-issue create <description>`
-- Decompose patterns → `/learn-decompose <path>`
-- Follow code → `/learn-follow <path>`
-</next_step_routing>
+---
+name: learn-second-opinion
+description: Get alternative perspectives — review, challenge, or consult
+argument-hint: "<target> [--mode review|challenge|consult]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Structured second-opinion on code, decisions, or plans via three modes: review (3 parallel agents),
+challenge (adversarial), or consult (interactive Q&A). Findings persist to learnings.md.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional mode flag.
+
+**Target resolution** (auto-detected):
+| Input | Resolution |
+|-------|-----------|
+| File path | Read file content |
+| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
+| `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
+| Phase number | Resolve via state.json.artifacts[] → plan.json |
+
+**Flags**: `--mode review|challenge|consult` (default: review)
+
+**Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
+
+**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
+</context>
+
+<state_machine>
+
+<states>
+S_RESOLVE    — 解析 target                          PERSIST: —
+S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
+S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
+S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
+S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved                DO: read target content
+  → S_RESOLVE     WHEN: unresolvable                   DO: AskUserQuestion for clarification
+
+S_CONTEXT:
+  → S_EXECUTE     DO: load specs + wiki search (optional, proceed without)
+
+S_EXECUTE:
+  → S_SYNTHESIZE  WHEN: mode == review                 DO: A_REVIEW
+  → S_SYNTHESIZE  WHEN: mode == challenge              DO: A_CHALLENGE
+  → S_SYNTHESIZE  WHEN: mode == consult                DO: A_CONSULT
+
+S_SYNTHESIZE:
+  → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
+
+S_PERSIST:
+  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
+
+</transitions>
+
+<actions>
+
+### A_REVIEW
+Spawn 3 Agents in single message:
+
+| Agent | Focus | Question |
+|-------|-------|----------|
+| Pragmatist | simplicity, YAGNI, maintenance | "Simplest thing that works? Maintenance burden?" |
+| Purist | correctness, edge cases, type safety | "What assumptions can be violated?" |
+| Strategist | scalability, architecture alignment | "Supports future growth? Fits architecture?" |
+
+Each returns: persona, verdict (approve/concern/reject), confidence, findings[{severity, description, location, suggestion}], summary.
+
+### A_CHALLENGE
+Spawn 1 adversarial Agent:
+- Find weakest assumption
+- Propose concrete breaking scenario
+- Identify single biggest risk
+- Suggest alternative approach
+- Apply forcing questions: "What invalidates this?", "Simplest thing that breaks this?", "What would you regret in 6 months?", "What implicit contract isn't enforced?"
+
+### A_CONSULT
+Interactive loop:
+1. Agent studies target
+2. Display "Target loaded. What would you like to know?"
+3. AskUserQuestion → Agent answers with code refs → repeat until "done"
+4. Compile Q&A into report
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Unknown --mode value | Use: review, challenge, or consult |
+| W001 | One review agent failed | Proceed with available perspectives |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
+- [ ] Synthesis with agreements, disagreements, verdict
+- [ ] Report written + findings appended to .workflow/specs/learnings.md
+</success_criteria>
+
+<next_step_routing>
+- Create issue → `/manage-issue create <description>`
+- Decompose patterns → `/learn-decompose <path>`
+- Follow code → `/learn-follow <path>`
+</next_step_routing>