maestro-flow 0.4.12 → 0.4.13

package/workflows/issue-gaps-analyze.md

@@ -1,5 +1,7 @@
 # Workflow: Issue Gaps Analysis
 
+> **CLI variants**: see `issue-gaps-analyze.codex.md` for codex-specific notes (CSV-wave variant using `spawn_agents_on_csv`).
+
 Root cause analysis for issues using CLI exploration and codebase context gathering.
 Supports single issue (ISS-ID) or batch (all open/registered) with classification and parallel analysis.
 Produces analysis records in issues.jsonl and context.md for downstream `plan --gaps`.

package/workflows/learn.md

@@ -8,7 +8,7 @@ Storage:
 
 **Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
 
-This workflow does NOT spawn agents or call CLI tools. It is a thin file operation: parse → infer → append → confirm.
+This workflow does NOT spawn sub-agents; it may invoke maestro CLI utilities (e.g. `maestro wiki search`, `maestro wiki list`) for list/search subcommands. The core capture flow is a thin file operation: parse → infer → append → confirm.
 
 ---
 

package/workflows/maestro-chain-execute.md

@@ -4,235 +4,17 @@
 > Both maestro and ralph sessions now use `maestro-ralph-execute` for step execution.
 > This file is kept for reference only and will be removed in a future version.
 
-Original description: Upgraded version of maestro's original direct execution strategy.
-Reads session status.json, loops through steps with per-step engine selection,
-context propagation, post-step Gemini analysis, and error handling.
-Dual-track progress: status.json (persistence + resume) and TodoWrite (UI visibility).
+## Migration
 
-**Prerequisites:**
-- Session directory with valid status.json (status: "running", pending steps)
-- TodoWrite initialized by selection workflow (Step 3h) with `MAESTRO:{chain_name}:` prefix
-- $SESSION_PATH passed from maestro.md dispatch
+- Caller dispatching from `maestro.md` → use `Skill({ skill: "maestro-ralph-execute" })`
+- Resume from session → `Skill({ skill: "maestro-ralph-execute" })` (auto-discovers latest running session via `.workflow/.maestro/*/status.json`)
 
-## Step 1: Load Session
+## References
 
-Read status.json from `$SESSION_PATH`.
+- `~/.maestro/workflows/maestro.md` — coordinator that creates sessions and dispatches to the unified executor
+- `~/.maestro/workflows/maestro-ralph-execute.md` — current canonical executor (handles both maestro static chains and ralph adaptive chains)
 
