maestro-flow-one 0.2.33 → 0.2.35

package/maestro-flow/commands/quality/refactor.md

@@ -1,67 +1,105 @@
----
-name: quality-refactor
-description: Use when accumulated tech debt needs systematic identification and safe reduction
-argument-hint: "[<scope>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Plan and execute targeted refactoring with safety guarantees through analysis, planning, and reflection-driven iteration. Identifies affected files and dependencies, creates a refactoring plan, confirms with the user before execution, then applies changes with test verification after every modification to ensure zero regressions. Each refactoring round records strategy, outcome, and adjustments in reflection-log.md.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/refactor.md
-</required_reading>
-
-<context>
-Scope: $ARGUMENTS (required)
-- Module path: "src/auth" - specific directory
-- Feature area: "authentication" - conceptual scope
-- "all" - full codebase scan
-
-If not provided, prompt user for scope.
-
-### Pre-load context (before refactoring)
-
-1. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Apply conventions to all refactored code.
-2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality gate for refactored code.
-3. **Role Knowledge**:
-   - Browse: `maestro search --category coding`
-   - Identify task-relevant entries, then load: `maestro wiki load <id1> [id2...]`
-4. All are optional — proceed without if unavailable.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/refactor.md' completely.
-
-**Knowledge inquiry on completion:**
-After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
-
-**Next-step routing on completion:**
-- All tests pass → `/quality-sync` (update codebase docs)
-- Test failures after refactor → `/quality-debug "test failures after refactor in {scope}"`
-- No test suite available → `/quality-auto-test {phase}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Refactoring scope/description required | Prompt user for module path, feature area, or "all" |
-| E002 | error | Test suite not available for affected area | Suggest creating tests first, or proceed with manual verification |
-| W001 | warning | Partial test coverage for affected area | Note uncovered areas, proceed with extra caution |
-</error_codes>
-
-<success_criteria>
-- [ ] Refactoring plan created and confirmed by user
-- [ ] Changes implemented according to plan
-- [ ] All tests pass after refactoring
-- [ ] No regressions introduced
-- [ ] reflection-log.md written with strategy and outcomes
-</success_criteria>
+---
+name: quality-refactor
+description: Use when accumulated tech debt needs systematic identification and safe reduction
+argument-hint: "[<scope>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Targeted refactoring with safety guarantees: plan → confirm → execute with test verification per change → reflection-log.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/refactor.md
+</required_reading>
+
+<context>
+Scope: $ARGUMENTS (required)
+- Module path: "src/auth" - specific directory
+- Feature area: "authentication" - conceptual scope
+- "all" - full codebase scan
+
+If not provided, prompt user for scope.
+
+### Pre-load context (before refactoring)
+
+1. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Apply conventions to all refactored code.
+2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality gate for refactored code.
+3. **Role Knowledge**:
+   - Browse: `maestro search --category coding`
+   - Identify task-relevant entries, then load: `maestro wiki load <id1> [id2...]`
+4. All are optional — proceed without if unavailable.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/refactor.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Analysis → Plan**
+- REQUIRED: Affected files and dependencies identified.
+- REQUIRED: Refactoring plan created with specific changes.
+- BLOCKED if missing: cannot refactor without identified targets.
+
+**GATE 2: Plan → Execution**
+- REQUIRED: User confirmed refactoring plan.
+- BLOCKED if not confirmed: do not apply changes without approval.
+
+**GATE 3: Execution → Completion**
+- REQUIRED: All changes applied with test verification per modification.
+- REQUIRED: Zero regressions (all tests pass).
+- REQUIRED: reflection-log.md written with strategy and outcomes.
+- BLOCKED if tests fail: fix regressions before completing.
+
+**Knowledge inquiry on completion:**
+After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes → `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All tests pass | `/quality-sync` (update codebase docs) |
+| Test failures after refactor | `/quality-debug "test failures after refactor in {scope}"` |
+| No test suite available | `/quality-auto-test {phase}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Refactoring scope/description required | Prompt user for module path, feature area, or "all" |
+| E002 | error | Test suite not available for affected area | Suggest creating tests first, or proceed with manual verification |
+| W001 | warning | Partial test coverage for affected area | Note uncovered areas, proceed with extra caution |
+</error_codes>
+
+<success_criteria>
+- [ ] Refactoring plan created and confirmed by user
+- [ ] Changes implemented according to plan
+- [ ] All tests pass after refactoring
+- [ ] No regressions introduced
+- [ ] reflection-log.md written with strategy and outcomes
+</success_criteria>

package/maestro-flow/commands/quality/retrospective.md

@@ -1,77 +1,123 @@
----
-name: quality-retrospective
-description: Use after completing a phase to extract lessons, patterns, and improvement opportunities
-argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/retrospective.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
-- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
-- @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
-- @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-Modes (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
-</context>
-
-<execution>
-Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invariants:
-
-1. **Read-only until Stage 6** — Stages 1–5 must not write anything except the in-memory retrospective record.
-2. **Parallel lens dispatch** — Stage 4 spawns one Agent per active lens in a single message (multiple Agent tool calls). All agents use `subagent_type: "general-purpose"` and `run_in_background: false`.
-3. **Match canonical issues schema** — Stage 6 issue routing must produce rows that pass `jq` parsing and match the schema in `workflows/issue.md` Step 4 exactly (status `"open"`, full `issue_history` entry, all required fields).
-4. **Reuse `manage-knowhow-capture tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`.
-5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
-6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
-7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{artifact_dir}/.history/` with a timestamp suffix first.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
-| E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
-| E003 | error | `--compare` requires a single phase argument | parse_input |
-| E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
-| E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
-| W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
-| W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
-| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS id; fell back to direct write | route_outputs |
-| W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly resolved (scan / single / range / all)
-- [ ] At least one phase selected and validated (status == "completed", artifacts exist)
-- [ ] All requested lens agents returned valid JSON, or W001 logged for partial coverage
-- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights, routing_recommendations
-- [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
-- [ ] Each insight has a stable `INS-{8hex}` id
-- [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
-- [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
-- [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
-- [ ] Note tips (if any) created via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`
-- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
-- [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
-- [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-knowhow list` to browse the knowhow library
-</success_criteria>
+---
+name: quality-retrospective
+description: Use after completing a phase to extract lessons, patterns, and improvement opportunities
+argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Post-execution retrospective (复盘): four parallel lenses (technical/process/quality/decision) → distill insights → route to spec/knowhow/issue stores.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/retrospective.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
+- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
+- @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
+- @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Modes (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Input → Lens Analysis** (Stages 1-3 → Stage 4)
+- REQUIRED: Mode resolved (scan/single/range/all) and phases validated.
+- REQUIRED: At least one phase selected with status=completed and existing artifacts.
+- REQUIRED: Read-only — no file writes in Stages 1-3.
+- BLOCKED if no valid phases: E004/E005.
+
+**GATE 2: Lens Analysis → Routing** (Stages 4-5 → Stage 6)
+- REQUIRED: All requested lens agents returned valid JSON (or W001 logged for partial).
+- REQUIRED: Insights distilled with stable `INS-{8hex}` IDs.
+- REQUIRED: Archive existing `retrospective.{md,json}` before overwrite.
+- BLOCKED if all lens agents failed: cannot synthesize without results.
+
+**GATE 3: Routing → Completion** (Stage 6 → Stages 7-8)
+- REQUIRED: `retrospective.json` written with metrics, findings, insights, routing.
+- REQUIRED: `retrospective.md` written (human-readable).
+- REQUIRED: Issue rows match canonical `issues.jsonl` schema (status "open", full fields).
+- REQUIRED: Note tips routed via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`.
+- BLOCKED if routing incomplete: finish all write operations before reporting.
+
+### Execution Constraints
+
+- **Parallel lens dispatch**: Stage 4 spawns one Agent per active lens in a single message.
+- **Stable IDs**: `INS-{8 hex}` from `hash(phase_num + lens + title)` — re-runs do not duplicate.
+- **No source modification**: Never modify verification.json, review.json, plan.json.
+- **Backward-compat**: Append to `.workflow/specs/learnings.md` only if file already exists.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
+| E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
+| E003 | error | `--compare` requires a single phase argument | parse_input |
+| E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
+| E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
+| W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
+| W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
+| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS id; fell back to direct write | route_outputs |
+| W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / single / range / all)
+- [ ] At least one phase selected and validated (status == "completed", artifacts exist)
+- [ ] All requested lens agents returned valid JSON, or W001 logged for partial coverage
+- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights, routing_recommendations
+- [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
+- [ ] Each insight has a stable `INS-{8hex}` id
+- [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
+- [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
+- [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
+- [ ] Note tips (if any) created via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`
+- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
+- [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
+- [ ] Confirmation banner displays routing counts and next-step suggestions
+</success_criteria>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Insights routed | `/manage-status` |
+| Issues created | `/manage-issue list --source retrospective` |
+| Knowhow captured | `/manage-knowhow list` |
+| More phases to review | `/quality-retrospective --all` |
+</completion>