maestro-flow 0.3.22 → 0.3.24

package/dist/src/index.d.ts

@@ -4,5 +4,9 @@ export { loadConfig, saveConfig } from './config/index.js';
 export { paths } from './config/paths.js';
 export { createManifest, addFile, addDir, saveManifest, findManifest, getAllManifests, deleteManifest, cleanManifestFiles, } from './core/manifest.js';
 export type { Manifest, ManifestEntry } from './core/manifest.js';
+export { migrateAndInject, injectContent, injectDocFile, removeContent, removeAllSections, hasSection, hasAnyMarkers, } from './core/tag-injector.js';
+export type { MigrateResult, MigrateAction, CopyStats } from './core/tag-injector.js';
+export { COMPONENT_DEFS } from './core/component-defs.js';
+export type { ComponentDef } from './core/component-defs.js';
 export type * from './types/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,OAAO,EACP,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClE,mBAAmB,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,OAAO,EACP,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,mBAAmB,kBAAkB,CAAC"}

package/dist/src/index.js

@@ -3,4 +3,6 @@ export { ExtensionLoader } from './core/extension-loader.js';
 export { loadConfig, saveConfig } from './config/index.js';
 export { paths } from './config/paths.js';
 export { createManifest, addFile, addDir, saveManifest, findManifest, getAllManifests, deleteManifest, cleanManifestFiles, } from './core/manifest.js';