-Extract: `session_id`, `chain_name`, `steps[]`, `context`, `auto_mode`, `exec_mode`, `cli_tool`, `gemini_session_id`.
-
-Set `$STEP_INDEX` = `current_step` (first pending step).
-
-Validate: `status == "running"` and at least one pending step exists.
-
-**TodoWrite sync (resume mode):** If TodoWrite has no `MAESTRO:{chain_name}:` entries (e.g., fresh context after `/maestro -c`), rebuild from status.json:
-
-```javascript
-const todos = steps.map((step, i) => ({
-  content: `MAESTRO:${chain_name}: [${i + 1}/${steps.length}] ${step.skill}`,
-  status: step.status === 'completed' ? 'completed'
-        : i === $STEP_INDEX ? 'in_progress'
-        : 'pending'
-}));
-TodoWrite({ todos });
-```
-
-Display banner:
-
-```
-============================================================
-  CHAIN EXECUTOR
-============================================================
-  Session: {session_id}
-  Chain:   {chain_name}
-  Steps:   {completed}/{total} done, starting from step {$STEP_INDEX}
-  Auto:    {auto_mode}
-  Exec:    {exec_mode}
-```
-
-## Step 2: Context & Argument Assembly
-
-Initialize context object from `status.json.context`:
-
-```
-context = {
-  current_phase,    // from status.json.context or top-level phase
-  user_intent,      // from status.json.context or top-level intent
-  issue_id,
-  milestone_num,
-  spec_session_id,
-  scratch_dir
-}
-```
-
-### assembleArgs(step)
-
-```
-1. Substitute placeholders in step.args:
-   {phase} → context.current_phase
-   {description} → context.user_intent (chainMap uses {description} as alias for user intent)
-   {issue_id} → context.issue_id
-   {spec_session_id} → context.spec_session_id
-   {scratch_dir} → context.scratch_dir
-   {milestone_num} → context.milestone_num
-
-2. In auto_mode, append per-command flag if not already present:
-   maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-impeccable → -y
-   maestro-plan → --auto
-   quality-test → --auto-fix
-   quality-retrospective → --auto-yes
-
-3. Shell-escape strings with single quotes for CLI delegate calls.
-```
-
-## Step 3: Step Loop
-
-For each step starting at `$STEP_INDEX`:
-
-### 3a. Select engine & display banner
-
-Read `step.engine` from status.json (pre-computed by selection workflow Step 3e).
-
-If `step.engine` is missing or null, fallback to auto selection:
-```
-  CLI: maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm,
-       maestro-roadmap, maestro-impeccable, quality-refactor
-  Internal: everything else (current-session Skill() call)
-```
-
-Display: `[Step {N}/{total}] /{step.skill} [{engine}] — {args}`
-
-Update status.json: step `status = "running"`, `engine`, `started_at`.
-
-Context window hint:
-- Step >= 4 and not autoYes: hint user about `/maestro -c` for fresh context resume.
-- autoYes and step >= 5: log warning to status.json.
-
-### 3b. Execute (engine-dependent)
-
-**Internal engine** — current-session Skill() call (synchronous, visible):
-
-```
-Skill({ skill: step.skill, args: assembledArgs })
-```
-
-**CLI engine** — template-driven, async, context-isolated:
-
-```
-1. Load template ~/.maestro/templates/cli/prompts/coordinate-step.txt
-2. Build analysisHints from previous step's next_step_hints
-   (prompt_additions, cautions, context_to_carry)
-3. Substitute template placeholders:
-   {{COMMAND}}, {{ARGS}}, {{STEP_N}}, {{AUTO_DIRECTIVE}},
-   {{CHAIN_NAME}}, {{ANALYSIS_HINTS}}
-4. Run:
-   Bash(maestro delegate "<prompt>" --to {cli_tool} --mode write,
-        run_in_background: true, timeout: 600000)
-5. **STOP** — wait for background callback
-```
-
-### 3c. Parse output & update context
-
-Scan step output for context propagation:
-
-```
-PHASE: N         → context.current_phase
-SPEC-xxx         → context.spec_session_id
-scratch_dir: path → context.scratch_dir
-```
-
-CLI: capture `exec_id` from stderr `[MAESTRO_EXEC_ID=<id>]`.
-
-**Persist context back to status.json** after each step — write updated `context` field and `current_step`. This enables resume via `/maestro -c`.
-
-### 3d. Handle result & sync dual tracking
-
-**Success:**
-1. status.json: mark step `status = "completed"`, set `completed_at`
-2. TodoWrite: mark current step `completed`, next step `in_progress`
-3. CLI: save output to `step-{N}-output.txt` in session directory
-
-```javascript
-// Dual-track update after each step
-function updateDualTracking(stepIndex, total, chain_name, result) {
-  // 1. status.json — already updated in 3c
-  // 2. TodoWrite — sync UI
-  const todos = getAllTodos().map(todo => {
-    if (!todo.content.startsWith(`MAESTRO:${chain_name}:`)) return todo;
-    const num = extractStepNum(todo.content);
-    if (num === stepIndex + 1) return { ...todo, status: result };
-    if (num === stepIndex + 2 && result === 'completed') return { ...todo, status: 'in_progress' };
-    return todo;
-  });
-  TodoWrite({ todos });
-}
-```
-
-**Failure:**
-1. status.json: mark step `"failed"` or `"skipped"`
-2. TodoWrite: mark step `completed` (skipped) or keep `in_progress` (retry)
-3. `auto_mode` → retry once, then skip
-4. Interactive → offer: Retry (max 2) / Skip / Abort
-5. Abort → status.json `status = "aborted"`, TodoWrite mark remaining `pending`, display resume hint: `/maestro -c`
-
-### 3e. Post-step analysis (CLI steps only)
-
-Skip if: step failed/skipped, or `engine == 'internal'`.
-
-Delegate to gemini (analysis mode, `--resume` if `gemini_session_id` exists) with prompt containing:
-- Step command, args, chain name, intent
-- Last 200 lines of step output
-- Next step info (command, args) if any
-
-Expected JSON response:
-
-```json
-{
-  "quality_score": "<0-100>",
-  "execution_assessment": {
-    "success": "<bool>",
-    "completeness": "<full|partial|minimal>",
-    "key_outputs": [],
-    "missing_outputs": []
-  },
-  "issues": [
-    { "severity": "critical|high|medium|low", "description": "" }
-  ],
-  "next_step_hints": {
-    "prompt_additions": "<extra context for next step>",
-    "cautions": ["<things to watch out for>"],
-    "context_to_carry": "<key facts from this step>"
-  },
-  "step_summary": ""
-}
-```
-
-On callback:
-1. Capture gemini `exec_id` → store as `gemini_session_id` in status.json for session continuity.
-2. Store analysis in `step_analyses[]` and `step-{N}-analysis.json` in session directory.
-3. Advance to next step (**3a**).
-
-## Step 4: Completion Report
-
-Finalize dual tracking:
-1. status.json: `status = "completed"`
-2. TodoWrite: all steps marked `completed` (or `completed` for skipped)
-
-```
-============================================================
-  MAESTRO SESSION COMPLETE
-============================================================
-  Session:  {session_id}
-  Chain:    {chain_name}
-  Steps:    {completed}/{total} completed
-  Phase:    {context.current_phase}
-
-  Results:
-    [✓] 1. maestro-plan — completed [cli] (quality: 85/100)
-    [✓] 2. maestro-verify — completed [internal]
-    [—] 3. quality-review — skipped [internal]
-
-  CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
-
-  Next: /maestro continue | /manage-status
-============================================================
-```
+The unified executor preserves all behaviour previously documented here:
+status.json persistence, TodoWrite dual-tracking, per-step engine selection (`Skill` vs `CLI`),
+context propagation across steps, post-step Gemini analysis for CLI steps,
+and retry/skip/abort on failure.

