maestro-flow 0.3.24 → 0.3.26

package/workflows/maestro.md

@@ -20,16 +20,7 @@ Parse $ARGUMENTS → extract flags, remainder is intent text.
   intent = arguments with all flags/valued options stripped, trimmed
 ```
 
-### 1b: Handle resume mode
-
-If `resumeMode`:
-1. Scan `.workflow/.maestro/` for latest session (or session ID if specified)
-2. Read `status.json` → find last completed step, remaining steps
-3. Set `$CHAIN` from status.json, `$STEP_INDEX` = last_completed + 1
-4. If no session found: **Error E004** — list available sessions
-5. Jump to **Step 4** at resume point
-
-### 1c: Read project state
+### 1b: Read project state
 
 Check `.workflow/state.json` existence.
 
@@ -54,7 +45,7 @@ Check `.workflow/state.json` existence.
 
 **If missing:** `$PROJECT_STATE = { initialized: false }`. If intent also empty → **Error E001** (suggest `maestro-init`).
 
-### 1d: Display banner
+### 1c: Display banner
 
 ```
 ============================================================
@@ -267,105 +258,36 @@ Create session directory `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/` and wri
   "cli_tool": "{cliTool}",
   "gemini_session_id": null,
   "step_analyses": [],
+  "context": {
+    "current_phase": "{resolved_phase}",
+    "user_intent": "{original_intent}",
+    "issue_id": "{resolved_issue_id or null}",
+    "spec_session_id": null,
+    "scratch_dir": null
+  },
   "steps": [{ "index": 0, "skill": "{cmd}", "args": "{args}", "engine": null, "status": "pending", "started_at": null, "completed_at": null }],
   "current_step": 0,
   "status": "running"
 }
 ```
 
-## Step 4: Execute Chain
-
-### Shared: context & argument assembly
-
-```
-Context object tracks: current_phase, user_intent, issue_id, spec_session_id, scratch_dir, auto_mode.
-
-assembleArgs: substitute placeholders {phase}, {description}, {issue_id}, {spec_session_id}, {scratch_dir} in step.args.
-  In auto_mode, append per-command flag if not already present:
-    maestro-analyze/brainstorm/roadmap/ui-design → -y
-    maestro-plan → --auto
-    quality-test → --auto-fix
-    quality-retrospective → --auto-yes
-
-Shell-escape strings with single quotes for CLI delegate calls.
-```
-
-### Step loop — for each step starting at `$STEP_INDEX` (default 0):
-
-**4a. Select engine & display banner:**
-
-Select engine per step (see 3e). Display step banner with index, command name, engine, args.
-- Step >= 4 and not autoYes: hint user about `/maestro -c` for fresh context resume.
-- autoYes and step >= 5: log warning to status.json.
-- Update status.json: step status = `"running"`, engine, started_at.
-
-**4b. Execute (engine-dependent):**
-
-**Skill** — invoke `Skill({ skill: step.cmd, args: assembledArgs })` directly (synchronous, visible).
-
-**CLI** — 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 `maestro delegate <prompt> --to {cliTool} --mode write` via `Bash(run_in_background: true, timeout: 600000)`
-5. **STOP** — wait for background callback
-
-**4c. Parse output & update context:**
-
-Scan step output for context propagation: `PHASE: N` → current_phase, `SPEC-xxx` → spec_session_id, `scratch_dir: path` → scratch_dir. CLI: capture exec_id from stderr.
-
-**4d. Handle result:**
-
-Success: mark `"completed"` in status.json. CLI: save output to `step-{N}-output.txt`.
-Failure: autoYes → retry once then skip. Interactive → Retry (max 2) / Skip / Abort. Abort → **Error E003** with resume hint.
-
-**4e. Post-step analysis (CLI steps only, multi-step chains):**
-
-Skip if: step failed/skipped, single-step chain, or `stepEngine === 'skill'`.
-
-Delegate to gemini (analysis mode, `--resume` if prior gemini_session_id exists) with prompt containing:
-- Step command, args, chain name, intent
-- Last 200 lines of step output
-- Next step info (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: capture gemini exec_id for session continuity, store analysis in `state.step_analyses[]` and `step-{N}-analysis.json`, advance to next step (**4a**).
+## Step 4: Dispatch
 
-**4f. Completion report:**
+### 4a: Low-complexity fast path
 
-```
-============================================================
-  MAESTRO SESSION COMPLETE
-============================================================
-  Session:  {session_id}
-  Chain:    {chain_name}
-  Steps:    {completed}/{total} completed
-  Phase:    {current_phase}
+If ALL conditions met:
+- clarity >= 2
+- task_type == `'quick'` or (action == `'create'` && object == `'feature'`)
+- NOT `forcedChain`, NOT `state_continue`
 
