maestro-flow 0.1.4 → 0.2.1

package/.codex/skills/manage-issue-execute/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: maestro-issue-execute
+description: Execute a planned solution for an issue via dual-mode dispatch. Auto-detects server UP (POST to /api/execution/dispatch) or DOWN (direct maestro cli). Updates issue status on completion with next-step routing to close, debug, or verify.
+argument-hint: "<ISS-ID> [--executor claude-code|codex|gemini] [--dry-run]"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# Issue Execute
+
+## Usage
+
+```bash
+$maestro-issue-execute "ISS-20260401-001"
+$maestro-issue-execute "ISS-20260401-001 --dry-run"
+$maestro-issue-execute "ISS-20260401-001 --executor codex"
+$maestro-issue-execute "ISS-20260401-001 --executor gemini"
+```
+
+**Flags**:
+- `<ISS-ID>` — Issue ID in `ISS-XXXXXXXX-NNN` format (required)
+- `--executor claude-code|codex|gemini` — Execution agent (default: claude-code)
+- `--dry-run` — Preview constructed prompt and steps without executing
+
+**State files**: `.workflow/issues/issues.jsonl` (read + write)
+
+---
+
+## Overview
+
+Sequential 4-step pipeline with conditional dispatch: load issue → dry-run check → detect mode → execute + update. Server-UP path posts to the orchestration API; Server-DOWN path invokes `maestro cli` directly. This is the third step in the issue resolution workflow: **analyze → plan → execute**.
+
+```
+Load Issue  →  [dry-run?]  →  Detect Mode  →  Dispatch  →  Update Status
+(+ solution     (display        server UP         POST       (apply_patch)
+  required)      + stop)        / DOWN          / cli
+```
+
+---
+
+## Implementation
+
+### Step 1: Load Issue and Validate Solution
+
+```javascript
+functions.update_plan({
+  explanation: "Starting issue execution",
+  plan: [
+    { step: "Load issue and validate solution", status: "in_progress" },
+    { step: "Detect dispatch mode", status: "pending" },
+    { step: "Execute solution", status: "pending" },
+    { step: "Update issue status", status: "pending" }
+  ]
+})
+```
+
+Read `.workflow/issues/issues.jsonl`, find row where `id == <ISS-ID>`. Validate:
+- ISS-ID format `ISS-[0-9]{8}-[0-9]{3}`
+- Row exists in file
+- `issue.solution` is non-null (E002 if missing — run `manage-issue-plan` first)
+
+If `--dry-run`: display the full constructed prompt and each step from `issue.solution.steps`, then stop.
+
+### Step 2: Detect Dispatch Mode
+
+```javascript
+// Read port from config (falls back to MAESTRO_PORT env var, then 3000)
+const configPort = (() => {
+  try { return JSON.parse(Read('.workflow/config.json'))?.server?.port } catch { return null }
+})()
+const port = configPort || functions.exec_command({ cmd: "echo ${MAESTRO_PORT:-3000}", workdir: "." }).stdout.trim()
+
+const healthCheck = functions.exec_command({
+  cmd: `curl -s -o /dev/null -w '%{http_code}' http://localhost:${port}/health`,
+  workdir: "."
+})
+const serverUp = healthCheck.stdout.trim() === "200"
+```
+
+| Mode | Condition | Action |
+|------|-----------|--------|
+| Server UP | HTTP 200 from /health | POST to `/api/execution/dispatch` |
+| Server DOWN | Any other result | Direct `maestro cli` execution |
+
+```javascript
+functions.update_plan({
+  explanation: `Dispatch mode: ${serverUp ? "server" : "cli"}`,
+  plan: [
+    { step: "Load issue and validate solution", status: "completed" },
+    { step: "Detect dispatch mode", status: "completed" },
+    { step: "Execute solution", status: "in_progress" },
+    { step: "Update issue status", status: "pending" }
+  ]
+})
+```
+
+### Step 3: Execute Solution
+
+Build the execution prompt from `issue.solution`:
+```
+PURPOSE: Implement solution for '${issue.title}'.
+TASK: ${solution.steps.map(s => `${s.order}. ${s.description} in ${s.file}`).join(' | ')}
+MODE: write
+CONTEXT: @src/**/* | Memory: Approach: ${solution.approach}
+  ${issue.analysis ? `Root cause: ${issue.analysis.root_cause}` : ''}
+EXPECTED: All steps implemented, all verification criteria met: ${solution.verification.join('; ')}
+CONSTRAINTS: Only modify files listed in steps | No scope creep
+```
+
+**Server UP**:
+```javascript
+// Write payload to temp file to avoid shell injection from prompt content
+const payload = JSON.stringify({ issue_id: issue.id, executor, prompt: execPrompt })
+Write(`/tmp/iss-exec-${issue.id}.json`, payload)
+functions.exec_command({
+  cmd: `curl -X POST http://localhost:${port}/api/execution/dispatch \
+    -H 'Content-Type: application/json' \
+    -d @/tmp/iss-exec-${issue.id}.json`,
+  workdir: "."
+})
+```
+
+**Server DOWN**:
+```javascript
+// Write prompt to temp file to avoid shell injection
+Write(`/tmp/iss-exec-${issue.id}.txt`, execPrompt)
+functions.exec_command({
+  cmd: `maestro cli -p "$(cat /tmp/iss-exec-${issue.id}.txt)" --tool ${executor === 'codex' ? 'codex' : 'claude'} --mode write`,
+  workdir: "."
+})
+```
+
+Set issue status to `in_progress` before dispatching via apply_patch.
+
+### Step 4: Update Issue Status and Report
+
+On success:
+```javascript
+// Read issues.jsonl, update the matching line in-place
+const historyEntry = { action: "executed", at: new Date().toISOString(), by: "manage-issue-execute", executor, summary: `Solution executed via ${serverUp ? "server" : "cli"}` }
+const raw = Read('.workflow/issues/issues.jsonl')
+const updated = raw.split('\n')
+  .filter(l => l.trim())
+  .map(l => {
+    const row = JSON.parse(l)
+    if (row.id !== issueId) return l
+    row.status = "resolved"
+    row.issue_history = [...(row.issue_history || []), historyEntry]
+    return JSON.stringify(row)
+  })
+  .join('\n') + '\n'
+Write('.workflow/issues/issues.jsonl', updated)
+```
+
+```javascript
+functions.update_plan({
+  explanation: "Execution complete",
+  plan: [
+    { step: "Load issue and validate solution", status: "completed" },
+    { step: "Detect dispatch mode", status: "completed" },
+    { step: "Execute solution", status: "completed" },
+    { step: "Update issue status", status: "completed" }
+  ]
+})
+```
+
+Display next-step routing:
+```
+=== EXECUTION COMPLETE ===
+Issue:     <ISS-ID>: <title>
+Executor:  <executor>
+Mode:      <server|cli>
+Status:    resolved
+
+Next steps:
+  Close:   $maestro-issue "close <ISS-ID> --resolution fixed"
+  Verify:  $maestro-verify "<phase>"
+  Debug:   $maestro-debug "<failure description>" (if issues found)
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No ISS-ID provided | Display usage hint |
+| E002 | error | No solution record on issue | Run `$maestro-issue-plan "<ISS-ID>"` first |
+| E003 | error | ISS-ID not found in issues.jsonl | Suggest `$maestro-issue "list"` |
+| E004 | error | Server dispatch or CLI execution failed | Log error, revert status to `open`, display failure details |
+
+---
+
+## Core Rules
+
+1. **Solution required**: Never dispatch without a valid `issue.solution` record
+2. **Dry-run first**: `--dry-run` always stops after displaying prompt — no execution
+3. **Status before dispatch**: Set status to `in_progress` before dispatching, `resolved` on success, `open` on failure
+4. **Revert on failure**: If dispatch fails, revert issue status to `open` via apply_patch
+5. **Preserve history**: Append to `issue_history`, never overwrite existing entries
+6. **Next-step routing**: Always display all three options (close / verify / debug) at the end

