maestro-flow 0.3.7 → 0.3.9

package/.codex/skills/maestro-milestone-complete/SKILL.md

@@ -1,158 +1,149 @@
----
-name: maestro-milestone-complete
-description: Archive completed milestone and prepare for next. Validates all phases complete, creates archive, extracts learnings, updates state.json.
-argument-hint: "[milestone] [--force]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Milestone Complete
-
-## Usage
-
-```bash
-$maestro-milestone-complete "v1.0"
-$maestro-milestone-complete              # uses current_milestone from state.json
-$maestro-milestone-complete --force "v1.0"  # skip audit check
-```
-
-**Flags**:
-- `[milestone]`: Target milestone identifier (default: current_milestone from state.json)
-- `--force`: Skip audit verification, complete without passing audit
-
-**Output**: `.workflow/milestones/{milestone}/` archive directory
-
----
-
-## Overview
-
-Sequential milestone archival: validate audit + phases -> create archive -> extract learnings -> update state -> report.
-
----
-
-## Implementation
-
-### Step 1: Parse Input
-
-1. Read `.workflow/state.json` to get `current_milestone`
-2. If `$ARGUMENTS` contains a milestone identifier, use it; otherwise use `current_milestone`
-3. Detect `--force` flag
-4. If no milestone resolvable: **E001** -- exit
-
-### Step 2: Validate Completion
-
-**2a. Check audit report:**
-```
-Read .workflow/milestone-audit-{milestone}.md
-```
-- If missing and not `--force`: **E002** -- warn "No audit report found. Run milestone-audit first." Ask user to proceed or abort.
-- If verdict is FAIL and not `--force`: **E002** -- exit with suggestion to fix failing items
-
-**2b. Verify all phases completed:**
-```
-For each phase in milestone (from roadmap.md):
-  Read .workflow/phases/{NN}-{slug}/index.json
-  If status != "completed": E003 -- list incomplete phases, exit
-```
-
-### Step 3: Create Archive
-
-1. Create archive directory:
-   ```bash
-   mkdir -p .workflow/milestones/{milestone}/phases/
-   ```
-
-2. Snapshot roadmap:
-   ```bash
-   cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
-   ```
-
-3. Archive each phase directory:
-   ```bash
-   cp -r .workflow/phases/{NN}-{slug}/ .workflow/milestones/{milestone}/phases/{NN}-{slug}/
-   ```
-
-4. Copy audit report (if exists):
-   ```bash
-   cp .workflow/milestone-audit-{milestone}.md .workflow/milestones/{milestone}/audit-report.md
-   ```
-
-### Step 4: Extract Learnings
-
-1. Load existing learnings from `.workflow/specs/learnings.md` to avoid duplicates
-2. For each phase, read `reflection-log.md` if exists:
-   - Extract strategy adjustments, patterns discovered, pitfalls encountered
-3. Append aggregated learnings to `.workflow/specs/learnings.md`:
-   ```markdown
-   ## Milestone {milestone} Learnings ({date})
-
-   ### Strategy Adjustments
-   - {from reflection-log entries}
-
-   ### Patterns Discovered
-   - {from reflection-log entries}
-
-   ### Pitfalls Encountered
-   - {from reflection-log entries}
-   ```
-
-### Step 5: Update State
-
-1. Update `.workflow/state.json`:
-   - `current_milestone` -> next version (increment minor)
-   - `current_phase` -> 1 (reset)
-   - `status` -> "idle"
-   - Reset `phases_summary` counters
-   - Preserve `accumulated_context` (decisions + deferred items carry forward)
-   - Set `last_updated` timestamp
-
-2. Clean up completed phase directories:
-   ```bash
-   rm -rf .workflow/phases/{NN}-{slug}/  # for each archived phase
-   ```
-   Keep `.workflow/phases/` directory (empty, ready for new milestone).
-
-### Step 6: Report and Route
-
-Display completion summary:
-```
-====================================================
-  MILESTONE COMPLETED: {milestone}
-====================================================
-
-Archived:
-  - {N} phases archived to .workflow/milestones/{milestone}/
-  - Roadmap snapshot saved
-  - Audit report archived
-  - {M} learnings extracted to specs/learnings.md
-
-State reset:
-  - Current milestone: {next_milestone}
-  - Current phase: 1
-  - Status: idle
-
-====================================================
-```
-
-Suggest next steps:
-- "Start planning next milestone?" -> Skill({ skill: "maestro-plan" })
-- "Project is idle." -> Skill({ skill: "manage-status" })
-
----
-
-## Error Handling
-
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone identifier required and not resolvable | Prompt user for milestone |
-| E002 | error | Audit not passed (missing or FAIL verdict) | Run milestone-audit first, or use --force |
-| E003 | error | Incomplete phases remain | Complete or verify remaining phases |
-
----
-
-## Core Rules
-
-- **Never delete** phase directories before archiving -- always copy first
-- **Preserve** `accumulated_context` across milestone boundaries
-- **Learnings dedup** -- check existing entries before appending
-- **Git commit** if in a git repo: `chore: complete milestone {milestone}`
-- **--force** bypasses audit check only, not phase completion check
+---
+name: maestro-milestone-complete
+description: Archive completed milestone scratch artifacts to milestones/ dir, move artifact entries to milestone_history, extract learnings, advance state.
+argument-hint: "[milestone] [--force]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Milestone Complete
+
+## Usage
+
+```bash
+$maestro-milestone-complete "M1"
+$maestro-milestone-complete              # uses current_milestone from state.json
+$maestro-milestone-complete --force "M1"  # skip audit check
+```
+
+**Output**: `.workflow/milestones/{milestone}/` archive directory
+
+---
+
+## Overview
+
+Sequential milestone archival: validate audit → archive scratch dirs → extract learnings → move artifact entries to milestone_history → advance state → clean scratch.
+
+---
+
+## Implementation
+
+### Step 1: Parse & Validate
+
+1. Read `.workflow/state.json` to get `current_milestone`, `artifacts[]`, `milestones[]`
+2. Determine target milestone (from args or current_milestone)
+3. Check `--force` flag
+4. If no milestone: **E001**
+5. Check audit report exists at `.workflow/milestones/{milestone}/audit-report.md`
+   - Missing + not --force: **E002**
+   - Verdict FAIL + not --force: **E002**
+6. Check all milestone artifacts completed:
+   - `state.json.artifacts.filter(a => a.milestone == target && a.status != "completed")`
+   - If any incomplete + not --force: **E003**
+
+### Step 2: Archive Scratch Dirs
+
+```bash
+mkdir -p .workflow/milestones/{milestone}/artifacts/
+
+# For each artifact path, copy to archive
+for artifact in milestone_artifacts:
+  if dir exists .workflow/{artifact.path}:
+    cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/$(basename {artifact.path})/
+```
+
+Snapshot roadmap:
+```bash
+cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
+```
+
+### Step 3: Extract Learnings
+
+- Read `.summaries/` from each execute artifact's plan dir
+- Read `reflection-log.md` if exists
+- Extract patterns, pitfalls, strategy adjustments
+- Append to `.workflow/specs/learnings.md`
+- Avoid duplicates (check existing entries)
+
+### Step 4: Archive Artifact Entries
+
+Move artifact entries from `state.json.artifacts[]` to `milestone_history`:
+
+```json
+{
+  "milestone_history": [
+    ...existing,
+    {
+      "id": "{milestone}",
+      "name": "{milestone_name}",
+      "status": "completed",
+      "completed_at": "{now}",
+      "archive_path": "milestones/{milestone}/",
+      "archived_artifacts": [ ...all milestone artifact entries... ]
+    }
+  ]
+}
+```
+
+Remove from `artifacts[]`:
+```
+state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target)
+```
+
+### Step 5: Advance State
+
+```
+next = state.json.milestones.find(m => m.status == "pending")
+if next:
+  state.json.current_milestone = next.id
+  next.status = "active"
+else:
+  state.json.current_milestone = null
+  state.json.status = "completed"
+
+state.json.last_updated = now()
+Write state.json (atomic)
+```
+
+### Step 6: Clean Scratch
+
+```bash
+for artifact in archived_artifacts:
+  rm -rf .workflow/{artifact.path}
+```
+
+### Step 7: Generate Summary & Report
+
+Write `.workflow/milestones/{milestone}/summary.md` with outcomes and learnings.
+Update `.workflow/project.md` Context section.
+
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone} ({name})
+Artifacts: {count} archived
+Next:      {next_milestone or "Project complete"}
+
+Next steps:
+  $maestro-milestone-release  -- Cut release
+  $maestro-analyze            -- Start next milestone
+  $manage-status              -- View state
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Milestone identifier required | Specify milestone |
+| E002 | error | Audit not passed | Run milestone-audit first |
+| E003 | error | Incomplete artifacts remain | Complete work first |
+
+---
+
+## Core Rules
+
+1. **Audit before archive** — refuse without passing audit (unless --force)
+2. **Atomic state update** — write state.json via tmp+rename
+3. **Learnings are mandatory** — always extract before archiving
+4. **Clean after archive** — remove scratch dirs only after successful copy
+5. **Advance state** — always set next milestone or mark project complete

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

