maestro-flow 0.4.11 → 0.4.13

package/workflows/issue-execute.md

@@ -25,7 +25,7 @@ Flags: --executor claude-code|codex|gemini (default: claude-code), --dry-run (de
 
 ```
 Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
-Require issue.solution with non-empty steps[] → error if missing (run manage-issue-plan first).
+Require issue.solution with non-empty steps[] → error if missing (run `maestro-plan --gaps {ISS-ID}` first).
 Resolve EXECUTOR → CLI tool (claude-code→claude, codex→codex, gemini→gemini), all with --mode write.
 ```
 

package/workflows/issue-gaps-analyze.md

@@ -1,5 +1,7 @@
 # Workflow: Issue Gaps Analysis
 
+> **CLI variants**: see `issue-gaps-analyze.codex.md` for codex-specific notes (CSV-wave variant using `spawn_agents_on_csv`).
+
 Root cause analysis for issues using CLI exploration and codebase context gathering.
 Supports single issue (ISS-ID) or batch (all open/registered) with classification and parallel analysis.
 Produces analysis records in issues.jsonl and context.md for downstream `plan --gaps`.

package/workflows/learn.md

@@ -8,7 +8,7 @@ Storage:
 
 **Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
 
-This workflow does NOT spawn agents or call CLI tools. It is a thin file operation: parse → infer → append → confirm.
+This workflow does NOT spawn sub-agents; it may invoke maestro CLI utilities (e.g. `maestro wiki search`, `maestro wiki list`) for list/search subcommands. The core capture flow is a thin file operation: parse → infer → append → confirm.
 
 ---
 

package/workflows/maestro-chain-execute.md

@@ -4,235 +4,17 @@
 > Both maestro and ralph sessions now use `maestro-ralph-execute` for step execution.
 > This file is kept for reference only and will be removed in a future version.
 
-Original description: Upgraded version of maestro's original direct execution strategy.
-Reads session status.json, loops through steps with per-step engine selection,
-context propagation, post-step Gemini analysis, and error handling.
-Dual-track progress: status.json (persistence + resume) and TodoWrite (UI visibility).
+## Migration
 
-**Prerequisites:**
-- Session directory with valid status.json (status: "running", pending steps)
-- TodoWrite initialized by selection workflow (Step 3h) with `MAESTRO:{chain_name}:` prefix
-- $SESSION_PATH passed from maestro.md dispatch
+- Caller dispatching from `maestro.md` → use `Skill({ skill: "maestro-ralph-execute" })`
+- Resume from session → `Skill({ skill: "maestro-ralph-execute" })` (auto-discovers latest running session via `.workflow/.maestro/*/status.json`)
 
-## Step 1: Load Session
+## References
 
-Read status.json from `$SESSION_PATH`.
+- `~/.maestro/workflows/maestro.md` — coordinator that creates sessions and dispatches to the unified executor
+- `~/.maestro/workflows/maestro-ralph-execute.md` — current canonical executor (handles both maestro static chains and ralph adaptive chains)
 
-Extract: `session_id`, `chain_name`, `steps[]`, `context`, `auto_mode`, `exec_mode`, `cli_tool`, `gemini_session_id`.
-
-Set `$STEP_INDEX` = `current_step` (first pending step).
-
-Validate: `status == "running"` and at least one pending step exists.
-
-**TodoWrite sync (resume mode):** If TodoWrite has no `MAESTRO:{chain_name}:` entries (e.g., fresh context after `/maestro -c`), rebuild from status.json:
-
-```javascript
-const todos = steps.map((step, i) => ({
-  content: `MAESTRO:${chain_name}: [${i + 1}/${steps.length}] ${step.skill}`,
-  status: step.status === 'completed' ? 'completed'
-        : i === $STEP_INDEX ? 'in_progress'
-        : 'pending'
-}));
-TodoWrite({ todos });
-```
-
-Display banner:
-
-```
-============================================================
-  CHAIN EXECUTOR
-============================================================
-  Session: {session_id}
-  Chain:   {chain_name}
-  Steps:   {completed}/{total} done, starting from step {$STEP_INDEX}
-  Auto:    {auto_mode}
-  Exec:    {exec_mode}
-```
-
-## Step 2: Context & Argument Assembly
-
-Initialize context object from `status.json.context`:
-
-```
-context = {
-  current_phase,    // from status.json.context or top-level phase
-  user_intent,      // from status.json.context or top-level intent
-  issue_id,
-  milestone_num,
-  spec_session_id,
-  scratch_dir
-}
-```
-
-### assembleArgs(step)
-
-```
-1. Substitute placeholders in step.args:
-   {phase} → context.current_phase
-   {description} → context.user_intent (chainMap uses {description} as alias for user intent)
-   {issue_id} → context.issue_id
-   {spec_session_id} → context.spec_session_id
-   {scratch_dir} → context.scratch_dir
-   {milestone_num} → context.milestone_num
-
-2. In auto_mode, append per-command flag if not already present:
-   maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-impeccable → -y
-   maestro-plan → --auto
-   quality-test → --auto-fix
-   quality-retrospective → --auto-yes
-
-3. Shell-escape strings with single quotes for CLI delegate calls.
-```
-
-## Step 3: Step Loop
-
-For each step starting at `$STEP_INDEX`:
-
-### 3a. Select engine & display banner
-
-Read `step.engine` from status.json (pre-computed by selection workflow Step 3e).
-
-If `step.engine` is missing or null, fallback to auto selection:
-```
-  CLI: maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm,
-       maestro-roadmap, maestro-impeccable, quality-refactor
-  Internal: everything else (current-session Skill() call)
-```
-
-Display: `[Step {N}/{total}] /{step.skill} [{engine}] — {args}`
-
-Update status.json: step `status = "running"`, `engine`, `started_at`.
-
-Context window hint:
-- Step >= 4 and not autoYes: hint user about `/maestro -c` for fresh context resume.
-- autoYes and step >= 5: log warning to status.json.
-
-### 3b. Execute (engine-dependent)
-
-**Internal engine** — current-session Skill() call (synchronous, visible):
-
-```
-Skill({ skill: step.skill, args: assembledArgs })
-```
-
-**CLI engine** — template-driven, async, context-isolated:
-
-```
-1. Load template ~/.maestro/templates/cli/prompts/coordinate-step.txt
-2. Build analysisHints from previous step's next_step_hints
-   (prompt_additions, cautions, context_to_carry)
-3. Substitute template placeholders:
-   {{COMMAND}}, {{ARGS}}, {{STEP_N}}, {{AUTO_DIRECTIVE}},
-   {{CHAIN_NAME}}, {{ANALYSIS_HINTS}}
-4. Run:
-   Bash(maestro delegate "<prompt>" --to {cli_tool} --mode write,
-        run_in_background: true, timeout: 600000)
-5. **STOP** — wait for background callback
-```
-
-### 3c. Parse output & update context
-
-Scan step output for context propagation:
-
-```
-PHASE: N         → context.current_phase
-SPEC-xxx         → context.spec_session_id
-scratch_dir: path → context.scratch_dir
-```
-
-CLI: capture `exec_id` from stderr `[MAESTRO_EXEC_ID=<id>]`.
-
-**Persist context back to status.json** after each step — write updated `context` field and `current_step`. This enables resume via `/maestro -c`.
-
-### 3d. Handle result & sync dual tracking
-
-**Success:**
-1. status.json: mark step `status = "completed"`, set `completed_at`
-2. TodoWrite: mark current step `completed`, next step `in_progress`
-3. CLI: save output to `step-{N}-output.txt` in session directory
-
-```javascript
-// Dual-track update after each step
-function updateDualTracking(stepIndex, total, chain_name, result) {
-  // 1. status.json — already updated in 3c
-  // 2. TodoWrite — sync UI
-  const todos = getAllTodos().map(todo => {
-    if (!todo.content.startsWith(`MAESTRO:${chain_name}:`)) return todo;
-    const num = extractStepNum(todo.content);
-    if (num === stepIndex + 1) return { ...todo, status: result };
-    if (num === stepIndex + 2 && result === 'completed') return { ...todo, status: 'in_progress' };
-    return todo;
-  });
-  TodoWrite({ todos });
-}
-```
-
-**Failure:**
-1. status.json: mark step `"failed"` or `"skipped"`
-2. TodoWrite: mark step `completed` (skipped) or keep `in_progress` (retry)
-3. `auto_mode` → retry once, then skip
-4. Interactive → offer: Retry (max 2) / Skip / Abort
-5. Abort → status.json `status = "aborted"`, TodoWrite mark remaining `pending`, display resume hint: `/maestro -c`
-
-### 3e. Post-step analysis (CLI steps only)
-
-Skip if: step failed/skipped, or `engine == 'internal'`.
-
-Delegate to gemini (analysis mode, `--resume` if `gemini_session_id` exists) with prompt containing:
-- Step command, args, chain name, intent
-- Last 200 lines of step output
-- Next step info (command, args) if any
-
-Expected JSON response:
-
-```json
-{
-  "quality_score": "<0-100>",
-  "execution_assessment": {
-    "success": "<bool>",
-    "completeness": "<full|partial|minimal>",
-    "key_outputs": [],
-    "missing_outputs": []
-  },
-  "issues": [
-    { "severity": "critical|high|medium|low", "description": "" }
-  ],
-  "next_step_hints": {
-    "prompt_additions": "<extra context for next step>",
-    "cautions": ["<things to watch out for>"],
-    "context_to_carry": "<key facts from this step>"
-  },
-  "step_summary": ""
-}
-```
-
-On callback:
-1. Capture gemini `exec_id` → store as `gemini_session_id` in status.json for session continuity.
-2. Store analysis in `step_analyses[]` and `step-{N}-analysis.json` in session directory.
-3. Advance to next step (**3a**).
-
-## Step 4: Completion Report
-
-Finalize dual tracking:
-1. status.json: `status = "completed"`
-2. TodoWrite: all steps marked `completed` (or `completed` for skipped)
-
-```
-============================================================
-  MAESTRO SESSION COMPLETE
-============================================================
-  Session:  {session_id}
-  Chain:    {chain_name}
-  Steps:    {completed}/{total} completed
-  Phase:    {context.current_phase}
-
-  Results:
-    [✓] 1. maestro-plan — completed [cli] (quality: 85/100)
-    [✓] 2. maestro-verify — completed [internal]
-    [—] 3. quality-review — skipped [internal]
-
-  CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
-
-  Next: /maestro continue | /manage-status
-============================================================
-```
+The unified executor preserves all behaviour previously documented here:
+status.json persistence, TodoWrite dual-tracking, per-step engine selection (`Skill` vs `CLI`),
+context propagation across steps, post-step Gemini analysis for CLI steps,
+and retry/skip/abort on failure.

package/workflows/maestro.md

@@ -357,6 +357,7 @@ const chainMap = {
   'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'brainstorm_visualize': [{ cmd: 'brainstorm-visualize', args: '"{description}"' }],
   'impeccable-build':       [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'impeccable-driven':      [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }],
@@ -424,7 +425,7 @@ detectNextAction(state):
 | Chain | Steps | Use Case |
 |-------|-------|----------|
 | `full-lifecycle` | plan → execute → verify → review → test → audit | Full milestone completion |
-| `spec-driven` | init → spec-generate → plan → execute → verify | From idea/requirements (heavy) |
+| `blueprint-driven` | init → blueprint → plan → execute → verify | From idea/requirements (heavy) |
 | `roadmap-driven` | init → roadmap → plan → execute → verify | From requirements (light) |
 | `brainstorm-driven` | brainstorm → plan → execute → verify | From exploration |
 | `impeccable-build` | impeccable --chain build → plan → execute → verify | From design system generation |

package/workflows/milestone-audit.md

@@ -8,19 +8,27 @@ Cross-phase integration audit for milestone completion. Based on artifact regist
 
 1. Read `.workflow/state.json`:
    - Determine target milestone (from $ARGUMENTS or current_milestone)
+   - If no milestone: ERROR E001
    - Get `artifacts[]` array
+   - Resolve milestone object from `milestones[]` by id
+   - Determine milestone type: `milestone_obj.type` (default `"standard"` if field missing)
 
-2. Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone
+2. **Standard milestone** (`type != "adhoc"`):
+   - Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone
 
-3. Group milestone artifacts by type → `analyze_artifacts`, `plan_artifacts`, `execute_artifacts`, `verify_artifacts`
+3. **Adhoc milestone** (`type == "adhoc"`):
+   - Skip roadmap.md parsing (roadmap may not exist)
+   - Phases are defined by `milestone_obj.phases[]` (typically `[1]` with slug `"standalone"`)
+
+4. Group milestone artifacts by type → `analyze_artifacts`, `plan_artifacts`, `execute_artifacts`, `verify_artifacts`
 
 ---
 
 ## Step 2: Phase Coverage Check
 
-Parse roadmap.md phases for this milestone. For each phase, verify completed artifacts exist for analyze, plan, and execute types.
+**Standard milestone**: Parse roadmap.md phases for this milestone. For each phase, verify completed artifacts exist for analyze, plan, and execute types. WARN if any phase is missing its execute artifact: "Phase {number} ({title}) missing execute artifact"
 
-WARN if any phase is missing its execute artifact: "Phase {number} ({title}) missing execute artifact"
+**Adhoc milestone**: Skip phase-level coverage check (no roadmap phases to validate). Instead, verify that at least one complete artifact chain exists: plan artifact (PLN) + execute artifact (EXC) with matching milestone ID. WARN if no execute artifact found.
 
 ---
 

package/workflows/milestone-complete.md

@@ -9,13 +9,15 @@ Archive completed milestone, move artifacts to history, and prepare for next.
 1. Read `.workflow/state.json`:
    - Determine target milestone (from $ARGUMENTS or current_milestone)
    - If no milestone: ERROR E001
+   - Resolve milestone object from `milestones[]` by id
+   - Determine milestone type: `milestone_obj.type` (default `"standard"` if field missing)
 
 2. Check milestone audit status:
    - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
    - If no audit report:
-     - WARN: "No audit report found. Run `/maestro-milestone-audit` first."
-     - Ask user: "Complete without audit?"
-     - If NO → exit
+     - ERROR E004: "No audit report found. Audit is a required hard contract — cannot complete without it."
+     - Guidance: "Run `/maestro-milestone-audit` first, then re-run this command."
+     - Exit (skipping audit is not permitted)
    - If verdict is FAIL: ERROR E002
 
 3. Verify all milestone artifacts have status "completed" → ERROR E003 if any incomplete (list ids and statuses)
@@ -30,9 +32,8 @@ Archive completed milestone, move artifacts to history, and prepare for next.
    ```
 
 2. Snapshot roadmap:
-   ```
-   cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
-   ```
+   - **Standard milestone**: `cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md`
+   - **Adhoc milestone**: Skip roadmap snapshot (roadmap may not exist)
 
 3. Archive scratch directories: copy each milestone artifact's `.workflow/{artifact.path}` to `.workflow/milestones/{milestone}/artifacts/{basename}/`
 
@@ -91,7 +92,9 @@ Check existing entries to avoid duplicates when appending in Step 3.
 
 2. Clear artifacts array: remove all entries where `milestone == target_milestone`
 
-3. Advance to next milestone: activate first pending milestone → set as `current_milestone`. If none pending → set `current_milestone = null`, `status = "completed"`
+3. Advance to next milestone:
+   - **Standard milestone**: activate first pending milestone → set as `current_milestone`. If none pending → set `current_milestone = null`, `status = "completed"`
+   - **Adhoc milestone**: Do NOT search for next milestone. Set `current_milestone = null`, `status = "idle"` (adhoc milestones are self-contained, no successor)
 
 4. Write state.json (atomic)
 
@@ -135,10 +138,12 @@ Artifacts: {count} archived
 Learnings: {learnings_count} extracted
 
 Archive: .workflow/milestones/{milestone}/
-Next:    {next_milestone or "Project complete"}
+Next:    {next_milestone or "Project complete" or "Ad-hoc task complete"}
 
 Next steps:
   /maestro-milestone-release    -- Cut a release
-  /maestro-analyze              -- Start next milestone
+  /maestro-analyze              -- Start next milestone (standard only)
   /manage-status                -- View project state
 ```
+
+**Adhoc milestone note:** When completing an adhoc milestone, the "Next steps" section omits "Start next milestone" since adhoc milestones have no successor in a roadmap chain.

package/workflows/milestone-release.md

@@ -0,0 +1,82 @@
+# Workflow: milestone-release
+
+Bump version, generate changelog, and tag the current milestone for release.
+
+> **STATUS: PLACEHOLDER** — minimal skeleton referenced by `maestro-milestone-release.md`.
+> Full release pipeline is TODO. Do not invoke until contents below are fleshed out.
+
+---
+
+## Arguments
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<milestone>` | Milestone id from `.workflow/state.json` `milestones[]` | current_milestone |
+| `--bump <level>` | Semver bump: `major` \| `minor` \| `patch` | `minor` |
+| `--dry-run` | Preview changes without writing | `false` |
+
+---
+
+## Step 1: Validation
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from `$ARGUMENTS` or `current_milestone`).
+   - If no milestone: ERROR E001.
+2. Verify milestone is **completed**:
+   - Read `.workflow/milestones/{milestone}/audit-report.md` — verdict must be `PASS`.
+   - If missing or non-PASS: ERROR E002 with guidance to run `/maestro-milestone-complete` first.
+3. Read package manifest (`package.json` / `pyproject.toml` / etc.) — locate current version. TODO: multi-manifest detection.
+
+---
+
+## Step 2: Version Bump
+
+1. Compute next version from `--bump` level (semver). TODO: prerelease/build metadata handling.
+2. Update manifest file in place. If `--dry-run`: print diff and exit.
+
+---
+
+## Step 3: Changelog Generation
+
+1. Read milestone audit report + retrospective insights (`.workflow/milestones/{milestone}/`).
+2. Render `CHANGELOG.md` entry — header `## [vX.Y.Z] - YYYY-MM-DD`, body grouped by `Added / Changed / Fixed / Removed`.
+3. TODO: integrate with `quality-retrospective` output for richer narrative.
+
+---
+
+## Step 4: Tag and Commit
+
+1. Stage updated manifest + `CHANGELOG.md`.
+2. Commit: `chore(release): vX.Y.Z — {milestone}`.
+3. Create annotated git tag `vX.Y.Z`.
+4. TODO: optionally push tag (`--push` flag).
+
+---
+
+## Outputs
+
+| Artifact | Status |
+|----------|--------|
+| Updated manifest version | written |
+| `CHANGELOG.md` entry | appended |
+| Git tag `vX.Y.Z` | created locally (not pushed) |
+
+---
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| E001 | No milestone resolvable |
+| E002 | Milestone not completed / audit not PASS |
+| E003 | Manifest file not found |
+| E004 | Git working tree dirty (uncommitted changes block tagging) |
+
+---
+
+## TODO (placeholder gaps)
+
+- Multi-package monorepo support.
+- Push tag + GitHub release integration.
+- Roll-back path on failed tag.
+- Wire to `manage-knowhow-capture` for release-note capture.

package/workflows/plan.md

@@ -18,22 +18,68 @@ All output goes to `.workflow/scratch/plan-{slug}-{date}/`.
 ## Scope Resolution
 
 ```
-Input: [phase] argument OR --dir <path>
+Input: [phase] argument OR --dir <path> OR --from <source>
 
 Worktree guard: reject if phase not in .workflow/worktree-scope.json owned_phases
 Auto-bootstrap: create minimal state.json if missing
 
-Resolution priority:
-  --dir <path>   → CONTEXT_DIR = path, scope from state.json artifact or "standalone"
-  no arguments   → scope = "milestone", CONTEXT_DIR = latest analyze artifact for current_milestone
-                   (ERROR E001 if no roadmap)
-  numeric arg    → scope = "phase", resolve PHASE_SLUG from roadmap.md,
-                   CONTEXT_DIR = latest analyze artifact for phase
-                   (ERROR if no init + roadmap)
+Resolution priority (highest to lowest):
+  1. --from analyze:ANL-xxx → CONTEXT_DIR = artifact path, scope = "standalone"
+     Uses analyze conclusions.implementation_scope to seed task generation
+  2. --from blueprint:BLP-xxx → CONTEXT_DIR = blueprint path, scope = "standalone"
+     Uses blueprint requirements + architecture to seed task generation
+  3. --from <other> (@file, path/) → load context-package.json from path, scope = "standalone"
+  4. --dir <path>   → CONTEXT_DIR = path, scope from state.json artifact or "standalone"
+  5. no arguments + roadmap → scope = "milestone", CONTEXT_DIR = latest analyze artifact for current_milestone
+     (ERROR E001 if no roadmap)
+  6. numeric arg    → scope = "phase", resolve PHASE_SLUG from roadmap.md,
+     CONTEXT_DIR = latest analyze artifact for phase
+     (ERROR if no init + roadmap)
+  7. no arguments + no roadmap → search state.json for latest analyze artifact
+     Found → scope = "standalone", CONTEXT_DIR = artifact path
+     Not found → ERROR E001
+
+Phase-to-Milestone resolution (when scope="phase"):
+  FOR each ms in state.json.milestones[]:
+    IF phase_number in ms.phases[]:
+      target_milestone = ms.id
+      BREAK
+  IF no match: target_milestone = current_milestone (fallback)
+
+  Use target_milestone (not current_milestone) for:
+    - artifact registration (P5 Step 4 milestone field)
+    - collision detection scope (P4.5)
+    - prior artifact lookups
+
+OUTPUT_DIR = .workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/
+```
+
+### Ad-hoc Milestone Auto-Creation (D-008)
+
+When plan resolves to `scope == "standalone"` AND `state.json.current_milestone == null`:
 
-OUTPUT_DIR = .workflow/scratch/plan-{PHASE_SLUG or milestone_slug}-{date}/
+```
+1. Generate adhoc milestone ID: "M-adhoc-{YYYYMMDD}-{HHmmss}"
+2. Create milestone entry:
+   {
+     "id": "M-adhoc-{YYYYMMDD}-{HHmmss}",
+     "type": "adhoc",
+     "name": "Ad-hoc: {plan_slug or analyze_title}",
+     "status": "active",
+     "phases": [1],
+     "phase_slugs": { "1": "standalone" },
+     "roadmap_ref": null,
+     "created_at": "{ISO-8601}"
+   }
+3. Push to state.json.milestones[]
+4. Set state.json.current_milestone = milestone.id
+5. Use this milestone ID for artifact registration (P5 Step 4)
 ```
 
+This ensures downstream commands (verify, milestone-audit, milestone-complete) have a valid milestone context without requiring roadmap.
+
+**Backward compatibility:** If `state.json.milestones[]` already has entries with `current_milestone != null`, skip creation (existing milestone takes precedence). Missing `type` field on legacy milestones defaults to `"standard"`.
+
 ---
 
 ## Flag Processing
@@ -48,6 +94,7 @@ OUTPUT_DIR = .workflow/scratch/plan-{PHASE_SLUG or milestone_slug}-{date}/
 | `--revise [instructions]` | Revise existing plan (skip P1-P3, load → modify → P4). Auto-discovers latest plan or use `--dir` |
 | `--check <plan-dir>` | Standalone plan verification (P4 only, read-only) |
 | `--tdd` | Generate TDD task chains (RED-GREEN-REFACTOR triplets). Load `@~/.maestro/workflows/tdd.md` for discipline and task structure |
+| `--from <source>` | Load upstream context directly (analyze:ANL-xxx, blueprint:BLP-xxx, brainstorm:ID, @file, or path). Bypasses roadmap requirement for analyze/blueprint sources |
 
 ---
 
@@ -78,10 +125,18 @@ When `--tdd` is active:
 ### Steps
 
 1. **Load user decisions**
-   - Read `${CONTEXT_DIR}/context.md` if exists, else warn (no upstream analyze)
-
-2. **Load spec reference** (if `--spec` flag or index.json has spec_ref)
-   - Read from `.workflow/.spec/${spec_ref}/`: spec-summary.md, requirements/_index.md, epics/_index.md
+   - If `--from` specified: resolve to `context-package.json` → load
+     - `constraints[locked]` → immutable constraints (planner must respect)
+     - `constraints[open]` → implementer discretion
+     - `constraints[deferred]` → explicitly scoped out
+     - `requirements[]` → task scope input
+     - `insights[]` → role analysis context (data models, state machines, architecture decisions)
+     - `open_questions[]` → flag areas needing clarification in P2
+   - Else: read `${CONTEXT_DIR}/context.md` if exists, else warn (no upstream analyze)
+   - Merge: if both `--from` and `context.md` exist, context-package takes precedence; context.md supplements
+
+2. **Load spec reference** (if `--spec` flag or index.json has blueprint_ref)
+   - Read from `.workflow/blueprint/${blueprint_ref}/`: blueprint-summary.md, requirements/_index.md, epics/_index.md
 
 3. **Load project specs**
    ```
@@ -106,12 +161,17 @@ When `--tdd` is active:
        - `scope.priority` → task/wave ordering
      - Skip parallel exploration
 
-5. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
+5b. **Merge context-package insights** (if `--from` was loaded)
+   - If context-package `insights[]` contain `area: "data-model"` or `area: "state-machine"`: inject as planner constraints
+   - Map `insights[].summary` to implementation guidance for relevant tasks
+   - These replace the need for a separate analyze step when brainstorm already provided sufficient role analysis
+
+6. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
    - Exploration angles (1-4 based on complexity): architecture, implementation, integration, risk
    - Spawn 1-4 `cli-explore-agent` in parallel, each with phase goal + success_criteria + one angle
    - Output: `.process/exploration-{angle}.json`, `.process/explorations-manifest.json`, `.process/context-package.json`
 
-5b. **CLI supplementary context** (runs in parallel with step 5, skip if `--gaps` or no CLI tools enabled)
+6b. **CLI supplementary context** (runs in parallel with step 6, skip if `--gaps` or no CLI tools enabled)
    ```
    IF no CLI tools enabled: skip
 
@@ -128,7 +188,7 @@ When `--tdd` is active:
    ```
    **On callback:** Parse result, merge into explorationContext as `cli_context` field. Planner uses patterns for task `read_first[]`, dependencies for wave ordering, conflict_risks for collision detection.
 
-6. **Gap-mode context** (if `--gaps`)
+7. **Gap-mode context** (if `--gaps`)
 
    Gap sources (in priority order, first non-empty wins, then additionals merged):
    - **Primary**: `.workflow/issues/issues.jsonl` — filter by phase_ref + status in ["registered","diagnosed"], mark as "planning"
@@ -171,9 +231,11 @@ When `--tdd` is active:
 
 **Purpose:** Generate the execution plan.
 
+**Rule:** Main flow MUST NOT create/modify TASK files. All planning delegated to planner agent. Upstream analyze results (conclusions.json / implementation_scope) MUST be passed into planner spawn as `explorationContext` in the same step.
+
 ### Standard Mode (default)
 
-Spawn `workflow-planner` agent with: context.md, spec-ref, doc-index.json, explorationContext (incl. implementationScope), clarificationContext, phase goal + success_criteria, templates (plan.json, task.json).
+Spawn `workflow-planner` agent with: context.md, spec-ref, doc-index.json, explorationContext (incl. implementationScope from P1 Step 5), clarificationContext, phase goal + success_criteria, templates (plan.json, task.json).
 
 **Task count guard**: Before spawning, assess scope complexity:
 - Single feature / simple change → expect **1-2 tasks** max
@@ -236,10 +298,11 @@ Every TASK-*.json MUST include these fields — they are NOT optional:
 
 ### Gap Mode (`--gaps`)
 
-For each gap from explorationContext (P1 Step 6), create `TASK-{NNN}.json`:
-- `type: "fix"`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-verifiable), `issue_id` (if source == "issue")
+Spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 7), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
+
+Planner: for each gap emit one task — `type: "fix"`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-verifiable), `issue_id` (if source == "issue"); assign IDs and waves; build plan.json.
 
-Bidirectional linking: update matching issues in `.workflow/issues/issues.jsonl` → `status: "planned"`. Build plan.json with gap-fix tasks.
+Bidirectional linking (main flow, post-planner): update matching issues in `.workflow/issues/issues.jsonl` → `status: "planned"`.
 
 ### Output
 - `plan.json` in PHASE_DIR
@@ -332,6 +395,7 @@ Bidirectional linking: update matching issues in `.workflow/issues/issues.jsonl`
 
 4. **Register artifact in state.json**
    - Find upstream analyze artifact by CONTEXT_DIR path
+   - Determine milestone: use target_milestone from scope resolution; if adhoc milestone was created in this session, use its ID
    - Create artifact: `{ id: "PLN-{NNN}", type: "plan", milestone, phase, scope, path, status: "completed", depends_on, harvested: false, created_at, completed_at }`
    - Append to `state.json.artifacts`, atomic write
 
@@ -389,11 +453,13 @@ Incrementally modify an existing plan without rebuilding from scratch.
      - Update convergence criteria
    - Parse instructions into concrete changes
 
-3. **Apply targeted changes**
-   - Modify affected TASK files in-place
-   - If tasks added/removed: re-sequence task IDs, regenerate wave assignments
-   - Update plan.json summary (task count, wave structure)
-   - Preserve unmodified tasks completely
+3. **Spawn `workflow-planner` agent for revision**
+   - Input: existing plan.json + all `.task/TASK-*.json` + parsed revision instructions + explorationContext (include implementation_scope if conclusions.json exists) + templates
+   - Planner:
+     - Modify affected TASK files in-place
+     - If tasks added/removed: re-sequence task IDs, regenerate wave assignments
+     - Update plan.json summary (task count, wave structure)
+     - Preserve unmodified tasks
 
 4. **Re-run plan-checker (P4)**
    - Validate modified plan with same checker as create mode