-  Results:
-    [✓] 1. maestro-plan — completed [cli] (quality: 85/100)
-    [✓] 2. maestro-verify — completed [skill]
-    [—] 3. quality-review — skipped [skill]
+Then: `Skill({ skill: "maestro-quick", args: '"{description}"' })`. **End.**
 
-  CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
+### 4b: Standard execution — read and follow execution workflow
 
-  Next: /maestro continue | /manage-status
-============================================================
-```
+For ALL chains (regardless of step count):
+1. status.json already created in Step 3f with `steps[]` and `context`
+2. Read `~/.maestro/workflows/maestro-chain-execute.md`
+3. Follow it with `$SESSION_PATH` = session directory from Step 3f
 
 ---
 

package/workflows/milestone-audit.md

@@ -71,6 +71,34 @@ Agent({
 
 ---
 
+## Step 5.5: CLI Supplementary Integration Scan (optional)
+
+**Purpose:** Use external CLI tool for broad cross-phase dependency and API consistency checks that complement the agent-based integration checker.
+
+**Skip if** no enabled CLI tools or milestone has only 1 phase.
+
+```
+IF no CLI tools enabled OR phases.length <= 1: skip to Step 6
+
+# Collect all modified files across execute artifacts
+all_execute_paths = execute_artifacts.map(a => a.path)
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Cross-phase integration scan for milestone completion
+TASK: Check for import/export consistency across phase boundaries | Detect shared type/interface mismatches | Identify configuration key conflicts between phases
+MODE: analysis
+CONTEXT: @${all_execute_paths as glob patterns}
+EXPECTED: JSON { import_issues: [{ file, import_path, issue }], type_mismatches: [{ type_name, definitions: [{ file, shape }] }], config_conflicts: [{ key, values: [{ file, value }] }] }
+CONSTRAINTS: Only check cross-phase boundaries | Ignore intra-phase issues
+" --role analyze --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:** Parse result, append to integration checker findings. Critical items surface in Step 6 verdict.
+
+---
+
 ## Step 6: Audit Report & Verdict
 
 1. Read the audit report generated by the integration checker

package/workflows/plan.md

@@ -100,6 +100,23 @@ default             → Create Mode: P1 → P2 → P3 → P4 → P4.5 → P5
    - 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)
+   ```
+   IF no CLI tools enabled: skip
+
+   Bash({
+     command: 'maestro delegate "PURPOSE: Gather implementation context for planning phase
+   TASK: Identify existing patterns for similar features | Map dependency graph of target modules | Find potential conflict points with other recent changes
+   MODE: analysis
+   CONTEXT: @**/*
+   EXPECTED: JSON { patterns: [{ name, files, description }], dependencies: [{ module, depends_on[] }], conflict_risks: [{ file, reason }] }
+   CONSTRAINTS: Focus on ${phase_goal} scope | Max 10 entries per category
+   " --role explore --mode analysis',
+     run_in_background: true
+   })
+   ```
+   **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`)
 
    Gap sources (in priority order, first non-empty wins, then additionals merged):

package/workflows/review.md

@@ -219,6 +219,52 @@ verdict:
 
 ---
 
+## Step 6.5: CLI Supplementary Analysis (standard + deep only)
+
+**Skip for quick level or if no enabled CLI tools.**
+
+**Purpose:** Use external CLI tool as a second opinion on critical findings before deep-dive. The CLI analysis supplements (not replaces) the agent review — its results are merged into findings.
+
+```
+IF level == "quick" OR no CLI tools enabled: skip to Step 7
+
+# Gather critical/high findings for CLI cross-check
+cli_targets = all_findings.filter(f => f.severity in ["critical", "high"])
+IF cli_targets.length == 0: skip to Step 7
+
+# Build concise review prompt from findings
+finding_summary = cli_targets.map(f => "${f.id}: [${f.severity}] ${f.file}:${f.line} — ${f.title}").join("\n")
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Cross-verify code review findings and identify missed issues
+TASK: For each finding, verify severity is accurate | Check for false positives | Identify any critical issues missed by initial review in the same files
+MODE: analysis
+CONTEXT: @${review_files as glob pattern}
+EXPECTED: JSON array of { finding_id, verified: bool, adjusted_severity?, missed_issues?: [{ severity, file, line, title, description }] }
+CONSTRAINTS: Only report missed issues of severity high or above | Do not duplicate existing findings
+
+Existing findings to verify:
+${finding_summary}
+" --role review --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:**
+```
+cli_result = maestro delegate output <id>
+Parse JSON from cli_result
+
+For each verified finding:
+  If adjusted_severity differs: update finding.severity, add finding.cli_note = "severity adjusted by CLI review"
+For each missed_issue:
+  Append to all_findings with id: "CLI-{NNN}", source: "cli-supplementary"
+
+Recalculate severity_dist after merge
+```
+
+---
+
 ## Step 7: Deep-Dive (Conditional)
 
 **Skip entirely for quick level.**