package/.codex/skills/manage-issue-plan/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: maestro-issue-plan
+description: Solution planning for a specific issue. Auto-detects analysis context, runs maestro cli planning, and attaches a structured solution record with ordered steps and verification criteria to the issue in issues.jsonl.
+argument-hint: "<ISS-ID> [--tool gemini|qwen] [--from-analysis]"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# Issue Plan
+
+## Usage
+
+```bash
+$maestro-issue-plan "ISS-20260401-001"
+$maestro-issue-plan "ISS-20260401-001 --from-analysis"
+$maestro-issue-plan "ISS-20260401-001 --tool qwen"
+```
+
+**Flags**:
+- `<ISS-ID>` — Issue ID in `ISS-XXXXXXXX-NNN` format (required)
+- `--tool gemini|qwen` — CLI tool for planning (default: gemini)
+- `--from-analysis` — Explicitly include analysis context. Auto-detected when `issue.analysis` exists.
+
+**State files**: `.workflow/issues/issues.jsonl` (read + write)
+
+---
+
+## Overview
+
+Sequential 4-step pipeline: load issue → build planning prompt → run CLI planning → attach solution record. When an analysis record exists (from `manage-issue-analyze`), it is automatically included in the planning prompt to ground the solution in known root cause and affected files. This is the second step in the issue resolution workflow: **analyze → plan → execute**.
+
+```
+Load Issue  →  Build Prompt  →  CLI Planning  →  Attach Solution
+(+ analysis    (auto-detect    (gemini/qwen)    (apply_patch)
+  context)      analysis)
+```
+
+---
+
+## Implementation
+
+### Step 1: Load Issue and Detect Analysis Context
+
+```javascript
+functions.update_plan({
+  explanation: "Starting issue planning",
+  plan: [
+    { step: "Load issue and detect analysis", status: "in_progress" },
+    { step: "Build planning prompt", status: "pending" },
+    { step: "Run CLI planning", status: "pending" },
+    { step: "Attach solution record", status: "pending" }
+  ]
+})
+```
+
+Read `.workflow/issues/issues.jsonl`, find the row where `id == <ISS-ID>`. Validate format and existence.
+
+Check analysis context:
+- `issue.analysis` non-null → `hasAnalysis = true` (auto-detect, no flag needed)
+- `--from-analysis` present AND `issue.analysis` is null → emit W001, proceed without context
+
+### Step 2: Build Planning Prompt
+
+```
+PURPOSE: Create a concrete, codebase-aware solution plan for '${issue.title}';
+  success = ordered steps with exact file paths, function names, and verification criteria.
+TASK: Define solution approach | Break into ordered steps | Identify files to change | Define verification
+MODE: analysis
+CONTEXT: @src/**/* | Memory: Issue: ${issue.description}
+  ${hasAnalysis ? `Root cause: ${analysis.root_cause}
+  Affected files: ${analysis.affected_files.join(', ')}
+  Fix direction: ${analysis.fix_direction}` : ''}
+EXPECTED: JSON: approach (string), steps [{order, description, file, action}],
+  verification (string[]), estimated_risk (low|medium|high)
+CONSTRAINTS: Concrete steps only | File:line references required | No speculative changes
+```
+
+### Step 3: Run CLI Planning
+
+> **Prompt safety**: `issue.title`, `issue.description`, and analysis fields may contain quotes or shell-special characters. Write the assembled prompt to a temp file before passing to exec_command.
+
+```javascript
+// Write prompt to temp file to avoid shell injection
+Write(`/tmp/iss-plan-${issueId}.txt`, prompt)
+functions.exec_command({
+  cmd: `maestro cli -p "$(cat /tmp/iss-plan-${issueId}.txt)" --tool ${tool} --mode analysis`,
+  workdir: "."
+})
+```
+
+Parse CLI output into `solution` object:
+```json
+{
+  "approach": "...",
+  "steps": [
+    { "order": 1, "description": "...", "file": "src/foo.ts", "action": "modify" },
+    { "order": 2, "description": "...", "file": "src/bar.ts", "action": "add" }
+  ],
+  "verification": ["Run unit tests for X", "Verify Y behavior"],
+  "estimated_risk": "medium",
+  "planned_at": "<ISO>",
+  "tool": "<tool>"
+}
+```
+
+```javascript
+functions.update_plan({
+  explanation: "Planning complete",
+  plan: [
+    { step: "Load issue and detect analysis", status: "completed" },
+    { step: "Build planning prompt", status: "completed" },
+    { step: "Run CLI planning", status: "completed" },
+    { step: "Attach solution record", status: "in_progress" }
+  ]
+})
+```
+
+### Step 4: Attach Solution Record and Report
+
+```javascript
+// Read issues.jsonl, update the matching line in-place
+const historyEntry = { action: "planned", at: new Date().toISOString(), by: "manage-issue-plan", summary: `Approach: ${solution.approach} — ${solution.steps.length} steps` }
+const raw = Read('.workflow/issues/issues.jsonl')
+const updated = raw.split('\n')
+  .filter(l => l.trim())
+  .map(l => {
+    const row = JSON.parse(l)
+    if (row.id !== issueId) return l
+    row.solution = solution
+    row.issue_history = [...(row.issue_history || []), historyEntry]
+    return JSON.stringify(row)
+  })
+  .join('\n') + '\n'
+Write('.workflow/issues/issues.jsonl', updated)
+```
+
+```javascript
+functions.update_plan({
+  explanation: "Solution attached",
+  plan: [
+    { step: "Load issue and detect analysis", status: "completed" },
+    { step: "Build planning prompt", status: "completed" },
+    { step: "Run CLI planning", status: "completed" },
+    { step: "Attach solution record", status: "completed" }
+  ]
+})
+```
+
+Display:
+```
+=== SOLUTION PLAN ===
+Issue:    <ISS-ID>: <title>
+Approach: <approach>
+Risk:     <estimated_risk>
+Steps:    <N>
+
+Steps:
+  1. <description> → <file> (<action>)
+  2. <description> → <file> (<action>)
+
+Verification:
+  - <verification 1>
+
+Next: $maestro-issue-execute "<ISS-ID>"
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No ISS-ID provided | Display usage hint |
+| E002 | error | ISS-ID not found in issues.jsonl | Suggest `$maestro-issue "list"` |
+| E003 | error | CLI planning returned no parseable result | Retry with different `--tool` |
+| W001 | warning | `--from-analysis` but no analysis record exists | Proceed without context; suggest `$maestro-issue-analyze` |
+
+---
+
+## Core Rules
+
+1. **Load before plan**: Validate issue existence before any CLI call
+2. **Auto-detect analysis**: Check `issue.analysis` — never require explicit `--from-analysis` if data is present
+3. **Concrete steps only**: Each step must have a file reference — no "investigate further" placeholders
+4. **Preserve existing fields**: Patch only `solution` + `issue_history` — all other issue fields unchanged
+5. **Append-only history**: Append to `issue_history`, never overwrite existing entries
+6. **Next-step routing**: Always display `$maestro-issue-execute "<ISS-ID>"` at the end

package/.codex/skills/manage-learn/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: maestro-learn
+description: Capture atomic learning insights into .workflow/learning/lessons.jsonl. Lightweight CRUD over the shared learning store — supports capture, list, search, and show modes. No LLM or CLI calls; all operations are pure file reads and writes.
+argument-hint: "[\"<insight text>\"|list|search <query>|show <INS-id>] [--category pattern|antipattern|decision|tool|gotcha|technique] [--tag t1,t2] [--phase N] [--confidence high|medium|low]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Manage Learn
+
+## Usage
+
+```bash
+$maestro-learn "Always read state.json before planning to detect current phase"
+$maestro-learn "list --limit 10 --category antipattern"
+$maestro-learn "search context propagation"
+$maestro-learn "show INS-a3f7b2c1"
+$maestro-learn "\"Zod v4 breaks z.object().strict() API\" --category gotcha --tag zod,typescript"
+```
+
+**Flags** (capture mode):
+- `--category <name>` — `pattern|antipattern|decision|tool|gotcha|technique`. Default: inferred from text keywords.
+- `--tag t1,t2` — Comma-separated tags. Always adds `manual` implicitly.
+- `--phase <N>` — Override auto-detected current phase. `--phase 0` forces no phase link.
+- `--confidence high|medium|low` — Default: medium.
+
+**Flags** (list/search mode):
+- `--tag t1,t2` — Filter by tag
+- `--category <name>` — Filter by category
+- `--phase <N>` — Filter by phase
+- `--lens <name>` — Filter by retrospective lens (technical|process|quality|decision)
+- `--limit <N>` — Row limit (default 20)
+
+**Storage**:
+- `.workflow/learning/lessons.jsonl` — append-only JSONL (shared with `quality-retrospective`)
+- `.workflow/learning/learning-index.json` — searchable index
+
+---
+
+## Overview
+
+Pure file-operation CRUD skill for the workflow learning library. No agent spawning, no CLI calls, no LLM inference — just parse-infer-append-confirm. Complements `quality-retrospective`: where retrospective extracts insights in bulk from completed phases, `manage-learn` captures one timeless insight at a time during active work. Both write to the same `lessons.jsonl` store, disambiguated by `source` and `lens` fields.
+
+```
+Parse Mode  →  Bootstrap Store  →  Execute Mode  →  Confirm
+(capture /       (on first use)     (Bash/Read/      (INS-id
+  list /          Bash+Write)        Write/Grep)      + hints)
+  search /
+  show)
+```
+
+---
+
+## Implementation
+
+### Step 1: Parse Mode and Validate Arguments
+
+Parse the first non-flag token from `$ARGUMENTS`:
+
+| First token | Mode |
+|-------------|------|
+| `list` | list |
+| `search` followed by query | search |
+| `show` followed by INS-id | show |
+| Empty | Prompt with `functions.request_user_input` |
+| Any other text (quoted or not) | capture |
+
+Validate `--category` if provided (allowed: pattern, antipattern, decision, tool, gotcha, technique). E002 if unknown.
+
+### Step 2: Bootstrap Learning Store (on first use)
+
+Check if `.workflow/learning/lessons.jsonl` exists. If not:
+```javascript
+// Create directory and empty files — use Bash + Write (apply_patch cannot create empty files reliably)
+Bash('mkdir -p .workflow/learning && touch .workflow/learning/lessons.jsonl')
+Write('.workflow/learning/learning-index.json', '{"version":1,"entries":[]}\n')
+```
+
+Verify `.workflow/` exists (E001 if not).
+
+### Step 3: Execute Mode
+
+#### Capture Mode
+
+1. **Infer category** from insight text (keyword heuristics, no LLM):
+
+| Keywords present in text | Inferred category |
+|--------------------------|-------------------|
+| always, should, prefer, best practice | pattern |
+| never, avoid, don't, pitfall, breaks | antipattern |
+| decided, chose, tradeoff, because, reason | decision |
+| tool, library, framework, package, cli | tool |
+| gotcha, surprising, unexpected, watch out | gotcha |
+| technique, approach, method, pattern for | technique |
+
+2. **Auto-link phase**: Read `.workflow/state.json` for `current_phase`. Resolve matching directory slug from `.workflow/phases/`. `--phase 0` forces null.
+
+3. **Generate stable INS-id**: `INS-{8 lowercase hex}` from `hash(insightText + timestamp)`.
+
+4. **Build lessons.jsonl row**:
+```json
+{
+  "id": "INS-a3f7b2c1",
+  "title": "<first 80 chars of insight>",
+  "summary": "<full insight text>",
+  "source": "manual",
+  "lens": null,
+  "category": "<inferred or explicit>",
+  "tags": ["manual", "<user tags...>"],
+  "phase": <N or null>,
+  "phase_slug": "<slug or null>",
+  "confidence": "<high|medium|low>",
+  "routed_to": null,
+  "routed_id": null,
+  "created_at": "<ISO>"
+}
+```
+
+5. **Append to lessons.jsonl**:
+```javascript
+// Append single JSON line — Bash echo avoids rewriting the whole file
+Bash(`echo '${JSON.stringify(insightRow)}' >> .workflow/learning/lessons.jsonl`)
+```
+
+6. **Update learning-index.json**: Read, push entry, write back:
+```javascript
+const index = JSON.parse(Read('.workflow/learning/learning-index.json'))
+index.entries.push({ id: insightRow.id, title: insightRow.title, category: insightRow.category, tags: insightRow.tags, phase: insightRow.phase, created_at: insightRow.created_at })
+Write('.workflow/learning/learning-index.json', JSON.stringify(index, null, 2) + '\n')
+```
+
+#### List Mode
+
+Read `learning-index.json` entries array. Apply filters (`--tag`, `--category`, `--phase`, `--lens`). Sort newest-first. Display up to `--limit` rows (default 20):
+
+```
+ID              Category     Phase  Tags              Title
+INS-a3f7b2c1   gotcha       3      manual,zod        Zod v4 breaks z.object().strict() API
+INS-b1c2d3e4   pattern      2      manual            Always read state.json before planning
+```
+
+#### Search Mode
+
+Grep across `lessons.jsonl` for the query string. Rank by field match weight: title (3) > tags (2) > summary (1). Display top matches with ID, category, phase, title.
+
+#### Show Mode
+
+Validate INS-id format `INS-[0-9a-f]{8}`. Find row in `lessons.jsonl` where `id` matches. Display full record with all fields. If `routed_to` is set, display the linked artifact path.
+
+### Step 4: Display Confirmation
+
+Capture mode:
+```
+=== INSIGHT CAPTURED ===
+ID:         INS-a3f7b2c1
+Category:   gotcha
+Phase:      3 (phase-03-api-layer)
+Confidence: medium
+Tags:       manual, zod, typescript
+
+Next: $maestro-learn "list"  or  $maestro-learn "search zod"
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `$maestro-init` first | parse_input |
+| E002 | error | Unknown `--category` value | parse_input |
+| E003 | error | `show` mode requires INS-id argument | show |
+| E004 | error | INS-id not found in lessons.jsonl | show |
+| W001 | warning | Auto-phase detection: current_phase found but no matching directory; phase set to null | capture |
+| W002 | warning | `learning-index.json` row count differs from `lessons.jsonl`; offer to rebuild index | list/search |
+
+---
+
+## Core Rules
+
+1. **No LLM or CLI calls**: This skill is pure file I/O — parse, infer, append, confirm. No `exec_command`, no `spawn_agent`.
+2. **Bootstrap on demand**: Create `.workflow/learning/` structure on first use; do not require it to exist.
+3. **Append-only lessons.jsonl**: Never rewrite or delete existing rows.
+4. **Stable INS-ids**: `INS-{8hex}` from `hash(insightText + timestamp)` — same text at different times gets different ids.
+5. **Source field**: Always `"manual"` for captures from this skill; `"retrospective"` is reserved for `quality-retrospective`.
+6. **Phase auto-link**: Read `state.json` automatically; `--phase 0` is the only way to force null.
+7. **Keyword inference is approximate**: When in doubt, default to `pattern` category rather than prompting user.