maestro-flow 0.3.22 → 0.3.24

package/.claude/commands/maestro-analyze.md

@@ -58,7 +58,7 @@ Phase 1: Load issues from .workflow/issues/issues.jsonl
 
 Phase 2: CLI exploration per issue
   - For each issue: build exploration prompt from issue.title, description, context, related_files
-  - Run maestro delegate --to gemini --mode analysis with codebase context
+  - Run maestro delegate --role analyze --mode analysis with codebase context
   - Gather affected files, call chains, root cause evidence
 
 Phase 3: Root cause synthesis → write issue.analysis

package/.claude/commands/maestro-brainstorm.md

@@ -53,7 +53,7 @@ Follow '~/.maestro/workflows/brainstorm.md' completely.
 
 Auto mode:
 - Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need spec package → Skill({ skill: "maestro-spec-generate", args: "--from-brainstorm {session_id}" })
+- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
 - Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
 - Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
 - `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)

package/.claude/commands/maestro-composer.md

@@ -150,11 +150,11 @@ If the spec file does not exist, use the built-in fallback mapping:
 | `testing` | skill | `quality-test` |
 | `review` | skill | `quality-review` |
 | `brainstorm` | skill | `maestro-brainstorm` |
-| `analysis` | cli | `maestro delegate --to gemini --mode analysis` |
+| `analysis` | cli | `maestro delegate --role analyze --mode analysis` |
 | `verify` | skill | `maestro-verify` |
 | `refactor` | skill | `quality-refactor` |
 | `debug` | skill | `quality-debug` |
-| `spec` | skill | `maestro-spec-generate` |
+| `spec` | skill | `maestro-roadmap --mode full` |
 | `checkpoint` | checkpoint | — |
 
 **Step 2.1** — Load `intent.json`.
@@ -210,7 +210,7 @@ options:
 | Artifact boundary | Source output_ports: plan, spec, analysis, review-findings |
 | Execution gate | Target executor contains `execute` |
 | Agent spawn | Target type is `agent` |
-| Long-running | Target is maestro-plan, maestro-spec-generate |
+| Long-running | Target is maestro-plan, maestro-roadmap --mode full |
 | User-defined | Step had `type_hint: checkpoint` |
 | Post-testing | Source executor contains `test` or `integration-test` |
 

package/.claude/commands/maestro-init.md

@@ -12,7 +12,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-spec-generate or maestro-roadmap as the next step.
+Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-roadmap (light mode, default) or maestro-roadmap --mode full (spec package) as the next step.
 </purpose>
 
 <required_reading>
@@ -48,8 +48,8 @@ Created:
   .workflow/specs/
 
 Next steps (choose one path to create roadmap):
-  /maestro-spec-generate <idea>                                -- Full spec package + roadmap (heavy)
-  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light)
+  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light, default)
+  /maestro-roadmap --mode full <idea>                          -- Full spec package + roadmap (heavy)
 
 Other commands:
   /manage-status                                               -- View project dashboard
@@ -74,5 +74,5 @@ Other commands:
 - [ ] `.workflow/config.json` created with user-selected granularity, workflow agents, gate preferences
 - [ ] `.workflow/specs/` initialized with convention files
 - [ ] Research completed (if enabled) — 4 parallel agents spawned
-- [ ] User knows next step is `/maestro-roadmap` or `/maestro-spec-generate`
+- [ ] User knows next step is `/maestro-roadmap` (light) or `/maestro-roadmap --mode full` (spec package)
 </success_criteria>

package/.claude/commands/maestro-roadmap.md

@@ -1,108 +1,164 @@
----
-name: maestro-roadmap
-description: Interactive roadmap creation with iterative refinement — lightweight alternative to spec-generate
-argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Create or revise a project roadmap through interactive requirement decomposition and iterative refinement. This is the lightweight path for structured decomposition — directly from requirements to roadmap without full specification documents. For the heavy path with formal specs, use maestro-spec-generate instead.
-
-Supports three modes:
-- **Create** (default): Build roadmap from requirements
-- **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
-- **Review** (`--review`): Health assessment of current roadmap — actual vs planned, drift detection, adjustment recommendations (read-only)
-
-Produces `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/roadmap.md
-@~/.maestro/templates/roadmap.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- requirement text, @file reference, or brainstorm session reference.
-
-**Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint
-- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
-- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
-- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly (e.g. `--revise "add phase 4 for perf optimization"` or `--revise "split phase 2 into 2a and 2b"`). If omitted, ask user for revision instructions via AskUserQuestion. Preserves completed phase progress.
-- `--review`: Roadmap health assessment — compare actual vs planned progress, detect drift, assess remaining phases (read-only, produces review report)
-
-**Input types:**
-- Direct text: `"Implement user authentication system with OAuth and 2FA"`
-- File reference: `@requirements.md`
-- Brainstorm import: `--from-brainstorm WFS-xxx`
-- No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`
-
-**Relationship to pipeline:**
-```
-maestro-brainstorm (optional upstream)
-        ↓ guidance-specification.md
-maestro-init (project setup — no roadmap)
-        ↓ project.md, state.json, config.json
-maestro-roadmap (this command — light path)
-        ↓ roadmap.md → .workflow/roadmap.md
-maestro-plan → maestro-execute → maestro-verify
-
-Alternative heavy path (skip maestro-roadmap):
-maestro-init → maestro-spec-generate → spec package + roadmap.md
-```
-
-Dual modes (Progressive vs Direct), auto-selection criteria, and minimum-phase principle are defined in workflow roadmap.md (Steps 2-3).
-</context>
-
-<execution>
-
-### Mode: Create (default)
-
-Follow '~/.maestro/workflows/roadmap.md' completely.
-
-**Next-step routing on completion:**
-- Roadmap approved → /maestro-analyze 1
-- Simple project, skip analysis → /maestro-plan 1
-- Need UI design first → /maestro-ui-design 1
-- View project dashboard → /manage-status
-
-### Mode: Revise (`--revise [instructions]`)
-
-Follow workflow roadmap.md "Mode: Revise" section for full algorithm (load state, obtain instructions, impact analysis, apply revisions, post-validation).
-
-### Mode: Review (`--review`)
-
-Follow workflow roadmap.md "Mode: Review" section for full algorithm (load state, assess dimensions, produce report).
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Requirement text or @file required | Prompt user for input |
-| E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
-| E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
-| E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
-| E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
-| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
-| W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
-| W005 | warning | External research agent failed | Continue without apiResearchContext |
-</error_codes>
-
-<success_criteria>
-- [ ] Requirement parsed with goal, constraints, stakeholders
-- [ ] Decomposition strategy selected (progressive or direct)
-- [ ] Phases defined with success criteria, dependencies, and requirement mappings
-- [ ] Every Active requirement from project.md mapped to exactly one phase
-- [ ] No circular dependencies in phase ordering
-- [ ] User approved roadmap (or auto-approved with -y)
-- [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
-- [ ] No phase directories created (phases are labels in roadmap, not directories)
-</success_criteria>
+---
+name: maestro-roadmap
+description: Roadmap generation with dual mode — light (requirement→roadmap) or full (requirement→spec package→roadmap)
+argument-hint: "<requirement> [--mode light|full] [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified roadmap generation with two execution paths:
+
+- **Light mode** (default): Directly from requirements to roadmap. No specification documents.
+- **Full mode** (`--mode full`): 7-phase document chain (Product Brief → PRD → Architecture → Epics → Roadmap) producing a complete specification package in `.workflow/.spec/` plus `.workflow/roadmap.md`.
+
+Additional operation modes (light mode only):
+- **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
+- **Review** (`--review`): Health assessment of current roadmap (read-only)
+
+Both modes produce `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/roadmap-common.md
+@~/.maestro/templates/roadmap.md
+</required_reading>
+
+<deferred_reading>
+- [roadmap.md](~/.maestro/workflows/roadmap.md) — read when mode is light (default)
+- [spec-generate.md](~/.maestro/workflows/spec-generate.md) — read when mode is full
+- [spec-config.json](~/.maestro/templates/spec-config.json) — read when initializing spec configuration (full mode)
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- requirement text, @file reference, or brainstorm session reference.
+
+**Flags (shared):**
+- `--mode light|full`: Execution path (default: light)
+- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
+- `-c` / `--continue`: Resume from last checkpoint
+- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
+
+**Flags (light mode only):**
+- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
+- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress.
+- `--review`: Roadmap health assessment (read-only)
+
+**Input types:**
+- Direct text: `"Implement user authentication system with OAuth and 2FA"`
+- File reference: `@requirements.md`
+- Brainstorm import: `--from-brainstorm WFS-xxx`
+- No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`
+
+**Pipeline position:**
+```
+maestro-brainstorm (optional upstream)
+        ↓ guidance-specification.md
+maestro-init (project setup)
+        ↓ project.md, state.json, config.json
+maestro-roadmap [--mode light]     → roadmap.md directly
+maestro-roadmap --mode full        → spec package + roadmap.md
+        ↓
+maestro-plan → maestro-execute → maestro-verify
+```
+
+**Note (full mode):** `maestro-init` MUST run before `--mode full`. It creates the `.workflow/` directory and project context.
+</context>
+
+<execution>
+
+### Mode routing
+
+1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
+2. Parse `--mode` flag:
+   - `light` or omitted → read `@~/.maestro/workflows/roadmap.md`, follow its process
+   - `full` → read `@~/.maestro/workflows/spec-generate.md`, follow its process
+3. If `--revise` or `--review` present → force light mode (these are light-mode-only operations)
+
+### Light mode (default)
+
+Follow `~/.maestro/workflows/roadmap.md` completely.
+
+Sub-modes:
+- **Create** (default): Build roadmap from requirements
+- **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
+- **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
+
+### Full mode (`--mode full`)
+
+Follow `~/.maestro/workflows/spec-generate.md` completely.
+
+### Next-step routing on completion
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Roadmap approved, need analysis | /maestro-analyze 1 |
+| Simple project, ready to plan | /maestro-plan 1 |
+| Need UI design first | /maestro-ui-design 1 |
+| View project dashboard | /manage-status |
+| Need project setup (full mode) | /maestro-init |
+</execution>
+
+<error_codes>
+
+**Shared:**
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Requirement/idea text or @file required | Prompt user for input |
+| E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
+
+**Light mode:**
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
+| E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
+| E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
+| W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
+
+**Full mode:**
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E006 | error | `.workflow/` not initialized | Run maestro-init first |
+| E007 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
+| W002 | warning | Codebase exploration failed | Continue without codebase context |
+| W003 | warning | Glossary has < 5 terms | Note in readiness check |
+| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
+</error_codes>
+
+<success_criteria>
+
+**Light mode:**
+- [ ] Requirement parsed with goal, constraints, stakeholders
+- [ ] Decomposition strategy selected (progressive or direct)
+- [ ] Phases defined with success criteria, dependencies, and requirement mappings
+- [ ] Every Active requirement from project.md mapped to exactly one phase
+- [ ] No circular dependencies in phase ordering
+- [ ] User approved roadmap (or auto-approved with -y)
+- [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
+- [ ] No phase directories created (phases are labels in roadmap, not directories)
+
+**Full mode (in addition to light mode criteria for roadmap):**
+- [ ] `spec-config.json` created with session metadata and phase tracking
+- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
+- [ ] `glossary.json` with 5+ core terms for cross-document consistency
+- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
+- [ ] All requirements have RFC 2119 keywords and acceptance criteria
+- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
+- [ ] Architecture includes state machine, config model, error handling, observability (service type)
+- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
+- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
+- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
+- [ ] `spec-summary.md` with one-page executive summary
+- [ ] All documents have valid YAML frontmatter with session_id
+- [ ] Glossary terms used consistently across all documents
+- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
+- [ ] `.workflow/roadmap.md` written
+</success_criteria>

package/.claude/commands/maestro.md

@@ -1,7 +1,7 @@
 ---
 name: maestro
-description: Intelligent coordinator - analyze intent + read project state → select optimal command chain → execute via Skill() or CLI delegate
-argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>] [--exec auto|cli|skill] [--tool <name>]"
+description: Intelligent coordinator - analyze intent + read project state → select optimal command chain → execute via internal or CLI delegate
+argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--exec auto|cli|internal] [--tool <name>] [--super]"
 allowed-tools:
   - Read
   - Write
@@ -19,17 +19,21 @@ Two routing modes:
 2. **State-based**: Read .workflow/state.json → determine next logical step → suggest/execute (triggered by `continue`/`next`)
 
 Per-step execution engine (default: auto):
-- **Skill()**: Observable steps — output visible in conversation, synchronous, user can intervene
+- **internal**: Execute via Skill() in current session — output visible in conversation, synchronous, user can intervene
 - **CLI delegate**: Heavy execution steps — context isolation, template-driven prompts, gemini quality analysis
 
 Produces session directory at `.workflow/.maestro/{session_id}/` with status.json tracking chain progress.
-Executes commands sequentially via Skill() with artifact propagation between steps.
+Executes commands sequentially with artifact propagation between steps.
 </purpose>
 
 <required_reading>
 @~/.maestro/workflows/maestro.md
 </required_reading>
 
+<deferred_reading>
+- [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
+</deferred_reading>
+
 <context>
 $ARGUMENTS — user intent text, or special keywords.
 
@@ -41,9 +45,9 @@ $ARGUMENTS — user intent text, or special keywords.
 - `-y` / `--yes` — Auto mode: skip clarification, skip confirmation, auto-skip on errors. Propagates to downstream commands that support it.
 - `-c` / `--continue` — Resume previous coordinator session from `.workflow/.maestro/*/status.json`
 - `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection). Valid: full-lifecycle, spec-driven, brainstorm-driven, execute-verify, quality-loop, milestone-close, quick, review
-- `--exec <mode>` — Execution engine: `auto` (default), `cli`, `skill`. Auto selects per step based on command complexity.
+- `--exec <mode>` — Execution engine: `auto` (default), `cli`, `internal`. `internal` = Skill() in current session; `cli` = delegate to external CLI. Auto selects per step based on command complexity.
 - `--tool <name>` — CLI tool for delegate execution (default: claude). Only used when engine=cli.
+- `--super` — Super mode: deliver production-ready complete software system. See Super Mode section below.
 
 **State files read:**
 - `.workflow/state.json` — project state machine + artifact registry
@@ -65,7 +69,7 @@ When `-y` is active, maestro propagates auto flags to downstream commands. Only
 | maestro-roadmap | `-y` | Skip interactive questions, use defaults (create/revise/review) |
 | maestro-ui-design | `-y` | Skip interactive selection, pick top variant |
 | maestro-plan | `--auto` | Skip interactive clarification |
-| maestro-spec-generate | `-y` | Skip interactive questions, use defaults |
+| maestro-roadmap --mode full | `-y` | Skip interactive questions, use defaults |
 | maestro-execute | *(none)* | No auto flag — executes all tasks normally |
 | maestro-verify | *(none)* | No auto flag — runs full verification |
 | quality-review | *(none)* | No auto flag — auto-detects level, runs fully |
@@ -84,6 +88,8 @@ In auto mode, maestro also:
 - Auto-skips on step errors (retry once, then skip and continue)
 
 Context cleanup hints, context window reminders, and completion report format are defined in workflow maestro.md (Steps 7a-1, 7f).
+
+**Super mode (`--super`):** Read `maestro-super.md` from deferred_reading, then follow it completely.
 </execution>
 
 <error_codes>
@@ -95,7 +101,6 @@ Context cleanup hints, context window reminders, and completion report format ar
 | E004 | error | Resume session not found | Show available sessions |
 | W001 | warning | Intent ambiguous, multiple chains possible | Present options, let user choose |
 | W002 | warning | Chain step completed with warnings | Log and continue |
-| E005 | error | Invalid chain name provided with --chain | Show valid chain names and exit |
 | W003 | warning | State suggests different chain than intent | Show discrepancy, let user decide |
 </error_codes>
 
@@ -103,12 +108,16 @@ Context cleanup hints, context window reminders, and completion report format ar
 - [ ] Intent classified with task_type, complexity, clarity_score
 - [ ] Project state read and incorporated into routing
 - [ ] Command chain selected and confirmed (or auto-confirmed with -y)
-- [ ] Per-step engine selected (auto routes heavy steps to CLI, observable steps to Skill)
+- [ ] Per-step engine selected (auto routes heavy steps to CLI, observable steps to internal)
 - [ ] Auto flags correctly propagated to supporting commands only
 - [ ] Session directory created at .workflow/.maestro/{session_id}/
 - [ ] status.json tracks per-step progress and execution engine
-- [ ] All chain steps executed via Skill() or CLI delegate with proper argument propagation
+- [ ] All chain steps executed via internal or CLI delegate with proper argument propagation
 - [ ] Phase numbers auto-detected and passed to downstream commands
 - [ ] Error handling: retry/skip/abort per step (auto-skip in -y mode)
 - [ ] Session summary displayed on completion
+- [ ] (super mode) Requirements expanded and validated via Gemini before roadmap creation
+- [ ] (super mode) Each milestone scored ≥ 80% before advancing
+- [ ] (super mode) All milestones completed with no user intervention
+- [ ] (super mode) Final system builds, starts, and passes all tests
 </success_criteria>

package/.claude/commands/quality-business-test.md

@@ -82,9 +82,9 @@ Follow '~/.maestro/workflows/business-test.md' completely.
 |------|----------|-----------|----------|
 | E001 | error | Phase number required | Prompt user for phase number |
 | E002 | error | Phase artifacts not found | Verify phase has artifacts in state.json |
-| E003 | error | No spec package AND no success_criteria (can't extract scenarios) | Run maestro-spec-generate or maestro-plan first |
+| E003 | error | No spec package AND no success_criteria (can't extract scenarios) | Run maestro-roadmap --mode full or maestro-plan first |
 | E004 | error | L1 critical failures block L2/L3 progression | Fix blockers first via quality-debug |
-| W001 | warning | Degraded mode (no spec package, using success_criteria) | Consider running maestro-spec-generate for full coverage |
+| W001 | warning | Degraded mode (no spec package, using success_criteria) | Consider running maestro-roadmap --mode full for full coverage |
 | W002 | warning | Some requirements have no testable acceptance criteria | Note in report, suggest spec refinement |
 | W003 | warning | Generator-Critic loop exhausted (3 iterations) without full convergence | Accept current state, proceed with known defects |
 | W004 | warning | Mock services not available for L3 scenarios | Skip L3 or run with --gen-code for TestContainers |

package/.claude/skills/team-quality-assurance/roles/scout/role.md

@@ -50,7 +50,7 @@ CONTEXT: @<scan-scope>
 EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
 CONSTRAINTS: Focus on actionable findings only
 ```
-Execute via: `maestro delegate "<prompt>" --to gemini --mode analysis`
+Execute via: `maestro delegate "<prompt>" --role analyze --mode analysis`
 
 After all perspectives complete:
 - Parse CLI outputs into structured findings

package/.claude/skills/team-review/roles/reviewer/role.md

@@ -52,7 +52,7 @@ Build prompt per group requesting 6 enrichment fields per finding:
 - `fix_complexity`: low / medium / high
 - `fix_dependencies`: finding IDs that must be fixed first
 
-Execute via `maestro delegate --to gemini --mode analysis --rule analysis-diagnose-bug-root-cause` (fallback: qwen -> codex). Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`.
+Execute via `maestro delegate --role review --mode analysis --rule analysis-diagnose-bug-root-cause`. Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`.
 
 ## Phase 4: Report Generation
 

package/.claude/skills/team-review/roles/scanner/role.md

@@ -59,7 +59,7 @@ Build prompt with target file patterns, toolchain dedup summary, and per-dimensi
 - PRF: Algorithm complexity, N+1 queries, unnecessary sync, memory leaks, missing caching
 - MNT: Architectural coupling, abstraction leaks, convention violations, dead code
 
-Execute via `maestro delegate --to gemini --mode analysis --rule analysis-review-code-quality` (fallback: qwen -> codex). Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.
+Execute via `maestro delegate --role review --mode analysis --rule analysis-review-code-quality`. Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.
 
 ### Tech Profile Scan
 

package/.claude/skills/team-tech-debt/roles/scanner/role.md

@@ -56,9 +56,9 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch
 - Classify findings into dimensions
 
 **Medium/High Complexity** (Fan-out):
-- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `maestro delegate --to gemini --mode analysis`
-- Fan-out B: CLI dimension analysis (parallel gemini per dimension -- code, architecture, testing, dependency, documentation)
-- Fan-out C (High only): Multi-perspective Gemini analysis (security, performance, code-quality, architecture)
+- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `maestro delegate --role explore --mode analysis`
+- Fan-out B: CLI dimension analysis (parallel per dimension -- code, architecture, testing, dependency, documentation) via `--role analyze`
+- Fan-out C (High only): Multi-perspective analysis (security, performance, code-quality, architecture) via `--role analyze`
 - Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings
 
 **Standardize each finding**:

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

@@ -1,7 +1,7 @@
 ---
 name: maestro
 description: Intelligent coordinator — analyze intent, read project state, select chain, execute wave-by-wave via spawn_agents_on_csv. Coordinator only assembles prompts and reads artifacts — never executes skills directly.
-argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--chain <name>]"
+argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--super]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
@@ -19,6 +19,10 @@ Each wave = 1 barrier task (solo) or N parallel non-barrier tasks.
 @~/.maestro/workflows/maestro.codex.md — authoritative `detectTaskType`, `detectNextAction`, `chainMap` (35+ intent patterns, 40+ chain types). Read before executing any step.
 </required_reading>
 
+<deferred_reading>
+- [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
+</deferred_reading>
+
 <context>
 $ARGUMENTS — user intent text, or special flags.
 
@@ -26,7 +30,7 @@ $ARGUMENTS — user intent text, or special flags.
 - `-y, --yes` — Auto mode: skip all prompts; propagate `-y` to each skill
 - `--continue` — Resume latest paused session from last incomplete wave
 - `--dry-run` — Display planned chain without executing
-- `--chain <name>` — Force specific chain (skips intent classification)
+- `--super` — Super mode: deliver production-ready complete software system. Read `maestro-super.md` from deferred_reading, then follow it completely.
 
 **Session state**: `.workflow/.maestro/{session-id}/`
 **Core output**: `tasks.csv` (master) + `wave-{N}-results.csv` (per wave) + `context.md` (report)
@@ -72,7 +76,7 @@ After a barrier skill completes **in its spawned sub-agent**, coordinator reads
 | `maestro-analyze` | `.workflow/.csv-wave/*/context.md`, `state.json` | `gaps`, `phase`, `analysis_dir` |
 | `maestro-plan` | `{artifact_dir}/plan.json`, `{artifact_dir}/.task/TASK-*.json` | `plan_dir`, `task_count`, `wave_count` |
 | `maestro-brainstorm` | `.workflow/.csv-wave/*/.brainstorming/` | `brainstorm_dir`, `features` |
-| `maestro-spec-generate` | `.workflow/.csv-wave/*/specs/` | `spec_session_id` |
+| `maestro-roadmap` | `.workflow/.csv-wave/*/specs/` | `spec_session_id` |
 | `maestro-execute` | `.workflow/.csv-wave/*/results.csv` | `exec_status`, `completed_tasks`, `failed_tasks` |
 
 **Non-barrier skills** (groupable into multi-task waves): `maestro-verify`, `quality-review`, `quality-test`, `quality-debug`, `quality-refactor`, `quality-sync`, `manage-*`
@@ -86,7 +90,7 @@ After each barrier skill completes, read its artifacts and update `state.context
 | `maestro-analyze` | `{artifacts}/context.md` | `analysis_dir`, `gaps` (extracted), `phase` (if unset) |
 | `maestro-plan` | `{artifacts}/plan.json` | `plan_dir`, `task_count`, `wave_count` from plan JSON |
 | `maestro-brainstorm` | `{artifacts}/` | `brainstorm_dir` |
