maestro-flow 0.1.0

package/workflows/issue-discover.md

@@ -0,0 +1,414 @@
+# 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
+
+```
+1. Extract mode from $ARGUMENTS:
+   - empty or no arguments → MULTI_PERSPECTIVE mode (Step 3)
+   - "by-prompt" → PROMPT_DRIVEN mode (Step 7)
+
+2. Remaining tokens after mode keyword = DISCOVERY_ARGS
+   For by-prompt: join remaining tokens as USER_PROMPT
+```
+
+---
+
+### Step 2: Validate Environment
+
+```
+1. Check .workflow/ exists
+   If not → fatal: "No project initialized. Run /maestro-init first."
+
+2. Check .workflow/issues/ exists
+   If not → mkdir -p .workflow/issues/
+
+3. Ensure issues.jsonl exists
+   If not → touch .workflow/issues/issues.jsonl
+
+4. Generate discovery session ID:
+   DBP-{YYYYMMDD}-{HHmmss}
+
+5. Create discovery session directory:
+   mkdir -p .workflow/issues/discoveries/{SESSION_ID}/
+
+6. 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 execution
+```
+
+Pass to each analysis agent so severity assessments align with project quality standards.
+
+---
+
+### Step 4: Launch Parallel Analysis
+
+```
+Launch analysis agents in batches of up to 4 concurrent:
+
+Batch 1: security, performance, reliability, maintainability
+Batch 2: scalability, ux, accessibility, compliance
+
+For each perspective, launch a CLI analysis:
+
+  maestro cli -p "PURPOSE: Discover {PERSPECTIVE} issues in the codebase.
+  Focus: {FOCUS_AREA}
+  Guiding question: {QUESTION}
+
+  TASK:
+  - Scan all source files for {PERSPECTIVE}-related problems
+  - Identify concrete issues with file:line references
+  - Rate each finding: critical / high / medium / low severity
+  - Provide brief fix direction for each finding
+
+  MODE: analysis
+  CONTEXT: @**/*
+  EXPECTED: JSON array of findings, each with:
+    title, severity, description, location (file:line), fix_direction, affected_components[]
+  CONSTRAINTS: Only report real issues with evidence, no speculative findings
+  " --tool gemini --mode analysis
+
+Store results per perspective in:
+  .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
+
+Update discovery-state.json:
+  perspectives_completed += ["{PERSPECTIVE}"]
+```
+
+### Step 5: Deduplicate Findings
+
+```
+1. Load all *-findings.json from the session directory
+2. Merge all findings into a single list
+3. Deduplicate by similarity:
+   - Group findings by affected file path
+   - Within each file group, compare descriptions
+   - If two findings describe the same issue (>80% description overlap
+     or same file:line), keep the one with higher severity
+4. Track: issues_found (pre-dedup), issues_deduplicated (post-dedup)
+5. Update discovery-state.json with counts
+```
+
+### Step 6: Create Issues from Findings
+
+```
+For each unique finding:
+1. Generate ISS-YYYYMMDD-NNN ID (same logic as create handler in issue.md)
+2. Build issue record:
+   {
+     "id": "{ID}",
+     "title": "{finding.title}",
+     "status": "registered",
+     "priority": {severity_to_priority},
+     "severity": "{finding.severity}",
+     "source": "discovery",
+     "phase_ref": null,
+     "gap_ref": null,
+     "description": "{finding.description}",
+     "fix_direction": "{finding.fix_direction}",
+     "context": {
+       "location": "{finding.location}",
+       "suggested_fix": "",
+       "notes": "Discovered by {PERSPECTIVE} analysis in session {SESSION_ID}"
+     },
+     "tags": ["{PERSPECTIVE}"],
+     "affected_components": {finding.affected_components},
+     "feedback": [],
+     "issue_history": [
+       {
+         "timestamp": "{NOW_ISO}",
+         "from_status": null,
+         "to_status": "registered",
+         "actor": "discovery-agent",
+         "note": "Auto-discovered via {PERSPECTIVE} perspective"
+       }
+     ],
+     "created_at": "{NOW_ISO}",
+     "updated_at": "{NOW_ISO}",
+     "resolved_at": null,
+     "resolution": null
+   }
+
+   Severity-to-priority mapping:
+     critical → 1
+     high     → 2
+     medium   → 3
+     low      → 4
+
+3. Append to .workflow/issues/issues.jsonl
+4. Also append to .workflow/issues/discoveries/{SESSION_ID}/discovery-issues.jsonl
+
+5. Update discovery-state.json:
+   status = "completed"
+   completed_at = NOW_ISO
+
+6. Display summary:
+   ====================================================
+     DISCOVERY COMPLETE: {SESSION_ID}
+     Mode: multi-perspective (8 perspectives)
+     Findings: {issues_found} raw, {issues_deduplicated} unique
+     Issues created: {issues_deduplicated}
+   ====================================================
+
+   BREAKDOWN BY PERSPECTIVE:
+     Security:        {count}
+     Performance:     {count}
+     Reliability:     {count}
+     Maintainability: {count}
+     Scalability:     {count}
+     UX:              {count}
+     Accessibility:   {count}
+     Compliance:      {count}
+
+   BREAKDOWN BY SEVERITY:
+     Critical: {count}
+     High:     {count}
+     Medium:   {count}
+     Low:      {count}
+
+7. Suggest next steps:
+   - Skill({ skill: "manage-issue", args: "list --severity critical" }) -- Review critical issues
+   - Skill({ skill: "manage-issue", args: "list" }) -- View all issues
+   - Skill({ skill: "manage-issue-discover", args: "by-prompt \"...\"" }) -- Explore specific area deeper
+```
+
+---
+
+## Prompt-Driven Discovery (discover-by-prompt)
+
+### Step 7: Parse User Prompt
+
+```
+1. Extract USER_PROMPT from DISCOVERY_ARGS
+   If empty → AskUserQuestion({
+     question: "What kind of issues should I look for?",
+     options: [
+       { label: "Error handling gaps", description: "Missing try/catch, unhandled promises, swallowed errors" },
+       { label: "API contract violations", description: "Mismatched types, missing validation, undocumented endpoints" },
+       { label: "Test coverage gaps", description: "Untested code paths, missing edge cases" },
+       { label: "Custom", description: "Describe what to look for" }
+     ]
+   })
+
+2. Store USER_PROMPT for exploration context
+```
+
+### Step 8: Plan Exploration Dimensions
+
+```
+Use Gemini CLI to decompose the user prompt into exploration dimensions:
+
+  maestro cli -p "PURPOSE: Decompose this issue discovery prompt into 3-5 specific exploration dimensions.
+
+  User wants to find: {USER_PROMPT}
+
+  TASK:
+  - Break down the prompt into concrete, searchable dimensions
+  - For each dimension: provide search patterns (regex/keywords), file patterns, and what constitutes a finding
+  - Output as JSON array of dimensions
+
+  MODE: analysis
+  EXPECTED: JSON array:
+    [{
+      name: string,
+      description: string,
+      search_patterns: string[],
+      file_patterns: string[],
+      finding_criteria: string
+    }]
+  " --tool gemini --mode analysis
+
+Store dimensions in:
+  .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
+```
+
+### Step 9: Gather Codebase Context
+
+```
+For each exploration dimension:
+
+1. Use @~/.maestro/templates/search-tool.json for semantic search:
+   {search_tool}(
+     project_root_path="{PROJECT_ROOT}",
+     query="{dimension.description}"
+   )
+
+2. Use ripgrep for pattern-based search:
+   For each pattern in dimension.search_patterns:
+     rg "{pattern}" --type-add "src:*.{ts,tsx,js,jsx,py,java,go}" --type src -n
+
+3. Collect matching files and code snippets
+4. Store context per dimension in:
+   .workflow/issues/discoveries/{SESSION_ID}/{dimension.name}-context.md
+```
+
+### Step 10: Iterative Exploration Loop
+
+```
+Max 3 rounds of exploration:
+
+Round 1: Initial analysis
+  - Analyze gathered context from Step 9
+  - Identify concrete issues with evidence
+  - Identify gaps in coverage (areas not yet explored)
+
+Round 2: Deepen search (if gaps found)
+  - For each identified gap:
+    - Refine search patterns
+    - Search adjacent files/modules
+    - Cross-reference with related code
+  - Merge new findings with Round 1
+
+Round 3: Final sweep (if significant gaps remain)
+  - Focus on high-severity patterns not yet covered
+  - Check cross-module interactions
+  - Finalize findings list
+
+After each round:
+  - Log findings count and coverage assessment
+  - If no new gaps or no new findings → exit loop early
+
+Store exploration log:
+  .workflow/issues/discoveries/{SESSION_ID}/exploration-log.md
+
+  ## Round {N}
+  - Files analyzed: {count}
+  - Findings: {count} new, {total} cumulative
+  - Gaps remaining: {list or "none"}
+```
+
+### Step 11: Generate Issues from Findings
+
+```
+1. Collect all findings from exploration rounds
+2. Deduplicate (same logic as Step 5):
+   - Group by affected file
+   - Merge similar descriptions
+   - Keep higher-severity duplicate
+
+3. For each unique finding:
+   - Generate ISS-YYYYMMDD-NNN ID
+   - Build issue record (same structure as Step 6)
+   - Set source = "discovery"
+   - Set tags = ["prompt-discovery", "{relevant dimension name}"]
+   - Set context.notes = "Discovered via prompt: {USER_PROMPT}"
+
+4. Append to .workflow/issues/issues.jsonl
+5. Append to .workflow/issues/discoveries/{SESSION_ID}/discovery-issues.jsonl
+
+6. Update discovery-state.json:
+   status = "completed"
+   completed_at = NOW_ISO
+
+7. Display summary:
+   ====================================================
+     DISCOVERY COMPLETE: {SESSION_ID}
+     Mode: prompt-driven
+     Prompt: "{USER_PROMPT}"
+     Rounds: {rounds_executed}
+     Findings: {raw_count} raw, {deduped_count} unique
+     Issues created: {deduped_count}
+   ====================================================
+
+   FINDINGS BY DIMENSION:
+     {dimension.name}: {count}
+     ...
+
+   BREAKDOWN BY SEVERITY:
+     Critical: {count}
+     High:     {count}
+     Medium:   {count}
+     Low:      {count}
+
+8. Suggest next steps:
+   - Skill({ skill: "manage-issue", args: "list --source discovery" }) -- View discovered issues
+   - Skill({ skill: "manage-issue-discover" }) -- Run full 8-perspective scan
+   - Skill({ skill: "manage-issue-discover", args: "by-prompt \"...\"" }) -- Explore another area
+```
+
+---
+
+## 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,286 @@
+# Workflow: Issue Execution
+
+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
+
+```
+1. Extract ISS-ID from first positional token in $ARGUMENTS
+   If empty → error E_NO_ISSUE_ID:
+     "Usage: /manage-issue-execute <ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]"
+     "Example: /manage-issue-execute ISS-20260318-001 --executor codex --dry-run"
+
+2. Parse optional flags:
+   --executor VALUE  → EXECUTOR (default: claude-code)
+   --dry-run         → DRY_RUN = true (default: false)
+
+3. Validate:
+   - ISS-ID matches pattern ISS-\d{8}-\d{3}
+   - EXECUTOR is one of: claude-code, codex, gemini
+```
+
+---
+
+### 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_NO_ISSUE_ID:
+     "Issue {ISS-ID} not found. Run /manage-issue list to see available issues."
+
+4. Check issue.solution exists and is not null:
+   If null → error E_NO_SOLUTION:
+     "Issue {ISS-ID} has no solution plan."
+     "Run first: /manage-issue-plan {ISS-ID}"
+
+5. Validate solution.steps is a non-empty array
+   If empty → error E_NO_SOLUTION:
+     "Solution plan has no steps. Re-run: /manage-issue-plan {ISS-ID}"
+
+6. Resolve EXECUTOR to CLI tool mapping:
+   - claude-code → claude (--tool claude --mode write)
+   - codex → codex (--tool codex --mode write)
+   - gemini → gemini (--tool gemini --mode write)
+
+7. Store issue record as ISSUE, solution as SOLUTION
+```
+
+---
+
+### Step 3: Dry Run (if --dry-run)
+
+```
+If DRY_RUN == true:
+
+  Display preview:
+
+  ====================================================
+    DRY RUN: {ISS-ID}
+    Executor: {EXECUTOR}
+    Steps: {SOLUTION.steps.length}
+  ====================================================
+
+  PROMPT TEMPLATE:
+    {SOLUTION.promptTemplate}
+
+  SOLUTION STEPS:
+  ---------------------------------------------------------------
+  #  | Action  | Title                          | Files
+  ---------------------------------------------------------------
+  {for each step in SOLUTION.steps}
+  {index} | {step.action} | {step.title} | {step.files joined by ", "}
+  {/for}
+  ---------------------------------------------------------------
+
+  CONTEXT:
+    {SOLUTION.context}
+
+  ====================================================
+  This is a dry run. No changes were made.
+  To execute: /manage-issue-execute {ISS-ID} --executor {EXECUTOR}
+  ====================================================
+
+  Exit (do not proceed to Steps 4-7).
+```
+
+---
+
+### Step 4: Detect Execution Mode
+
+```
+1. Check if maestro dashboard server is running:
+   curl http://127.0.0.1:3001/api/health --connect-timeout 2 -s -o /dev/null -w "%{http_code}"
+
+2. If HTTP 200 → SERVER_UP = true
+   Otherwise → SERVER_UP = false
+
+3. Log execution mode:
+   "Execution mode: {SERVER_UP ? 'Server dispatch' : 'Direct CLI'}"
+```
+
+---
+
+### Step 5a: Server UP Path
+
+```
+If SERVER_UP == true:
+
+1. Build dispatch payload:
+   {
+     "issueId": "{ISS-ID}",
+     "executor": "{EXECUTOR}",
+     "solution": {
+       "steps": {SOLUTION.steps},
+       "context": "{SOLUTION.context}",
+       "promptTemplate": "{SOLUTION.promptTemplate}"
+     }
+   }
+
+2. POST to server:
+   curl -X POST http://127.0.0.1:3001/api/execution/dispatch \
+     -H "Content-Type: application/json" \
+     -d '{PAYLOAD_JSON}' \
+     --connect-timeout 5 -s
+
+3. Parse response:
+   - If HTTP 200/201 → DISPATCH_SUCCESS = true, store response as DISPATCH_RESULT
+   - If error → DISPATCH_SUCCESS = false, fall through to Step 5b
+
+4. If DISPATCH_SUCCESS:
+   - Do NOT update JSONL manually (server manages status)
+   - Store DISPATCH_RESULT for display in Step 6
+   - Skip to Step 6
+
+5. If DISPATCH_FAILED:
+   - Log: "Server dispatch failed, falling back to direct CLI execution"
+   - Proceed to Step 5b
+```
+
+### Step 5b: Server DOWN Path
+
+```
+If SERVER_UP == false (or server dispatch failed):
+
+1. Build execution prompt from SOLUTION:
+   EXEC_PROMPT = "{SOLUTION.promptTemplate}
+
+   SOLUTION STEPS:
+   {for each step in SOLUTION.steps}
+   {index}. [{step.action}] {step.title}
+      Files: {step.files joined by ', '}
+      Description: {step.description}
+   {/for}
+
+   CONTEXT: {SOLUTION.context}
+
+   ISSUE: {ISS-ID} - {ISSUE.title}
+   CONSTRAINTS: Follow solution steps in order. Verify each step before proceeding."
+
+2. Update JSONL: Set issue status → in_progress
+   - Read all lines from .workflow/issues/issues.jsonl
+   - Update matching record:
+     status = "in_progress"
+     updated_at = NOW_ISO
+     Add issue_history entry:
+       {
+         "timestamp": "{NOW_ISO}",
+         "from_status": "{ISSUE.status}",
+         "to_status": "in_progress",
+         "actor": "{EXECUTOR}",
+         "note": "Execution started (direct CLI)"
+       }
+   - Rewrite file
+
+3. Execute via CLI:
+   maestro cli -p "{EXEC_PROMPT}" --tool {CLI_TOOL} --mode write
+
+4. Evaluate result:
+   - If CLI exits successfully → EXEC_SUCCESS = true
+   - If CLI fails → EXEC_SUCCESS = false
+
+5. Update JSONL based on result:
+   If EXEC_SUCCESS:
+     status = "resolved"
+     resolved_at = NOW_ISO
+     updated_at = NOW_ISO
+     Add issue_history entry:
+       {
+         "timestamp": "{NOW_ISO}",
+         "from_status": "in_progress",
+         "to_status": "resolved",
+         "actor": "{EXECUTOR}",
+         "note": "Solution executed successfully"
+       }
+
+   If EXEC_FAILED:
+     status = "open"
+     updated_at = NOW_ISO
+     Add issue_history entry:
+       {
+         "timestamp": "{NOW_ISO}",
+         "from_status": "in_progress",
+         "to_status": "open",
+         "actor": "{EXECUTOR}",
+         "note": "Execution failed — reverted to open"
+       }
+   - Rewrite JSONL file
+
+6. Store result for display
+```
+
+---
+
+### Step 6: Display Result
+
+```
+Display execution summary:
+
+====================================================
+  EXECUTION {EXEC_SUCCESS or DISPATCH_SUCCESS ? "COMPLETE" : "FAILED"}: {ISS-ID}
+  Mode: {SERVER_UP ? "Server dispatch" : "Direct CLI"}
+  Executor: {EXECUTOR}
+====================================================
+
+ISSUE: {ISSUE.title}
+STATUS: {new status}
+
+{If SERVER_UP and DISPATCH_SUCCESS}
+  Dispatch ID: {DISPATCH_RESULT.id or "N/A"}
+  Server is managing execution lifecycle.
+
+{If not SERVER_UP and EXEC_SUCCESS}
+  Solution applied successfully.
+  Files modified: {list from SOLUTION.steps[].files}
+
+{If failure}
+  Execution failed. Issue reverted to open status.
+  Review the error output above and consider:
+  - Re-running with a different executor
+  - Revising the solution plan
+
+====================================================
+```
+
+---
+
+### Step 7: Suggest Next Steps
+
+```
+If execution succeeded:
+  - Skill({ skill: "manage-issue", args: "close {ISS-ID} --resolution \"Fixed via {EXECUTOR} execution\"" }) -- Close the issue
+  - Skill({ skill: "manage-issue", args: "status {ISS-ID}" }) -- View updated issue
+  - Skill({ skill: "quality-test", args: "" }) -- Run tests to verify fix
+
+If execution failed:
+  - Skill({ skill: "manage-issue-execute", args: "{ISS-ID} --executor codex" }) -- Retry with different executor
+  - Skill({ skill: "manage-issue-plan", args: "{ISS-ID}" }) -- Revise solution plan
+  - Skill({ skill: "manage-issue-analyze", args: "{ISS-ID} --depth deep" }) -- Re-analyze with deeper context
+  - Skill({ skill: "manage-issue", args: "status {ISS-ID}" }) -- View current issue state
+```
+
+---
+
+## Output
+
+- **Updated**: `.workflow/issues/issues.jsonl` -- issue status transitions (open -> in_progress -> resolved/open)
+- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct CLI (maestro cli --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