maestro-flow 0.3.22 → 0.3.23

package/workflows/cli-tools-usage.md

@@ -22,7 +22,8 @@ maestro delegate "<PROMPT>" [options]
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--to <name>` | Tool: gemini, qwen, codex, claude, opencode | First enabled in config |
+| `--to <tool>` | Explicit tool: gemini, qwen, codex, claude, opencode | First enabled in config |
+| `--role <role>` | Capability role: analyze, explore, review, implement, plan, brainstorm, research | — (resolves via config) |
 | `--mode <mode>` | `analysis` (read-only) or `write` (create/modify/delete) | `analysis` |
 | `--model <model>` | Model override | Tool's `primaryModel` |
 | `--cd <dir>` | Working directory | Current directory |
@@ -32,6 +33,19 @@ maestro delegate "<PROMPT>" [options]
 | `--resume [id]` | Resume session (last if no id, comma-separated for merge) | — |
 | `--backend <type>` | Adapter backend: `direct` or `terminal` (tmux/wezterm) | `direct` |
 
+### Tool Resolution Priority
+
+1. `--to <tool>` — explicit tool selection (backward compat, highest priority)
+2. `--role <role>` — capability-based auto-selection via config
+3. No flag — first enabled tool in config
+
+### Role-Based Tool Selection
+
+Roles map to tools via `cli-tools.json` configuration:
+- User-defined roles in `roles` section override built-in defaults
+- Workspace `.maestro/cli-tools.json` overrides global `~/.maestro/cli-tools.json`
+- Built-in roles: `analyze`, `explore`, `review`, `implement`, `plan`, `brainstorm`, `research`
+
 ### Mode Definition (Authoritative)
 
 | Mode | Permission | Auto-Invoke Safe | Use For |
@@ -236,6 +250,6 @@ Proactively invoke `maestro delegate` when these conditions are met — no user
 
 - Default `--mode analysis` (safe, read-only)
 - Wait for results before next action
-- Tool fallback: `gemini` → `qwen` → `codex`
+- Use `--role` for capability-based tool selection; fallback chain is config-driven
 - Rule suggestions are guidelines — choose the best fit
 </execution>

package/workflows/codex-instructions.md

@@ -0,0 +1,150 @@
+# Codex Code Guidelines
+
+
+## Code Quality Standards
+
+### Code Quality
+- Follow project's existing patterns
+- Match import style and naming conventions
+- Single responsibility per function/class
+- DRY (Don't Repeat Yourself)
+- YAGNI (You Aren't Gonna Need It)
+
+### Testing
+- Test all public functions
+- Test edge cases and error conditions
+- Mock external dependencies
+- Target 80%+ coverage
+
+### Error Handling
+- Proper try-catch blocks
+- Clear error messages
+- Graceful degradation
+- Don't expose sensitive info
+
+## Core Principles
+
+**Incremental Progress**:
+- Small, testable changes
+- Commit working code frequently
+- Build on previous work (subtasks)
+
+**Evidence-Based**:
+- Study 3+ similar patterns before implementing
+- Match project style exactly
+- Verify with existing code
+
+**Pragmatic**:
+- Boring solutions over clever code
+- Simple over complex
+- Adapt to project reality
+
+**Context Continuity** (Multi-Task):
+- Leverage resume for consistency
+- Maintain established patterns
+- Test integration between subtasks
+
+**Git Operations** (Parallel Task Safety):
+- Only stage/commit files directly produced by current task
+- Never touch unrelated changes or other task outputs
+- Use `git add <specific-files>` instead of `git add .`
+- Verify staged files before commit to avoid cross-task conflicts
+
+**Multi-CLI Coexistence** (CRITICAL):
+- If your task conflicts with existing uncommitted changes, **STOP and report the conflict** instead of overwriting
+- Treat all pre-existing uncommitted changes as intentional work-in-progress by other tools
+
+
+## System Optimization
+
+**Direct Binary Calls**: Always call binaries directly in `functions.shell`, set `workdir`, avoid shell wrappers (`bash -lc`, `cmd /c`, etc.)
+
+**Text Editing Priority**:
+1. Use `apply_patch` tool for all routine text edits
+2. Fall back to `sed` for single-line substitutions if unavailable
+3. Avoid Python editing scripts unless both fail
+
+**apply_patch invocation**:
+```json
+{
+  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
+  "workdir": "<workdir>",
+  "justification": "Brief reason"
+}
+```
+
+**Windows UTF-8 Encoding** (before commands):
+```powershell
+[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+chcp 65001 > $null
+```
+
+## Context Acquisition (MCP Tools Priority)
+
+**For task context gathering and analysis, ALWAYS prefer MCP tools**:
+
+1. **mcp__ace-tool__search_context** - HIGHEST PRIORITY for code discovery
+   - Semantic search with real-time codebase index
+   - Use for: finding implementations, understanding architecture, locating patterns
+   - Example: `mcp__ace-tool__search_context(project_root_path="/path", query="authentication logic")`
+
+2. **smart_search** - Fallback for structured search
+   - Use `smart_search(query="...")` for keyword/regex search
+   - Use `smart_search(action="find_files", pattern="*.ts")` for file discovery
+   - Supports modes: `auto`, `hybrid`, `exact`, `ripgrep`
+
+3. **read_file** - Batch file reading
+   - Read multiple files in parallel: `read_file(path="file1.ts")`, `read_file(path="file2.ts")`
+   - Supports glob patterns: `read_file(path="src/**/*.config.ts")`
+
+**Priority Order**:
+```
+ACE search_context (semantic) → smart_search (structured) → read_file (batch read) → shell commands (fallback)
+```
+
+**NEVER** use shell commands (`cat`, `find`, `grep`) when MCP tools are available.
+
+## Workflow Session Awareness
+
+| Workflow | Directory | Summary File |
+|----------|-----------|-------------|
+| `workflow-plan` | `.workflow/active/WFS-*/` | `workflow-session.json` |
+| `workflow-lite-plan` | `.workflow/.lite-plan/{date}-{slug}/` | `plan.json` |
+| `analyze-with-file` | `.workflow/.analysis/ANL-*/` | `conclusions.json` |
+| `multi-cli-plan` | `.workflow/.multi-cli-plan/*/` | `session-state.json` |
+| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
+| Other | `.workflow/.debug/`, `.workflow/.scratchpad/`, `.workflow/archives/` | — |
+
+Before starting work, scan recent sessions (7 days) to avoid conflicts and reuse prior work:
+- Overlapping file scope → warn, suggest referencing prior session
+- Complementary findings → feed into current task context
+
+
+## Knowledge Capture
+
+- **Spec writes** → always `<spec-entry>` closed-tag format with `category`, `keywords`, `date`, `source`. Never raw Markdown. Route through `spec-add` when possible.
+- **Capture signal** → when execution surfaces non-obvious knowledge (plan deviation, retry pattern, root cause, constraint violation), ask user once whether to persist it. Match category to content: decisions→`arch`, pitfalls→`debug`/`learning`, patterns→`coding`, rules→`quality`.
+- **Promotion** → at milestone close, scan learnings for repeated keywords (≥2 entries) and offer to graduate them into formal conventions.
+- **Traceability** → every entry needs a source anchor: `file:line`, `INS-{id}`, commit, or phase path.
+
+## Execution Checklist
+
+**Before**:
+- [ ] Understand PURPOSE and TASK clearly
+- [ ] Use ACE search_context first, fallback to smart_search for discovery
+- [ ] Use read_file to batch read context files, find 3+ patterns
+- [ ] Check RULES templates and constraints
+
+**During**:
+- [ ] Follow existing patterns exactly
+- [ ] Write tests alongside code
+- [ ] Run tests after every change
+- [ ] Commit working code incrementally
+
+**After**:
+- [ ] All tests pass
+- [ ] Coverage meets target
+- [ ] Build succeeds
+- [ ] All EXPECTED deliverables met
+- [ ] Non-obvious knowledge surfaced? → offer `spec-add`

package/workflows/delegate-usage.md

@@ -22,7 +22,8 @@ maestro delegate "<PROMPT>" [options]
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--to <tool>` | Tool: gemini, qwen, codex, claude, opencode | First enabled in config |
+| `--to <tool>` | Explicit tool: gemini, qwen, codex, claude, opencode | First enabled in config |
+| `--role <role>` | Capability role: analyze, explore, review, implement, plan, brainstorm, research | — (resolves via config) |
 | `--mode <mode>` | `analysis` (read-only) or `write` (create/modify/delete) | `analysis` |
 | `--model <model>` | Model override | Tool's `primaryModel` |
 | `--cd <dir>` | Working directory | Current directory |
@@ -32,6 +33,19 @@ maestro delegate "<PROMPT>" [options]
 | `--includeDirs <dirs>` | Additional directories (comma-separated) | — |
 | `--backend <type>` | Adapter backend: `direct` or `terminal` (tmux/wezterm) | `direct` |
 
+### Tool Resolution Priority
+
+1. `--to <tool>` — explicit tool selection (backward compat, highest priority)
+2. `--role <role>` — capability-based auto-selection via config
+3. No flag — first enabled tool in config
+
+### Role-Based Tool Selection
+
+Roles map to tools via `cli-tools.json` configuration:
+- User-defined roles in `roles` section override built-in defaults
+- Workspace `.maestro/cli-tools.json` overrides global `~/.maestro/cli-tools.json`
+- Built-in roles: `analyze`, `explore`, `review`, `implement`, `plan`, `brainstorm`, `research`
+
 ### Mode Definition (Authoritative)
 
 | Mode | Permission | Auto-Invoke Safe | Use For |
@@ -284,7 +298,7 @@ Proactively invoke `maestro delegate` when these conditions are met — no user
 
 - Default `--mode analysis` (safe, read-only)
 - Always `Bash(run_in_background: true)` — stop immediately, wait for callback
-- Tool fallback: `gemini` → `qwen` → `codex`
+- Use `--role` for capability-based tool selection; fallback chain is config-driven
 - Rule suggestions are guidelines — choose the best fit
 - Use `inject` for supplementary context mid-execution; `after_complete` for chained multi-step tasks
 </execution>

package/workflows/execute.md

@@ -48,16 +48,30 @@ For each PLAN_DIR in PLAN_DIRS (sequential):
 
 ## E0.5: Execution Options Confirmation
 
-**Purpose:** Let user choose how tasks execute. Supports both menu selection and natural language intent (e.g., "前端用gemini，后端用codex，其余agent"). Skipped when `-y` flag or executionContext already confirmed.
+**Purpose:** Let user choose how tasks execute. Reads available tools from `delegate-config show --json` to build dynamic options. Supports both menu selection and natural language intent. Skipped when `-y` flag or executionContext already confirmed.
 
 ### Skip conditions
 
 - `-y` flag → use resolved defaults, skip prompt
 - `executionContext.executionMethod` already set → skip (confirmed in /maestro-plan)
 
+### Pre-step: Load tool config
+
+```
+Run: maestro delegate-config show --json
+Parse: { tools, roles } — extract enabled tool names and domain tags
+Build dynamic options from enabled tools (exclude agent which is always available)
+```
+
 ### Tool Call
 
+Build AskUserQuestion dynamically from enabled tools:
+
 ```
+// availableTools = enabled tools from delegate-config (e.g. ["gemini", "claude", "codex"])
+// frontendTool = first tool with "frontend" tag, fallback first enabled
+// backendTool = first tool with "backend" tag, fallback first enabled
+
 AskUserQuestion({
   questions: [
     {
@@ -65,10 +79,10 @@ AskUserQuestion({
       header: "Executor",
       multiSelect: false,
       options: [
-        { label: "Auto (Recommended)", description: "Per-task domain routing: frontend→gemini, backend→codex, general→agent" },
+        { label: "Auto (Recommended)", description: `Per-task domain routing: frontend→${frontendTool}, backend→${backendTool}, general→agent` },
         { label: "Agent", description: "Claude Code agent for all tasks (fastest)" },
-        { label: "Codex", description: "Codex CLI for all tasks (strong for complex backend)" },
-        { label: "Gemini", description: "Gemini CLI for all tasks (strong for frontend/UI)" }
+        // One option per enabled CLI tool:
+        ...availableTools.map(t => ({ label: t, description: `${t} CLI for all tasks` }))
       ]
     },
     {
@@ -77,8 +91,8 @@ AskUserQuestion({
       multiSelect: false,
       options: [
         { label: "Skip (Recommended)", description: "No code review, proceed to verification" },
-        { label: "Gemini Review", description: "Gemini CLI: git diff quality review" },
-        { label: "Codex Review", description: "Codex CLI: git-aware code review" }
+        // One option per enabled CLI tool with review capability:
+        ...availableTools.map(t => ({ label: `${t} Review`, description: `${t} CLI: git diff quality review` }))
       ]
     }
   ]
@@ -91,11 +105,11 @@ AskUserQuestion({
 
 | Answer | executionMethod | domainRouting |
 |--------|----------------|---------------|
-| "Auto" | `"auto"` | `{ frontend: "gemini", backend: "codex", default: "agent" }` |
-| "Agent" / "Codex" / "Gemini" | that value | not used |
-| Other text with domain rules | `"auto"` | Parse from user text (see examples below) |
+| "Auto" | `"auto"` | `{ frontend: frontendTool, backend: backendTool, default: "agent" }` |
+| "Agent" / tool name | that value | not used |
+| Other text with domain rules | `"auto"` | Parse from user text |
 
-Other text parsing examples:
+Other text parsing — match tool names dynamically from enabled tools:
 
 | User types | domainRouting |
 |------------|---------------|
@@ -134,9 +148,9 @@ If executionContext is available in memory:
 Read ${PLAN_DIR}/plan.json
 
 executionMethod = E0.5 selection || --method flag || config.json.execution.method || "auto"
-defaultExecutor = --executor flag || config.json.execution.default_executor || "gemini"
+defaultExecutor = --executor flag || config.json.execution.default_executor || first enabled tool from delegate-config
 executorAssignments = plan.json.executor_assignments || {}
-domainRouting = E0.5 domainRouting || { frontend: "gemini", backend: "codex", default: "agent" }
+domainRouting = E0.5 domainRouting || built from delegate-config domain tags (frontend→tag match, backend→tag match, default→"agent")
 codeReviewTool = E0.5 selection || "Skip"
 ```
 
@@ -340,9 +354,9 @@ If none critical: log "passed" and continue to E2.6
 If codeReviewTool == "Skip": continue to E3
 
 Dispatch review via maestro delegate (run_in_background: true):
-  --to gemini|codex (per codeReviewTool selection) --mode analysis
+  --to ${codeReviewTool} --mode analysis
   Prompt: review git diff (execution start → HEAD) for correctness, style, bugs
-  Rule: analysis-review-code-quality (gemini only)
+  Rule: analysis-review-code-quality
   Expected: severity-ranked issues with file:line references and fix suggestions
 
 Wait for completion, log findings summary

package/workflows/init.md

@@ -1,6 +1,6 @@
 # Workflow: init
 
-Project initialization with automatic state detection. Creates project infrastructure only — roadmap creation is handled by maestro-spec-generate or maestro-roadmap.
+Project initialization with automatic state detection. Creates project infrastructure only — roadmap creation is handled by maestro-roadmap (light or full mode).
 
 ---
 
@@ -143,7 +143,7 @@ Verify all required directories and files exist:
    - Config highlights (mode, granularity, execution method, enabled agents)
    - Research summary (if research was run)
 3. Route next steps:
-   - "Run `/maestro-spec-generate` to create full spec package with roadmap (heavy path)"
+   - "Run `/maestro-roadmap --mode full` to create full spec package with roadmap (heavy path)"
    - "Run `/maestro-roadmap` to create interactive roadmap directly (light path)"
    - "Run `/manage-status` to view project dashboard"
    - "Run `/maestro-brainstorm` to explore ideas first"

package/workflows/issue-discover.md

@@ -109,7 +109,7 @@ Per perspective → delegate analysis:
   CONTEXT: @**/*
   EXPECTED: JSON array: [{ title, severity, description, location, fix_direction, affected_components[] }]
   CONSTRAINTS: Evidence-backed findings only
-  " --to gemini --mode analysis
+  " --role analyze --mode analysis
 
 Results → .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
 Update discovery-state.json: perspectives_completed += ["{PERSPECTIVE}"]
@@ -170,7 +170,7 @@ Delegate to decompose USER_PROMPT into 3-5 exploration dimensions:
 
   maestro delegate "Decompose into searchable dimensions: {USER_PROMPT}
   EXPECTED: JSON array: [{ name, description, search_patterns[], file_patterns[], finding_criteria }]
-  " --to gemini --mode analysis
+  " --role analyze --mode analysis
 
 Store → .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
 ```

package/workflows/maestro-super.md

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

package/workflows/maestro.codex.md

@@ -138,7 +138,7 @@ const chainMap = {
   // ── Multi-step chains ────────────────────────────────────────────────────
   'spec-driven': [
     { cmd: 'maestro-init' },
-    { cmd: 'maestro-spec-generate', args: '"{description}"' },
+    { cmd: 'maestro-roadmap', args: '--mode full "{description}"' },
     { cmd: 'maestro-plan',          args: '{phase}' },
     { cmd: 'maestro-execute',       args: '{phase}' },
     { cmd: 'maestro-verify',        args: '{phase}' }
@@ -306,9 +306,9 @@ MAESTRO-COORDINATE: {chain_name}  (dry run)
 
 Create session directory `.workflow/.maestro/maestro-{timestamp}/`.
 
-**Barrier skills** (solo wave, coordinator analyzes artifacts after): `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-spec-generate`, `maestro-execute`.
+**Barrier skills** (solo wave, coordinator analyzes artifacts after): `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-roadmap`, `maestro-execute`.
 
-**Auto-flag injection** (when AUTO_YES): `maestro-analyze/-brainstorm/-ui-design/-spec-generate` → `-y`, `maestro-plan` → `--auto`, `quality-test` → `--auto-fix`, `quality-retrospective` → `--auto-yes`.
+**Auto-flag injection** (when AUTO_YES): `maestro-analyze/-brainstorm/-roadmap/-ui-design` → `-y`, `maestro-plan` → `--auto`, `quality-test` → `--auto-fix`, `quality-retrospective` → `--auto-yes`.
 
 Initialize `state.json` with: session_id, intent, chain_name, auto_yes, context (phase, dirs, issue_id, gaps), waves[], and steps[] (each with index, cmd, args, status=pending).
 
@@ -352,7 +352,7 @@ Context updates per barrier skill:
 | `maestro-analyze` | `analysis_dir`, gaps (from context.md markers), phase (if detected) |
 | `maestro-plan` | `plan_dir`, task/wave count (from plan.json) |
 | `maestro-brainstorm` | `brainstorm_dir` |
-| `maestro-spec-generate` | `spec_session_id` (SPEC-* pattern) |
+| `maestro-roadmap` | `spec_session_id` (SPEC-* pattern) |
 | `maestro-execute` | `exec_completed`/`exec_failed` counts (from results.csv) |
 
 **Key principle**: The coordinator owns all context assembly. Sub-agents receive a fully-resolved `skill_call`.

package/workflows/maestro.md

@@ -1,7 +1,7 @@
 # Workflow: maestro
 
 Intelligent coordinator that routes user intent to optimal command chain based on project state.
-Dual execution engines: **Skill()** (in-process, synchronous) and **CLI delegate** (via `maestro delegate`, async with gemini quality analysis).
+Dual execution engines: **Skill()** (in-process, synchronous) and **CLI delegate** (via `maestro delegate`, async with role-based tool selection).
 Default `auto` mode selects engine based on chain complexity.
 
 **Prerequisites:**
@@ -222,7 +222,7 @@ resolvePhase — priority order:
   3. From project state artifacts: in-progress execute → first incomplete phase → latest artifact phase
   4. null if chain is 'analyze-plan-execute' (uses {scratch_dir} instead)
   5. null if all chain commands are phase-independent:
-     manage-status, manage-issue, manage-issue-discover, maestro-init, maestro-spec-generate,
+     manage-status, manage-issue, manage-issue-discover, maestro-init,
      maestro-fork, maestro-merge, maestro-roadmap, spec-setup, manage-knowhow, manage-knowhow-capture,
      manage-learn, manage-codebase-rebuild, manage-codebase-refresh, maestro-milestone-audit,
      maestro-milestone-complete
@@ -245,7 +245,7 @@ Engine is selected **per step**, not per chain.
 ```
 If execMode is 'cli' or 'skill' → force that engine for all steps.
 In 'auto' mode, select per step:
-  CLI steps (heavy, context-isolated): maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm, maestro-spec-generate, maestro-roadmap, maestro-ui-design, quality-refactor
+  CLI steps (heavy, context-isolated): maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm, maestro-roadmap, maestro-ui-design, quality-refactor
   Skill steps (everything else): observable, interactive, lightweight (verify, review, test, debug, milestone-*, manage-*, spec-*, quick, etc.)
 ```
 
@@ -282,7 +282,7 @@ Context object tracks: current_phase, user_intent, issue_id, spec_session_id, sc
 
 assembleArgs: substitute placeholders {phase}, {description}, {issue_id}, {spec_session_id}, {scratch_dir} in step.args.
   In auto_mode, append per-command flag if not already present:
-    maestro-analyze/brainstorm/roadmap/ui-design/spec-generate → -y
+    maestro-analyze/brainstorm/roadmap/ui-design → -y
     maestro-plan → --auto
     quality-test → --auto-fix
     quality-retrospective → --auto-yes
@@ -425,7 +425,7 @@ const chainMap = {
 
   // ── Multi-step chains ──
   'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }],
-  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-spec-generate', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  '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}' }],
   'ui-design-driven':     [{ cmd: 'maestro-ui-design', args: '{phase}' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],