maestro-flow 0.3.8 → 0.3.10

package/workflows/execute.md

@@ -2,32 +2,59 @@
 
 Wave-based parallel execution with atomic commits, breakpoint resume, and optional sync/reflection.
 
+Core principle: **Execute per-plan, not per-phase.** Each plan's wave DAG runs independently. Multiple plans execute sequentially.
+
 ---
 
 ## Prerequisites
 
-- Phase has a completed plan: `plan.json` + `.task/TASK-*.json` exist
-- `index.json` present with `plan.waves` populated
+- Plan exists in scratch directory: `plan.json` + `.task/TASK-*.json`
 - OR: executionContext handoff received from `/workflow:plan`
 
 ---
 
-## Phase Resolution
+## Plan Resolution
 
 ```
-Input: <phase> argument (number or slug) OR --dir <path>
+Input: [phase] argument OR --dir <path>
 
-IF --dir <path> is provided:
-  1. Set PHASE_DIR = <path> (absolute or relative to project root)
-  2. Validate directory exists and contains index.json
-  3. Set SCRATCH_MODE = true (skip roadmap validation, phase transition)
-  4. Set PHASE_NUM = null, PHASE_SLUG = directory basename
+# Worktree scope check
+IF file_exists(".workflow/worktree-scope.json"):
+  scope = read(".workflow/worktree-scope.json")
+  IF <phase> is a number AND <phase> NOT IN scope.owned_phases:
+    ERROR "Phase {phase} not owned by this worktree. Owned: {scope.owned_phases}"
+    EXIT
 
-ELSE (standard phase resolution):
-  1. If number: find .workflow/phases/{NN}-*/index.json
-  2. If slug: find .workflow/phases/*-{slug}/index.json
-  3. Validate plan exists (index.json.plan.task_count > 0)
-  4. Set PHASE_DIR = resolved path
+# Auto-bootstrap state.json if missing
+IF NOT file_exists(".workflow/state.json"):
+  mkdir -p .workflow/scratch/
+  Write minimal state.json
+
+IF --dir <path> is provided:
+  1. Set PLAN_DIRS = [<path>]  // single plan
+  2. Validate directory exists and contains plan.json
+
+ELSE IF no arguments:
+  // Find all pending plans for current milestone
+  1. Read state.json.artifacts
+  2. Filter: milestone == current_milestone, type == "plan", status == "completed"
+  3. Exclude plans that already have a corresponding EXC artifact (same path)
+  4. Sort by phase order (from roadmap), adhoc plans last
+  5. Set PLAN_DIRS = filtered plan paths
+  6. If empty: ERROR E001 "No pending plans found"
+
+ELSE IF argument is a number:
+  // Find pending plans for specific phase
+  1. Read state.json.artifacts
+  2. Filter: milestone == current_milestone, type == "plan", status == "completed", phase == arg
+  3. Exclude plans with existing EXC artifacts
+  4. Set PLAN_DIRS = filtered plan paths
+
+// Execute plans sequentially
+FOR each PLAN_DIR IN PLAN_DIRS:
+  execute_single_plan(PLAN_DIR)
+  register_exc_artifact(PLAN_DIR)
+  extract_incremental_learnings(PLAN_DIR)
 ```
 
 ---
@@ -43,11 +70,11 @@ ELSE (standard phase resolution):
 
 ---
 
-## E1: Load Plan
+## E1: Load Plan (per PLAN_DIR)
 
-**Purpose:** Build or receive the execution queue.
+**Purpose:** Build or receive the execution queue for a single plan.
 
-### From executionContext handoff (preferred)
+### From executionContext handoff (preferred, first plan only)
 
 ```
 If executionContext is available in memory:
@@ -60,23 +87,22 @@ If executionContext is available in memory:
   Skip disk reload
 ```
 
-### From disk (fallback / resume)
+### From disk (fallback / resume / subsequent plans)
 
 ```
-Read ${PHASE_DIR}/index.json
-Read ${PHASE_DIR}/plan.json
+Read ${PLAN_DIR}/plan.json
 
 executionMethod = --method flag || config.json.execution.method || "agent"
 defaultExecutor = --executor flag || config.json.execution.default_executor || "gemini"
-executorAssignments = index.json.plan.executor_assignments || {}
+executorAssignments = plan.json.executor_assignments || {}
 ```
 
 ### Detect completed tasks (breakpoint resume)
 
 ```
 completed_tasks = []
-For each task_id in index.json.plan.task_ids:
-  Read .task/${task_id}.json
+For each task_id in plan.json.task_ids:
+  Read ${PLAN_DIR}/.task/${task_id}.json
   If status == "completed":
     completed_tasks.push(task_id)
 
@@ -89,7 +115,7 @@ If completed_tasks.length > 0:
 ### Build wave execution queue
 
 ```
