maestro-flow 0.3.14 → 0.3.16

package/.codex/skills/maestro-brainstorm/SKILL.md

@@ -163,31 +163,22 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 
 ### Session Initialization
 
-```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-// Parse flags
-const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-const continueMode = $ARGUMENTS.includes('--continue')
-const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
-const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 6
-
-// Parse brainstorm-specific flags
-const countMatch = $ARGUMENTS.match(/--count\s+(\d+)/)
-const roleCount = countMatch ? Math.min(parseInt(countMatch[1]), 9) : 3
-const skipQuestions = $ARGUMENTS.includes('--skip-questions')
-
-// Clean topic text
-const topicArg = $ARGUMENTS
-  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--count\s+\d+|--skip-questions/g, '')
-  .trim()
-
-const slug = topicArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
-const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `${dateStr}-brainstorm-${slug}`
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-
-Bash(`mkdir -p ${sessionFolder}/.brainstorming`)
+```
+Parse from $ARGUMENTS:
+  AUTO_YES       ← --yes | -y
+  continueMode   ← --continue
+  maxConcurrency ← --concurrency | -c N  (default: 6)
+  roleCount      ← --count N  (default: 3, max: 9)
+  skipQuestions   ← --skip-questions
+  topicArg       ← remaining text after flag removal
+
+Derive:
+  slug           ← topicArg kebab-cased, max 40 chars
+  dateStr        ← UTC+8 YYYYMMDD
+  sessionId      ← "{dateStr}-brainstorm-{slug}"
+  sessionFolder  ← ".workflow/.csv-wave/{sessionId}"
+
+mkdir -p {sessionFolder}/.brainstorming
 ```
 
 ### Phase 1: Topic Resolution -> CSV
@@ -231,37 +222,22 @@ Bash(`mkdir -p ${sessionFolder}/.brainstorming`)
 
 #### Wave 1: Guidance Specification (Single Agent)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 1` AND `status == pending`
-3. No prev_context needed (wave 1 has no predecessors)
-4. Write `wave-1.csv`
-5. Execute:
+1. Extract wave 1 pending rows from master `tasks.csv` into `wave-1.csv` (no prev_context needed)
+2. Execute:
 
 ```javascript
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
   instruction: buildGuidanceInstruction(sessionFolder, topicArg),
-  max_concurrency: 1,
-  max_runtime_seconds: 600,
+  max_concurrency: 1, max_runtime_seconds: 600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      analysis_file: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
+  output_schema: { id, status: [completed|failed], findings, analysis_file, error }
 })
 ```
 
-6. Read `wave-1-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-1.csv`
-8. Read generated `guidance-specification.md` for wave 2 context propagation
+3. Merge results into master `tasks.csv`, delete `wave-1.csv`
+4. Read generated `guidance-specification.md` for wave 2 context propagation
 
 **Guidance agent responsibilities**:
 - Analyze topic, extract 5-10 core domain terms
@@ -272,40 +248,23 @@ spawn_agents_on_csv({
 
 #### Wave 2: Role Analysis (Parallel, 3-9 Agents)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 2` AND `status == pending`
-3. Build `prev_context` from wave 1 findings:
-   ```
-   [Task 1: Guidance Specification] Generated guidance-specification.md with N features, M terms defined...
-   ```
-4. Include `guidance-specification.md` content in prev_context for each role agent
-5. Write `wave-2.csv` with `prev_context` column
-6. Execute:
+1. Extract wave 2 pending rows from master `tasks.csv`
+2. Build `prev_context` from wave 1 findings + `guidance-specification.md` content
+3. Write `wave-2.csv` with `prev_context` column
+4. Execute:
 
 ```javascript
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-2.csv`,
   id_column: "id",
   instruction: buildRoleAnalysisInstruction(sessionFolder),
-  max_concurrency: maxConcurrency,
-  max_runtime_seconds: 900,
+  max_concurrency: maxConcurrency, max_runtime_seconds: 900,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      analysis_file: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
+  output_schema: { id, status: [completed|failed], findings, analysis_file, error }
 })
 ```
 
-7. Read `wave-2-results.csv`, merge into master `tasks.csv`
-8. Delete `wave-2.csv`
+5. Merge results into master `tasks.csv`, delete `wave-2.csv`
 
 **Role agent responsibilities**:
 - Read guidance-specification.md for framework context
@@ -321,19 +280,10 @@ spawn_agents_on_csv({
 
 #### Wave 3: Synthesis + Feature Index (Single Agent)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 3` AND `status == pending`
