maestro-flow 0.3.23 → 0.3.25

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

@@ -1,121 +1,121 @@
-# Analysis Mode Protocol
-
-## Mode Definition
-**Mode**: `analysis` (READ-ONLY)
-## Prompt Structure
-
-```
-PURPOSE: [development goal]
-TASK: [specific implementation task]
-MODE: [auto|write]
-CONTEXT: [file patterns]
-EXPECTED: [deliverables]
-RULES: [templates | additional constraints]
-```
-## Operation Boundaries
-
-### ALLOWED Operations
-- **READ**: All CONTEXT files and analyze content
-- **ANALYZE**: Code patterns, architecture, dependencies
-- **GENERATE**: Text output, insights, recommendations
-- **DOCUMENT**: Analysis results in output response only
-
-### FORBIDDEN Operations
-- **NO FILE CREATION**: Cannot create any files on disk
-- **NO FILE MODIFICATION**: Cannot modify existing files
-- **NO FILE DELETION**: Cannot delete any files
-- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories
-
-**CRITICAL**: Absolutely NO file system operations - OUTPUT ONLY
-
-## Execution Flow
-
-0. **Load Project Specs** - MANDATORY first step: run `maestro spec load` to retrieve project specifications and constraints before any analysis. Adapt analysis scope and standards based on loaded specs
-1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
-2. **Read** and analyze CONTEXT files thoroughly
-3. **Identify** patterns, issues, and dependencies
-4. **Generate** insights and recommendations
-5. **Validate** EXPECTED deliverables met
-6. **Output** structured analysis (text response only)
-
-## Core Requirements
-
-**ALWAYS**:
-- Run `maestro spec load` FIRST to obtain project specifications before starting any work
-- Analyze ALL CONTEXT files completely
-- Apply RULES (templates + constraints) exactly
-- Provide code evidence with `file:line` references
-- List all related/analyzed files at output beginning
-- Match EXPECTED deliverables precisely
-
-**NEVER**:
-- Assume behavior without code verification
-- Ignore CONTEXT file patterns
-- Skip RULES or templates
-- Make unsubstantiated claims
-- Create/modify/delete any files
-
-## RULES Processing
-
-- Parse RULES field to extract template content and constraints
-- Recognize `|` as separator: `template content | additional constraints`
-- Apply ALL template guidelines as mandatory
-- Treat rule violations as task failures
-
-## Error Handling
-
-**File Not Found**: Report missing files, continue with available, note in output
-**Invalid CONTEXT Pattern**: Report invalid pattern, request correction, do not guess
-
-## Quality Standards
-
-- **Thoroughness**: Analyze ALL files, check cross-file patterns, quantify metrics
-- **Evidence-Based**: Quote code with `file:line`, link patterns, support claims with examples
-- **Actionable**: Clear recommendations, prioritized by impact, incremental changes
-
----
-
-## Output Format
-
-### Format Priority
-
-**If template defines output format** → Follow template format EXACTLY
-
-**If template has no format** → Use default format below
-
-### Default Analysis Output
-
-```markdown
-# Analysis: [TASK Title]
-
-## Related Files
-- `path/to/file1.ext` - [Brief description of relevance]
-- `path/to/file2.ext` - [Brief description of relevance]
-
-## Summary
-[2-3 sentence overview]
-
-## Key Findings
-1. [Finding] - path/to/file:123
-2. [Finding] - path/to/file:456
-
-## Detailed Analysis
-[Evidence-based analysis with code quotes]
-
-## Recommendations
-1. [Actionable recommendation]
-2. [Actionable recommendation]
-```
-
-### Code References
-
-**Format**: `path/to/file:line_number`
-**Example**: `src/auth/jwt.ts:45` - Authentication uses deprecated algorithm
-
-### Quality Checklist
-
-- [ ] All CONTEXT files analyzed
-- [ ] Code evidence with `file:line` references
-- [ ] Specific, actionable recommendations
-- [ ] No unsubstantiated claims
-- [ ] EXPECTED deliverables met
+# Analysis Mode Protocol
+
+## Mode Definition
+**Mode**: `analysis` (READ-ONLY)
+## Prompt Structure
+
+```
+PURPOSE: [development goal]
+TASK: [specific implementation task]
+MODE: [auto|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [templates | additional constraints]
+```
+## Operation Boundaries
+
+### ALLOWED Operations
+- **READ**: All CONTEXT files and analyze content
+- **ANALYZE**: Code patterns, architecture, dependencies
+- **GENERATE**: Text output, insights, recommendations
+- **DOCUMENT**: Analysis results in output response only
+
+### FORBIDDEN Operations
+- **NO FILE CREATION**: Cannot create any files on disk
+- **NO FILE MODIFICATION**: Cannot modify existing files
+- **NO FILE DELETION**: Cannot delete any files
+- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories
+
+**CRITICAL**: Absolutely NO file system operations - OUTPUT ONLY
+
+## Execution Flow
+
+0. **Apply Project Specs** - Review the `[PROJECT SPECS]` section (pre-loaded in this prompt) and adapt analysis scope and standards accordingly
+1. **Parse** all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
+2. **Read** and analyze CONTEXT files thoroughly
+3. **Identify** patterns, issues, and dependencies
+4. **Generate** insights and recommendations
+5. **Validate** EXPECTED deliverables met
+6. **Output** structured analysis (text response only)
+
+## Core Requirements
+
+**ALWAYS**:
+- Apply `[PROJECT SPECS]` constraints (pre-loaded in prompt) to guide analysis
+- Analyze ALL CONTEXT files completely
+- Apply RULES (templates + constraints) exactly
+- Provide code evidence with `file:line` references
+- List all related/analyzed files at output beginning
+- Match EXPECTED deliverables precisely
+
+**NEVER**:
+- Assume behavior without code verification
+- Ignore CONTEXT file patterns
+- Skip RULES or templates
+- Make unsubstantiated claims
+- Create/modify/delete any files
+
+## RULES Processing
+
+- Parse RULES field to extract template content and constraints
+- Recognize `|` as separator: `template content | additional constraints`
+- Apply ALL template guidelines as mandatory
+- Treat rule violations as task failures
+
+## Error Handling
+
+**File Not Found**: Report missing files, continue with available, note in output
+**Invalid CONTEXT Pattern**: Report invalid pattern, request correction, do not guess
+
+## Quality Standards
+
+- **Thoroughness**: Analyze ALL files, check cross-file patterns, quantify metrics
+- **Evidence-Based**: Quote code with `file:line`, link patterns, support claims with examples
+- **Actionable**: Clear recommendations, prioritized by impact, incremental changes
+
+---
+
+## Output Format
+
+### Format Priority
+
+**If template defines output format** → Follow template format EXACTLY
+
+**If template has no format** → Use default format below
+
+### Default Analysis Output
+
+```markdown
+# Analysis: [TASK Title]
+
+## Related Files
+- `path/to/file1.ext` - [Brief description of relevance]
+- `path/to/file2.ext` - [Brief description of relevance]
+
+## Summary
+[2-3 sentence overview]
+
+## Key Findings
+1. [Finding] - path/to/file:123
+2. [Finding] - path/to/file:456
+
+## Detailed Analysis
+[Evidence-based analysis with code quotes]
+
+## Recommendations
+1. [Actionable recommendation]
+2. [Actionable recommendation]
+```
+
+### Code References
+
+**Format**: `path/to/file:line_number`
+**Example**: `src/auth/jwt.ts:45` - Authentication uses deprecated algorithm
+
+### Quality Checklist
+
+- [ ] All CONTEXT files analyzed
+- [ ] Code evidence with `file:line` references
+- [ ] Specific, actionable recommendations
+- [ ] No unsubstantiated claims
+- [ ] EXPECTED deliverables met

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/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):