pi-maestro-flow 0.2.0 → 0.3.0

package/workflows/maestro-link-coordinate.md

@@ -0,0 +1,114 @@
+# Workflow: maestro-link-coordinate
+
+Chain-graph coordinator via `maestro coordinate` CLI endpoint. Loads a chain graph, walks node by node via step-mode subcommands. Each command node executed through `maestro delegate` internally.
+
+---
+
+### Step 1: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+- Flags: `--list`, `-y`/`--yes`, `-c`/`--continue [id]`, `--chain <name>`, `--tool <name>` (default: claude)
+- `intent` = remaining text after flag removal
+
+---
+
+### Step 2: Handle --list
+
+```bash
+maestro coordinate list
+```
+
+Exit after display.
+
+---
+
+### Step 3: Start or Resume Session
+
+#### 3a: New session (step mode)
+
+```bash
+maestro coordinate start "{intent}" --tool {cliTool} [--chain {forcedChain}] [-y]
+```
+
+Include `--chain` and `-y` only when set. Returns JSON with `session_id`, `status`, `graph_id`, `current_node`, `last_step`, `history`.
+
+#### 3b: Resume existing session
+
+```bash
+maestro coordinate next {resumeId}
+```
+
+If bare `-c` (no ID), omit session ID to resume latest step_paused session. Same JSON output format.
+
+---
+
+### Step 4: Step Loop
+
+Loop `maestro coordinate next {session_id}` while `status === "step_paused"`. Log each step: `[Step N] /{cmd} — {outcome} — {summary}`. Exit loop on `completed` or `failed` → **Step 5**.
+
+The walker handles internally:
+- Prompt assembly (command nodes via `coordinate-step` template, decision nodes inline)
+- CLI execution via `maestro delegate --to {tool} --mode {write|analysis}`
+- Decision auto-resolution: `expr` (static, instant) or `llm` (CLI spawn, expects `DECISION: <target>\nREASONING: <text>`). Expr fallback to LLM when no matching/default edge.
+- max_visits loop prevention, state persistence to `.workflow/.maestro/coordinate-{session_id}/`
+- Channel telemetry published to `~/.maestro/data/async/` broker, observable via `maestro coordinate watch`
+
+> **Step-mode latency note**: LLM-driven decisions fire synchronous CLI spawns (several seconds). Do not impose tight per-step deadlines. Static `expr` decisions remain instant.
+
+---
+
+### Step 5: Completion
+
+```bash
+maestro coordinate status {session_id}
+```
+
+Display final summary:
+
+```
+============================================================
+  COORDINATE COMPLETE
+============================================================
+  Session: {session_id}
+  Graph:   {graph_id}
+  Status:  {completed|failed}
+
+  Steps:
+    [✓] plan — success — Plan generated
+    [✓] execute — success — Implementation done
+    [✗] verify — failure — 2 issues found
+    [→] check_result → retry_plan (decision)
+    [✓] retry_plan — success — Gaps fixed
+    [✓] retry_execute — success — All passing
+
+  Completed: {N} | Failed: {N}
+============================================================
+```
+
+---
+
+## CLI Endpoint Reference
+
+| Command | Description | Output |
+|---------|-------------|--------|
+| `maestro coordinate list` | List all chain graphs | Table to stdout |
+| `maestro coordinate start "intent" --chain X --tool Y` | Start step-mode session | JSON (session_id, status, last_step) |
+| `maestro coordinate next [sessionId]` | Execute next step | JSON (updated state) |
+| `maestro coordinate status [sessionId]` | Query session state | JSON (full state) |
+| `maestro coordinate run "intent" --chain X --tool Y` | Autonomous full run | JSON (final state) |
+| `maestro coordinate watch <sessionId> [--follow] [--since N] [--format json\|text]` | Stream walker events from broker (observer, read-only) | JSONL/text to stdout |
+| `maestro coordinate report --session <sid> --node <id> --status SUCCESS\|FAILURE [...]` | Agent-invoked result writer — the authoritative command-node result channel | Writes `.workflow/.maestro/coordinate-{sid}/reports/{node}.json`, exits 0 |
+
+---
+
+## Core Rules
+
+1. **All execution via CLI endpoint** — `maestro coordinate start/next/run`, never direct walker calls
+2. **Step mode by default** — `start` pauses after each command node, `next` advances one step
+3. **JSON protocol** — all subcommands output structured JSON to stdout, logs to stderr
+4. **Session persistence** — state at `.workflow/.maestro/coordinate-{session_id}/walker-state.json`
+5. **Decision auto-resolve** — walker evaluates `ctx.result.status` internally between steps; falls back to the injected LLM decider when `expr` has no matching edge and no default
+6. **Resume** — `next {sessionId}` continues any step_paused session
+7. **Autonomous fallback** — `run` walks entire graph without pausing (backward compat)
+8. **Observation is separate from driving** — `watch` is a read-only tail on the broker; it does not advance the walker. Use it alongside `next` or `run` for live progress without disturbing the driver loop.
+9. **Result channel** — command-node results are written by the agent via `maestro coordinate report` to a JSON file the walker reads preferentially over stdout parsing.