-3. Check deps -- if all wave 2 tasks failed, skip synthesis
-4. Build `prev_context` from wave 2 findings:
-   ```
-   [Task 2: System Architect Analysis] Key findings: microservice architecture with event sourcing...
-   [Task 3: UI Designer Analysis] Key findings: component-based design system with real-time cursors...
-   [Task 4: Product Manager Analysis] Key findings: MVP focuses on document editing + presence...
-   ```
-5. Write `wave-3.csv` with `prev_context` column
-6. Execute `spawn_agents_on_csv` for synthesis agent
-7. Merge results into master `tasks.csv`
-8. Delete `wave-3.csv`
+1. If all wave 2 tasks failed, skip synthesis entirely
+2. Extract wave 3 pending rows, build `prev_context` from wave 2 findings
+3. Write `wave-3.csv`, execute `spawn_agents_on_csv` for synthesis agent (same output_schema pattern)
+4. Merge results into master `tasks.csv`, delete `wave-3.csv`
 
 **Synthesis agent responsibilities**:
 - Cross-role analysis: consensus, conflicts, unique contributions
@@ -347,9 +297,8 @@ spawn_agents_on_csv({
 
 **Objective**: Generate final results and human-readable report.
 
-1. Read final master `tasks.csv`
-2. Export as `results.csv`
-3. Generate `context.md`:
+1. Export final `tasks.csv` as `results.csv`
+2. Generate `context.md`:
 
 ```markdown
 # Brainstorm Report -- {topic}
@@ -411,11 +360,7 @@ spawn_agents_on_csv({
 
 #### Protocol
 
-1. **Read** `{session_folder}/discoveries.ndjson` before own analysis
-2. **Skip covered**: If discovery of same type + dedup key exists, skip
-3. **Write immediately**: Append findings as found
-4. **Append-only**: Never modify or delete
-5. **Deduplicate**: Check before writing
+Read `discoveries.ndjson` before analysis. Append-only: dedup by type+key before writing, never modify/delete.
 
 ```bash
 echo '{"ts":"<ISO>","worker":"{id}","type":"terminology","data":{"term":"CRDT","definition":"Conflict-free Replicated Data Type","aliases":["conflict-free"],"category":"technical"}}' >> {session_folder}/discoveries.ndjson

package/.codex/skills/maestro-composer/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: maestro-composer
+description: Interactive workflow template composer — parse natural language into DAG of skill nodes, auto-inject checkpoints, confirm pipeline interactively, persist as reusable JSON template to ~/.maestro/templates/workflows/
+argument-hint: "\"workflow description\" [--resume] [--edit <template-path>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Interactive workflow template composer. Parses natural language into a reusable DAG template
+via 5 phases with user confirmation at each boundary. Templates saved globally at
+`~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
+
+Sequential interactive flow (no spawn_agents_on_csv — this is design, not execution):
+```
+Parse NL → [confirm] → Resolve to nodes → [confirm] → Inject checkpoints → Confirm pipeline → Persist
+```
+
+Three entry modes:
+1. **New design**: Phase 1-5
+2. **Resume design**: Load draft from `.workflow/templates/design-drafts/`
+3. **Edit template**: Load existing, modify, re-save
+</purpose>
+
+<context>
+$ARGUMENTS — natural language workflow description, or flags.
+
+**Flags:**
+- `--resume` — Resume in-progress design session
+- `--edit <template-path>` — Edit an existing template
+
+**Shared constants:**
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `WFD` |
+| Template dir (global) | `~/.maestro/templates/workflows/` |
+| Template index (global) | `~/.maestro/templates/workflows/index.json` |
+| Design drafts dir (local) | `.workflow/templates/design-drafts/` |
+| Template ID format | `wft-<slug>-<YYYYMMDD>` |
+| Node ID format | `N-<seq>` (e.g. N-001), `CP-<seq>` for checkpoints |
+| Max nodes | 20 |
+
+**Entry routing:**
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Resume | `--resume` or existing WFD session | Phase 0: Resume |
+| Edit | `--edit <path>` | Phase 0: Load + Edit |
+| New | Default | Phase 1: Parse |
+
+**Node catalog**: Read `~/.maestro/templates/workflows/specs/node-catalog.md` at Phase 2 (deferred).
+**Template schema**: Read `~/.maestro/templates/workflows/specs/template-schema.md` at Phase 5 (deferred).
+</context>
+
+<execution>
+
+### Phase 0: Resume / Edit (conditional)
+
+**Resume** (`--resume`):
+1. Scan `.workflow/templates/design-drafts/WFD-*/` for in-progress designs
+2. Multiple → AskUserQuestion for selection
+3. Load draft → skip to last incomplete phase
+
+**Edit** (`--edit <path>`):
+1. Load template JSON
+2. Show pipeline visualization (Phase 4 format)
+3. AskUserQuestion: which nodes to modify/add/remove
+4. Re-enter at Phase 3
+
+---
+
+### Phase 1: Parse — Semantic Intent Extraction
+
+**Step 1.1** — Parse `$ARGUMENTS`. If empty, AskUserQuestion:
+```
+"Describe the workflow you want to automate.
+Include: what steps to run, in what order, and what varies each time.
+Example: 'analyze the code, then plan, implement, and test the feature'"
+```
+
+**Step 1.2** — Extract sequential actions as candidate nodes:
+
+| Signal | Candidate Type |
+|--------|---------------|
+| "analyze", "review", "explore" | analysis (cli) |
+| "plan", "design", "spec" | planning (skill) |
+| "implement", "build", "code", "fix" | execution (skill) |
+| "test", "validate", "verify" | testing (skill) |
+| "brainstorm", "ideate" | brainstorm (skill) |
+| "review code" | review (skill) |
+| "then", "next", "after" | sequential edge |
+| "parallel", "simultaneously" | parallel edge |
+
+**Step 1.3** — Extract variables (inputs that vary per run).
+
+**Step 1.4** — Classify task type: `bugfix | feature | tdd | review | brainstorm | spec-driven | roadmap | refactor | integration-test | quick-task | custom`
+
+**Step 1.5** — Assess complexity: `simple` (1-3 nodes), `medium` (4-7), `complex` (8+)
+
+**Step 1.6** — Write `intent.json` to `.workflow/templates/design-drafts/WFD-<slug>-<date>/`.
+
+**Step 1.7 — Interactive confirmation**: Display description, task type, complexity, detected steps (numbered with type_hint), and variables. AskUserQuestion: `Continue to resolution` / `Edit steps` / `Add a step` / `Cancel`
+
+---
+
+### Phase 2: Resolve — Map Steps to Executor Nodes
+
+**Read deferred**: `~/.maestro/templates/workflows/specs/node-catalog.md`
+
+If spec not found, use built-in fallback:
+
+| type_hint | executor type | executor |
+|-----------|--------------|----------|
+| `planning` | skill | `maestro-plan` |
+| `execution` | skill | `maestro-execute` |
+| `testing` | skill | `quality-test` |
+| `review` | skill | `quality-review` |
+| `brainstorm` | skill | `maestro-brainstorm` |
+| `analysis` | cli | `maestro delegate --to gemini --mode analysis` |
+| `verify` | skill | `maestro-verify` |
+| `refactor` | skill | `quality-refactor` |
+| `debug` | skill | `quality-debug` |
+| `spec` | skill | `maestro-spec-generate` |
+| `checkpoint` | checkpoint | — |
+
+**Step 2.1** — Load `intent.json`, map each step to executor.
+
+**Step 2.2** — Build `args_template` with variable placeholders and context injection:
+- Planning after analysis → `--context {prev_output_path}`
+- Execution after planning → inherit phase
+- Testing after execution → inherit phase
+
+**Step 2.3** — Assign `parallel_group` for parallel steps.
+
+**Step 2.4** — Write `nodes.json`.
+
+**Step 2.5 — Interactive confirmation**: Display resolved nodes table (ID, type, executor, args) and parallel groups. AskUserQuestion: `Continue to checkpoint injection` / `Change executor` / `Change node type` / `Back to intent` / `Cancel`
+
+---
+
+### Phase 3: Enrich — Inject Checkpoints + Build DAG
+
+**Step 3.1** — Load `nodes.json`. Build sequential edges. For parallel groups: fan-out/fan-in.
+
+**Step 3.2** — Auto-inject checkpoint nodes:
+
+| Rule | Condition |
+|------|-----------|
+| Artifact boundary | Source output_ports: plan, spec, analysis, review-findings |
+| Execution gate | Target executor contains `execute` |
+| Agent spawn | Target type is `agent` |
+| Long-running | Target is maestro-plan, maestro-spec-generate |
+| User-defined | Step had `type_hint: checkpoint` |
+| Post-testing | Source executor contains `test` or `integration-test` |
+
+Set `auto_continue: false` for checkpoints before user-facing deliverables.
+
+**Step 3.3** — Finalize `context_schema`, validate DAG (no cycles, no orphans).
+
+**Step 3.4** — Write `dag.json`. → Proceed to Phase 4.
+
+---
+
+### Phase 4: Confirm — Visualize + User Approval
+
+**Step 4.1** — Render ASCII pipeline: vertical node chain with `|` connectors showing each node (ID, type, executor, args) and checkpoint nodes (auto-continue vs pause-for-user). Footer: required variables, checkpoint counts, node counts.
+
+**Step 4.2** — AskUserQuestion: `Confirm & Save` / `Edit a node` / `Add a node` / `Remove a node` / `Rename template` / `Re-run checkpoint injection` / `Cancel`
+
+**Step 4.3** — Loop edits until Confirm or Cancel.
+
+---
+
+### Phase 5: Persist — Assemble + Save Template
+
+**Read deferred**: `~/.maestro/templates/workflows/specs/template-schema.md`
+
+**Step 5.1** — Load `intent.json` + `dag.json`. Assemble template JSON.
+
+**Step 5.2** — Determine slug (kebab-case). If exists, append `-v2`.
+
+**Step 5.3** — Write `~/.maestro/templates/workflows/<slug>.json`.
+
+**Step 5.4** — Update `~/.maestro/templates/workflows/index.json`.
+
+**Step 5.5** — Output summary: path, template ID, node/checkpoint counts, required variables. Include usage commands: `$maestro-player <slug> --context goal="..."`, `$maestro-composer --edit <path>`, `$maestro-player --list`.
+
+**Step 5.6** — Clean up design draft directory.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Empty description and no flags | AskUserQuestion for description |
+| E002 | error | 0 steps extracted | Ask to rephrase with action verbs |
+| E003 | error | Node count exceeds 20 | Suggest splitting into sub-workflows |
+| E004 | error | DAG cycle detected | Show cycle, ask to resolve |
+| E005 | error | Resume session not found | Show available drafts |
+| E006 | error | Edit template not found | Show available templates |
+| W001 | warning | Ambiguous executor mapping | Show candidates, let user choose |
+| W002 | warning | No checkpoint rules triggered | Warn, offer manual add |
+| W003 | warning | Deferred spec not found | Use built-in fallback |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and confirmed by user (Phase 1 gate)
+- [ ] Nodes resolved and confirmed by user (Phase 2 gate)
+- [ ] DAG built with auto-injected checkpoints
+- [ ] Pipeline visualized and confirmed by user (Phase 4 gate)
+- [ ] Template JSON written to `~/.maestro/templates/workflows/<slug>.json`
+- [ ] Template index updated
+- [ ] Deferred specs loaded only when phase needs them
+</success_criteria>