pi-maestro-flow 0.2.0 → 0.3.1

package/workflows/issue-discover.md

@@ -0,0 +1,238 @@
+# Workflow: Issue Discovery
+
+Automated issue discovery via multi-perspective analysis or prompt-driven exploration.
+
+## Input
+
+- `$ARGUMENTS`: empty (multi-perspective) or `by-prompt [prompt text]`
+- Operates on `.workflow/issues/`
+
+---
+
+### Step 1: Parse Mode
+
+```
+Mode from $ARGUMENTS:
+  empty         → MULTI_PERSPECTIVE (Step 3)
+  "by-prompt"   → PROMPT_DRIVEN (Step 7), remaining tokens = USER_PROMPT
+```
+
+---
+
+### Step 2: Validate Environment
+
+```
+Require .workflow/ exists → fatal if missing: "No project initialized. Run /maestro-init first."
+Ensure .workflow/issues/ and issues.jsonl exist (create if missing).
+
+Session ID: DBP-{YYYYMMDD}-{HHmmss}
+Session dir: .workflow/issues/discoveries/{SESSION_ID}/
+
+Initialize discovery-state.json:
+  {
+    "id": "{SESSION_ID}",
+    "mode": "{discover|discover-by-prompt}",
+    "status": "in_progress",
+    "started_at": "{NOW_ISO}",
+    "completed_at": null,
+    "perspectives_completed": [],
+    "issues_found": 0,
+    "issues_deduplicated": 0
+  }
+```
+
+---
+
+## Multi-Perspective Discovery (discover)
+
+### Step 3: Define Analysis Perspectives
+
+```
+8 analysis perspectives, each with a focus area and guiding questions:
+
+1. SECURITY
+   Focus: Authentication, authorization, input validation, secrets, injection
+   Question: "What security vulnerabilities or unsafe patterns exist?"
+
+2. PERFORMANCE
+   Focus: N+1 queries, unbounded loops, missing caching, memory leaks, large payloads
+   Question: "What performance bottlenecks or inefficiencies exist?"
+
+3. RELIABILITY
+   Focus: Error handling, retry logic, race conditions, data integrity, graceful degradation
+   Question: "What failure modes are unhandled or could cause data loss?"
+
+4. MAINTAINABILITY
+   Focus: Code duplication, tight coupling, missing abstractions, unclear naming, dead code
+   Question: "What makes this codebase harder to understand or change?"
+
+5. SCALABILITY
+   Focus: Hardcoded limits, single-threaded bottlenecks, stateful assumptions, schema rigidity
+   Question: "What will break or degrade as load/data/users increase?"
+
+6. UX
+   Focus: Confusing flows, missing feedback, inconsistent behavior, accessibility gaps
+   Question: "What creates friction or confusion for end users?"
+
+7. ACCESSIBILITY
+   Focus: Screen reader support, keyboard navigation, color contrast, ARIA labels, focus management
+   Question: "What barriers exist for users with disabilities?"
+
+8. COMPLIANCE
+   Focus: Logging gaps, audit trails, data retention, privacy controls, regulatory requirements
+   Question: "What regulatory or policy requirements are not met?"
+```
+
+### Step 3.5: Load Project Specs
+
+```
+specs_content = maestro spec load --category coding
+```
+
+Pass to each analysis agent so severity assessments align with project quality standards.
+
+---
+
+### Step 4: Launch Parallel Analysis
+
+```
+Batches of 4 concurrent agents:
+  Batch 1: security, performance, reliability, maintainability
+  Batch 2: scalability, ux, accessibility, compliance
+
+Per perspective → delegate analysis:
+
+  maestro delegate "PURPOSE: Discover {PERSPECTIVE} issues in the codebase.
+  Focus: {FOCUS_AREA} | Question: {QUESTION}
+  TASK: Scan source files → identify issues with file:line → rate severity → suggest fix
+  MODE: analysis
+  CONTEXT: @**/*
+  EXPECTED: JSON array: [{ title, severity, description, location, fix_direction, affected_components[] }]
+  CONSTRAINTS: Evidence-backed findings only
+  " --role analyze --mode analysis
+
+Results → .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
+Update discovery-state.json: perspectives_completed += ["{PERSPECTIVE}"]
+```
+
+### Step 5: Deduplicate Findings
+
+```
+Merge all *-findings.json → single list.
+Deduplicate: group by file path, merge entries with >80% description overlap
+or same file:line (keep higher severity).
+Track issues_found (pre-dedup) and issues_deduplicated (post-dedup) in discovery-state.json.
+```
+
+### Step 6: Create Issues from Findings
+
+```
+Per unique finding → generate ISS-YYYYMMDD-NNN, build issue record:
+  {
+    "id", "title", "status": "registered",
+    "priority": severity_to_priority(critical→1, high→2, medium→3, low→4),
+    "severity", "source": "discovery",
+    "description", "fix_direction",
+    "context": { "location", "notes": "Discovered by {PERSPECTIVE} in {SESSION_ID}" },
+    "tags": ["{PERSPECTIVE}"],
+    "affected_components",
+    "issue_history": [{ from: null, to: "registered", actor: "discovery-agent" }],
+    "created_at", "updated_at"
+  }
+
+Append to: .workflow/issues/issues.jsonl + discoveries/{SESSION_ID}/discovery-issues.jsonl
+Finalize discovery-state.json: status = "completed", completed_at = NOW_ISO
+
+Display summary: session ID, mode, raw/unique counts, per-perspective breakdown, severity breakdown.
+
+Next steps:
+  - manage-issue list --severity critical
+  - manage-issue list
+  - see also: /manage-issue-discover usage docs (by-prompt mode for focused scans)
+```
+
+---
+
+## Prompt-Driven Discovery (discover-by-prompt)
+
+### Step 7: Parse User Prompt
+
+```
+Extract USER_PROMPT from DISCOVERY_ARGS.
+If empty → prompt user to select focus area:
+  - Error handling gaps | API contract violations | Test coverage gaps | Custom
+```
+
+### Step 8: Plan Exploration Dimensions
+
+```
+Delegate to decompose USER_PROMPT into 3-5 exploration dimensions:
+
+  maestro delegate "Decompose into searchable dimensions: {USER_PROMPT}
+  EXPECTED: JSON array: [{ name, description, search_patterns[], file_patterns[], finding_criteria }]
+  " --role analyze --mode analysis
+
+Store → .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
+```
+
+### Step 9: Gather Codebase Context
+
+```
+Per dimension (prefer maestro explore over rg):
+  1. maestro explore "{dimension.description}" per dimension, parallel
+  2. Fallback: Semantic search via {search_tool} + rg for dimension.search_patterns
+  3. Collect matching files/snippets → {SESSION_ID}/{dimension.name}-context.md
+```
+
+### Step 10: Iterative Exploration Loop
+
+```
+Up to 3 rounds (exit early if no new gaps/findings):
+  Round 1: Analyze context → identify issues + coverage gaps
+  Round 2: maestro explore for gap patterns → search adjacent files → merge findings
+  Round 3: Final sweep on uncovered high-severity patterns + cross-module interactions
+
+Log per round → {SESSION_ID}/exploration-log.md:
+  Files analyzed, new/cumulative findings, remaining gaps.
+```
+
+### Step 11: Generate Issues from Findings
+
+```
+Deduplicate all findings (same logic as Step 5).
+Per unique finding → issue record (same structure as Step 6):
+  source = "discovery", tags = ["prompt-discovery", "{dimension.name}"]
+  context.notes = "Discovered via prompt: {USER_PROMPT}"
+
+Append to: issues.jsonl + discoveries/{SESSION_ID}/discovery-issues.jsonl
+Finalize discovery-state.json: status = "completed"
+
+Display summary: session, prompt, rounds, raw/unique counts, per-dimension + severity breakdown.
+
+Next steps:
+  - manage-issue list --source discovery
+  - see also: /manage-issue-discover usage docs (full 8-perspective scan and by-prompt mode)
+```
+
+---
+
+## Output
+
+- **Session artifacts**: `.workflow/issues/discoveries/{SESSION_ID}/`
+  - `discovery-state.json` -- session metadata and progress
+  - `discovery-issues.jsonl` -- issues found in this session
+  - `*-findings.json` -- raw findings per perspective (discover mode)
+  - `exploration-plan.json` -- dimensions (discover-by-prompt mode)
+  - `*-context.md` -- gathered context per dimension
+  - `exploration-log.md` -- round-by-round exploration log
+- **Issues**: appended to `.workflow/issues/issues.jsonl`
+
+## Quality Criteria
+
+- Multi-perspective mode covers all 8 analysis angles
+- Prompt-driven mode decomposes user intent into searchable dimensions
+- Findings backed by concrete file:line evidence
+- Deduplication prevents duplicate issue records
+- Discovery session fully traceable via session directory
+- All created issues follow the issue.json template schema
+- ID generation avoids collisions with existing issues

