maestro-flow 0.5.36 → 0.5.37

package/.agents/skills/quality-refactor/SKILL.md

@@ -14,94 +14,94 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<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 → `invoke_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>
+<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 load --type spec --category coding` to load coding conventions. Apply conventions to all refactored code.
+2. **Review specs**: Run `maestro load --type spec --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 load --type knowhow --id <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 → `invoke_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/.agents/skills/quality-retrospective/SKILL.md

@@ -14,112 +14,112 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<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 `invoke_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 `invoke_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>
+<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 `invoke_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 `invoke_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>