maestro-flow 0.3.24 → 0.3.26

package/templates/cli/protocols/write-protocol.md

@@ -1,138 +1,138 @@
-# Write Mode Protocol
-## Prompt Structure
-
-```
-PURPOSE: [development goal]
-TASK: [specific implementation task]
-MODE: [auto|write]
-CONTEXT: [file patterns]
-EXPECTED: [deliverables]
-RULES: [templates | additional constraints]
-```
-## Operation Boundaries
-
-### MODE: write
-- **READ**: All CONTEXT files and analyze content
-- **CREATE**: New files (documentation, code, configuration)
-- **MODIFY**: Existing files (update content, refactor code)
-- **DELETE**: Files when explicitly required
-
-**Restrictions**: Follow project conventions, cannot break existing functionality
-
-**Constraint**: Must test every change
-
-## Execution Flow
-
-### MODE: write
-0. **Load Project Specs** - MANDATORY first step: run `maestro spec load` to retrieve project specifications and constraints before any implementation. Apply loaded specs to guide coding standards, architecture decisions, and quality gates
-1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
-2. **Read** CONTEXT files, find 3+ similar patterns
-3. **Plan** implementation following RULES
-4. **Execute** requested file operations
-5. **Validate** changes
-6. **Report** file changes
-
-## Core Requirements
-
-**ALWAYS**:
-- Run `maestro spec load` FIRST to obtain project specifications before starting any work
-- Study CONTEXT files - find 3+ similar patterns before implementing
-- Apply RULES exactly
-- Test continuously (auto mode)
-- Commit incrementally (auto mode)
-- Match project style exactly
-- List all created/modified files at output beginning
-
-**NEVER**:
-- Make assumptions without code verification
-- Ignore existing patterns
-- Skip tests (auto mode)
-- Use clever tricks over boring solutions
-- Break backward compatibility
-- Exceed 3 failed attempts without stopping
-
-
-**Three-Attempt Rule**: On 3rd failure, stop and report what attempted, what failed, root cause
-
-| Error Type | Response |
-|------------|----------|
-| Syntax/Type | Review → Fix → Re-run tests |
-| Runtime | Analyze stack → Add handling → Test |
-| Test Failure | Debug → Review setup → Fix |
-| Build Failure | Check messages → Fix incrementally |
-
----
-
-## Output Format
-
-### Format Priority
-
-**If template defines output format** → Follow template format EXACTLY
-
-**If template has no format** → Use default format below
-
-### Task Implementation
-
-```markdown
-# Implementation: [TASK Title]
-
-## Changes
-- Created: `path/to/file1.ext` (X lines)
-- Modified: `path/to/file2.ext` (+Y/-Z lines)
-- Deleted: `path/to/file3.ext`
-
-## Summary
-[2-3 sentence overview]
-
-## Key Decisions
-1. [Decision] - Rationale and reference to similar pattern
-2. [Decision] - path/to/reference:line
-
-## Implementation Details
-[Evidence-based description with code references]
-
-## Testing
-- Tests written: X new tests
-- Tests passing: Y/Z tests
-
-## Validation
-✅ Tests: X passing
-✅ Build: Success
-
-## Next Steps
-[Recommendations if any]
-```
-
-### Partial Completion
-
-```markdown
-# Task Status: Partially Completed
-
-## Completed
-- [What worked]
-- Files: `path/to/completed.ext`
-
-## Blocked
-- **Issue**: [What failed]
-- **Root Cause**: [Analysis]
-- **Attempted**: [Solutions tried - attempt X of 3]
-
-## Required
-[What's needed to proceed]
-
-## Recommendation
-[Suggested next steps]
-```
-
-### Code References
-
-**Format**: `path/to/file:line_number`
-**Example**: `src/auth/jwt.ts:45` - Implemented following pattern from `src/auth/session.ts:78`
-
-### Quality Checklist
-
-- [ ] All tests pass
-- [ ] Build succeeds
-- [ ] All EXPECTED deliverables met
-- [ ] Code follows existing patterns
-- [ ] File changes listed at beginning
+# Write Mode Protocol
+## Prompt Structure
+
+```
+PURPOSE: [development goal]
+TASK: [specific implementation task]
+MODE: [auto|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [templates | additional constraints]
+```
+## Operation Boundaries
+
+### MODE: write
+- **READ**: All CONTEXT files and analyze content
+- **CREATE**: New files (documentation, code, configuration)
+- **MODIFY**: Existing files (update content, refactor code)
+- **DELETE**: Files when explicitly required
+
+**Restrictions**: Follow project conventions, cannot break existing functionality
+
+**Constraint**: Must test every change
+
+## Execution Flow
+
+### MODE: write
+0. **Apply Project Specs** - Review the `[PROJECT SPECS]` section (pre-loaded in this prompt) and apply specs to guide coding standards, architecture decisions, and quality gates
+1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
+2. **Read** CONTEXT files, find 3+ similar patterns
+3. **Plan** implementation following RULES
+4. **Execute** requested file operations
+5. **Validate** changes
+6. **Report** file changes
+
+## Core Requirements
+
+**ALWAYS**:
+- Apply `[PROJECT SPECS]` constraints (pre-loaded in prompt) to guide implementation
+- Study CONTEXT files - find 3+ similar patterns before implementing
+- Apply RULES exactly
+- Test continuously (auto mode)
+- Commit incrementally (auto mode)
+- Match project style exactly
+- List all created/modified files at output beginning
+
+**NEVER**:
+- Make assumptions without code verification
+- Ignore existing patterns
+- Skip tests (auto mode)
+- Use clever tricks over boring solutions
+- Break backward compatibility
+- Exceed 3 failed attempts without stopping
+
+
+**Three-Attempt Rule**: On 3rd failure, stop and report what attempted, what failed, root cause
+
+| Error Type | Response |
+|------------|----------|
+| Syntax/Type | Review → Fix → Re-run tests |
+| Runtime | Analyze stack → Add handling → Test |
+| Test Failure | Debug → Review setup → Fix |
+| Build Failure | Check messages → Fix incrementally |
+
+---
+
+## Output Format
+
+### Format Priority
+
+**If template defines output format** → Follow template format EXACTLY
+
+**If template has no format** → Use default format below
+
+### Task Implementation
+
+```markdown
+# Implementation: [TASK Title]
+
+## Changes
+- Created: `path/to/file1.ext` (X lines)
+- Modified: `path/to/file2.ext` (+Y/-Z lines)
+- Deleted: `path/to/file3.ext`
+
+## Summary
+[2-3 sentence overview]
+
+## Key Decisions
+1. [Decision] - Rationale and reference to similar pattern
+2. [Decision] - path/to/reference:line
+
+## Implementation Details
+[Evidence-based description with code references]
+
+## Testing
+- Tests written: X new tests
+- Tests passing: Y/Z tests
+
+## Validation
+✅ Tests: X passing
+✅ Build: Success
+
+## Next Steps
+[Recommendations if any]
+```
+
+### Partial Completion
+
+```markdown
+# Task Status: Partially Completed
+
+## Completed
+- [What worked]
+- Files: `path/to/completed.ext`
+
+## Blocked
+- **Issue**: [What failed]
+- **Root Cause**: [Analysis]
+- **Attempted**: [Solutions tried - attempt X of 3]
+
+## Required
+[What's needed to proceed]
+
+## Recommendation
+[Suggested next steps]
+```
+
+### Code References
+
+**Format**: `path/to/file:line_number`
+**Example**: `src/auth/jwt.ts:45` - Implemented following pattern from `src/auth/session.ts:78`
+
+### Quality Checklist
+
+- [ ] All tests pass
+- [ ] Build succeeds
+- [ ] All EXPECTED deliverables met
+- [ ] Code follows existing patterns
+- [ ] File changes listed at beginning

