pi-maestro-flow 0.2.0 → 0.3.1

package/workflows/issue-gaps-analyze.md

@@ -0,0 +1,215 @@
+# Workflow: Issue Gaps Analysis
+
+> **CLI variants**: see `issue-gaps-analyze.codex.md` for codex-specific notes (CSV-wave variant using `spawn_agents_on_csv`).
+
+Root cause analysis for issues using CLI exploration and codebase context gathering.
+Supports single issue (ISS-ID) or batch (all open/registered) with classification and parallel analysis.
+Produces analysis records in issues.jsonl and context.md for downstream `plan --gaps`.
+
+**Invoked by**: `maestro-analyze --gaps [ISS-ID]`
+
+## Input
+
+- `ISS-ID` (optional): Specific issue to analyze. If omitted, analyze all open/registered issues.
+- `TOOL`: CLI tool for exploration (default: gemini)
+- `DEPTH`: `standard` or `deep` (default: standard)
+
+## Pipeline
+
+```
+Load Issues → Classify & Group → Parallel Analysis (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 (classification), go directly to Step 3
+
+If no ISS-ID:
+  Load all issues where status == "open" || status == "registered"
+  → fatal if none found (E_NO_ISSUES)
+
+Validate: at least 1 issue loaded.
+```
+
+---
+
+### Step 2: Classify & Group (batch mode only)
+
+```
+Group loaded issues by overlap in affected area:
+
+Classification dimensions:
+  - location: file path prefix (e.g. src/auth/, src/api/)
+  - component: affected_components field overlap
+  - category: issue.category or severity level
+
+Grouping rules:
+  1. Same location prefix (first 2 path segments) → same group
+  2. Shared affected_components → same group
+  3. Remaining ungrouped → individual groups (1 issue each)
+
+Output: GROUPS[] where each group = { group_id, label, issues[], shared_context_keywords[] }
+
+Display group breakdown to user (skip if AUTO_YES).
+```
+
+---
+
+### Step 3: Gather Codebase Context (per group)
+
+```
+For each group:
+  Merge keywords from all issues in group: title, description, location, affected_components.
+  Deduplicate keywords.
+
+  Standard depth: maestro explore per group (keywords as prompt), fallback grep; flag analysis as [LOW CONFIDENCE] (grep fallback, semantic depth lost).
+  Deep depth: maestro explore multi-prompt + semantic Agent search (error handling,
+    data flow, deps), merge results.
+
+  Build GROUP_CONTEXT: related files, key snippets (max 50 lines), dependency chain.
+  Shared context benefits co-located issues — avoids redundant exploration.
+```
+
+---
+
+### Step 4: Run Analysis (per group, parallel across groups)
+
+```
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Launch analysis for each group in parallel using Agent tool:
+
+  Agent({
+    subagent_type: "general-purpose",
+    prompt: "Root cause analysis for issues in group [{group.label}]:
+      {for each issue in group}
+        ISS-{id}: {title} — {description}, severity: {severity}, location: {location}
+      {end}
+      CODEBASE CONTEXT: {GROUP_CONTEXT}
+      TASK: For EACH issue — identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix direction. Note cross-issue relationships within this group.
+      EXPECTED: JSON array [{ iss_id, root_cause, impact, related_files[], confidence, suggested_approach, cross_refs[] }]
+      CONSTRAINTS: Evidence-only, no speculation. Use Read/Grep to verify before concluding."
+  })
+
+Alternatively, attempt CLI delegate first per group:
+
+  MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: maestro delegate "<same prompt>" --role analyze --mode analysis
+
+  If delegate fails (timeout, unavailable, parse error):
+    Fall back to Agent tool with same prompt; set analysis confidence=low and flag as [LOW CONFIDENCE] (delegate failed).
+    Record fallback in analysis metadata: { tool: "agent-fallback", reason: "<error>" }
+
+Validate response per issue: all required fields present.
+Parse failure → save raw output to issue feedback for review.
+```
+
+---
+
+### Step 5: Build Analysis Record (per issue)
+
+```
+For each issue from Step 4 results:
+
+Construct IssueAnalysis:
+  {
+    root_cause,
+    affected_files: related_files,
+    impact_scope: impact,
+    fix_direction: suggested_approach,
+    confidence,
+    cross_refs: [ISS-IDs of related issues in same group],
+    analyzed_at: NOW_ISO,
+    tool: TOOL or "agent-fallback",
+    depth: DEPTH
+  }
+```
+
+---
+
+### Step 6: Update Issues in JSONL
+
+```
+Read-modify-write issues.jsonl (single pass for all analyzed issues):
+  For each issue:
+    Set issue.analysis = ANALYSIS, updated_at = NOW_ISO
+    Append issue.history: { action: "analyzed", at: NOW_ISO, by: "maestro-analyze --gaps" }
+    Status unchanged (analysis is metadata enrichment).
+Verify: re-read file, confirm analysis field present for all updated issues.
+```
+
+---
+
+### Step 7: Output context.md
+
+```
+Aggregate all analyzed issues into context.md, organized by group:
+
+  # Context: Issue Gaps Analysis
+
+  **Date**: {date}
+  **Issues analyzed**: {count}
+  **Groups**: {group_count}
+
+  ## 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 that span multiple groups or share root causes}
+
+  ## Constraints
+
+  ### Locked
+  {constraints derived from root cause evidence}
+
+  ### Free
+  {implementation choices left to planner}
+
+Write context.md to session output directory.
+```
+
+---
+
+### 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 with deeper context)
+  - manage-issue list (review all issues)
+```
+
+---
+
+## Output
+
+- **Updated**: `.workflow/issues/issues.jsonl` -- issue records enriched with `analysis` field
+- **Created**: `context.md` -- aggregated root causes grouped for downstream `plan --gaps`
+- **Analysis fields**: root_cause, affected_files, impact_scope, fix_direction, confidence, cross_refs, analyzed_at, tool, depth
+
+## Quality Criteria
+
+- Issues classified by location/component overlap before analysis
+- Groups analyzed in parallel (Agent or delegate per group)
+- CLI delegate attempted first; Agent fallback on failure
+- Analysis grounded in actual codebase evidence (file:line references)
+- Cross-issue relationships captured within groups (cross_refs)
+- JSON result validated before writing to JSONL
+- Issue status unchanged (analysis is non-destructive enrichment)
+- Single-pass read-modify-write preserves JSONL integrity
+- context.md organized by group with cross-group dependencies
+- Next-step routing guides to plan --gaps

package/workflows/issue-plan.md

@@ -0,0 +1,110 @@
+# Workflow: Issue Planning
+
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-plan` command.
+> Use `maestro-plan --gaps` instead, which generates TASK files linked to issues via `task_refs`.
+
+Solution planning for a specific issue with codebase-aware step generation and prompt template construction.
+
+## Input
+
+- `$ARGUMENTS`: `<ISS-ID> [--tool gemini|qwen] [--from-analysis]`
+- Operates on `.workflow/issues/`
+
+---
+
+### Step 1: Parse Arguments
+
+```
+Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
+Flags: --tool gemini|qwen (default: gemini), --from-analysis (default: auto-detect)
+```
+
+---
+
+### Step 2: Load Issue and Validate
+
+```
+Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
+Status check: open/registered → proceed; other → warn but continue (non-destructive).
+If solution already exists → confirm overwrite with user (abort if declined).
+```
+
+---
+
+### Step 3: Load Analysis Context
+
+```
+If ISSUE.analysis exists → build ANALYSIS_CONTEXT from root_cause, impact,
+related_files, confidence, suggested_approach.
+If null and --from-analysis explicit → warn (suggest running analyze first).
+Otherwise ANALYSIS_CONTEXT = "" (proceed without).
+```
+
+---
+
+### Step 4: Generate Solution via CLI
+
+```
+Delegate planning prompt with issue details + ANALYSIS_CONTEXT:
+
+  MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: maestro delegate "Generate step-by-step solution for {ISS-ID}: {ISSUE.title}
+  ISSUE: title, description, severity, location, fix_direction
+  {ANALYSIS_CONTEXT}
+  TASK: Break into atomic steps with action types (create|modify|delete|test)
+  EXPECTED: JSON { steps: [{ title, description, files[], action }], context, promptTemplate }
+  CONSTRAINTS: Concrete, file-specific steps
+  " --to {TOOL} --mode analysis
+
+Validate response: steps[] non-empty, each with title/description/files/action.
+Parse failure → save raw output to issue feedback for review.
+```
+
+---
+
+### Step 5: Build Solution Record
+
+```
+Construct IssueSolution:
+  { steps, context, promptTemplate, planned_at: NOW_ISO, planned_by: TOOL }
+```
+
+---
+
+### Step 6: Update Issue in JSONL
+
+```
+Read-modify-write issues.jsonl:
+  Set issue.solution = SOLUTION, updated_at = NOW_ISO
+  Append issue_history: actor "planning-agent", note "{N} steps generated"
+  Status unchanged (planning is metadata enrichment).
+Verify: re-read file, confirm solution field present.
+```
+
+---
+
+### Step 7: Display Solution Steps Table and Next Steps
+
+```
+Display: approach summary, steps table (# | action | title | files), prompt template.
+
+Next steps:
+  - manage-issue-execute {ISS-ID} (execute | --dry-run | --executor codex)
+  - manage-issue status {ISS-ID}
+```
+
+---
+
+## Output
+
+- **Updated**: `.workflow/issues/issues.jsonl` -- issue record enriched with `solution` field
+- **Solution fields**: steps[], context, promptTemplate, planned_at, planned_by
+
+## Quality Criteria
+
+- Solution steps are concrete with specific file targets and action types
+- Analysis context included when available for better accuracy
+- Prompt template is self-contained and executable by an agent
+- JSON result validated before writing to JSONL
+- Issue status unchanged (planning is non-destructive enrichment)
+- Read-modify-write pattern preserves other issues in JSONL
+- Next-step routing guides user to execution