+export { migrateAndInject, injectContent, injectDocFile, removeContent, removeAllSections, hasSection, hasAnyMarkers, } from './core/tag-injector.js';
+export { COMPONENT_DEFS } from './core/component-defs.js';
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,OAAO,EACP,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,OAAO,EACP,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,aAAa,GACd,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/cli.ts","../src/index.ts","../src/agents/cli-agent-runner.ts","../src/agents/cli-history-store.ts","../src/agents/dashboard-bridge.ts","../src/agents/parallel-cli-runner.ts","../src/agents/terminal-adapter.ts","../src/agents/terminal-backend.ts","../src/async/delegate-broker-client.ts","../src/async/delegate-broker.ts","../src/async/delegate-control.ts","../src/async/index.ts","../src/brainstorm-visualize/frame.ts","../src/brainstorm-visualize/server.ts","../src/commands/brainstorm-visualize.ts","../src/commands/cli.ts","../src/commands/collab.ts","../src/commands/coordinate.ts","../src/commands/delegate.ts","../src/commands/ext.ts","../src/commands/hooks.ts","../src/commands/install-backend.ts","../src/commands/install.ts","../src/commands/knowhow.ts","../src/commands/launcher.ts","../src/commands/msg.ts","../src/commands/overlay.ts","../src/commands/run.ts","../src/commands/serve.ts","../src/commands/spec.ts","../src/commands/stop.ts","../src/commands/tool.ts","../src/commands/uninstall.ts","../src/commands/update.ts","../src/commands/view.ts","../src/commands/wiki.ts","../src/commands/install-ui/backupconfig.tsx","../src/commands/install-ui/blueprintpreview.logic.ts","../src/commands/install-ui/blueprintpreview.tsx","../src/commands/install-ui/componentgrid.logic.ts","../src/commands/install-ui/componentgrid.tsx","../src/commands/install-ui/configpanel.tsx","../src/commands/install-ui/cyberitem.tsx","../src/commands/install-ui/cyberdeckblueprint.tsx","../src/commands/install-ui/executionview.tsx","../src/commands/install-ui/gradientheader.tsx","../src/commands/install-ui/hooksconfig.tsx","../src/commands/install-ui/installconfirm.tsx","../src/commands/install-ui/installexecution.tsx","../src/commands/install-ui/installflow.tsx","../src/commands/install-ui/installhub.tsx","../src/commands/install-ui/installresult.tsx","../src/commands/install-ui/mcpconfig.tsx","../src/commands/install-ui/resultdashboard.tsx","../src/commands/install-ui/reviewpanel.tsx","../src/commands/install-ui/shortcutfooter.tsx","../src/commands/install-ui/statuslineconfig.tsx","../src/commands/install-ui/stepselector.tsx","../src/commands/install-ui/index.ts","../src/commands/install-ui/types.ts","../src/commands/overlay-ui/overlaylist.tsx","../src/commands/overlay-ui/index.ts","../src/commands/uninstall-ui/uninstallflow.tsx","../src/commands/uninstall-ui/index.ts","../src/config/cli-tools-config.ts","../src/config/index.ts","../src/config/paths.ts","../src/config/template-discovery.ts","../src/coordinator/cli-executor.ts","../src/coordinator/coordinate-broker-adapter.ts","../src/coordinator/expr-evaluator.ts","../src/coordinator/graph-loader.ts","../src/coordinator/graph-types.ts","../src/coordinator/graph-walker.ts","../src/coordinator/index.ts","../src/coordinator/intent-router.ts","../src/coordinator/llm-decider.ts","../src/coordinator/output-parser.ts","../src/coordinator/parallel-executor.ts","../src/coordinator/prompt-assembler.ts","../src/coordinator/step-analyzer.ts","../src/core/component-defs.ts","../src/core/extension-loader.ts","../src/core/manifest.ts","../src/core/tag-injector.ts","../src/core/tool-registry.ts","../src/core/overlay/applier.ts","../src/core/overlay/loader.ts","../src/core/overlay/patcher.ts","../src/core/overlay/section-parser.ts","../src/core/overlay/types.ts","../src/db/connection-pool.ts","../src/db/index.ts","../src/db/tenant-migrator.ts","../src/db/tenant-schema.ts","../src/db/schema/core/index.ts","../src/db/schema/core/organizations.ts","../src/db/schema/core/permissions.ts","../src/db/schema/core/refresh-tokens.ts","../src/db/schema/core/users.ts","../src/hooks/auto-mode.ts","../src/hooks/constants.ts","../src/hooks/context-budget.ts","../src/hooks/context-monitor.ts","../src/hooks/coordinator-tracker.ts","../src/hooks/delegate-monitor.ts","../src/hooks/hook-engine.ts","../src/hooks/hook-manager.ts","../src/hooks/index.ts","../src/hooks/keyword-spec-injector.ts","../src/hooks/preflight-core.ts","../src/hooks/session-context.ts","../src/hooks/skill-context.ts","../src/hooks/spec-bridge.ts","../src/hooks/spec-injector.ts","../src/hooks/statusline.ts","../src/hooks/team-monitor.ts","../src/hooks/workflow-hooks.ts","../src/hooks/workspace.ts","../src/hooks/__tests__/statusline-visual-test.ts","../src/hooks/guards/index.ts","../src/hooks/guards/preflight-guard.ts","../src/hooks/guards/prompt-guard.ts","../src/hooks/guards/spec-validator.ts","../src/hooks/guards/workflow-guard.ts","../src/hooks/plugins/index.ts","../src/hooks/plugins/spec-injection-plugin.ts","../src/hooks/plugins/telemetry-plugin.ts","../src/i18n/detect.ts","../src/i18n/index.ts","../src/i18n/types.ts","../src/i18n/locales/en.ts","../src/i18n/locales/zh.ts","../src/mcp/delegate-channel-relay.ts","../src/mcp/server.ts","../src/middleware/auth.ts","../src/middleware/permission.ts","../src/middleware/rate-limit.ts","../src/middleware/tenant.ts","../src/middleware/validation.ts","../src/migrations/_template.ts","../src/migrations/index.ts","../src/migrations/run.ts","../src/migrations/v1-to-v2.ts","../src/routes/auth.ts","../src/routes/members.ts","../src/routes/organizations.ts","../src/services/auth.service.ts","../src/services/password.service.ts","../src/services/rbac.service.ts","../src/services/token.service.ts","../src/team/phase-orchestrator.ts","../src/team/phase-types.ts","../src/tools/collab-adapter.ts","../src/tools/edit-file.ts","../src/tools/index.ts","../src/tools/merge-validator.ts","../src/tools/namespace-guard.ts","../src/tools/phase-gate-evaluator.ts","../src/tools/read-file.ts","../src/tools/read-many-files.ts","../src/tools/spec-entry-parser.ts","../src/tools/spec-init.ts","../src/tools/spec-keyword-index.ts","../src/tools/spec-loader.ts","../src/tools/store-knowhow.ts","../src/tools/team-activity.ts","../src/tools/team-agents.ts","../src/tools/team-mailbox.ts","../src/tools/team-members.ts","../src/tools/team-msg.ts","../src/tools/team-tasks-mcp.ts","../src/tools/team-tasks.ts","../src/tools/transition-recorder.ts","../src/tools/write-file.ts","../src/types/hono.d.ts","../src/types/index.ts","../src/types/tool-schema.ts","../src/utils/cli-format.ts","../src/utils/file-reader.ts","../src/utils/get-version.ts","../src/utils/jsonl-log.ts","../src/utils/migration-registry.ts","../src/utils/path-validator.ts","../src/utils/state-schema.ts","../shared/agent-types.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/templates/cli/prompts/workflow-skill-conflict-patterns.txt

