maestro-flow 0.1.0

package/workflows/integration-test.md

@@ -0,0 +1,343 @@
+# Integration Test Workflow
+
+Self-iterating integration test cycle that combines exploration, test design, execution, reflection, and adaptive strategy adjustment. Runs automated tests in a closed loop that self-corrects until convergence.
+
+6-phase cycle: Explore -> Design -> Develop -> Test -> Reflect -> Adjust
+Adaptive strategy: Conservative -> Aggressive -> Surgical -> Reflective
+L0-L3 progressive layers: Static Analysis -> Unit -> Integration -> E2E
+
+---
+
+### Step 1: Parse Input and Initialize
+
+**Parse arguments:**
+
+| Input | Result |
+|-------|--------|
+| No arguments | Error E001 |
+| Phase number | Resolve `.workflow/phases/{NN}-{slug}/` |
+| `--max-iter N` | Set MAX_ITER = N (default 5) |
+| `--layer L2` | Start from L2 layer |
+
+Check for existing integration test session:
+```bash
+ls .workflow/phases/{NN}-*/.tests/integration/state.json 2>/dev/null
+```
+
+If session exists: offer resume or restart.
+
+**Initialize session:**
+
+Create `.tests/integration/` directory.
+
+Write initial `state.json`:
+```json
+{
+  "phase": "{phase}",
+  "started_at": "{ISO timestamp}",
+  "current_iteration": 0,
+  "max_iterations": 5,
+  "strategy": "conservative",
+  "current_layer": "L0",
+  "pass_rates": [],
+  "convergence_threshold": 95,
+  "status": "running"
+}
+```
+
+Initialize `reflection-log.md`:
+```markdown
+# Integration Test Reflection Log
+Phase: {phase_name}
+Started: {timestamp}
+
+## Iterations
+```
+
+---
+
+### Step 1.3: Load Project Specs
+
+```
+specs_content = maestro spec load --category test
+arch_content = maestro spec load --category planning
+```
+
+`specs_content` for test conventions; `arch_content` for module boundaries in Step 2-3.
+
+---
+
+### Step 1.5: Load Previously Generated Tests
+
+Check for tests already generated by `quality-test-gen`:
+
+```
+generated_tests = []
+IF file exists "${PHASE_DIR}/.tests/test-gen-report.json":
+  report = read_json("${PHASE_DIR}/.tests/test-gen-report.json")
+  FOR test_entry IN report.generated:
+    IF test_entry.layer is "integration" or "e2e":
+      generated_tests.push(test_entry)
+  IF generated_tests.length > 0:
+    display "Found {generated_tests.length} pre-generated integration/e2e tests from test-gen. Will incorporate into test plan."
+```
+
+These tests are merged into the test plan in Step 3 (Design) — they are executed but not re-generated.
+
+---
+
+### Step 2: Explore
+
+**Phase 1: Explore codebase for testable integration points.**
+
+Discover:
+- Module boundaries and cross-module calls
+- API endpoints and their handlers
+- Database interactions and queries
+- External service integrations
+- Event flows and message passing
+
+```bash
+# Find cross-module imports
+grep -r "import.*from.*\.\./" src/ --include="*.ts" --include="*.tsx" -l 2>/dev/null | head -20
+
+# Find API route definitions
+grep -r "router\.\|app\.\(get\|post\|put\|delete\)" src/ --include="*.ts" -l 2>/dev/null | head -20
+
+# Find database calls
+grep -r "prisma\.\|query\|findMany\|findOne\|create\|update\|delete" src/ --include="*.ts" -l 2>/dev/null | head -20
+```
+
+Map integration points: which modules talk to which, through what interfaces.
+
+---
+
+### Step 3: Design
+
+**Phase 2: Design integration test plan.**
+
+**Merge pre-generated tests** (from Step 1.5):
+If `generated_tests` is not empty, incorporate them into the test plan directly — mark as "pre-existing" so Step 4 (Develop) skips writing them and Step 5 (Test Execute) includes them in the run.
+
+Based on exploration (and pre-generated tests if available), design tests per layer:
+
+**L0 - Static Analysis:**
+- Type check command
+- Lint command
+- Dead code detection
+
+**L1 - Unit Tests (isolation):**
+- Critical functions identified in explore
+- Edge cases for core logic
+
+**L2 - Integration Tests:**
+- API endpoint tests (request -> response)
+- Cross-module interaction tests
+- Database query tests (with fixtures)
+
+**L3 - E2E Tests:**
+- Critical user flows
+- Happy path + error path
+
+Write test plan to `.tests/integration/test-plan.json`:
+```json
+{
+  "layers": {
+    "L0": { "commands": ["tsc --noEmit", "eslint src/"], "expected_pass": true },
+    "L1": { "test_files": [...], "test_count": N },
+    "L2": { "test_files": [...], "test_count": N },
+    "L3": { "test_files": [...], "test_count": N }
+  },
+  "total_tests": M
+}
+```
+
+---
+
+### Step 4: Develop
+
+**Phase 3: Develop/write test code.**
+
+For each layer (current and below), write tests following existing patterns.
+Use quality-test-gen's RED-GREEN methodology for test writing.
+
+For integration tests (L2) specifically:
+- Set up test fixtures (DB seeds, mock services)
+- Write request/response assertions
+- Test error handling paths
+- Verify cross-module data flow
+
+---
+
+### Step 5: Test Execute
+
+**Phase 4: Execute tests for current layer.**
+
+Run tests progressively (L0 must pass before L1, etc.):
+
+```bash
+# L0: Static analysis
+tsc --noEmit 2>&1 | tail -30
+eslint src/ 2>&1 | tail -30
+
+# L1: Unit tests
+{test_command} --testPathPattern="unit|__tests__" 2>&1 | tail -50
+
+# L2: Integration tests
+{test_command} --testPathPattern="integration" 2>&1 | tail -50
+
+# L3: E2E tests
+{test_command} --testPathPattern="e2e" 2>&1 | tail -50
+```
+
+Record results in `test-results-iter-{N}.json`:
+```json
+{
+  "iteration": N,
+  "timestamp": "{ISO timestamp}",
+  "strategy": "{current_strategy}",
+  "layers": {
+    "L0": { "status": "pass|fail", "errors": [...] },
+    "L1": { "total": N, "passed": P, "failed": F, "pass_rate": 95.0 },
+    "L2": { "total": N, "passed": P, "failed": F, "pass_rate": 87.5 },
+    "L3": { "total": N, "passed": P, "failed": F, "pass_rate": 100.0 }
+  },
+  "overall_pass_rate": 92.3
+}
+```
+
+Calculate overall pass rate.
+
+---
+
+### Step 6: Reflect
+
+**Phase 5: Reflect on iteration results.**
+
+Analyze what happened:
+- Which tests failed and why?
+- Is pass rate improving, plateauing, or regressing?
+- Are failures clustered in one area or spread out?
+- Is the current strategy working?
+
+Append to `reflection-log.md`:
+```markdown
+## Iteration {N}
+Strategy: {strategy_name}
+Pass rate: {rate}% (previous: {prev_rate}%)
+Delta: {+/-}%
+
+### What worked
+- {observation}
+
+### What failed
+- {test}: {reason}
+
+### Pattern detected
+- {pattern, e.g., "all failures in auth module"}
+
+### Strategy assessment
+- Current strategy: {effective|ineffective|partially_effective}
+- Recommendation: {keep|switch_to_X}
+```
+
+---
+
+### Step 7: Adjust
+
+**Phase 6: Adjust strategy based on reflection.**
+
+**Adaptive Strategy Engine:**
+
+| Condition | Strategy | Behavior |
+|-----------|----------|----------|
+| Iteration 1-2 | Conservative | Fix obvious failures, don't refactor |
+| Pass rate >80% AND failures similar to previous | Aggressive | Batch-fix related failures together |
+| New regressions appeared | Surgical | Revert last changes, fix regression only |
+| Stuck 3+ iterations (rate not improving) | Reflective | Step back, re-analyze root cause pattern |
+
+**Strategy transitions:**
+```
+Conservative -> (pass rate >80%) -> Aggressive
+Aggressive -> (regression) -> Surgical
+Surgical -> (regression fixed) -> Aggressive
+Any -> (stuck 3+ iters) -> Reflective
+Reflective -> (new insight) -> Conservative (restart approach)
+```
+
+Update state.json with new strategy and iteration count.
+
+**Convergence check:**
+- If overall_pass_rate >= convergence_threshold (95%): CONVERGED -> go to Step 8
+- If iteration >= max_iterations: MAX_ITER_REACHED -> go to Step 8
+- Otherwise: go back to Step 4 (next iteration)
+
+---
+
+### Step 8: Complete
+
+**Complete integration test cycle.**
+
+Update state.json: status -> "complete" or "max_iter_reached".
+
+Write `.tests/integration/summary.json`:
+```json
+{
+  "phase": "{phase}",
+  "completed_at": "{ISO timestamp}",
+  "iterations": N,
+  "final_pass_rate": 97.5,
+  "converged": true,
+  "strategy_history": ["conservative", "conservative", "aggressive"],
+  "layers": {
+    "L0": { "status": "pass" },
+    "L1": { "pass_rate": 100.0 },
+    "L2": { "pass_rate": 95.0 },
+    "L3": { "pass_rate": 100.0 }
+  },
+  "bugs_discovered": [...],
+  "regressions_fixed": [...]
+}
+```
+
+Update index.json with integration test results.
+
+---
+
+### Step 9: Report
+
+```
+=== INTEGRATION TEST CYCLE ===
+Phase:       {phase_name}
+Iterations:  {N}/{max_iter}
+Converged:   {yes/no} (threshold: {threshold}%)
+
+Layer Results:
+  L0 Static:      {pass/fail}
+  L1 Unit:        {pass_rate}% ({passed}/{total})
+  L2 Integration: {pass_rate}% ({passed}/{total})
+  L3 E2E:         {pass_rate}% ({passed}/{total})
+
+Overall:     {final_pass_rate}%
+Strategy:    {final_strategy} (transitioned {N} times)
+
+Bugs Found:  {bug_count}
+Regressions: {regression_count} found, {fixed_count} fixed
+
+Files:
+  {target_dir}/.tests/integration/state.json
+  {target_dir}/.tests/integration/reflection-log.md
+  {target_dir}/.tests/integration/summary.json
+
+Next steps:
+  {suggested_next_command}
+```
+
+**Next step routing:**
+
+| Result | Suggestion |
+|--------|------------|
+| Converged (>=95%) | Skill({ skill: "maestro-verify", args: "{phase}" }) to update validation |
+| Max iter, >80% | Skill({ skill: "quality-test", args: "{phase}" }) for manual UAT on remaining gaps |
+| Max iter, <80% | Skill({ skill: "quality-debug" }) for deep investigation |
+| Bugs discovered | Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) to plan fixes |