-waves = plan.json.waves (or index.json.plan.waves)
+waves = plan.json.waves
 
 execution_queue = []
 For each wave in waves:
@@ -195,7 +221,9 @@ For each wave in execution_queue (sequential):
     Read .workflow/state.json
     If state.json.status != "executing":
       state.json.status = "executing"
-      state.json.phases_summary.in_progress += 1
+      # Worktree mode: skip phases_summary (reconciled on merge)
+      IF NOT file_exists(".workflow/worktree-scope.json"):
+        state.json.phases_summary.in_progress += 1
       state.json.last_updated = now()
       Write .workflow/state.json
 
@@ -466,7 +494,7 @@ If config.json.workflow.reflection == true:
     - Any blocked tasks?
     - Patterns observed?
 
-  Append to ${PHASE_DIR}/reflection-log.md:
+  Append to ${PLAN_DIR}/reflection-log.md:
     ## Reflection - Wave Execution {timestamp}
     - Strategy adjustments: [...]
     - Patterns noted: [...]
@@ -506,12 +534,50 @@ If NOT SCRATCH_MODE:
 
 ---
 
+## E5: Register Artifact & Extract Learnings (per PLAN_DIR)
+
+**Purpose:** Register execution completion and extract incremental learnings.
+
+```
+// Register EXC artifact
+Read .workflow/state.json
+plan_artifact = state.json.artifacts.find(a => a.type == "plan" && a.path == PLAN_DIR_relative)
+next_id = max(artifacts.filter(a => a.type == "execute").map(a => parseInt(a.id.replace("EXC-","")))) + 1
+
+artifact = {
+  id: "EXC-{next_id padded to 3}",
+  type: "execute",
+  milestone: plan_artifact.milestone,
+  phase: plan_artifact.phase,
+  scope: plan_artifact.scope,
+  path: plan_artifact.path,    // same path — execute writes into plan dir
+  status: "completed",
+  depends_on: plan_artifact.id,
+  harvested: false,
+  created_at: execution_start_time,
+  completed_at: now()
+}
+
+state.json.artifacts.push(artifact)
+state.json.last_updated = now()
+Write state.json (atomic)
+
+// Incremental learning extraction
+Read all ${PLAN_DIR}/.summaries/TASK-*-summary.md
+Extract: strategy adjustments, patterns discovered, pitfalls encountered
+Append to .workflow/specs/learnings.md under "## Entries"
+Mark artifact.harvested = true
+Write state.json (atomic)
+```
+
+---
+
 ## Error Handling
 
 | Error | Action |
 |-------|--------|
-| Phase directory not found | Abort: "Phase {phase} not found." |
-| No plan exists | Abort: "No plan found. Run /workflow:plan first." |
+| No pending plans found | Abort: "No pending plans. Run /workflow:plan first." |
+| Plan directory not found | Abort: "Plan dir not found." |
 | Task file missing | Skip task, log error, continue wave |
 | Agent spawn fails | Retry once, then mark task as "blocked" |
 | Delegate fails | Resume with `--resume ${fixedId}`, then fallback to agent |

package/workflows/fork.md

