maestro-flow 0.3.8 → 0.3.10

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)
@@ -374,7 +404,15 @@ spawn_agents_on_csv({
    }
    ```
 
-5. **Issue linking** (if --gaps): Update issues in `issues.jsonl` with status `planned`, link to TASK IDs.
+5. **Issue linking** (if --gaps):
+   For each created TASK-{NNN}.json that has `issue_id`:
+   - Update corresponding issue in `.workflow/issues/issues.jsonl`:
+     - `task_refs`: append TASK-{NNN} to array
+     - `task_plan_dir`: relative path to `.task/` directory
+     - `status`: "planned"
+     - `updated_at`: now()
+   - Append history entry: `{ action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }`
+   This ensures bidirectional issue ↔ TASK traceability for dashboard display.
 
 6. **Display summary + options** (skip options if AUTO_YES):
    ```

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.

package/README.md

@@ -32,9 +32,10 @@ You describe what you want. Maestro-Flow figures out which agents to use, in wha
 # Or step by step
 /maestro-init                    # Set up project workspace
 /maestro-roadmap                 # Create phased roadmap interactively
-/maestro-plan 1                  # Generate execution plan for Phase 1
-/maestro-execute 1               # Wave-based parallel agent execution
-/maestro-verify 1                # Goal-backward verification
+/maestro-analyze                 # Multi-dimensional analysis
+/maestro-plan                    # Generate execution plan
+/maestro-execute                 # Wave-based parallel agent execution
+/maestro-verify                  # Goal-backward verification
 ```
 
 ### The Pipeline
@@ -48,11 +49,13 @@ graph LR
     E --> F[execute]
     F --> G[verify]
     G --> H[review]
-    H --> I[test]
-    I --> J[transition]
-    J -->|next phase| D
+    H --> I[milestone-audit]
+    I --> J[milestone-complete]
+    J -->|next milestone| D
 ```
 
+All work artifacts live in `.workflow/scratch/`, tracked by `state.json` artifact registry. Phases are labels in the roadmap, not directories.
+
 ### Quick Channels
 
 | Channel | Flow | When |
@@ -67,9 +70,9 @@ graph LR
 
 ### 1. Structured Pipeline
 
-Phase-based execution with explicit status tracking. Each phase moves through analyze > plan > execute > verify > review > test > transition. The dashboard shows what's happening and what to do next.
+Scratch-based milestone workflow with artifact registry tracking. Each milestone moves through analyze > plan > execute > verify > review > milestone-audit > milestone-complete. All artifacts live in `.workflow/scratch/`, registered in `state.json`. The dashboard shows what's happening and what to do next.
 
-51 slash commands across 6 categories power every stage — from project initialization to quality retrospective.
+49 slash commands across 6 categories power every stage — from project initialization to quality retrospective.
 
 ### 2. Autonomous Autopilot
 
@@ -94,10 +97,10 @@ graph LR
 | Stage | Command | What Happens |
 |-------|---------|-------------|
 | **Discover** | `/manage-issue-discover` | 8-perspective scan: bugs, UX, tech debt, security, performance, testing gaps, code quality, documentation |
-| **Analyze** | `/manage-issue-analyze` | Root cause analysis via CLI exploration |
-| **Plan** | `/manage-issue-plan` | Generate solution steps with target files and verification criteria |
-| **Execute** | `/manage-issue-execute` | Dashboard API dispatch or direct CLI execution |
-| **Close** | Automatic | Verification passes > resolved > closed |
+| **Analyze** | `/maestro-analyze --gaps` | Root cause analysis via CLI exploration, writes `issue.analysis` |
+| **Plan** | `/maestro-plan --gaps` | Generate TASK files linked to issues via `task_refs` |
+| **Execute** | `/maestro-execute` | Wave-based parallel execution with automatic issue status sync |
+| **Close** | Automatic | All linked tasks completed > resolved > closed |
 
 Quality commands (`review`, `test`, `verify`) automatically create issues for problems they find. Issue fixes flow back into the phase pipeline. The loop closes itself.
 
@@ -168,7 +171,7 @@ Maestro-Flow coordinates multiple AI agents in parallel:
 | `context-monitor` | Monitors context usage, injects warnings when running low |
 | `spec-injector` | Auto-injects project specs into subagent prompts by agent type |
 | `delegate-monitor` | Tracks async delegate task completion |
-| `team-monitor` | Team collaboration message awareness |
+| `team-monitor` | Collab heartbeat — reports activity to `.workflow/collab/activity.jsonl` for teammate awareness |
 | `telemetry` | Execution telemetry collection |
 | `session-context` | Injects workflow state at session start |
 | `skill-context` | Injects workflow state when invoking workflow skills |
@@ -195,13 +198,13 @@ maestro overlay bundle -o team.json    # Pack for sharing
 
 ---
 
-## 51 Commands, 21 Agents
+## 49 Commands, 21 Agents
 
 ### Commands
 
 | Category | Count | Prefix | Purpose |
 |----------|-------|--------|---------|
-| **Core Workflow** | 20 | `maestro-*` | Full lifecycle — init, brainstorm, roadmap, analyze, plan, execute, verify, coordinate, milestones, overlays, UI design |
+| **Core Workflow** | 18 | `maestro-*` | Full lifecycle — init, brainstorm, roadmap, analyze, plan, execute, verify, coordinate, milestones, overlays, UI design |
 | **Management** | 12 | `manage-*` | Issue lifecycle, codebase docs, knowledge capture, memory, harvest, status |
 | **Quality** | 9 | `quality-*` | Review, test, debug, test-gen, integration-test, business-test, refactor, retrospective, sync |
 | **Learning** | 5 | `learn-*` | Unified retro, follow-along, pattern decompose, investigate, second opinion |
@@ -236,8 +239,9 @@ maestro install
 ```bash
 /maestro-init                  # Initialize project
 /maestro-roadmap               # Create roadmap
-/maestro-plan 1                # Plan Phase 1
-/maestro-execute 1             # Execute with agents
+/maestro-analyze               # Analyze current milestone
+/maestro-plan                  # Plan (outputs to scratch/)
+/maestro-execute               # Execute all pending plans
 
 # Or just:
 /maestro "build a REST API for user management"
@@ -287,9 +291,9 @@ maestro/
 │       │   └── execution/   # ExecutionScheduler + WaveExecutor
 │       └── shared/          # Shared types
 ├── .claude/
-│   ├── commands/            # 51 slash commands (.md)
+│   ├── commands/            # 49 slash commands (.md)
 │   └── agents/              # 21 agent definitions (.md)
-├── workflows/               # 47 workflow implementations (.md)
+├── workflows/               # 45 workflow implementations (.md)
 ├── templates/               # JSON templates (task, plan, issue, ...)
 └── extensions/              # Plugin system
 ```
@@ -313,8 +317,9 @@ maestro/
 - **[Delegate Async Guide](guide/delegate-async-guide.md)** — Async task delegation: CLI & MCP usage, message injection, chaining, broker lifecycle
 - **[Overlay Guide](guide/overlay-guide.md)** — Non-invasive command extensions: overlay format, section injection, bundle/import, interactive TUI management
 - **[Hooks Guide](guide/hooks-guide.md)** — Hook system architecture, 9 hooks, spec injection, context budget, configuration
-- **[Team Lite — User Guide](guide/team-lite-guide.md)** — Daily workflow for 2-8 person teams: join, sync, activity awareness, conflict preflight
-- **[Team Lite — Design](guide/team-lite-design.md)** — Architecture, data model, and namespace boundary between human-collab and agent-pipeline domains
+- **[Worktree Parallel Dev Guide](guide/worktree-guide.md)** — Milestone-level worktree parallelism: fork, sync, merge, scope enforcement, dashboard integration
+- **[Collab — User Guide](guide/team-lite-guide.md)** — Multi-person collaboration for 2-8 person teams: join, sync, activity awareness, conflict preflight, task management, namespace isolation
+- **[Collab — Design](guide/team-lite-design.md)** — Architecture, data model, namespace boundary between human-collab (`.workflow/collab/`) and agent-pipeline (`.workflow/.team/`) domains
 
 ---