maestro-flow 0.5.3 → 0.5.31

package/workflows/refactor.md

@@ -1,30 +1,21 @@
 # Refactor Workflow
 
-Systematically reduce tech debt through scope analysis, task planning, and reflection-driven execution. Each refactoring round records strategy, outcome, and adjustments. Existing tests must pass after every change.
+Reduce tech debt through scope analysis, task planning, and reflection-driven execution. Tests MUST pass after every change.
 
-Output: scratch/{YYYYMMDD}-refactor-{slug}/ with index.json + reflection-log.md + .task/ + .summaries/
-
----
-
-## Prerequisites
-
-- `.workflow/` directory initialized
-- Test suite available for affected scope (E002 if missing)
+Output: `scratch/{YYYYMMDD}-refactor-{slug}/` with index.json + reflection-log.md + .task/ + .summaries/
 
 ---
 
 ### Step 1: Parse Scope
 
-**Parse scope from $ARGUMENTS:**
-
-- Module path (e.g., "src/auth") -> scan that directory
-- Feature area (e.g., "authentication") -> search for related files
-- "all" -> full codebase scan
-- Empty -> prompt user:
-
-Prompt user for scope type: module path, feature area, or full codebase.
+| Input | Action |
+|-------|--------|
+| Module path (e.g., "src/auth") | Scan that directory |
+| Feature area (e.g., "authentication") | Search for related files |
+| "all" | Full codebase scan |
+| Empty | Prompt user |
 
-Generate slug from scope (lowercase, hyphens, max 40 chars). Set date = YYYYMMDD.
+Generate slug (lowercase, hyphens, max 40 chars). Set date = YYYYMMDD.
 
 ---
 
