maestro-flow 0.1.4 → 0.2.0

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

@@ -1,167 +1,167 @@
----
-name: maestro-init
-description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
-argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-## Auto Mode
-
-When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
-
-# Maestro Init (Single Agent)
-
-## Usage
-
-```bash
-$maestro-init ""
-$maestro-init "--auto"
-$maestro-init "--from-brainstorm brainstorm-auth-20260318"
-```
-
-**Flags**:
-- `--auto`: Skip interactive questioning; extract from provided document
-- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
-
-**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
-
----
-
-## Overview
-
-Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
-
----
-
-## Implementation
-
-### Step 1: Parse Arguments
-
-Extract flags from arguments:
-- `--auto` flag presence
-- `--from-brainstorm SESSION-ID` value
-- Remaining text as project description
-
-### Step 2: Detect Project State
-
-```bash
-# Check existing state
-ls .workflow/state.json 2>/dev/null
-ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
-```
-
-Classify as:
-- **existing**: `.workflow/state.json` found — warn and exit (E002)
-- **code**: Source files present but no `.workflow/` — onboarding existing codebase
-- **empty**: Greenfield project
-
-### Step 3: Gather Project Information
-
-**If `--from-brainstorm`**:
-- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
-- Extract: vision, goals, constraints, terminology, tech decisions
-- Skip interactive questioning
-
-**If `--auto`**:
-- Extract project info from provided document/@ reference
-- Minimal interactive questions (confirm core value only)
-
-**Otherwise (interactive)**:
-- Deep questioning flow:
-  1. What is the core value proposition?
-  2. Who are the target users?
-  3. What are the key requirements? (follow threads, don't rush)
-  4. What are known constraints/limitations?
-  5. What tech stack preferences exist?
-- Follow each thread with clarifying questions until satisfied
-
-### Step 4: Read Templates
-
-Read the following templates:
-- `~/.maestro/templates/project.md`
-- `~/.maestro/templates/state.json`
-- `~/.maestro/templates/config.json`
-
-### Step 5: Create .workflow/ Structure
-
-```bash
-mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
-```
-
-### Step 6: Write project.md
-
-Populate template with gathered information:
-- Project name, core value proposition
-- Requirements: Validated / Active / Out of Scope
-- Key decisions and constraints
-- Tech stack (detected or specified)
-
-Write to `.workflow/project.md`.
-
-### Step 7: Write state.json
-
-Initialize state from template:
-- `current_phase`: null
-- `current_milestone`: null
-- `status`: "initialized"
-
-Write to `.workflow/state.json`.
-
-### Step 8: Write config.json
-
-Configuration questions (or defaults for --auto):
-- Granularity: fine / medium / coarse
-- Workflow agents: enable/disable optional agents
-- Gate preferences: verification strictness
-
-Write to `.workflow/config.json`.
-
-### Step 9: Initialize specs/
-
-Create convention files in `.workflow/specs/`:
-- `conventions.md` — detected or specified coding conventions
-- `learnings.md` — empty, populated during phase transitions
-
-### Step 10: Completion Report
-
-```
-=== WORKFLOW INITIALIZED ===
-Project: {project_name}
-State:   .workflow/state.json (active)
-
-Created:
-  .workflow/project.md
-  .workflow/state.json
-  .workflow/config.json
-  .workflow/specs/
-
-Next steps (choose one path to create roadmap):
-  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
-  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
-
-Other commands:
-  $maestro-status                   -- View project dashboard
-  $maestro-brainstorm "<topic>"     -- Explore ideas first
-  $maestro-quick "<task>"           -- Quick ad-hoc task
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No arguments when --auto requires document | Ask user for document reference |
-| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
-| E003 | error | Brainstorm session not found | List available sessions |
-| W001 | warning | Could not detect tech stack | Continue with manual input |
-
----
-
-## Core Rules
-
-1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
-2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
-3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
-4. **Templates are source of truth** — always read templates before writing files
-5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)
+---
+name: maestro-init
+description: Initialize project with auto state detection — creates .workflow/ directory, project.md, state.json, config.json, and specs/
+argument-hint: "[--auto] [--from-brainstorm SESSION-ID]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `--auto`: After config questions, run research without further interaction. Expects idea document via @ reference.
+
+# Maestro Init (Single Agent)
+
+## Usage
+
+```bash
+$maestro-init ""
+$maestro-init "--auto"
+$maestro-init "--from-brainstorm brainstorm-auth-20260318"
+```
+
+**Flags**:
+- `--auto`: Skip interactive questioning; extract from provided document
+- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
+
+**Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
+
+---
+
+## Overview
+
+Sequential project setup skill. Detects project state (empty/code/existing), gathers project information through deep questioning or document extraction, then creates the `.workflow/` directory structure. No parallel agents — single sequential flow.
+
+---
+
+## Implementation
+
+### Step 1: Parse Arguments
+
+Extract flags from arguments:
+- `--auto` flag presence
+- `--from-brainstorm SESSION-ID` value
+- Remaining text as project description
+
+### Step 2: Detect Project State
+
+```bash
+# Check existing state
+ls .workflow/state.json 2>/dev/null
+ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
+```
+
+Classify as:
+- **existing**: `.workflow/state.json` found — warn and exit (E002)
+- **code**: Source files present but no `.workflow/` — onboarding existing codebase
+- **empty**: Greenfield project
+
+### Step 3: Gather Project Information
+
+**If `--from-brainstorm`**:
+- Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
+- Extract: vision, goals, constraints, terminology, tech decisions
+- Skip interactive questioning
+
+**If `--auto`**:
+- Extract project info from provided document/@ reference
+- Minimal interactive questions (confirm core value only)
+
+**Otherwise (interactive)**:
+- Deep questioning flow:
+  1. What is the core value proposition?
+  2. Who are the target users?
+  3. What are the key requirements? (follow threads, don't rush)
+  4. What are known constraints/limitations?
+  5. What tech stack preferences exist?
+- Follow each thread with clarifying questions until satisfied
+
+### Step 4: Read Templates
+
+Read the following templates:
+- `~/.maestro/templates/project.md`
+- `~/.maestro/templates/state.json`
+- `~/.maestro/templates/config.json`
+
+### Step 5: Create .workflow/ Structure
+
+```bash
+mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
+```
+
+### Step 6: Write project.md
+
+Populate template with gathered information:
+- Project name, core value proposition
+- Requirements: Validated / Active / Out of Scope
+- Key decisions and constraints
+- Tech stack (detected or specified)
+
+Write to `.workflow/project.md`.
+
+### Step 7: Write state.json
+
+Initialize state from template:
+- `current_phase`: null
+- `current_milestone`: null
+- `status`: "initialized"
+
+Write to `.workflow/state.json`.
+
+### Step 8: Write config.json
+
+Configuration questions (or defaults for --auto):
+- Granularity: fine / medium / coarse
+- Workflow agents: enable/disable optional agents
+- Gate preferences: verification strictness
+
+Write to `.workflow/config.json`.
+
+### Step 9: Initialize specs/
+
+Create convention files in `.workflow/specs/`:
+- `conventions.md` — detected or specified coding conventions
+- `learnings.md` — empty, populated during phase transitions
+
+### Step 10: Completion Report
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+
+Next steps (choose one path to create roadmap):
+  $maestro-spec-generate "<idea>"   -- Full spec package + roadmap (heavy)
+  $maestro-roadmap "<requirement>"  -- Direct interactive roadmap (light)
+
+Other commands:
+  $maestro-status                   -- View project dashboard
+  $maestro-brainstorm "<topic>"     -- Explore ideas first
+  $maestro-quick "<task>"           -- Quick ad-hoc task
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No arguments when --auto requires document | Ask user for document reference |
+| E002 | error | .workflow/ already exists | Show status, suggest manage-status |
+| E003 | error | Brainstorm session not found | List available sessions |
+| W001 | warning | Could not detect tech stack | Continue with manual input |
+
+---
+
+## Core Rules
+
+1. **Never create roadmap** — init only creates .workflow/ structure; roadmap is a separate step
+2. **Deep questioning over speed** — follow threads, ask clarifying questions (unless --auto)
+3. **Detect, don't assume** — scan for existing files, package managers, frameworks before asking
+4. **Templates are source of truth** — always read templates before writing files
+5. **Idempotent check** — if .workflow/ exists, refuse to overwrite (E002)

package/.codex/skills/maestro-link-coordinate/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: maestro-link-coordinate
+description: Step-mode graph coordinator via maestro coordinate CLI endpoint. Walks chain graphs node by node using start/next/status subcommands. Decision and gate nodes auto-resolve between steps. Session persisted for resume via -c.
+argument-hint: "\"intent text\" [--list] [-c [sessionId]] [--chain <name>] [--tool <tool>] [-y]"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+## Auto Mode
+
+When `-y` or `--yes`: Skip step confirmations between nodes. Runs to completion without pausing.
+
+# Maestro Link Coordinate
+
+## Usage
+
+```bash
+$maestro-link-coordinate "implement OAuth2 authentication"
+$maestro-link-coordinate "--list"
+$maestro-link-coordinate -c "MLC-20260401-143022"
+$maestro-link-coordinate --chain quality-full-cycle "fix all test failures"
+$maestro-link-coordinate -y "refactor auth module"
+```
+
+**Flags**:
+- `--list` — List all available chain graphs (uses `maestro coordinate list`)
+- `-c / --continue [sessionId]` — Resume `step_paused` session; uses last session if no id given
+- `--chain <name>` — Force a specific chain graph
+- `--tool <tool>` — CLI tool override for command nodes (default: claude)
+- `-y / --yes` — Auto mode: no step confirmations
+
+**CLI endpoints used**:
+- `maestro coordinate list` — enumerate available chains
+- `maestro coordinate start "intent" --chain X` — begin step-mode session
+- `maestro coordinate next [sessionId]` — advance one step
+- `maestro coordinate status [sessionId]` — query current state
+- `maestro coordinate run "intent"` — autonomous full run (used when `-y`)
+- `maestro coordinate watch <sessionId> [--follow]` — read-only event tail
+- `maestro coordinate report` — agent-invoked result writer (authoritative result channel)
+
+---
+
+## Overview
+
+Step-mode coordinator that drives `maestro coordinate` CLI subcommands one node at a time. Each call to `maestro coordinate next` advances the walker one graph node forward. Decision nodes resolve via `strategy: 'expr'` fast-path with LLM decider fallback. Gate nodes auto-bypass when conditions are met. The driver loop calls `next` until session status is `completed` or `step_paused` (on user checkpoint). Sessions are persisted by the server; `-c` resumes from the last paused node.
+
+```
++-------------------------------------------------------------------+
+|  maestro-link-coordinate Driver Loop                               |
++-------------------------------------------------------------------+
+|                                                                   |
+|  Phase 1: Session Start                                           |
+|     +-- Parse flags                                               |
+|     +-- [--list] exec: coordinate list → display → stop           |
+|     +-- [-c] exec: coordinate status [sessionId] → resume loop    |
+|     +-- exec: coordinate start "intent" --chain X                 |
+|     +-- Parse sessionId from output                               |
+|                                                                   |
+|  Phase 2: Step Driver Loop                                        |
+|     +-- while (status != completed):                              |
+|     |   +-- exec: coordinate next [sessionId]                     |
+|     |   +-- Parse node type from output:                          |
+|     |   |   command    → display result, [confirm?]               |
+|     |   |   decision   → auto-resolved by walker (expr / llm)     |
+|     |   |   gate       → auto-bypassed if conditions met          |
+|     |   |   checkpoint → pause, display status, await user        |
+|     |   +-- Update progress display                               |
+|     +-- exec: coordinate status [sessionId] after completion      |
+|                                                                   |
+|  Phase 3: Completion Summary                                       |
+|     +-- Display per-node execution results                        |
+|     +-- Show final session state                                  |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Implementation
+
+### Phase 1: Session Start
+
+```javascript
+functions.update_plan({
+  explanation: "Starting link-coordinate session",
+  plan: [
+    { step: "Phase 1: Session start", status: "in_progress" },
+    { step: "Phase 2: Step driver loop", status: "pending" },
+    { step: "Phase 3: Completion summary", status: "pending" }
+  ]
+})
+```
+
+**Quick-exit: `--list`**
+```javascript
+functions.exec_command({
+  cmd: "maestro coordinate list",
+  workdir: "."
+})
+// Display output and stop
+```
+
+**Resume mode: `-c [sessionId]`**
+```javascript
+functions.exec_command({
+  cmd: `maestro coordinate status ${sessionId || ''}`,
+  workdir: "."
+})
+// Parse sessionId from output, skip to Phase 2 driver loop
+```
+
+**Fresh session**:
+```javascript
+functions.exec_command({
+  cmd: `maestro coordinate start "${intent}"${chain ? ' --chain ' + chain : ''}`,
+  workdir: "."
+})
+// Parse sessionId from JSON output: { "session_id": "...", "chain": "...", "first_node": "..." }
+```
+
+### Phase 2: Step Driver Loop
+
+```javascript
+functions.update_plan({
+  explanation: "Stepping through chain graph",
+  plan: [
+    { step: "Phase 1: Session start", status: "completed" },
+    { step: "Phase 2: Step driver loop", status: "in_progress" },
+    { step: "Phase 3: Completion summary", status: "pending" }
+  ]
+})
+```
+
+Main loop:
+```javascript
+while (status !== 'completed' && status !== 'failed') {
+  functions.exec_command({
+    cmd: `maestro coordinate next ${sessionId}`,
+    workdir: "."
+  })
+  // Parse response JSON: { node_type, node_id, status, result, next_status }
+}
+```
+
+**Node type handling**:
+
+| node_type | Action |
+|-----------|--------|
+| `command` | Display result summary; if `!AUTO_YES`, call `request_user_input` to confirm before next |
+| `decision` | Auto-resolved by walker (expr fast-path or LLM). Display resolved edge. |
+| `gate` | Auto-bypassed if conditions met. Display gate status. |
+| `checkpoint` | Pause loop, display current state, await explicit user `$maestro-link-coordinate -c` |
+| `eval` | Display evaluation result and score |
+
+**Auto mode (`-y`)**: Use `maestro coordinate run "${intent}"` instead of start + next loop for autonomous execution.
+
+**Watch mode** (optional, for long-running steps):
+```javascript
+functions.exec_command({
+  cmd: `maestro coordinate watch ${sessionId} --follow`,
+  workdir: "."
+})
+```
+
+### Phase 3: Completion Summary
+
+```javascript
+functions.exec_command({
+  cmd: `maestro coordinate status ${sessionId}`,
+  workdir: "."
+})
+```
+
+```javascript
+functions.update_plan({
+  explanation: "Link-coordinate complete",
+  plan: [
+    { step: "Phase 1: Session start", status: "completed" },
+    { step: "Phase 2: Step driver loop", status: "completed" },
+    { step: "Phase 3: Completion summary", status: "completed" }
+  ]
+})
+```
+
+Display:
+```
+=== GRAPH WALK COMPLETE ===
+Session:  <sessionId>
+Chain:    <chain>
+Nodes:    <N> executed
+
+NODE RESULTS:
+  [1] <node_id> (command)  — completed ✓
+  [2] <node_id> (decision) — resolved: <edge>
+  [3] <node_id> (command)  — completed ✓
+
+To re-run: $maestro-link-coordinate "<intent>" --chain <chain>
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and no `--list`/`--chain` provided | Suggest `--list` to see available chains |
+| E002 | error | Chain graph not found | Display `maestro coordinate list` output |
+| E003 | error | Step execution failed on a command node | Check node result, use `-c` to retry from that node |
+| E004 | error | Resume session not found | List sessions in coordinate status |
+| E005 | error | `maestro coordinate` CLI endpoint unavailable | Check maestro installation |
+
+---
+
+## Core Rules
+
+1. **Quick-exit for `--list`**: Never start a session if user only wants to list chains
+2. **One step at a time**: Drive with `coordinate next` calls — never batch-advance multiple nodes
+3. **Decision nodes are walker-owned**: Never try to resolve decision nodes manually; trust walker output
+4. **Checkpoint is a hard pause**: Never auto-advance past a checkpoint node without explicit user confirmation
+5. **Resume is server-side**: Session state is held by the server; `-c` only provides the sessionId — the walker has all state
+6. **Auto mode uses `run`**: When `-y`, use `coordinate run` directly rather than the start + next loop
+7. **Status is authoritative**: After loop exits, always call `coordinate status` to get the canonical final state