@@ -0,0 +1,309 @@
+# Workflow: fork
+
+Create a git worktree for an entire milestone, enabling inter-milestone parallel development. Copies `.workflow/` context into the worktree since `.workflow/` is gitignored.
+
+Worktrees operate at the **milestone level** — all phases within a milestone are owned by one worktree and executed sequentially inside it. Per-phase parallelism within a milestone is not supported.
+
+---
+
+## Step 1: Parse Arguments and Flags
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+// Parse flags
+const syncMode = $ARGUMENTS.includes('--sync')
+const baseMatch = $ARGUMENTS.match(/--base\s+(\S+)/)
+const baseBranch = baseMatch ? baseMatch[1] : 'HEAD'
+
+// Parse milestone number: -m <N> or bare <N>
+const mFlagMatch = $ARGUMENTS.match(/-m\s+(\d+)/)
+const cleaned = $ARGUMENTS
+  .replace(/--sync|--base\s+\S+|-m\s+\d+/g, '')
+  .trim()
+const bareNumMatch = cleaned.match(/^(\d+)$/)
+const milestoneNum = mFlagMatch
+  ? parseInt(mFlagMatch[1])
+  : bareNumMatch
+    ? parseInt(bareNumMatch[1])
+    : null
+```
+
+---
+
+## Step 2: Validate Prerequisites
+
+```
+IF NOT file_exists(".workflow/state.json"):
+  ERROR E001: "Project not initialized. Run maestro-init first."
+  EXIT
+
+IF NOT file_exists(".workflow/roadmap.md"):
+  ERROR E002: "No roadmap found. Run maestro-roadmap first."
+  EXIT
+
+IF file_exists(".workflow/worktree-scope.json"):
+  ERROR E003: "Cannot fork from inside a worktree. Run from the main worktree."
+  EXIT
+
+IF milestoneNum === null:
+  ERROR E004: "Milestone number required. Usage: maestro-fork -m <number>"
+  EXIT
+
+Read .workflow/state.json → projectState
+Read .workflow/config.json → config (if exists, else use defaults)
+
+worktreeRoot = config.worktree?.root ?? ".worktrees"
+branchPrefix = config.worktree?.branch_prefix ?? "milestone/"
+```
+
+---
+
+## Step 3: Resolve Milestone
+
+```
+// Lookup milestone by number from state.json.milestones[]
+IF NOT projectState.milestones || NOT Array.isArray(projectState.milestones):
+  ERROR E005: "No milestones defined in state.json."
+  EXIT
+
+// milestones[] is 0-indexed, milestoneNum is 1-based
+milestoneEntry = projectState.milestones[milestoneNum - 1]
+
+IF NOT milestoneEntry:
+  availableList = projectState.milestones
+    .map((m, i) => "  M" + (i + 1) + ": " + m.name + " (" + m.title + ")")
+    .join("\n")
+  ERROR E006: "Milestone {milestoneNum} not found.\nAvailable:\n{availableList}"
+  EXIT
+
+milestoneName = milestoneEntry.name       // e.g. "Production"
+milestoneTitle = milestoneEntry.title      // e.g. "生产就绪"
+milestonePhases = milestoneEntry.phases    // e.g. [3, 4]
+milestoneSlug = milestoneName.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+```
+
+---
+
+## Step 4: Sync Mode (--sync)
+
+If `syncMode` is true, this is a sync operation on an existing worktree, not a fork.
+
+```
+IF syncMode:
+  Read .workflow/worktrees.json → registry
+  entry = registry.worktrees.find(w =>
+    w.milestone_num === milestoneNum && w.status === "active"
+  )
+
+  IF NOT entry:
+    ERROR E007: "No active worktree for milestone {milestoneNum} ({milestoneName})"
+    EXIT
+
+  // Step 4a: Pull source code
+  Bash("cd {entry.path} && git merge main")
+  IF conflict:
+    WARN "Merge conflict in worktree. Resolve in {entry.path} before continuing."
+    EXIT
+
+  // Step 4b: Re-copy shared context
+  Copy .workflow/project.md → {entry.path}/.workflow/project.md
+  Copy .workflow/roadmap.md → {entry.path}/.workflow/roadmap.md
+  Copy .workflow/config.json → {entry.path}/.workflow/config.json (if exists)
+  Copy .workflow/specs/ → {entry.path}/.workflow/specs/ (if exists)
+
+  Display "Worktree for M{milestoneNum} ({milestoneName}) synced with main."
+  EXIT (sync complete)
+```
+
+---
+
+## Step 5: Validate & Confirm
+
+```
+// Load phase index files for all milestone phases
+phaseList = []
+for (phaseNum of milestonePhases):
+  Glob: .workflow/phases/{NN}-*/index.json where NN matches phaseNum
+  Read index.json → phaseIndex
+  phaseList.push(phaseIndex)
+
+// Validate: milestone should have at least one non-completed phase
+nonCompleted = phaseList.filter(p => p.status !== "completed")
+IF nonCompleted.length === 0:
+  Display "All phases in M{milestoneNum} ({milestoneName}) are already completed. Nothing to fork."
+  EXIT
+
+// Check for already-forked milestone
+IF file_exists(".workflow/worktrees.json"):
+  Read .workflow/worktrees.json → existingRegistry
+  alreadyForked = existingRegistry.worktrees.find(w =>
+    w.milestone_num === milestoneNum && w.status === "active"
+  )
+  IF alreadyForked:
+    ERROR E008: "M{milestoneNum} already has an active worktree at {alreadyForked.path}. Merge or cleanup first."
+    EXIT
+
+Display "Fork Milestone {milestoneNum}: {milestoneName} ({milestoneTitle})"
+Display "Phases ({phaseList.length}):"
+for (p of phaseList):
+  Display "  Phase {p.phase}: {p.title} [{p.status}]"
+
+AskUserQuestion: "Create worktree for this milestone? (y/n)"
+IF response !== 'y': EXIT
+```
+
+---
+
+## Step 6: Create Worktree
+
+```
+const forkSessionId = "fork-" + getUtc8ISOString().substring(0, 19).replace(/[-:T]/g, '')
+const baseCommit = Bash("git rev-parse HEAD").trim()
+const branch = branchPrefix + milestoneSlug
+const wtPath = worktreeRoot + "/m" + milestoneNum + "-" + milestoneSlug
+
+// 6a: Clean up stale worktree/branch if exists
+IF directory_exists(wtPath):
+  Bash("git worktree remove --force {wtPath}") // ignore errors
+Bash("git branch -D {branch}") // ignore errors (may not exist)
+
+// 6b: Create worktree
+Bash("git worktree add -b {branch} {wtPath} {baseBranch}")
+
+// 6c: Create .workflow/ structure in worktree
+Bash("mkdir -p {wtPath}/.workflow/phases")
+
+// 6d: Copy shared context (read-only)
+Copy .workflow/project.md → {wtPath}/.workflow/project.md
+Copy .workflow/roadmap.md → {wtPath}/.workflow/roadmap.md
+IF file_exists(".workflow/config.json"):
+  Copy .workflow/config.json → {wtPath}/.workflow/config.json
+IF directory_exists(".workflow/specs"):
+  Copy .workflow/specs/ → {wtPath}/.workflow/specs/
+
+// 6e: Copy ALL phase directories for this milestone
+ownedPhaseNumbers = []
+for (p of phaseList):
+  NN = String(p.phase).padStart(2, '0')
+  Copy .workflow/phases/{NN}-{p.slug}/ → {wtPath}/.workflow/phases/{NN}-{p.slug}/
+  ownedPhaseNumbers.push(p.phase)
+
+// 6f: Copy completed dependency phase dirs outside this milestone (read-only reference)
+allDeps = new Set()
+for (p of phaseList):
+  for (dep of p.depends_on):
+    IF NOT ownedPhaseNumbers.includes(dep):
+      allDeps.add(dep)
+
+for (dep of allDeps):
+  depNN = String(dep).padStart(2, '0')
+  Glob: .workflow/phases/{depNN}-*/index.json
+  Read → depIndex
+  Copy .workflow/phases/{depNN}-{depIndex.slug}/ → {wtPath}/.workflow/phases/{depNN}-{depIndex.slug}/
+
+// 6g: Write worktree-scope.json
+Write {wtPath}/.workflow/worktree-scope.json:
+  {
+    "worktree": true,
+    "milestone_num": milestoneNum,
+    "milestone": milestoneName,
+    "owned_phases": ownedPhaseNumbers,
+    "main_worktree": resolve(cwd),
+    "branch": branch,
+    "base_commit": baseCommit,
+    "created_at": getUtc8ISOString()
+  }
+
+// 6h: Write scoped state.json
+Read .workflow/state.json → mainState
+firstPending = phaseList.find(p => p.status !== "completed")
+scopedState = {
+  ...mainState,
+  current_phase: firstPending?.phase ?? phaseList[0].phase,
+  current_milestone: milestoneName
+}
+Write {wtPath}/.workflow/state.json: scopedState
+```
+
+---
+
+## Step 7: Update Main Registry
+
+```
+IF file_exists(".workflow/worktrees.json"):
+  Read .workflow/worktrees.json → registry
+ELSE:
+  registry = { version: "1.0", worktrees: [], fork_sessions: [] }
+
+registry.worktrees.push({
+  milestone_num: milestoneNum,
+  milestone: milestoneName,
+  slug: milestoneSlug,
+  branch: branch,
+  path: wtPath,
+  base_commit: baseCommit,
+  status: "active",
+  created_at: getUtc8ISOString(),
+  owned_phases: ownedPhaseNumbers,
+  fork_session: forkSessionId
+})
+
+registry.fork_sessions.push({
+  session_id: forkSessionId,
+  created_at: getUtc8ISOString(),
+  milestone_num: milestoneNum,
+  milestone: milestoneName,
+  base_branch: baseBranch,
+  base_commit: baseCommit
+})
+
+Write .workflow/worktrees.json: registry
+
+// Mark milestone phases as "forked" in main
+for (p of phaseList):
+  IF p.status !== "completed":
+    NN = String(p.phase).padStart(2, '0')
+    Read .workflow/phases/{NN}-{p.slug}/index.json → idx
+    idx.status = "forked"
+    idx.updated_at = getUtc8ISOString()
+    Write .workflow/phases/{NN}-{p.slug}/index.json: idx
+
+mainState.last_updated = getUtc8ISOString()
+Write .workflow/state.json: mainState
+```
+
+---
+
+## Step 8: Display Summary
+
+```
+Display:
+  === FORK COMPLETE ===
+  Session:    {forkSessionId}
+  Base:       {baseBranch} ({baseCommit.substring(0, 7)})
+  Milestone:  M{milestoneNum} — {milestoneName} ({milestoneTitle})
+  Branch:     {branch}
+  Path:       {wtPath}
+  Phases:     {ownedPhaseNumbers.join(', ')}
+
+  Next steps (run in the worktree):
+    cd {wtPath}
+
+    # Sequential lifecycle for each phase:
+    /maestro-analyze {firstPending.phase}
+    /maestro-plan {firstPending.phase}
+    /maestro-execute {firstPending.phase}
+    /maestro-verify {firstPending.phase}
+    /maestro-phase-transition {firstPending.phase}
+    # ... repeat for next phases in milestone
+
+  Or delegate (automated):
+    maestro delegate "run full lifecycle for milestone" --cd {wtPath} --mode write
+
+  Sync worktree with main (if needed later):
+    /maestro-fork -m {milestoneNum} --sync
+
+  When all phases in milestone complete:
+    /maestro-merge -m {milestoneNum}
+```

package/workflows/init.md

@@ -4,6 +4,15 @@ Project initialization with automatic state detection. Creates project infrastru
 
 ---
 
+## Worktree Guard
+
+```
+# Block in worktree
+IF file_exists(".workflow/worktree-scope.json"):
+  ERROR "Cannot run maestro-init inside a worktree. Run from the main worktree."
+  EXIT
+```
+
 ## Step 1: State Detection
 
 Detect current project state to determine initialization path.
@@ -41,7 +50,7 @@ CHECK .workflow/state.json exists?
 
    If `--auto` flag: skip interactive questioning, extract from @ referenced document.
    If `--from-brainstorm SESSION-ID`:
-   - Locate brainstorm session directory (`.workflow/scratch/brainstorm-*/` or `.workflow/phases/*/`)
+   - Locate brainstorm session directory (`.workflow/scratch/brainstorm-*/`)
    - Read `guidance-specification.md`:
      - Problem statement → project vision + core value
      - Features → project goals (Active requirements)

package/workflows/issue-analyze.md

@@ -1,5 +1,9 @@
 # Workflow: Issue Analysis
 
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-analyze` command.
+> Use `maestro-analyze --gaps [ISS-ID]` instead, which integrates issue root cause analysis
+> into the unified analyze pipeline. See `~/.maestro/workflows/issue-gaps-analyze.md`.
+
 Root cause analysis for a specific issue using CLI exploration and codebase context gathering.
 
 ## Input