@@ -163,13 +163,48 @@ const phaseArg = $ARGUMENTS
   .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--auto|--gaps|--parallel|--collab|--dir\s+\S+|--spec\s+\S+/g, '')
   .trim()
 
+// Auto-bootstrap state.json if missing
+if (!fileExists('.workflow/state.json')) {
+  Bash('mkdir -p .workflow/scratch/')
+  writeMinimalStateJson()
+}
+
+// Scope determination (per scratch-milestone-architecture)
+const state = JSON.parse(Read('.workflow/state.json'))
+let scope, phaseNum = null, phaseSlug, contextDir
+
+if (dirMatch) {
+  contextDir = dirMatch[1]
+  phaseSlug = contextDir.split('/').pop()
+  // Inherit scope from parent artifact if registered
+  const parentArtifact = state.artifacts.find(a => a.path === contextDir)
+  scope = parentArtifact?.scope || 'standalone'
+} else if (phaseArg === '') {
+  if (state.current_milestone && fileExists('.workflow/roadmap.md')) {
+    scope = 'milestone'
+    phaseSlug = slugify(state.milestones.find(m => m.id === state.current_milestone)?.name || state.current_milestone)
+    // Find latest analyze artifact for this milestone
+    contextDir = state.artifacts.filter(a => a.type === 'analyze' && a.milestone === state.current_milestone && a.status === 'completed').pop()?.path
+  } else {
+    ERROR('E001: No args and no roadmap')
+  }
+} else if (/^\d+$/.test(phaseArg)) {
+  scope = 'phase'
+  phaseNum = parseInt(phaseArg)
+  phaseSlug = resolvePhaseSlugFromRoadmap(phaseNum)
+  contextDir = state.artifacts.filter(a => a.type === 'analyze' && a.milestone === state.current_milestone && a.phase === phaseNum && a.status === 'completed').pop()?.path
+} else {
+  scope = state.current_milestone ? 'adhoc' : 'standalone'
+  phaseSlug = phaseArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+}
+
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = dirMatch
-  ? `plan-${dirMatch[1].split('/').pop()}-${dateStr}`
-  : `plan-phase${phaseArg}-${dateStr}`
+const sessionId = `plan-${phaseSlug}-${dateStr}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
+const scratchDir = `.workflow/scratch/plan-${phaseSlug}-${dateStr}`
 
 Bash(`mkdir -p ${sessionFolder}`)
+Bash(`mkdir -p ${scratchDir}/.task/`)
 ```
 
 ---