-| `maestro-spec-generate` | `{artifacts}/` | `spec_session_id` (extracted) |
+| `maestro-roadmap` | `{artifacts}/` | `spec_session_id` (extracted) |
 | `maestro-execute` | `{artifacts}/results.csv` | `exec_completed`, `exec_failed` (counted by status) |
 </barrier_skills>
 
@@ -98,8 +102,7 @@ After each barrier skill completes, read its artifacts and update `state.context
 
 **Fresh mode**:
 1. Read `.workflow/state.json` for project context (derive current phase from artifact registry, `workflow_name`)
-2. If `--chain` given, use directly
-3. Otherwise classify intent via keyword heuristics (see chain_map)
+2. Classify intent via keyword heuristics (see chain_map)
 4. No match + not AUTO_YES → one clarifying question via `AskUserQuestion`
 5. Resolve chain's skill list
 6. Create session dir `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/` and write `status.json`:
@@ -153,13 +156,13 @@ After each barrier skill completes, read its artifacts and update `state.context
 
 ### Skill Call Assembly
 
-**Barrier skills**: `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-spec-generate`, `maestro-execute`
+**Barrier skills**: `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-roadmap`, `maestro-execute`
 
 **Auto-yes flag map** (appended when `status.auto_mode` is true):
 
 | Skill | Flag |
 |-------|------|