package/workflows/issue-analyze.md

@@ -0,0 +1,226 @@
+# Workflow: Issue Analysis
+
+Root cause analysis for a specific issue using CLI exploration and codebase context gathering.
+
+## Input
+
+- `$ARGUMENTS`: `<ISS-ID> [--tool gemini|qwen] [--depth standard|deep]`
+- Operates on `.workflow/issues/`
+
+---
+
+### Step 1: Parse Arguments
+
+```
+1. Extract ISS-ID from first positional token in $ARGUMENTS
+   If empty → error E_NO_ISSUE_ID:
+     "Usage: /manage-issue-analyze <ISS-ID> [--tool gemini|qwen] [--depth standard|deep]"
+     "Example: /manage-issue-analyze ISS-20260318-001 --tool gemini --depth deep"
+
+2. Parse optional flags:
+   --tool VALUE    → TOOL (default: gemini)
+   --depth VALUE   → DEPTH (default: standard)
+
+3. Validate:
+   - ISS-ID matches pattern ISS-\d{8}-\d{3}
+   - TOOL is one of: gemini, qwen
+   - DEPTH is one of: standard, deep
+```
+
+---
+
+### Step 2: Load Issue and Validate
+
+```
+1. Check .workflow/issues/issues.jsonl exists
+   If not → fatal: "No issues file. Run /manage-issue create first."
+
+2. Read .workflow/issues/issues.jsonl line by line
+3. Parse each line as JSON, find record where id == ISS-ID
+   If not found → error E_ISSUE_NOT_FOUND:
+     "Issue {ISS-ID} not found. Run /manage-issue list to see available issues."
+
+4. Check issue status:
+   - If status is 'open' or 'registered' → proceed
+   - Otherwise → warning E_INVALID_STATUS:
+     "Issue {ISS-ID} has status '{status}'. Analysis typically runs on open issues."
+     Proceed anyway (analysis is non-destructive metadata enrichment).
+
+5. Store issue record as ISSUE for subsequent steps
+```
+
+---
+
+### Step 3: Gather Codebase Context
+
+```
+1. Extract keywords from ISSUE.title and ISSUE.description
+   - Split into significant words (>3 chars, skip stop words)
+   - Include ISSUE.context.location if present
+   - Include ISSUE.affected_components[] if present
+
+2. If DEPTH == "standard":
+   - Use Grep to search for each keyword in source files:
+     rg "{keyword}" --type-add "src:*.{ts,tsx,js,jsx,py,java,go}" --type src -l
+   - Collect up to 20 matching file paths
+   - For top 5 files by match count, read relevant sections (10 lines around match)
+
+3. If DEPTH == "deep":
+   - Run standard keyword grep (above)
+   - Additionally, launch Agent for semantic search:
+     Search for code related to: "{ISSUE.title} - {ISSUE.description}"
+     Focus on: error handling, data flow, dependencies
+   - Merge results from both approaches
+
+4. Build CONTEXT_SUMMARY:
+   - List of related files with brief relevance notes
+   - Key code snippets (max 50 lines total)
+   - Dependency chain if identifiable
+
+5. Store as CODEBASE_CONTEXT for CLI prompt
+```
+
+---
+
+### Step 4: Run CLI Analysis
+
+```
+1. Build analysis prompt:
+
+   maestro cli -p "PURPOSE: Root cause analysis for issue {ISS-ID}: {ISSUE.title}
+   Identify the root cause, assess impact, and suggest an approach.
+
+   ISSUE DETAILS:
+   - Title: {ISSUE.title}
+   - Description: {ISSUE.description}
+   - Severity: {ISSUE.severity}
+   - Location: {ISSUE.context.location or 'unknown'}
+   - Fix Direction: {ISSUE.fix_direction or 'none provided'}
+
+   CODEBASE CONTEXT:
+   {CODEBASE_CONTEXT}
+
+   TASK:
+   - Identify the root cause with file:line references
+   - Assess impact scope (which components/features affected)
+   - List all related files that need attention
+   - Rate confidence in the analysis (high/medium/low)
+   - Suggest a fix approach (brief, actionable)
+
+   MODE: analysis
+   CONTEXT: @**/*
+   EXPECTED: JSON object with fields:
+     root_cause: string (clear explanation),
+     impact: string (scope of impact),
+     related_files: string[] (file paths),
+     confidence: 'high'|'medium'|'low',
+     suggested_approach: string (actionable fix direction)
+   CONSTRAINTS: Only cite evidence found in codebase, no speculation
+   " --tool {TOOL} --mode analysis
+
+2. Parse CLI output:
+   - Extract JSON object from response
+   - Validate required fields: root_cause, impact, related_files, confidence, suggested_approach
+   - If parsing fails → error E_ANALYSIS_FAILED:
+     "Analysis did not return valid JSON. Raw output saved for review."
+     Store raw output in ISSUE feedback for manual review.
+
+3. Store parsed result as ANALYSIS_RESULT
+```
+
+---
+
+### Step 5: Build Analysis Record
+
+```
+1. Construct IssueAnalysis record:
+   {
+     "root_cause": "{ANALYSIS_RESULT.root_cause}",
+     "impact": "{ANALYSIS_RESULT.impact}",
+     "related_files": {ANALYSIS_RESULT.related_files},
+     "confidence": "{ANALYSIS_RESULT.confidence}",
+     "suggested_approach": "{ANALYSIS_RESULT.suggested_approach}",
+     "analyzed_at": "{NOW_ISO}",
+     "analyzed_by": "{TOOL}"
+   }
+
+2. Store as ANALYSIS record for next step
+```
+
+---
+
+### Step 6: Update Issue in JSONL
+
+```
+1. Read all lines from .workflow/issues/issues.jsonl
+2. Find the line matching ISS-ID
+3. Update the issue record:
+   - Set issue.analysis = ANALYSIS
+   - Set issue.updated_at = NOW_ISO
+   - Add issue_history entry:
+     {
+       "timestamp": "{NOW_ISO}",
+       "from_status": "{ISSUE.status}",
+       "to_status": "{ISSUE.status}",
+       "actor": "analysis-agent",
+       "note": "Root cause analysis completed (confidence: {ANALYSIS.confidence})"
+     }
+   - Status stays unchanged (analysis is metadata enrichment, not a status transition)
+
+4. Rewrite .workflow/issues/issues.jsonl:
+   - Replace the matching line with updated record (single JSON line)
+   - Write all lines back to file
+
+5. Verify file integrity:
+   - Re-read file, confirm ISS-ID record has analysis field
+```
+
+---
+
+### Step 7: Display Summary and Next Steps
+
+```
+Display analysis summary:
+
+====================================================
+  ANALYSIS COMPLETE: {ISS-ID}
+  Tool: {TOOL}    Depth: {DEPTH}
+====================================================
+
+ROOT CAUSE:
+  {ANALYSIS.root_cause}
+
+IMPACT:
+  {ANALYSIS.impact}
+
+CONFIDENCE: {ANALYSIS.confidence}
+
+RELATED FILES:
+  {for each file in ANALYSIS.related_files}
+  - {file}
+  {/for}
+
+SUGGESTED APPROACH:
+  {ANALYSIS.suggested_approach}
+====================================================
+
+Suggest next steps:
+  - Skill({ skill: "manage-issue-plan", args: "{ISS-ID}" }) -- Generate solution plan
+  - Skill({ skill: "manage-issue-plan", args: "{ISS-ID} --tool {TOOL}" }) -- Plan with same tool
+  - Skill({ skill: "manage-issue", args: "status {ISS-ID}" }) -- View full issue details
+```
+
+---
+
+## Output
+
+- **Updated**: `.workflow/issues/issues.jsonl` -- issue record enriched with `analysis` field
+- **Analysis fields**: root_cause, impact, related_files, confidence, suggested_approach, analyzed_at, analyzed_by
+
+## Quality Criteria
+
+- Analysis grounded in actual codebase evidence (file:line references)
+- JSON result validated before writing to JSONL
+- Issue status unchanged (analysis is non-destructive enrichment)
+- Read-modify-write pattern preserves other issues in JSONL
+- Next-step routing guides user to solution planning