package/workflows/maestro.md

@@ -357,6 +357,7 @@ const chainMap = {
   'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'brainstorm_visualize': [{ cmd: 'brainstorm-visualize', args: '"{description}"' }],
   'impeccable-build':       [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'impeccable-driven':      [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }],

package/workflows/milestone-complete.md

@@ -15,9 +15,9 @@ Archive completed milestone, move artifacts to history, and prepare for next.
 2. Check milestone audit status:
    - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
    - If no audit report:
-     - WARN: "No audit report found. Run `/maestro-milestone-audit` first."
-     - Ask user: "Complete without audit?"
-     - If NO → exit
+     - ERROR E004: "No audit report found. Audit is a required hard contract — cannot complete without it."
+     - Guidance: "Run `/maestro-milestone-audit` first, then re-run this command."
+     - Exit (skipping audit is not permitted)
    - If verdict is FAIL: ERROR E002
 
 3. Verify all milestone artifacts have status "completed" → ERROR E003 if any incomplete (list ids and statuses)

package/workflows/milestone-release.md

@@ -0,0 +1,82 @@
+# Workflow: milestone-release
+
+Bump version, generate changelog, and tag the current milestone for release.
+
+> **STATUS: PLACEHOLDER** — minimal skeleton referenced by `maestro-milestone-release.md`.
+> Full release pipeline is TODO. Do not invoke until contents below are fleshed out.
+
+---
+
+## Arguments
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<milestone>` | Milestone id from `.workflow/state.json` `milestones[]` | current_milestone |
+| `--bump <level>` | Semver bump: `major` \| `minor` \| `patch` | `minor` |
+| `--dry-run` | Preview changes without writing | `false` |
+
+---
+
+## Step 1: Validation
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from `$ARGUMENTS` or `current_milestone`).
+   - If no milestone: ERROR E001.
+2. Verify milestone is **completed**:
+   - Read `.workflow/milestones/{milestone}/audit-report.md` — verdict must be `PASS`.
+   - If missing or non-PASS: ERROR E002 with guidance to run `/maestro-milestone-complete` first.
+3. Read package manifest (`package.json` / `pyproject.toml` / etc.) — locate current version. TODO: multi-manifest detection.
+
+---
+
+## Step 2: Version Bump
+
+1. Compute next version from `--bump` level (semver). TODO: prerelease/build metadata handling.
+2. Update manifest file in place. If `--dry-run`: print diff and exit.
+
+---
+
+## Step 3: Changelog Generation
+
+1. Read milestone audit report + retrospective insights (`.workflow/milestones/{milestone}/`).
+2. Render `CHANGELOG.md` entry — header `## [vX.Y.Z] - YYYY-MM-DD`, body grouped by `Added / Changed / Fixed / Removed`.
+3. TODO: integrate with `quality-retrospective` output for richer narrative.
+
+---
+
+## Step 4: Tag and Commit
+
+1. Stage updated manifest + `CHANGELOG.md`.
+2. Commit: `chore(release): vX.Y.Z — {milestone}`.
+3. Create annotated git tag `vX.Y.Z`.
+4. TODO: optionally push tag (`--push` flag).
+
+---
+
+## Outputs
+
+| Artifact | Status |
+|----------|--------|
+| Updated manifest version | written |
+| `CHANGELOG.md` entry | appended |
+| Git tag `vX.Y.Z` | created locally (not pushed) |
+
+---
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| E001 | No milestone resolvable |
+| E002 | Milestone not completed / audit not PASS |
+| E003 | Manifest file not found |
+| E004 | Git working tree dirty (uncommitted changes block tagging) |
+
+---
+
+## TODO (placeholder gaps)
+
+- Multi-package monorepo support.
+- Push tag + GitHub release integration.
+- Roll-back path on failed tag.
+- Wire to `manage-knowhow-capture` for release-note capture.

package/workflows/plan.md

@@ -166,12 +166,12 @@ When `--tdd` is active:
    - Map `insights[].summary` to implementation guidance for relevant tasks
    - These replace the need for a separate analyze step when brainstorm already provided sufficient role analysis
 
-5. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
+6. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
    - Exploration angles (1-4 based on complexity): architecture, implementation, integration, risk
    - Spawn 1-4 `cli-explore-agent` in parallel, each with phase goal + success_criteria + one angle
    - Output: `.process/exploration-{angle}.json`, `.process/explorations-manifest.json`, `.process/context-package.json`
 
-5b. **CLI supplementary context** (runs in parallel with step 5, skip if `--gaps` or no CLI tools enabled)
+6b. **CLI supplementary context** (runs in parallel with step 6, skip if `--gaps` or no CLI tools enabled)
    ```
    IF no CLI tools enabled: skip
 
@@ -188,7 +188,7 @@ When `--tdd` is active:
    ```
    **On callback:** Parse result, merge into explorationContext as `cli_context` field. Planner uses patterns for task `read_first[]`, dependencies for wave ordering, conflict_risks for collision detection.
 
-6. **Gap-mode context** (if `--gaps`)
+7. **Gap-mode context** (if `--gaps`)
 
    Gap sources (in priority order, first non-empty wins, then additionals merged):
    - **Primary**: `.workflow/issues/issues.jsonl` — filter by phase_ref + status in ["registered","diagnosed"], mark as "planning"
@@ -298,7 +298,7 @@ Every TASK-*.json MUST include these fields — they are NOT optional:
 
 ### Gap Mode (`--gaps`)
 
-Spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 6), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
+Spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 7), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
 
 Planner: for each gap emit one task — `type: "fix"`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-verifiable), `issue_id` (if source == "issue"); assign IDs and waves; build plan.json.
 

