maestro-flow 0.3.24 → 0.3.25

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

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.