package/workflows/issue-execute.md

@@ -0,0 +1,110 @@
+# Workflow: Issue Execution
+
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-execute` command.
+> Use `maestro-execute` instead, which handles wave-based execution with automatic issue status sync.
+
+Execute a planned solution for an issue via dual-mode agent dispatch (server or direct CLI).
+
+## Input
+
+- `$ARGUMENTS`: `<ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]`
+- Operates on `.workflow/issues/`
+
+---
+
+### Step 1: Parse Arguments
+
+```
+Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
+Flags: --executor claude-code|codex|gemini (default: claude-code), --dry-run (default: false)
+```
+
+---
+
+### Step 2: Load Issue and Validate
+
+```
+Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
+Require issue.solution with non-empty steps[] → error if missing (run `maestro-plan --gaps {ISS-ID}` first).
+Resolve EXECUTOR → CLI tool (claude-code→claude, codex→codex, gemini→gemini), all with --mode write.
+```
+
+---
+
+### Step 3: Dry Run (if --dry-run)
+
+```
+If DRY_RUN: display prompt template, steps table (action | title | files),
+and context. No changes made. Exit before Step 4.
+```
+
+---
+
+### Step 4: Detect Execution Mode
+
+```
+Health check: curl http://127.0.0.1:3001/api/health
+  HTTP 200 → SERVER_UP (server dispatch) | otherwise → Direct CLI
+```
+
+---
+
+### Step 5a: Server UP Path
+
+```
+POST to http://127.0.0.1:3001/api/execution/dispatch:
+  { "issueId", "executor", "solution": { steps, context, promptTemplate } }
+
+Success (200/201) → server manages status lifecycle, skip to Step 6.
+Failure → fall through to Step 5b (direct CLI fallback).
+```
+
+### Step 5b: Server DOWN Path
+
+```
+Build EXEC_PROMPT from SOLUTION (promptTemplate + steps + context + constraints).
+
+Status transitions in issues.jsonl with issue_history entries:
+  1. Set status → in_progress (actor: EXECUTOR, note: "Execution started")
+  2. Execute: maestro delegate "{EXEC_PROMPT}" --to {CLI_TOOL} --mode write
+  3. On success → status = "resolved", resolved_at = NOW_ISO
+     On failure → status = "open" (revert, no stuck in_progress)
+
+Read-modify-write pattern preserves other issues.
+```
+
+---
+
+### Step 6: Display Result
+
+```
+Display: execution status (COMPLETE/FAILED), mode, executor, issue title, new status.
+  Server dispatch → show dispatch ID, "server managing lifecycle"
+  Direct CLI success → show modified files list
+  Failure → "reverted to open", suggest re-run or revise plan
+```
+
+---
+
+### Step 7: Suggest Next Steps
+
+```
+Success → close issue, view status, run tests
+Failure → retry with different executor, revise plan, re-analyze with --depth deep
+```
+
+---
+
+## Output
+
+- **Updated**: `.workflow/issues/issues.jsonl` -- issue status transitions (open -> in_progress -> resolved/open)
+- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct delegate (maestro delegate --mode write)
+
+## Quality Criteria
+
+- Dual-mode execution: server dispatch preferred, CLI fallback automatic
+- Dry-run mode shows full prompt without side effects
+- Status transitions recorded in issue_history with actor and timestamp
+- Failed execution reverts status to open (no stuck in_progress)
+- Read-modify-write pattern preserves other issues in JSONL
+- Next-step routing adapts based on success or failure

package/workflows/issue-gaps-analyze.codex.md

@@ -0,0 +1,256 @@
+# Workflow: Issue Gaps Analysis (Codex — CSV Wave)
+
+## Pipeline
+
+```
+Load Issues → Classify & Group → Generate tasks.csv → Wave 1: Explore (parallel per issue) → Wave 2: Synthesize (per group) → Write issue.analysis → Output context.md
+```
+
+---
+
+### Step 1: Load Issues
+
+```
+If ISS-ID provided:
+  Load single issue from .workflow/issues/issues.jsonl
+  → fatal if file missing or ID not found (E_ISSUE_NOT_FOUND)
+  → skip Step 2 (single issue = single group)
+
+If no ISS-ID:
+  Load all issues where status == "open" || status == "registered"
+  → fatal if none found (E_NO_ISSUES)
+```
+
+---
+
+### Step 2: Classify & Group (batch mode only)
+
+```
+Group loaded issues by affected area overlap:
+
+Classification dimensions:
+  - location: file path prefix (first 2 segments, e.g. src/auth/)
+  - component: affected_components field overlap
+  - category: issue.category or severity
+
+Grouping rules:
+  1. Same location prefix → same group
+  2. Shared affected_components → same group
+  3. Remaining ungrouped → individual groups (1 issue each)
+
+Output: GROUPS[] = { group_id, label, issues[], shared_keywords[] }
+
+Display group breakdown (skip if AUTO_YES).
+```
+
+---
+
+### Step 3: Generate tasks.csv
+
+Generate CSV with two waves:
+- **Wave 1**: One exploration row per issue (parallel within wave)
+- **Wave 2**: One synthesis row per group (parallel across groups, depends on its issues in wave 1)
+
+```csv
+id,title,description,iss_id,group_id,group_label,deps,context_from,wave,status,findings,analysis_json,error
+```
+
+**Wave 1 rows** — one per issue:
+
+```csv
+"1","Explore: ISS-xxx {title}","Root cause exploration for ISS-xxx: {description}. Location: {location}. Severity: {severity}. Fix hint: {fix_direction}. Search keywords: {keywords from title+description+components}. TASK: maestro explore keywords (preferred) or grep keywords → read top matches → trace call chain → identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix. EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }. CONSTRAINTS: Evidence-only, use file reads to verify.","ISS-xxx","G1","src/auth","","","1","","","",""
+```
+
+**Wave 2 rows** — one per group:
+
+```csv
+"N","Synthesize: {group_label}","Compile exploration findings for group [{group_label}]. For each issue: validate root cause evidence, identify cross-issue relationships, build analysis record. Output: JSON array [{ iss_id, root_cause, affected_files, impact_scope, fix_direction, confidence, cross_refs }]. Note shared root causes and dependency chains across issues in this group.","","G1","src/auth","1;2;3","1;2;3","2","","","",""
+```
+
+**Column definitions**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Unique task identifier |
+| `title` | Input | Short task title |
+| `description` | Input | Full exploration/synthesis instructions |
+| `iss_id` | Input | Issue ID (wave 1 only, empty for wave 2) |
+| `group_id` | Input | Group identifier |
+| `group_label` | Input | Group label for display |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `context_from` | Input | Task IDs whose findings this task needs |
+| `wave` | Input | 1 = explore, 2 = synthesize |
+| `status` | Output | `pending` → `completed` / `failed` |
+| `findings` | Output | Key findings summary (max 500 chars) |
+| `analysis_json` | Output | Structured analysis JSON (wave 2 only) |
+| `error` | Output | Error message if failed |
+
+Write `tasks.csv` to session folder.
+
+---
+
+### Step 4: Wave 1 — Explore (parallel per issue)
+
+Filter `wave == 1 && status == pending`. Write `wave-1.csv`.
+
+```javascript
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,
+  id_column: "id",
+  instruction: `You are analyzing a specific issue for root cause. Read the 'description' column for full instructions. Use file reads and grep to gather evidence. Write findings as a concise summary with file:line references. Write analysis_json as a JSON object: { root_cause, impact, related_files[], confidence, suggested_approach }.`,
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
+  output_schema: { id, status: ["completed"|"failed"], findings, analysis_json, error }
+})
+```
+
+Merge results into master `tasks.csv`, delete `wave-1.csv`.
+
+**Per-issue agent responsibilities**:
+1. **Keyword Search** — grep issue keywords in source, find top 20 relevant paths
+2. **Context Read** — read top 5 matches with 10 lines surrounding context
+3. **Call Chain Trace** — trace 2-3 levels from issue location
+4. **Root Cause Identification** — pinpoint file:line with evidence
+5. **Impact Assessment** — scope of affected functionality
+
+---
+
+### Step 5: Wave 2 — Synthesize (parallel per group)
+
+Filter `wave == 2 && status == pending`. Build `prev_context` from wave 1 findings of issues in same group. Write `wave-2.csv` with `prev_context` column.
+
+```javascript
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep:
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-2.csv`,
+  id_column: "id",
+  instruction: `You are synthesizing root cause analysis for a group of related issues. Read prev_context for per-issue exploration findings. Validate evidence, identify cross-issue relationships and shared root causes. Output analysis_json as a JSON array: [{ iss_id, root_cause, affected_files, impact_scope, fix_direction, confidence, cross_refs }].`,
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-2-results.csv`,
+  output_schema: { id, status: ["completed"|"failed"], findings, analysis_json, error }
+})
+```
+
+Merge results into master `tasks.csv`, delete `wave-2.csv`.
+
+**Synthesis agent responsibilities**:
+1. Parse per-issue findings from prev_context
+2. Validate root cause evidence (file:line exists, logic holds)
+3. Identify cross-issue relationships within group
+4. Build consolidated analysis array with cross_refs
+5. Flag shared root causes that affect multiple issues
+
+---
+
+### Step 6: Write Analysis to issues.jsonl
+
+```
+Parse analysis_json from wave 2 results.
+
+For each issue in the analysis array:
+  Build IssueAnalysis record:
+    {
+      root_cause,
+      affected_files,
+      impact_scope,
+      fix_direction,
+      confidence,
+      cross_refs,
+      analyzed_at: NOW_ISO,
+      tool: "spawn_agents_on_csv",
+      depth: DEPTH
+    }
+
+  Read-modify-write issues.jsonl (single pass):
+    Set issue.analysis = ANALYSIS, updated_at = NOW_ISO
+    Append issue.history: { action: "analyzed", at: NOW_ISO, by: "maestro-analyze --gaps" }
+    Status unchanged (non-destructive enrichment).
+
+Verify: re-read, confirm analysis field present for all updated issues.
+```
+
+---
+
+### Step 7: Output context.md
+
+```
+Aggregate results organized by group:
+
+  # Context: Issue Gaps Analysis
+
+  **Date**: {date}
+  **Issues analyzed**: {count}
+  **Groups**: {group_count}
+  **Session**: {sessionFolder}
+
+  ## Group: {group.label}
+
+  ### ISS-{id}: {title}
+  - **Root cause**: {root_cause}
+  - **Affected files**: {affected_files}
+  - **Impact scope**: {impact_scope}
+  - **Fix direction**: {fix_direction}
+  - **Confidence**: {confidence}
+  - **Cross-refs**: {related ISS-IDs}
+
+  (repeat per issue, per group)
+
+  ## Cross-Group Dependencies
+  {issues sharing root causes across groups}
+
+  ## Constraints
+
+  ### Locked
+  {constraints from root cause evidence}
+
+  ### Free
+  {implementation choices left to planner}
+
+Write context.md to session folder + copy to scratchDir.
+Register artifact in state.json.
+```
+
+---
+
+### Step 8: Display Summary and Next Steps
+
+```
+Display: group breakdown, per-issue root cause, confidence, cross-refs.
+
+Next steps:
+  - maestro-plan --gaps (plan fix tasks linked to analyzed issues)
+  - maestro-analyze --gaps {ISS-ID} (re-analyze specific issue)
+  - manage-issue list (review all issues)
+```
+
+---
+
+## Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/
+├── tasks.csv            # master state
+├── results.csv          # final export
+├── wave-1.csv           # temporary (deleted after merge)
+├── wave-2.csv           # temporary (deleted after merge)
+├── discoveries.ndjson   # shared board (append-only)
+├── context.md           # decisions for plan --gaps
+```
+
+## Output
+
+- **Updated**: `.workflow/issues/issues.jsonl` — enriched with `analysis` field per issue
+- **Created**: `context.md` — grouped root causes for downstream `plan --gaps`
+- **Created**: `results.csv` — full task execution results
+
+## Quality Criteria
+
+- Issues classified into groups before CSV generation
+- Wave 1 agents run parallel (one per issue, bounded by maxConcurrency)
+- Wave 2 agents run parallel (one per group, after wave 1 deps met)
+- Cross-issue relationships captured via cross_refs
+- Single-pass JSONL update preserves integrity
+- context.md organized by group with cross-group section