-| `maestro-analyze`, `maestro-brainstorm`, `maestro-ui-design`, `maestro-spec-generate` | `-y` |
+| `maestro-analyze`, `maestro-brainstorm`, `maestro-ui-design`, `maestro-roadmap` | `-y` |
 | `maestro-plan` | `--auto` |
 | `quality-test` | `--auto-fix` |
 | `quality-retrospective` | `--auto-yes` |
@@ -238,7 +241,7 @@ Accumulated across all waves. Updated after each wave completes.
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Intent unclassifiable after clarification | Default to `feature` chain |
-| E002 | error | `--chain` value not in chain map | List valid chains, abort |
+| E002 | error | Intent unresolvable after retry | List available chains, abort |
 | E003 | error | Wave timeout (max_runtime_seconds) | Mark step `failed`, abort chain |
 | E004 | error | Barrier artifact not found | Retry wave once, then abort |
 | E005 | error | `--continue`: no session found | List sessions, prompt |

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

@@ -329,7 +329,7 @@ spawn_agents_on_csv({
 ## Next Steps
 - Skill: maestro-analyze -- Evaluate feasibility + lock decisions
 - Skill: maestro-plan -- Plan directly if scope is clear
-- Skill: maestro-spec-generate -- Generate full spec package from brainstorm
+- Skill: maestro-roadmap --mode full -- Generate full spec package from brainstorm
 ```
 
 4. Copy artifacts to output `.brainstorming/` directory (phase mode or scratch mode target)

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

@@ -116,11 +116,11 @@ If spec not found, use built-in fallback:
 | `testing` | skill | `quality-test` |
 | `review` | skill | `quality-review` |
 | `brainstorm` | skill | `maestro-brainstorm` |
-| `analysis` | cli | `maestro delegate --to gemini --mode analysis` |
+| `analysis` | cli | `maestro delegate --role analyze --mode analysis` |
 | `verify` | skill | `maestro-verify` |
 | `refactor` | skill | `quality-refactor` |
 | `debug` | skill | `quality-debug` |
-| `spec` | skill | `maestro-spec-generate` |
+| `spec` | skill | `maestro-roadmap --mode full` |
 | `checkpoint` | checkpoint | — |
 
 **Step 2.1** — Load `intent.json`, map each step to executor.
@@ -149,7 +149,7 @@ If spec not found, use built-in fallback:
 | Artifact boundary | Source output_ports: plan, spec, analysis, review-findings |
 | Execution gate | Target executor contains `execute` |
 | Agent spawn | Target type is `agent` |
-| Long-running | Target is maestro-plan, maestro-spec-generate |
+| Long-running | Target is maestro-plan, maestro-roadmap |
 | User-defined | Step had `type_hint: checkpoint` |
 | Post-testing | Source executor contains `test` or `integration-test` |
 

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

@@ -102,7 +102,7 @@ Create in `.workflow/specs/`: `conventions.md` (detected coding conventions), `l
 
 ### Step 10: Completion Report
 
-Display created files and next steps: `$maestro-spec-generate` (full spec), `$maestro-roadmap` (light), `$manage-status`, `$maestro-brainstorm`, `$maestro-quick`.
+Display created files and next steps: `$maestro-roadmap --mode full` (full spec), `$maestro-roadmap` (light), `$manage-status`, `$maestro-brainstorm`, `$maestro-quick`.
 
 </execution>