@@ -87,7 +91,7 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ```
 1. Build analysis prompt:
 
-   maestro cli -p "PURPOSE: Root cause analysis for issue {ISS-ID}: {ISSUE.title}
+   maestro delegate "PURPOSE: Root cause analysis for issue {ISS-ID}: {ISSUE.title}
    Identify the root cause, assess impact, and suggest an approach.
 
    ISSUE DETAILS:
@@ -116,7 +120,7 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
      confidence: 'high'|'medium'|'low',
      suggested_approach: string (actionable fix direction)
    CONSTRAINTS: Only cite evidence found in codebase, no speculation
-   " --tool {TOOL} --mode analysis
+   " --to {TOOL} --mode analysis
 
 2. Parse CLI output:
    - Extract JSON object from response

package/workflows/issue-discover.md

@@ -115,7 +115,7 @@ Batch 2: scalability, ux, accessibility, compliance
 
 For each perspective, launch a CLI analysis:
 
-  maestro cli -p "PURPOSE: Discover {PERSPECTIVE} issues in the codebase.
+  maestro delegate "PURPOSE: Discover {PERSPECTIVE} issues in the codebase.
   Focus: {FOCUS_AREA}
   Guiding question: {QUESTION}
 
@@ -130,7 +130,7 @@ For each perspective, launch a CLI analysis:
   EXPECTED: JSON array of findings, each with:
     title, severity, description, location (file:line), fix_direction, affected_components[]
   CONSTRAINTS: Only report real issues with evidence, no speculative findings
-  " --tool gemini --mode analysis
+  " --to gemini --mode analysis
 
 Store results per perspective in:
   .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
@@ -262,7 +262,7 @@ For each unique finding:
 ```
 Use Gemini CLI to decompose the user prompt into exploration dimensions:
 