package/workflows/maestro-super.md

@@ -0,0 +1,120 @@
+# Super Mode (`--super`)
+
+Goal: deliver a production-ready, complete software system from user requirements. No user decisions needed — maestro autonomously expands, refines, and implements until the system meets mainstream quality standards.
+
+Super mode implies `-y` (all auto flags propagated) plus these additional behaviors:
+
+## 1. Requirement Expansion
+
+On receiving user intent, autonomously expand incomplete requirements into a complete product scope. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Delegate via role (`maestro delegate --role analyze --mode analysis`) for requirement completeness analysis and gap-filling. Accept requirements that add real user value; discard noise.
+
+## 2. Progressive Document Loading
+
+Read execution documents (workflow maestro.md, chain steps) incrementally per-phase rather than loading all upfront. Each milestone loads only the relevant section to preserve context window.
+
+## 3. Autonomous Decision-Making
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: All design/architecture/scope decisions are made via Gemini delegate (`--mode analysis`). No AskUserQuestion calls. Decision criteria: mainstream industry standards, pragmatism, simplicity.
+
+## 4. Auto-Advance Milestones
+
+After each milestone completes and passes verification, automatically advance to the next milestone without user confirmation. Run `maestro-milestone-complete` → next milestone chain automatically.
+
+## 5. Quality Gate Scoring
+
+Each milestone must pass a readiness score before advancing. Prevents premature exit.
+
+| Dimension | Weight | Minimum |
+|-----------|--------|---------|
+| Code completeness (features implemented vs planned) | 25% | 90% |
+| Test coverage (lines + branches) | 20% | 70% |
+| Build & run success (clean build, app starts) | 20% | 100% |
+| Code quality (lint clean, no ts errors) | 15% | 90% |
+| Integration coherence (cross-module contracts) | 10% | 80% |
+| Documentation (API docs, README, setup guide) | 10% | 60% |
+| **Weighted total** | | **≥ 80%** |
+
+Score is computed via `maestro-execute` verification gate + Gemini analysis. If score < 80%, generate fix plan and re-execute until threshold is met (max 3 retries per milestone, then report blockers).
+
+## 6. Completion Criteria
+
+Super mode only terminates when:
+- All roadmap milestones completed and scored ≥ 80%
+- Final system builds, starts, and passes all tests
+- Gemini confirms the system is production-ready via final audit
+
+## 7. State Tracking
+
+Super mode extends the standard session `status.json` (`.workflow/.maestro/{session_id}/status.json`). No extra files — all state in one place.
+
+### 7a. status.json 扩展字段
+
+```json
+{
+  "session_id": "...",
+  "status": "running",
+  "super": true,
+  "super_state": "expanding|planning|executing|scoring|advancing|completed|blocked",
+  "current_milestone": 1,
+  "total_milestones": 3,
+  "expanded_requirements": "...",
+  "milestones": [
+    {
+      "index": 1,
+      "name": "...",
+      "status": "pending|executing|scoring|completed|blocked",
+      "chain_session_id": null,
+      "retries": 0,
+      "max_retries": 3,
+      "scores": {
+        "code_completeness": null,
+        "test_coverage": null,
+        "build_success": null,
+        "code_quality": null,
+        "integration_coherence": null,
+        "documentation": null,
+        "weighted_total": null
+      },
+      "score_history": [],
+      "decisions": []
+    }
+  ],
+  "decision_log": [],
+  "steps": [ ... ]
+}
+```
+
+`super_state` values:
+- `expanding` — requirement expansion via Gemini
+- `planning` — roadmap/spec/plan generation
+- `executing` — milestone chain execution (plan → execute → verify)
+- `scoring` — quality gate evaluation
+- `advancing` — milestone-complete + next milestone setup
+- `completed` — all milestones passed
+- `blocked` — max retries exceeded, needs user intervention
+
+### 7b. State transitions
+
+```
+[start] → expanding → planning → executing(M1) → scoring(M1)
+  → score ≥ 80% → advancing → executing(M2) → ...
+  → score < 80% → retries < 3 → executing(M1) (retry)
+  → score < 80% → retries = 3 → blocked
+  → all milestones completed → completed
+```
+
+### 7c. Resume (`-c` or `continue`)
+
+On resume, read `status.json`:
+1. Check `super: true` → enter super mode resume
+2. Read `super_state` + `current_milestone` → determine resume point
+3. Read milestone's `status` → resume from exact phase (e.g., interrupted during `scoring` → re-run scoring)
+4. Load `decision_log` for Gemini continuity
+
+### 7d. State update discipline
+
+Update `status.json` at every state transition:
+- Before milestone chain → set milestone `status: "executing"`, increment retries if retry
+- After scoring → write scores to milestone, append to `score_history`
+- After advancing → set previous milestone `status: "completed"`, bump `current_milestone`
+- On block → set milestone `status: "blocked"`, set `super_state: "blocked"`