package/workflows/debug.md

@@ -144,6 +144,41 @@ All agents run concurrently. Collect all results.
 
 ---
 
+### Step 5.5: CLI Supplementary Evidence Gathering (optional)
+
+**Purpose:** Use external CLI tool for broad codebase evidence collection before spawning debug agents. Provides agents with richer context without consuming their token budget on exploration.
+
+**Skip if** no enabled CLI tools or standalone mode with minimal context.
+
+```
+IF no CLI tools enabled: skip to Step 6
+
+# Build evidence request from symptoms
+symptom_summary = symptoms or gap descriptions, concatenated
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Gather codebase evidence related to a bug investigation
+TASK: Trace call chains for affected functions | Find recent changes to related files | Identify error handling gaps | Check for similar patterns elsewhere
+MODE: analysis
+CONTEXT: @${affected_files or scoped_path}/**/*
+EXPECTED: JSON { call_chains: [{ entry, chain: [file:line...] }], recent_changes: [{ file, commits: [...] }], error_gaps: [{ file, line, description }], similar_patterns: [{ file, line, description }] }
+CONSTRAINTS: Focus on code paths related to the symptoms | Max 20 entries per category
+
+Symptoms: ${symptom_summary}
+" --role explore --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:**
+```
+cli_evidence = maestro delegate output <id>
+Parse and append to evidence.ndjson with type: "cli-exploration"
+Pass cli_evidence as supplementary_context to debug agent prompts in Step 5/6
+```
+
+---
+
 ### Step 6: Spawn Single Debug Agent (sequential mode)
 
 Spawn general-purpose agent (`run_in_background: false`) with:

package/workflows/execute.md

@@ -336,6 +336,29 @@ If constraints exist:
   Scan each for disallowed import patterns → critical "tech_stack_violation" per match
 ```
 
