maestro-flow 0.3.15 → 0.3.17

package/workflows/issue-execute.md

@@ -15,18 +15,8 @@ Execute a planned solution for an issue via dual-mode agent dispatch (server or
 ### 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
+Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
+Flags: --executor claude-code|codex|gemini (default: claude-code), --dry-run (default: false)
 ```
 
 ---
@@ -34,29 +24,9 @@ Execute a planned solution for an issue via dual-mode agent dispatch (server or
 ### 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
+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 manage-issue-plan first).
+Resolve EXECUTOR → CLI tool (claude-code→claude, codex→codex, gemini→gemini), all with --mode write.
 ```
 
 ---
@@ -64,37 +34,8 @@ Execute a planned solution for an issue via dual-mode agent dispatch (server or
 ### 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).
+If DRY_RUN: display prompt template, steps table (action | title | files),
+and context. No changes made. Exit before Step 4.
 ```
 
 ---
@@ -102,14 +43,8 @@ If DRY_RUN == true:
 ### 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'}"
+Health check: curl http://127.0.0.1:3001/api/health
+  HTTP 200 → SERVER_UP (server dispatch) | otherwise → Direct CLI
 ```
 
 ---
@@ -117,109 +52,25 @@ If DRY_RUN == true:
 ### 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
+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
 
 ```
-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 delegate:
-   maestro delegate "{EXEC_PROMPT}" --to {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
+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.
 ```
 
 ---
@@ -227,32 +78,10 @@ If SERVER_UP == false (or server dispatch failed):
 ### 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
-
-====================================================
+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
 ```
 
 ---
@@ -260,16 +89,8 @@ STATUS: {new status}
 ### 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
+Success → close issue, view status, run tests
+Failure → retry with different executor, revise plan, re-analyze with --depth deep
 ```
 
 ---

package/workflows/issue-plan.md

@@ -15,18 +15,8 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ### Step 1: Parse Arguments
 
 ```
-1. Extract ISS-ID from first positional token in $ARGUMENTS
-   If empty → error E_NO_ISSUE_ID:
-     "Usage: /manage-issue-plan <ISS-ID> [--tool gemini|qwen] [--from-analysis]"
-     "Example: /manage-issue-plan ISS-20260318-001 --tool gemini"
-
-2. Parse optional flags:
-   --tool VALUE      → TOOL (default: gemini)
-   --from-analysis   → FROM_ANALYSIS = true (default: auto-detect)
-
-3. Validate:
-   - ISS-ID matches pattern ISS-\d{8}-\d{3}
-   - TOOL is one of: gemini, qwen
+Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
+Flags: --tool gemini|qwen (default: gemini), --from-analysis (default: auto-detect)
 ```
 
 ---
@@ -34,29 +24,9 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ### 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
-   - If status is other → warn but proceed (planning is non-destructive)
-
-5. If issue.solution exists and is not null:
-   AskUserQuestion({
-     question: "Issue {ISS-ID} already has a solution plan. Overwrite?",
-     options: [
-       { label: "Yes", description: "Replace existing solution with new plan" },
-       { label: "No", description: "Keep existing solution, abort planning" }
-     ]
-   })
-   If "No" → exit gracefully
-
-6. Store issue record as ISSUE
+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).
 ```
 
 ---
@@ -64,27 +34,10 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ### Step 3: Load Analysis Context
 
 ```
-1. Check if ISSUE.analysis exists and is not null:
-
-   If analysis exists:
-     - HAS_ANALYSIS = true
-     - Extract: root_cause, impact, related_files, confidence, suggested_approach
-     - Build ANALYSIS_CONTEXT:
-       "PRIOR ANALYSIS (confidence: {confidence}):
-        Root Cause: {root_cause}
-        Impact: {impact}
-        Related Files: {related_files joined by newline}
-        Suggested Approach: {suggested_approach}"
-
-   If analysis is null:
-     - HAS_ANALYSIS = false
-     - If --from-analysis was explicitly passed:
-       → warning E_NO_ANALYSIS:
-         "No analysis record on {ISS-ID}. Proceeding without analysis context."
-         "For better results, run: /manage-issue-analyze {ISS-ID}"
-     - ANALYSIS_CONTEXT = ""
-
-2. Store ANALYSIS_CONTEXT for CLI prompt
+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).
 ```
 
 ---
@@ -92,44 +45,18 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ### Step 4: Generate Solution via CLI
 
 ```
