maestro-flow 0.4.10 → 0.4.12

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

@@ -0,0 +1,154 @@
+---
+name: learn-investigate
+description: Investigate questions with hypothesis testing and evidence logging
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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
+- `specs/learnings.md` — appended `<spec-entry>` blocks
+
+**Storage read**: source files in scope + `maestro wiki search` + `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 + 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 + 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: ask_user
+  → 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 wiki search "<question>"` + search 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 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/.agents/skills/learn-retro/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: learn-retro
+description: Retrospective of git activity and decision quality
+argument-hint: "[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--tag <tag>] [--id <id>] [--compare]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
+
+All insights persist to `specs/learnings.md` as `<spec-entry>` blocks.
+</purpose>
+
+<context>
+$ARGUMENTS — lens selection and scope flags.
+
+**Lens**: `--lens git` | `--lens decision` | `--lens all` (default: all)
+
+**Git lens flags**: `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare` (vs prior retro)
+**Decision lens flags**: `--phase N`, `--tag <tag>`, `--id <id>` (single decision by wiki/INS id)
+
+**Storage write**:
+- `.workflow/knowhow/KNW-retro-{date}.md` — unified report
+- `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
+- `specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
+
+**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE       — 解析 lens + flags                           PERSIST: —
+S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
+S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
+S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
+S_PERSIST     — 写 spec-entry 块                             PERSIST: specs/learnings.md
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_GIT         WHEN: lens == git OR all               DO: ensure .workflow/knowhow/ exists (mkdir -p)
+  → S_DECISION    WHEN: lens == decision                  DO: ensure .workflow/knowhow/ exists (mkdir -p)
+
+S_GIT:
+  → S_DECISION    WHEN: lens == all                          DO: A_GIT_ANALYSIS
+  → S_REPORT      WHEN: lens == git                          DO: A_GIT_ANALYSIS
+
+S_DECISION:
+  → S_REPORT      DO: A_DECISION_ANALYSIS
+
+S_REPORT:
+  → S_PERSIST     DO: write KNW-retro-{date}.md + .json
+
+S_PERSIST:
+  → END           DO: append insights to specs/learnings.md via `maestro spec add learning`
+  RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
+
+</transitions>
+
+<actions>
+
+### A_GIT_ANALYSIS
+
+**Parallel git commands**:
+```bash
+git log --since="{start}" --format="%H|%aN|%ae|%ai|%s" --shortstat
+git log --since="{start}" --format="COMMIT:%H|%aN" --numstat
+git log --since="{start}" --format="%at|%aN|%ai|%s" | sort -n
+git log --since="{start}" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+git shortlog --since="{start}" -sn --no-merges
+```
+Apply --author and --area filters.
+
+**Compute metrics**:
+
+| Metric | Formula |
+|--------|---------|
+| Test ratio | test_insertions / total_insertions * 100% |
+| Churn rate | files changed >2x / total unique files |
+| Sessions | Cluster commits by >2hr gaps in timestamps |
+| LOC/session-hour | net_loc / total_session_hours |
+
+**Per-author breakdown**: commits, LOC, top 3 areas, test ratio, session count.
+
+**Trend** (if --compare or prior KNW-retro-*.json exists): compute deltas, flag >20% changes.
+
+**Distill insights**: high churn files (instability), low test ratio areas (<20%), session patterns, area drift vs roadmap.
+
+### A_DECISION_ANALYSIS
+
+**Collect** (parallel):
+```bash
+maestro wiki search "decision" --json
+maestro wiki list --type spec --json
+git log --oneline --all --grep="decision\|chose\|decided" -20
+```
+Plus: architecture-constraints.md, phase context Locked/Deferred sections, specs/learnings.md.
+Apply --phase/--tag/--id filters.
+
+**Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
+
+**Evaluate** — spawn 3 Agents in single message:
+
+| Agent | Dimension | Grades |
+|-------|-----------|--------|
+| Technical Soundness | Implementation matches intent? Context changed? | sound / degraded / violated |
+| Cost Assessment | Complexity added? Coupling/debt? | low-cost / acceptable / expensive / debt-creating |
+| Alternative Hindsight | Right call with current knowledge? Reversible? | confirmed / questionable / should-revisit |
+
+**Classify lifecycle**:
+
+| Status | Criteria |
+|--------|---------|
+| Validated | sound + low/acceptable + confirmed |
+| Aging | sound + expensive + confirmed |
+| Questionable | degraded/violated + questionable |
+| Stale | any + should-revisit |
+| Reversed | code contradicts decision |
+
+**Recommend**: Aging → tech debt review, Questionable → create issue, Stale → refresh, Reversed → document reversal.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | Not in git repo (git lens) | Navigate to git repo |
+| E002 | No commits in window (git lens) | Increase --days |
+| E003 | No decisions found (decision lens) | Check wiki/specs or provide --id |
+| E004 | --id not found in wiki or knowhow | Verify the decision ID exists |
+| W002 | No prior retro for comparison | Skip trend; first retro = baseline |
+| W003 | One perspective agent failed | Proceed with available perspectives |
+</error_codes>
+
+<success_criteria>
+- [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
+- [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
+- [ ] Unified report + structured JSON written
+- [ ] specs/learnings.md appended with stable INS-ids
+</success_criteria>
+
+<next_step_routing>
+- Browse insights → `/manage-learn list --tag retro`
+- Deep dive churn → `/learn-follow <path>`
+- Fix test gaps → `/quality-auto-test <area>`
+- Investigate stale decision → `/learn-investigate <question>`
+</next_step_routing>

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

@@ -0,0 +1,124 @@
+---
+name: learn-second-opinion
+description: Get alternative perspectives — review, challenge, or consult
+argument-hint: "<target> [--mode review|challenge|consult]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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 `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): `invoke_skill("spec-load")` for conventions + `maestro wiki 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 specs/learnings.md      PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved                DO: read target content
+  → S_RESOLVE     WHEN: unresolvable                   DO: ask_user 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 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. ask_user → 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 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>