package/workflows/retrospective.md

@@ -2,7 +2,7 @@
 
 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 never modifies existing phase artifacts.
+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).
 
 ---
 

package/workflows/roadmap.md

@@ -102,7 +102,7 @@ Follow roadmap-common.md **Roadmap Write Logic** (overwrite vs edit rules, state
 ## Step 6: Handoff
 
 Display summary (strategy, phase count, milestones, roadmap path) and offer next steps:
-- `maestro-init` — set up project (if not yet initialized)
+- `maestro-blueprint` — generate formal spec package for the roadmap (if heavier spec is needed)
 - `maestro-plan 1` — plan first phase
 - `maestro-brainstorm 1` — explore first phase ideas
 - `manage-status` — view project dashboard

package/workflows/spec-generate.md

@@ -11,6 +11,8 @@ brainstorm (optional) → init (REQUIRED) → spec-generate → plan → execute
 Alternative light path: init → roadmap (light mode) → plan (skip spec-generate)
 ```
 
+> **Relation to blueprint**: `spec-generate` is the full-pipeline superset of `blueprint` (adds P7 roadmap stage on top of P0–P6 spec chain). Use `blueprint` when only specs are needed; use `spec-generate` when downstream `roadmap → plan` execution is intended.
+
 ## Architecture
 
 ```

package/workflows/specs-add.md

@@ -1,4 +1,9 @@
-# Workflow: specs-add
+---
+name: spec-add
+alias: spec-add
+---
+
+# Workflow: spec-add
 
 Add a `<spec-entry>` closed-tag entry to a single target spec file by category.
 

package/workflows/specs-load.md

@@ -1,4 +1,9 @@
-# Workflow: specs-load
+---
+name: spec-load
+alias: spec-load
+---
+
+# Workflow: spec-load
 
 Load spec files filtered by category. Supports project, global, team, and personal scopes.
 

package/workflows/specs-setup.md

@@ -1,4 +1,9 @@
-# Workflow: specs-setup
+---
+name: spec-setup
+alias: spec-setup
+---
+
+# Workflow: spec-setup
 
 System specs initialization -- scan project structure, detect tech stack, generate convention files.
 

package/workflows/sync.md

@@ -47,6 +47,19 @@ Read .workflow/codebase/doc-index.json
 Extract: components[], features[], requirements[], architecture_decisions[]
 ```
 
+**Degradation path — doc-index.json missing:**
+
+```
+If .workflow/codebase/doc-index.json does NOT exist:
+  1. Emit WARNING: "doc-index.json missing — sync cannot perform impact analysis."
+  2. Prompt user with two choices:
+     (a) Run `/manage-codebase-rebuild` to build doc-index, then re-run sync (recommended)
+     (b) Fall back to git-diff-only mode: skip Steps 3-5, emit raw changed-file
+         list from Step 2 as the sync output (no component/feature mapping)
+  3. If user picks (b): set DEGRADED_MODE = true and continue with git diff only.
+  4. If user picks (a) or no answer: exit with code E002.
+```
+
 ### Step 4: Impact Chain Traversal
 
 For each `changed_file` in `changed_files[]`:

package/workflows/tools-spec.md

@@ -1,5 +1,9 @@
 # Tool Spec Reference
 
+<reference>
+Tool specs are a **subtype of knowhow** (`tool: true` frontmatter on knowhow documents). For the full knowhow data model, lifecycle, and management commands, see `knowhow.md`. This file documents only the tool-specific subset.
+</reference>
+
 Shared reference for tool spec registration and execution commands.
 
 ## Storage

package/workflows/ui-design.md

@@ -6,9 +6,9 @@ User reviews via compare.html, selects winner(s), design solidified as code refe
 
 Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
 
-> **Note:** This is the full self-contained pipeline. When ui-ux-pro-max skill is available,
-> the command routes to `ui-style.md` instead (lightweight delegation).
-> This workflow runs when the skill is absent or `--full` is explicitly requested.
+> **Note:** This is the primary implementation. When the `ui-ux-pro-max` skill is available,
+> the command may delegate to `ui-style.md` for a lightweight path. This workflow is the
+> fallback when the skill is unavailable, and is also used when `--full` is explicitly requested.
 
 ---
 

package/workflows/wiki-manage.md

@@ -44,6 +44,8 @@ Run in parallel: `maestro wiki health`, `list --json`, `orphans`, `hubs --top 5`
 
 Display: health score, entry counts by type, broken links, orphan count, top hubs. Include health status message and quick-action commands (`/wiki-connect --fix`, `/wiki-digest`, `/manage-wiki cleanup --fix`, `maestro wiki graph`).
 
+> **Scope split (complementary, not conflicting):** `/wiki-connect --fix` repairs/augments `related` links between existing entries (no deletion). `/manage-wiki cleanup --fix` deletes/flags orphans and removes broken-link entries from frontmatter. Run `wiki-connect` first to maximize link recovery, then `cleanup` to handle the true residual orphans.
+
 ---
 
 ## Subcommand: search <query>