+### Check 4: CLI Supplementary Validation (optional)
+
+**Purpose:** Use external CLI tool for semantic validation that structural checks miss — dead code, unused exports, circular dependencies introduced by execution.
+
+```
+IF no CLI tools enabled OR completed_tasks.length == 0: skip
+
+modified_files = collect all files modified by completed tasks
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Validate execution output for semantic issues
+TASK: Check for circular dependency introduction | Detect dead code / unused exports | Verify public API consistency (no breaking changes to existing exports)
+MODE: analysis
+CONTEXT: @${modified_files as glob}
+EXPECTED: JSON { circular_deps: [{ cycle: [file...] }], dead_code: [{ file, line, symbol }], breaking_changes: [{ file, export_name, change_type }] }
+CONSTRAINTS: Only check modified files and their direct importers | severity = critical for breaking_changes, warning for others
+" --role analyze --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:** Parse result. Append critical-severity items to violations list. Log warnings separately.
+
 ### Gate Logic
 
 ```

package/workflows/maestro-chain-execute.md

@@ -0,0 +1,204 @@
+# Workflow: maestro-chain-execute
+
+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.
+Tracks all progress via status.json (the JSON file created during selection).
+
+**Prerequisites:**
+- Session directory with valid status.json (status: "running", pending steps)
+- $SESSION_PATH passed from maestro.md dispatch
+
+## Step 1: Load Session
+
+Read status.json from `$SESSION_PATH`.
+
+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.
+
+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,
+  spec_session_id,
+  scratch_dir,
+  auto_mode         // from status.json.auto_mode
+}
+```
+
+### assembleArgs(step)
+
+```
+1. Substitute placeholders in step.args:
+   {phase} → context.current_phase
+   {description} → context.user_intent
+   {issue_id} → context.issue_id
+   {spec_session_id} → context.spec_session_id
+   {scratch_dir} → context.scratch_dir
+
+2. In auto_mode, append per-command flag if not already present:
+   maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-ui-design → -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
+
+Per-step engine selection:
+
+```
+If exec_mode is 'cli' or 'skill' → force that engine for all steps.
+
+In 'auto' mode, select per step:
+  CLI steps (heavy, context-isolated):
+    maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm,
+    maestro-roadmap, maestro-ui-design, quality-refactor
+
+  Skill steps (observable, interactive, lightweight):
+    everything else — verify, review, test, debug, milestone-*,
+    manage-*, spec-*, quick, etc.
+```
+
+Display: `[Step {N}/{total}] /{cmd} [{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)
+
+**Skill engine** — invoke directly (synchronous, visible):
+
+```
+Skill({ skill: step.cmd, 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
+
+**Success:** mark step `status = "completed"`, set `completed_at` in status.json.
+CLI: save output to `step-{N}-output.txt` in session directory.
+
+**Failure:**
+- `auto_mode` → retry once, then skip (mark `"skipped"`).
+- Interactive → offer: Retry (max 2) / Skip / Abort.
+- Abort → **Error E003** — update status.json `status = "aborted"`, display resume hint: `/maestro -c`.
+
+### 3e. Post-step analysis (CLI steps only)
+
+Skip if: step failed/skipped, or `engine == 'skill'`.
+
+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
+
+Update status.json: `status = "completed"`.
+
+```
+============================================================
+  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 [skill]
+    [—] 3. quality-review — skipped [skill]
+
+  CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
+
+  Next: /maestro continue | /manage-status
+============================================================
+```