@@ -42,15 +33,11 @@ Write index.json: id, type="refactor", title, status="active", scope, plan (empt
 specs_content = maestro spec load --category coding
 ```
 
-Used in Step 3 to detect pattern violations against project conventions.
-
 ---
 
 ### Step 3: Scope Analysis
 
-**Analyze scope for tech debt:**
-
-Read all files in scope. Use specs_content to detect convention violations. Categorize issues:
+Read all files in scope. Use specs_content to detect convention violations. Categorize:
 
 1. **Duplication** - copy-paste patterns
 2. **Complexity** - long functions, deep nesting, high cyclomatic complexity
@@ -59,49 +46,40 @@ Read all files in scope. Use specs_content to detect convention violations. Cate
 5. **Dead code** - unused functions, unreachable branches
 6. **Pattern violations** - inconsistent with specs/ conventions
 
-Present category/count/severity summary table. Confirm with user before planning.
+Present summary table. Confirm with user before planning.
 
 ---
 
 ### Step 4: Plan Refactoring
 
-Write plan.json (scope, total_tasks, strategy="incremental", task IDs).
-
-For each issue, create `.task/TASK-{NNN}.json`: id, title, status=pending, type=refactor, category, description, read_first (files), files (path/action/target/change), convergence criteria, implementation steps, risk level.
+Write plan.json + `.task/TASK-{NNN}.json` per issue (id, title, status=pending, type=refactor, category, files, convergence criteria, risk level).
 
-Order: quick wins first, high risk last, dependencies respected. Update index.json plan fields.
+Order: quick wins first, high risk last, dependencies respected.
 
-Present plan to user: affected files, risk areas, dependency impacts. Ask approval/modifications/rejection.
+Present plan to user (affected files, risk areas, dependency impacts). Ask: approve / modify / reject.
 
 ---
 
 ### Step 5: Execute with Reflection
 
-**Execute each task with reflection tracking:**
-
-Initialize reflection-log.md (scope, timestamp).
-
 For each task:
-- **5a.** Implement the refactoring change.
-- **5b.** Run test suite (npm test / pytest / go test).
-- **5c.** Record in reflection-log.md: strategy, result, test status, adjustment needed, files changed.
-- **5d.** On test failure: revert, record, retry with adjusted strategy (max 2 retries). If still failing: mark "blocked", continue.
-- **5e.** Update task status (completed/blocked), write summary, update index.json execution and reflection fields.
+- **5a.** Implement the change
+- **5b.** Run test suite
+- **5c.** Record in reflection-log.md: strategy, result, test status, adjustment, files changed
+- **5d.** On test failure: revert, retry with adjusted strategy (max 2 retries). Still failing → mark "blocked"
+- **5e.** Update task status, write summary, update index.json
 
 ---
 
 ### Step 6: Final Verification
 
-Run full test suite. Record final state in reflection-log.md: test results, tasks completed/blocked, key learnings.
+Run full test suite. Record final state in reflection-log.md.
 
 ---
 
 ### Step 7: Complete
 
-Update index.json: status="completed", execution counts, reflection rounds + strategy_adjustments.
-
-Present summary: tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings.
-List artifacts: reflection-log.md, .summaries/.
+Update index.json: `status="completed"`.
 
-If regressions found: list affected tests and suggest quality-debug.
+Present: tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings. If regressions: list affected tests, suggest quality-debug.
 

package/workflows/retrospective.md

@@ -1,17 +1,6 @@
 # Retrospective Workflow
 
-Multi-lens 复盘 of completed phase artifacts. Consumes existing execution outputs (verification.json, review.json, issues.jsonl, .summaries/, state.json, uat.md, plan.json) and routes distilled insights into the spec / note / issue / knowhow stores.
-
-This is a **post-execution analysis** workflow. It reads only — until the routing stage, where it writes new spec stubs, issue rows, memory entries, and knowhow entries. It **does not modify existing phase artifacts**; it writes to the spec / issue / knowhow stores as configured outputs (new entries appended; pre-existing phase outputs such as verification.json, review.json, uat.md, .summaries/ are never altered).
-
----
-
-## Prerequisites
-
-- `.workflow/` initialized (`.workflow/state.json` exists)
-- At least one completed phase (via artifact registry in state.json)
-- Target phase has been executed (has `.task/` and `.summaries/`)
-- `maestro delegate` available (used for the four lens analyses via Agent calls)
+Multi-lens 复盘 of completed phase artifacts. Read-only until routing stage, where it writes to spec / issue / knowhow stores. NEVER modifies existing phase artifacts.
 
 ---
 
@@ -102,12 +91,10 @@ Archive existing retrospective.{json,md} to "{candidate.phase_dir}/.history/retr
 
 ## Stage 3: load_artifacts (per phase)
 
-For each selected phase (using `candidate.phase_dir` resolved in Stage 2), build the in-memory artifacts bundle:
-
 ```
-artifact_dir = candidate.phase_dir  (resolved from artifact registry)
+artifact_dir = candidate.phase_dir
 
-Load artifacts bundle from artifact_dir:
+Load artifacts bundle:
   index           ← {artifact_dir}/index.json
   state           ← .workflow/state.json
   plan            ← {artifact_dir}/plan.json
@@ -148,9 +135,7 @@ delta = { vs_phase, tasks_completed, gaps_found, issues_opened, rework_iteration
 
 ## Stage 4: multi_lens_analysis
 
-Spawn one Agent per active lens **in parallel** (single message, multiple Agent calls). Each agent receives the artifacts bundle as a structured context block in its prompt and returns JSON.
-
-**All agent calls use `run_in_background: false`** (subagents cannot receive hook callbacks).
+Spawn one Agent per active lens **in parallel** (`run_in_background: false`). Each returns JSON.
 
 ### Lens registry
 
@@ -248,43 +233,31 @@ Return ONLY a single JSON object, no prose, matching this schema:
 
 ### Spawn pattern
 
-Spawn all active lenses in parallel as `general-purpose` Agents (run_in_background: false), each receiving the rendered lens prompt template.
-
-Collect results into `lens_results = { technical, process, quality, decision }`. If any lens fails, log W001 and proceed with successful lenses.
+Spawn all lenses in parallel. Collect into `lens_results`. If any fails, log W001, proceed with successful lenses.
 
 ---
 
 ## Stage 5: synthesize
 
-Merge lens results into the canonical retrospective record.
-
 ### Generate insight IDs
 
-Assign `INS-{8 lowercase hex}` per insight using stable hash of `phase_num + lens + title` (idempotent across re-runs).
+`INS-{8 lowercase hex}` via stable hash of `phase_num + lens + title` (idempotent).
 
 ### Build retrospective.json
 
-Assemble the canonical record with structure: `{ phase, phase_slug, phase_title, retrospected_at, lenses_run, metrics, delta, findings_by_lens, distilled_insights, routing_recommendations, tweetable }`. See full schema in [Schemas](#retrospectivejson) section. Each insight's `routed_id` is null here (populated in Stage 6).
+Structure: `{ phase, phase_slug, phase_title, retrospected_at, lenses_run, metrics, delta, findings_by_lens, distilled_insights, routing_recommendations, tweetable }`. Each insight's `routed_id` is null (populated in Stage 6).
 
-### Build retrospective.md (human-readable)
+### Build retrospective.md
 
-Render a markdown report with these sections:
-1. **Header**: tweetable quote, phase metadata, lenses run
-2. **Metrics table**: all metrics fields from Stage 3
-3. **Delta table** (if --compare): ± values for key metrics
-4. **Findings by Lens**: for each lens → numbered wins, challenges, watch_patterns with evidence_refs
-5. **Distilled Insights**: per insight → category, lens, confidence, tags, routed_to, summary, evidence refs
-6. **Routing Recommendations table**: insight_id | target | rationale
+Sections: Header (tweetable, metadata) → Metrics table → Delta table (if --compare) → Findings by Lens → Distilled Insights → Routing Recommendations.
 
-Write both `{artifact_dir}/retrospective.json` and `{artifact_dir}/retrospective.md`.
+Write both to `{artifact_dir}/`.
 
 ---
 
 ## Stage 6: route_outputs
 
-**Skip entirely if `--no-route` flag is set.**
-
-For each routing recommendation, prompt the user (unless `--auto-yes`) and execute the routing action.
+**Skip if `--no-route`.** Prompt user per recommendation (skip if `--auto-yes`).
 
 ### Display routing table
 
@@ -326,8 +299,6 @@ insight.routed_id = "{target_file}#INS-{INS_id}"
 
 #### Target: note
 
-Reuse the existing `manage-learn` skill in tip mode — do not duplicate the learning pipeline.
-
 ```
 Invoke manage-learn tip with:
   text = "[Retro phase {NN} / {lens}] {insight.title}: {insight.summary}"
@@ -371,7 +342,7 @@ After all routings complete, re-write `retrospective.json` with the `routed_id`
 
 ## Stage 7: persist_insights
 
-Append every distilled insight (regardless of routing target, including `routed_to: "none"`) to the knowhow store.
+Append every distilled insight (including `routed_to: "none"`) to the knowhow store.
 
 ### Bootstrap
 
@@ -400,37 +371,17 @@ For each insight in `distilled_insights`, append a `<spec-entry>` to `.workflow/
 </spec-entry>
 ```
 
-WikiIndexer auto-indexes each entry — no manual index update required.
-
-### Backward-compat append to specs/learnings.md
-
-Append learnings to `.workflow/specs/learnings.md` (shared with milestone-complete's learning extraction) using `<spec-entry>` closed-tag format:
-
-```
-Append each insight to .workflow/specs/learnings.md as <spec-entry> with:
-  category="learning", keywords (3-5 extracted), date, source="retrospective"
-  Body: title, summary, phase/lens/INS_id metadata
-
-Create file with roles frontmatter + "## Entries" header if it does not exist.
-```
+Also append each insight to `.workflow/specs/learnings.md` as `<spec-entry>` with `category="learning"` (backward compat with milestone-complete).
 
 ---
 
 ## Stage 8: next_step
 
-Print confirmation banner and route the user.
+Print: phase, lenses run, insight count, routing summary, output paths.
 
-```
-Print banner: phase, lenses run, insight count, routing summary (spec/note/issue/knowhow counts with target paths), output file paths.
-
-Suggested next steps:
-  manage-status                              — Review project state
-  manage-issue list --source retrospective   — Triage created issues
-  manage-learn list                          — Browse the insights library
-  maestro-milestone-audit                    — Audit milestone if all phases done
-```
+Next steps: `manage-status` | `manage-issue list --source retrospective` | `manage-learn list` | `maestro-milestone-audit`
 
-If `mode == "range"` or `--all`, loop Stages 3-8 per phase, then print aggregate batch summary (phases retrospected, total insights/specs/notes/issues).
+If range/all mode: loop Stages 3-8 per phase, then print aggregate summary.
 
 ---