-  maestro cli -p "PURPOSE: Decompose this issue discovery prompt into 3-5 specific exploration dimensions.
+  maestro delegate "PURPOSE: Decompose this issue discovery prompt into 3-5 specific exploration dimensions.
 
   User wants to find: {USER_PROMPT}
 
@@ -280,7 +280,7 @@ Use Gemini CLI to decompose the user prompt into exploration dimensions:
       file_patterns: string[],
       finding_criteria: string
     }]
-  " --tool gemini --mode analysis
+  " --to gemini --mode analysis
 
 Store dimensions in:
   .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json

package/workflows/issue-execute.md

@@ -1,5 +1,8 @@
 # Workflow: Issue Execution
 
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-execute` command.
+> Use `maestro-execute` instead, which handles wave-based execution with automatic issue status sync.
+
 Execute a planned solution for an issue via dual-mode agent dispatch (server or direct CLI).
 
 ## Input
@@ -182,8 +185,8 @@ If SERVER_UP == false (or server dispatch failed):
        }
    - Rewrite file
 
-3. Execute via CLI:
-   maestro cli -p "{EXEC_PROMPT}" --tool {CLI_TOOL} --mode write
+3. Execute via delegate:
+   maestro delegate "{EXEC_PROMPT}" --to {CLI_TOOL} --mode write
 
 4. Evaluate result:
    - If CLI exits successfully → EXEC_SUCCESS = true
@@ -274,7 +277,7 @@ If execution failed:
 ## Output
 
 - **Updated**: `.workflow/issues/issues.jsonl` -- issue status transitions (open -> in_progress -> resolved/open)
-- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct CLI (maestro cli --mode write)
+- **Execution modes**: Server dispatch (POST /api/execution/dispatch) or Direct delegate (maestro delegate --mode write)
 
 ## Quality Criteria
 

package/workflows/issue-plan.md

@@ -1,5 +1,8 @@
 # Workflow: Issue Planning
 
+> **DEPRECATED**: This workflow was used by the deleted `manage-issue-plan` command.
+> Use `maestro-plan --gaps` instead, which generates TASK files linked to issues via `task_refs`.
+
 Solution planning for a specific issue with codebase-aware step generation and prompt template construction.
 
 ## Input
@@ -91,7 +94,7 @@ Solution planning for a specific issue with codebase-aware step generation and p
 ```
 1. Build planning prompt:
 
-   maestro cli -p "PURPOSE: Generate a step-by-step solution plan for issue {ISS-ID}: {ISSUE.title}
+   maestro delegate "PURPOSE: Generate a step-by-step solution plan for issue {ISS-ID}: {ISSUE.title}
    Produce an actionable, ordered list of implementation steps.
 
    ISSUE DETAILS:
@@ -116,7 +119,7 @@ Solution planning for a specific issue with codebase-aware step generation and p
      context: string (approach summary),
      promptTemplate: string (execution prompt for the agent)
    CONSTRAINTS: Steps must be concrete and file-specific, not vague
-   " --tool {TOOL} --mode analysis
+   " --to {TOOL} --mode analysis
 
 2. Parse CLI output:
    - Extract JSON object from response