package/workflows/test-gen.md

@@ -58,6 +58,34 @@ Apply --layer filter if set.
 
 ---
 
+### Step 3.5: CLI Supplementary Test Analysis (optional)
+
+**Purpose:** Use external CLI tool to analyze source code and suggest edge cases and boundary conditions that manual classification may miss.
+
+**Skip if** no enabled CLI tools or classified files are all "skip".
+
+```
+IF no CLI tools enabled OR all files classified as "skip": skip to Step 4
+
+# Build file list for analysis
+target_files = unit + integration + e2e files, map to paths
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Analyze source files to identify test-worthy edge cases and boundary conditions
+TASK: For each file, identify: error handling paths | boundary conditions | state transitions | external dependency interactions
+MODE: analysis
+CONTEXT: @${target_files as glob}
+EXPECTED: JSON array of { file, edge_cases: [{ description, type: boundary|error|state|integration, priority: high|medium }] }
+CONSTRAINTS: Only report non-obvious cases | Max 5 edge cases per file | Focus on untested paths
+" --role analyze --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:** Parse result, merge edge_cases into Step 4 test_cases for matching files. Mark CLI-suggested cases with `source: "cli-analysis"`.
+
+---
+
 ### Step 4: Generate Test Plan
 
 For each gap + classified file, create a test entry:

package/workflows/verify.md

@@ -102,6 +102,44 @@ The `constraint_violations[]` array is included in the final `verification.json`
 
 ---
 
+## V0.8: CLI Supplementary Verification (optional)
+
+**Purpose:** Use external CLI tool for broad anti-pattern and completeness scan as a supplementary signal before structural verification. Results feed into V1 as pre-collected evidence.
+
+**Skip if** no enabled CLI tools.
+
+```
+IF no CLI tools enabled: skip to V1
+
+# Collect modified files list from task summaries
+modified_files_list = modified_files.join(", ")
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Pre-verify code completeness and anti-patterns in modified files
+TASK: Check for TODO/FIXME/HACK markers | Detect stub implementations (empty functions, placeholder returns) | Verify imports are used | Check for console.log/print debug statements left behind
+MODE: analysis
+CONTEXT: @${modified_files as glob pattern}
+EXPECTED: JSON { anti_patterns: [{ type, file, line, description, severity }], completeness_flags: [{ file, issue, severity }] }
+CONSTRAINTS: Only scan the listed modified files | severity = blocker|warning|info
+" --role analyze --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:**
+```
+cli_verify = maestro delegate output <id>
+Parse JSON result
+
+# Merge into constraint_violations for V3 aggregation
+For each anti_pattern with severity == "blocker":
+  Append to constraint_violations as { id: "CLI-AP-{NNN}", type: "cli_anti_pattern", ... }
+
+Pass cli_verify.completeness_flags as supplementary context to V1 verification
+```
+
+---
+
 ## V1: Goal-Backward Verification
 
 **Purpose:** Verify execution results match phase goals through 3-layer structural checking.