package/workflows/issue.md

@@ -0,0 +1,338 @@
+# Workflow: Issue Management
+
+CRUD operations and lifecycle management for project issues.
+
+## Input
+
+- `$ARGUMENTS`: subcommand + options
+- Operates on `.workflow/issues/`
+
+---
+
+### Step 1: Parse Subcommand
+
+```
+Extract SUBCOMMAND (first token) and ARGS (remaining) from $ARGUMENTS.
+Valid: create | list | status | update | close | link
+Missing/invalid → error with usage: /manage-issue <create|list|status|update|close|link> [options]
+```
+
+---
+
+### Step 2: Validate Issues Directory
+
+```
+Require .workflow/ exists → fatal if missing: "No project initialized. Run /maestro-init first."
+Auto-create if missing: .workflow/issues/, issues.jsonl, issue-history.jsonl
+```
+
+---
+
+### Step 3: Route to Subcommand Handler
+
+```
+Route: create→Step 4, list→Step 5, status→Step 6, update→Step 7, close→Step 8, link→Step 9
+```
+
+---
+
+### Step 4: Create Issue
+
+Parse options from ARGS:
+
+```
+Options:
+  --title TEXT        Issue title (required)
+  --severity VALUE    critical|high|medium|low (default: medium)
+  --source VALUE      planned|supplement|bug|review|verification|discovery|manual (default: manual)
+  --phase VALUE       Phase reference, e.g. "01-auth" (optional)
+  --milestone VALUE   Milestone reference, e.g. "MVP" (optional, auto-derived from state.json if omitted)
+  --description TEXT  Detailed description (optional, prompted if missing)
+  --priority NUMBER   1-5, lower is higher priority (default: 3)
+  --tags TAG1,TAG2    Comma-separated tags (optional)
+
+If --title is missing:
+  AskUserQuestion({ question: "What is the issue title?" })
+
+Derive milestone_ref if not provided:
+  IF --milestone not provided AND file_exists(".workflow/state.json"):
+    milestone_ref = state.json.current_milestone
+  ELSE:
+    milestone_ref = --milestone value or null
+```
+
+Generate issue ID:
+
+```
+ID = ISS-{YYYYMMDD}-{NNN} where NNN = next available 3-digit sequence for today
+Scan both issues.jsonl and issue-history.jsonl to avoid collisions.
+```
+
+Build issue record from template:
+
+```json
+{
+  "id": "{ID}",
+  "title": "{TITLE}",
+  "status": "open",
+  "priority": {PRIORITY},
+  "severity": "{SEVERITY}",
+  "source": "{SOURCE}",
+  "milestone_ref": "{MILESTONE_REF or null}",
+  "phase_ref": "{PHASE_REF or null}",
+  "gap_ref": null,
+  "description": "{DESCRIPTION}",
+  "fix_direction": "",
+  "context": {
+    "location": "",
+    "suggested_fix": "",
+    "notes": ""
+  },
+  "tags": ["{TAGS}"],
+  "affected_components": [],
+  "feedback": [],
+  "issue_history": [
+    {
+      "timestamp": "{NOW_ISO}",
+      "from_status": null,
+      "to_status": "open",
+      "actor": "user",
+      "note": "Issue created"
+    }
+  ],
+  "created_at": "{NOW_ISO}",
+  "updated_at": "{NOW_ISO}",
+  "resolved_at": null,
+  "resolution": null
+}
+```
+
+Write to storage:
+
+```
+Append record as single JSONL line to .workflow/issues/issues.jsonl.
+Display confirmation: ID, title, status, severity.
+```
+
+Ask for supplementary information:
+
+```
+Prompt user for supplementary context (background, repro steps, related issues, notes).
+If provided → append supplement entry {content, stage:"post_creation", author:"user", created_at} to issue record.
+If empty → skip.
+```
+
+Cross-milestone conflict check (for supplement issues):
+
+```
+IF source == "supplement" AND milestone_ref set:
+  Scan other milestones' plan.json for files_to_create[] that overlap with affected_components.
+  If overlap found → warn about cross-milestone conflict, suggest minimal fix vs deferral.
+```
+
+Suggest next steps:
+
+```
+Suggest: status {ID}, link {ID} --task TASK-NNN, list
+```
+
+---
+
+### Step 5: List Issues
+
+Parse filter options from ARGS:
+
+```
+Options:
+  --status VALUE      Filter by status (open|in_progress|completed|failed|deferred)
+  --phase VALUE       Filter by phase_ref
+  --milestone VALUE   Filter by milestone_ref
+  --severity VALUE    Filter by severity (critical|high|medium|low)
+  --source VALUE      Filter by source
+  --all               Include closed issues from issue-history.jsonl
+```
+
+Read and filter:
+
+```
+Read issues.jsonl (+ issue-history.jsonl if --all).
+Apply matching filters: status, phase_ref (contains), severity, milestone_ref, source.
+Sort by priority (ascending), then severity (critical > high > medium > low).
+```
+
+Display tabular output:
+
+```
+ISSUES ({count} found):
+---------------------------------------------------------------
+ID                | Status      | Sev    | Pri | Title
+---------------------------------------------------------------
+ISS-20260315-001  | open        | high   |  2  | Refresh token rotation
+ISS-20260315-002  | in_progress | medium |  3  | Missing input validation
+---------------------------------------------------------------
+
+Filters applied: {list of active filters or "none"}
+```
+
+If no issues found:
+
+```
+No issues found{with applied filters}.
+
+Create one: Skill({ skill: "manage-issue", args: "create --title \"...\"" })
+Discover issues: Skill({ skill: "manage-issue-discover" })
+```
+
+---
+
+### Step 6: Show Issue Status
+
+Parse issue ID from ARGS:
+
+```
+Extract ISS-XXXXXXXX-NNN from ARGS (prompt if missing).
+Lookup in issues.jsonl, fallback to issue-history.jsonl → error if not found.
+```
+
+Display full detail view:
+
+```
+====================================================
+  ISSUE: {id}
+  TITLE: {title}
+  STATUS: {status}    SEVERITY: {severity}    PRIORITY: {priority}
+====================================================
+
+SOURCE:     {source}
+PHASE:      {phase_ref or "none"}
+GAP REF:    {gap_ref or "none"}
+CREATED:    {created_at}
+UPDATED:    {updated_at}
+RESOLVED:   {resolved_at or "pending"}
+
+DESCRIPTION:
+  {description}
+
+FIX DIRECTION:
+  {fix_direction or "not specified"}
+
+CONTEXT:
+  Location:      {context.location or "not specified"}
+  Suggested Fix: {context.suggested_fix or "none"}
+  Notes:         {context.notes or "none"}
+
+TAGS: {tags joined by ", " or "none"}
+AFFECTED: {affected_components joined by ", " or "none"}
+
+HISTORY:
+  {for each entry in issue_history}
+  [{timestamp}] {from_status} -> {to_status} ({actor}): {note}
+  {/for}
+
+FEEDBACK:
+  {for each entry in feedback}
+  [{timestamp}] ({type}): {content}
+  {/for}
+  {or "none"}
+
+RESOLUTION:
+  {resolution or "not resolved"}
+====================================================
+```
+
+Suggest next steps based on status:
+
+```
+open → suggest: update --status in_progress, link --task
+in_progress → suggest: close --resolution, update --status deferred
+completed/failed/deferred → "This issue is archived."
+```
+
+---
+
+### Step 7: Update Issue
+
+Parse issue ID and field updates from ARGS:
+
+```
+Options:
+  ISS-XXXXXXXX-NNN       Issue ID (required, first positional arg)
+  --status VALUE          New status (open|in_progress)
+  --priority NUMBER       New priority (1-5)
+  --severity VALUE        New severity (critical|high|medium|low)
+  --tags TAG1,TAG2        Replace tags
+  --add-tag TAG           Add a tag
+  --phase VALUE           Set phase_ref
+  --milestone VALUE       Set milestone_ref
+  --fix-direction TEXT    Set fix_direction
+  --description TEXT      Update description
+  --note TEXT             Add feedback entry (type=clarification)
+```
+
+Process update:
+
+```
+Find record by ID in issues.jsonl → error if not found.
+Apply each provided option to the corresponding field.
+If --status changed → append issue_history entry {timestamp, from_status, to_status, actor:"user"}.
+If --note provided → append feedback entry {timestamp, type:"clarification", content}.
+Set updated_at, rewrite issues.jsonl, display changed fields.
+```
+
+---
+
+### Step 8: Close Issue
+
+Parse issue ID and resolution from ARGS:
+
+```
+Options:
+  ISS-XXXXXXXX-NNN     Issue ID (required)
+  --resolution TEXT     Resolution description (required)
+  --status VALUE       Final status: completed|failed|deferred (default: completed)
+```
+
+Process close:
+
+```
+Find record by ID in issues.jsonl → error if not found.
+Prompt for --resolution if missing.
+Set status (default "completed"), resolved_at, resolution; append issue_history entry.
+Move record from issues.jsonl → issue-history.jsonl.
+Display: ID, final status, resolution.
+```
+
+---
+
+### Step 9: Link Issue to Task
+
+Parse issue ID and task reference from ARGS:
+
+```
+Options:
+  ISS-XXXXXXXX-NNN     Issue ID (required)
+  --task TASK-NNN       Task ID to link (required)
+```
+
+Process bidirectional link:
+
+```
+Find issue by ID in issues.jsonl → error if not found.
+Locate task file via artifact registry (.workflow/{path}/.task/{TASK_ID}.json)
+  or scratch fallback (.workflow/scratch/*/.task/{TASK_ID}.json) → error if not found.
+
+Update issue: set gap_ref (if null), add TASK_ID to affected_components, append issue_history entry.
+Update task: append issue ID to "issue_refs" field.
+
+Display: linked pair, issue title, task path.
+Suggest: status {ISSUE_ID}, update --status in_progress.
+```
+
+---
+
+## Output
+
+- **Storage**: `.workflow/issues/issues.jsonl` (active), `.workflow/issues/issue-history.jsonl` (closed)
+- **Format**: One JSON object per line (JSONL), append-friendly
+- **ID scheme**: `ISS-YYYYMMDD-NNN` (NNN auto-incremented per day)
+