-1. Build planning prompt:
-
-   maestro delegate "PURPOSE: Generate a step-by-step solution plan for issue {ISS-ID}: {ISSUE.title}
-   Produce an actionable, ordered list of implementation steps.
-
-   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'}
-
-   {ANALYSIS_CONTEXT}
-
-   TASK:
-   - Break the fix into ordered, atomic implementation steps
-   - Each step: title, description, target file(s), action type (create|modify|delete|test)
-   - Include a context summary explaining the overall approach
-   - Generate a promptTemplate string that an executor agent can use to implement the fix
-
-   MODE: analysis
-   CONTEXT: @**/*
-   EXPECTED: JSON object with fields:
-     steps: [{ title: string, description: string, files: string[], action: string }],
-     context: string (approach summary),
-     promptTemplate: string (execution prompt for the agent)
-   CONSTRAINTS: Steps must be concrete and file-specific, not vague
-   " --to {TOOL} --mode analysis
-
-2. Parse CLI output:
-   - Extract JSON object from response
-   - Validate required fields: steps (array with length > 0), context, promptTemplate
-   - Each step must have: title, description, files, action
-   - If parsing fails → error E_PLANNING_FAILED:
-     "Planning did not return valid JSON. Raw output saved for review."
-     Store raw output in ISSUE feedback.
-
-3. Store parsed result as SOLUTION_RESULT
+Delegate planning prompt with issue details + ANALYSIS_CONTEXT:
+
+  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.
 ```
 
 ---
@@ -137,16 +64,8 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ### Step 5: Build Solution Record
 
 ```
-1. Construct IssueSolution record:
-   {
-     "steps": {SOLUTION_RESULT.steps},
-     "context": "{SOLUTION_RESULT.context}",
-     "promptTemplate": "{SOLUTION_RESULT.promptTemplate}",
-     "planned_at": "{NOW_ISO}",
-     "planned_by": "{TOOL}"
-   }
-
-2. Store as SOLUTION record for next step
+Construct IssueSolution:
+  { steps, context, promptTemplate, planned_at: NOW_ISO, planned_by: TOOL }
 ```
 
 ---
@@ -154,27 +73,11 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ### 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.solution = SOLUTION
-   - Set issue.updated_at = NOW_ISO
-   - Add issue_history entry:
-     {
-       "timestamp": "{NOW_ISO}",
-       "from_status": "{ISSUE.status}",
-       "to_status": "{ISSUE.status}",
-       "actor": "planning-agent",
-       "note": "Solution plan generated ({SOLUTION.steps.length} steps)"
-     }
-   - Status stays unchanged (planning is metadata enrichment)
-
-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 solution field
+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.
 ```
 
 ---
@@ -182,35 +85,11 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ### Step 7: Display Solution Steps Table and Next Steps
 
 ```
-Display solution summary:
-
-====================================================
-  SOLUTION PLAN: {ISS-ID}
-  Tool: {TOOL}    Analysis: {HAS_ANALYSIS ? "included" : "none"}
-====================================================
-
-APPROACH:
-  {SOLUTION.context}
-
-STEPS:
----------------------------------------------------------------
-#  | Action  | Title                          | Files
----------------------------------------------------------------
-1  | modify  | Fix token validation           | src/auth.ts
-2  | create  | Add refresh token handler      | src/refresh.ts
-3  | test    | Add auth test cases            | tests/auth.test.ts
----------------------------------------------------------------
-
-PROMPT TEMPLATE (for executor):
-  {SOLUTION.promptTemplate}
-
-====================================================
-
-Suggest next steps:
-  - Skill({ skill: "manage-issue-execute", args: "{ISS-ID}" }) -- Execute solution
-  - Skill({ skill: "manage-issue-execute", args: "{ISS-ID} --dry-run" }) -- Preview execution
-  - Skill({ skill: "manage-issue-execute", args: "{ISS-ID} --executor codex" }) -- Execute with Codex
-  - Skill({ skill: "manage-issue", args: "status {ISS-ID}" }) -- View full issue details
+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}
 ```
 
 ---