@@ -180,25 +215,20 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**:
-
-| Condition | Action |
-|-----------|--------|
-| `--dir <path>` provided | Use path directly, set SCRATCH_MODE = true |
-| Number argument | Resolve `.workflow/phases/{NN}-*/` |
-| Slug argument | Resolve `.workflow/phases/*-{slug}/` |
+1. **Scope resolution**: Already determined in Session Initialization (milestone/phase/adhoc/standalone)
 
-2. **Context loading**:
-   - Read `{PHASE_DIR}/context.md` (user decisions from analyze)
-   - Read `{PHASE_DIR}/index.json` (phase metadata, success criteria)
-   - Read spec-ref if `--spec` flag or index.json has spec_ref
+2. **Context loading** (from upstream analyze artifact or --dir):
+   - Read `{contextDir}/context.md` (user decisions from analyze) — if contextDir resolved
+   - Read `.workflow/project.md` — project vision and constraints
+   - Read `.workflow/roadmap.md` — phase structure and dependencies
+   - Read spec-ref if `--spec` flag
    - Read `.workflow/codebase/doc-index.json` if exists
-   - Read `{PHASE_DIR}/design-ref/MASTER.md` if exists (UI design reference)
+   - Find design artifacts from `state.json.artifacts[]` (type=brainstorm with ui-designer) for MASTER.md
    - Load project specs via `maestro spec load --category planning`
 
 3. **Upstream analysis check**:
-   - If `{PHASE_DIR}/conclusions.json` exists and has content: reuse as exploration context, skip wave 1
-   - If `{PHASE_DIR}/explorations.json` exists: load as additional context
+   - If `{contextDir}/conclusions.json` exists and has content: reuse as exploration context, skip wave 1
+   - If `{contextDir}/explorations.json` exists: load as additional context
 
 4. **Gap mode** (if `--gaps`):
    - Load gaps from `.workflow/issues/issues.jsonl` (primary), `verification.json` (fallback), `uat.md` (additional)

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

@@ -73,7 +73,7 @@ $maestro-roadmap --from-brainstorm WFS-001 "Enhance auth system"
 |     +-- Interactive refinement (max 3 rounds, skip if -y)                 |
 |     +-- Generate context.md with roadmap summary                          |
 |     +-- Write .workflow/roadmap.md                                        |
-|     +-- Create phase directories under .workflow/phases/                  |
+|     +-- Ensure .workflow/scratch/ directory exists                         |
 |     +-- Display summary with next steps                                   |
 |                                                                           |
 +---------------------------------------------------------------------------+