@@ -77,7 +77,7 @@ MODE: analysis
 CONTEXT: @.workflow/.archives/*/IMPL_PLAN.md @.workflow/.archives/manifest.json
 EXPECTED: Conflict patterns with frequency and resolution
 CONSTRAINTS: analysis=READ-ONLY
-" --to gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
+" --role analyze --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
 ```
 
 **Pattern Grouping**:

package/templates/cli/prompts/workflow-skill-lessons-learned.txt

@@ -73,7 +73,7 @@ MODE: analysis
 CONTEXT: @.workflow/.archives/manifest.json
 EXPECTED: Aggregated lessons with frequency counts
 CONSTRAINTS: analysis=READ-ONLY
-" --to gemini --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
+" --role analyze --mode analysis --rule workflow-skill-aggregation --cd .workflow/.archives
 ```
 
 **Severity Classification**:

package/templates/search-tools.md

@@ -17,7 +17,7 @@ Semantic Search → Grep (pattern) → Glob (files) → CLI (deep analysis)
 | Find by intent/behavior | Semantic search tool (see above) |
 | Known identifier/regex | `Grep` |
 | Find files by name/ext | `Glob` |
-| Complex cross-file reasoning | `maestro delegate --to gemini --mode analysis` |
+| Complex cross-file reasoning | `maestro delegate --role analyze --mode analysis` |
 | Read identified file | `Read` |
 
 ## Fallback

package/templates/workflows/specs/node-catalog.md

@@ -128,7 +128,7 @@ Deliver: [specify expected output format]
 | `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` |
 | `spec` | skill | `maestro-spec-generate` |
 | `refactor` | skill | `quality-refactor` |
 | `integration-test` | skill | `quality-integration-test` |

package/workflows/brainstorm.md

@@ -432,7 +432,7 @@ Execute analysis for ONE specified role with optional interactive context gather
 - Enhancements applied (EP-IDs)
 - Complexity score and review status
 - Next:
-  Skill({ skill: "maestro-spec-generate", args: "--from-brainstorm {sessionId}" })  — Generate full spec package
+  Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {sessionId}" })  — Generate full spec package
   Skill({ skill: "maestro-analyze", args: "{topic}" })   — Evaluate feasibility + lock decisions
   Skill({ skill: "maestro-analyze", args: "{phase} -q" })   — Quick decision extraction only
   Skill({ skill: "maestro-plan", args: "{phase}" })       — Plan directly (if scope is clear)

package/{.claude/CLAUDE.md → workflows/claude-instructions.md}

@@ -1,26 +1,25 @@
-# Maestro
-
-Workflow orchestration CLI with MCP endpoint support and extensible architecture.
-
-- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
-
-## Delegate & CLI
-
-- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
-- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
-
-**Strictly follow the cli-tools.json configuration**
-
-Available CLI endpoints are dynamically defined by the config file
-
-## Code Diagnostics
-
-- **Prefer `mcp__ide__getDiagnostics`** for code error checking over shell-based TypeScript compilation
-
-## 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.
-
+# Maestro
+
+Workflow orchestration CLI with MCP endpoint support and extensible architecture.
+
+- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
+
+## Delegate & CLI
+
+- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
+- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
+
+**Strictly follow the cli-tools.json configuration**
+
+Available CLI endpoints are dynamically defined by the config file
+
+## Code Diagnostics
+
+- **Prefer `mcp__ide__getDiagnostics`** for code error checking over shell-based TypeScript compilation
+
+## 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.

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
 ```