@@ -303,7 +303,8 @@ spawn_agents_on_csv({
 
 5. **Write outputs**:
    - Write `.workflow/roadmap.md` using standard roadmap template structure
-   - Create phase directories: `.workflow/phases/{NN}-{slug}/` with empty `index.json`
+   - Ensure `.workflow/scratch/` directory exists (phases are labels, not directories)
+   - Update `state.json` milestones array and set `current_milestone`
    - Update `.workflow/state.json` (if exists): set `current_phase: 1`
 
 6. Display summary:

package/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md

@@ -126,8 +126,8 @@ Read-only status report with progress milestones. No pipeline advancement.
 
 **CLI equivalent for human monitoring** (works while coordinator is blocked):
 ```bash
-maestro msg list -s "<session_id>" --type progress --last 10
-maestro msg list -s "<session_id>" --type blocker
+maestro agent-msg list -s "<session_id>" --type progress --last 10
+maestro agent-msg list -s "<session_id>" --type blocker
 ```
 
 Then STOP.

package/.codex/skills/team-executor/roles/executor/commands/monitor.md

@@ -97,7 +97,7 @@ const blockerMsgs = mcp__maestro-tools__team_msg({
 [executor] Commands: 'resume' to advance | 'check' to refresh
 
 **CLI monitoring** (works while executor is blocked):
-maestro msg list -s "<session_id>" --type progress --last 10
+maestro agent-msg list -s "<session_id>" --type progress --last 10
 ```
 
 Then STOP.

package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md

@@ -67,8 +67,8 @@ Read-only status report from tasks.json + team_msg progress, then STOP.
 
 **CLI equivalent for human monitoring** (no coordinator needed):
 ```bash
-maestro msg list -s "<session_id>" --type progress --last 10
-maestro msg list -s "<session_id>" --type blocker
+maestro agent-msg list -s "<session_id>" --type progress --last 10
+maestro agent-msg list -s "<session_id>" --type blocker
 ```
 
 ## handleResume

package/.codex/skills/team-lifecycle-v4/specs/knowledge-transfer.md

@@ -131,7 +131,7 @@ Prevents redundant research across tasks.
 ## 6. Progress Milestone Protocol
 
 Workers report progress during execution via `team_msg`. This provides:
-- **Human CLI monitoring**: `maestro msg list -s <session-id> --type progress` works while coordinator is blocked in `wait_agent`
+- **Human CLI monitoring**: `maestro agent-msg list -s <session-id> --type progress` works while coordinator is blocked in `wait_agent`
 - **Coordinator post-wait trace**: Full execution history for forensics and status display
 - **Blocker awareness**: Coordinator knows where worker got stuck on timeout
 
@@ -169,7 +169,7 @@ mcp__maestro-tools__team_msg({
 `wait_agent` is **blocking** — coordinator cannot read team_msg during wait. Progress is only consumed:
 1. On `handleCheck` (user types "check" while coordinator is idle)
 2. On `handleResume` after `wait_agent` returns (drain bus before collecting discoveries)
-3. By human via `maestro msg list` CLI (works anytime, independent of coordinator)
+3. By human via `maestro agent-msg list` CLI (works anytime, independent of coordinator)
 
 ### Relationship to Discoveries
 

package/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md

@@ -107,7 +107,7 @@ Output:
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
 
 **CLI monitoring** (works while coordinator is blocked):
-maestro msg list -s "<session_id>" --type progress --last 10
+maestro agent-msg list -s "<session_id>" --type progress --last 10
 ```
 
 Then STOP.

package/.codex/skills/team-review/roles/coordinator/commands/monitor.md

@@ -66,7 +66,7 @@ Output:
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
 
 **CLI monitoring** (works while coordinator is blocked):
-maestro msg list -s "<session_id>" --type progress --last 10
+maestro agent-msg list -s "<session_id>" --type progress --last 10
 ```
 
 Then STOP.

package/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md

@@ -56,7 +56,7 @@ Session: <session-id>
 Commands: 'resume' to advance | 'check' to refresh
 
 **CLI monitoring** (works while coordinator is blocked):
-maestro msg list -s "<session_id>" --type progress --last 10
+maestro agent-msg list -s "<session_id>" --type progress --last 10
 ```
 
 Output status -- do NOT advance pipeline.

package/.codex/skills/team-testing/roles/coordinator/commands/monitor.md

@@ -71,7 +71,7 @@ Output:
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
 
 **CLI monitoring** (works while coordinator is blocked):
-maestro msg list -s "<session_id>" --type progress --last 10
+maestro agent-msg list -s "<session_id>" --type progress --last 10
 ```
 
 Then STOP.