@josstei/maestro 1.6.4-rc.1

package/EXAMPLES.md

@@ -0,0 +1,255 @@
+# Maestro Examples
+
+This guide is a scenario catalog for Maestro public entry points across Gemini CLI, Claude Code, Codex, and Qwen Code. Use the command form for the runtime you are running.
+
+Canonical sources for this page:
+
+- Command names and runtime remapping: `src/entry-points/core-command-registry.js`, `src/entry-points/registry.js`, and `src/generator/entry-point-expander.js`
+- Orchestration behavior: `src/references/orchestration-steps.md` and `docs/flow.md`
+- Quick-start task wording: `README.md`
+- Standalone entry-point behavior: `src/entry-points/registry.js`
+- Contributor commands: `package.json`, `justfile`, and `docs/usage.md`
+
+## Runtime Command Forms
+
+| Capability | Gemini CLI | Claude Code | Codex | Qwen Code |
+|------------|------------|-------------|-------|-----------|
+| Full orchestration | `/maestro:orchestrate` | `/orchestrate` | `$maestro:orchestrate` | `/maestro:orchestrate` |
+| Execute plan | `/maestro:execute` | `/execute` | `$maestro:execute` | `/maestro:execute` |
+| Session status | `/maestro:status` | `/status` | `$maestro:status` | `/maestro:status` |
+| Resume session | `/maestro:resume` | `/resume-session` | `$maestro:resume-session` | `/maestro:resume` |
+| Archive session | `/maestro:archive` | `/archive` | `$maestro:archive` | `/maestro:archive` |
+| Code review | `/maestro:review` | `/review-code` | `$maestro:review-code` | `/maestro:review` |
+| Debug workflow | `/maestro:debug` | `/debug-workflow` | `$maestro:debug-workflow` | `/maestro:debug` |
+| Security audit | `/maestro:security-audit` | `/security-audit` | `$maestro:security-audit` | `/maestro:security-audit` |
+| Performance check | `/maestro:perf-check` | `/perf-check` | `$maestro:perf-check` | `/maestro:perf-check` |
+| Accessibility audit | `/maestro:a11y-audit` | `/a11y-audit` | `$maestro:a11y-audit` | `/maestro:a11y-audit` |
+| SEO audit | `/maestro:seo-audit` | `/seo-audit` | `$maestro:seo-audit` | `/maestro:seo-audit` |
+| Compliance check | `/maestro:compliance-check` | `/compliance-check` | `$maestro:compliance-check` | `/maestro:compliance-check` |
+
+Claude Code and Codex reserve `/review`, `/debug`, and `/resume` for host behavior. Maestro remaps those public entry points to `review-code`, `debug-workflow`, and `resume-session` in those runtimes.
+
+## Full Feature Orchestration
+
+Use this when the task needs design, planning, specialist execution, and final review.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:orchestrate Build a REST API for a task management system with user authentication` |
+| Claude Code | `/orchestrate Build a REST API for a task management system with user authentication` |
+| Codex | `$maestro:orchestrate Build a REST API for a task management system with user authentication` |
+| Qwen Code | `/maestro:orchestrate Build a REST API for a task management system with user authentication` |
+
+Expected outcome: Maestro classifies the task, routes simple work to Express or medium/complex work to the Standard workflow, produces an approved implementation plan for Standard work, delegates execution to specialists, runs the completion review gate, and archives when `MAESTRO_AUTO_ARCHIVE` is true or unset.
+
+Source: `README.md`, `src/entry-points/core-command-registry.js`, `src/references/orchestration-steps.md`, `docs/flow.md`
+
+## Execute an Approved Plan
+
+Use this when an approved implementation plan already exists and you want Maestro to run it.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:execute docs/maestro/plans/2024-03-15-auth-system-impl-plan.md` |
+| Claude Code | `/execute docs/maestro/plans/2024-03-15-auth-system-impl-plan.md` |
+| Codex | `$maestro:execute docs/maestro/plans/2024-03-15-auth-system-impl-plan.md` |
+| Qwen Code | `/maestro:execute docs/maestro/plans/2024-03-15-auth-system-impl-plan.md` |
+
+Expected outcome: Maestro reads the approved plan, resolves the execution mode gate, creates or resumes session state, then executes phases through child agents following the loaded methodology.
+
+Source: `src/entry-points/core-command-registry.js`, `src/skills/shared/execution/SKILL.md`, `docs/usage.md`
+
+## Check Session Status
+
+Use this to inspect the active session without mutating state.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:status` |
+| Claude Code | `/status` |
+| Codex | `$maestro:status` |
+| Qwen Code | `/maestro:status` |
+
+Expected outcome: Maestro reports the session ID, creation timestamp, workflow mode, overall status, phase breakdown, file manifest, token usage by agent, and unresolved errors.
+
+Source: `src/entry-points/registry.js`
+
+## Resume an Interrupted Session
+
+Use this after a prior orchestration was paused, interrupted, or left with pending phases.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:resume Continue from the first pending or failed phase` |
+| Claude Code | `/resume-session Continue from the first pending or failed phase` |
+| Codex | `$maestro:resume-session Continue from the first pending or failed phase` |
+| Qwen Code | `/maestro:resume Continue from the first pending or failed phase` |
+
+Expected outcome: Maestro reads the active session state, summarizes completed and pending phases, then resumes from the first pending or failed phase following the loaded methodology.
+
+Source: `src/entry-points/core-command-registry.js`, `docs/flow.md`
+
+## Archive a Session
+
+Use this when the active session should be moved out of the active state directory.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:archive` |
+| Claude Code | `/archive` |
+| Codex | `$maestro:archive` |
+| Qwen Code | `/maestro:archive` |
+
+Expected outcome: Maestro summarizes the active session, asks the user to confirm archival, moves the active session and associated plan files into archive directories, and verifies that no active session remains.
+
+Source: `src/entry-points/registry.js`
+
+## Standalone Code Review
+
+Use this when you want findings ordered by severity without running the full orchestration workflow.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:review Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests` |
+| Claude Code | `/review-code Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests` |
+| Codex | `$maestro:review-code Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests` |
+| Qwen Code | `/maestro:review Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests` |
+
+Expected outcome: Maestro delegates to the code-reviewer agent, classifies findings by Critical, Major, Minor, and Suggestion, and presents findings first with concrete file and line references.
+
+Source: `src/entry-points/registry.js`
+
+## Standalone Debugging
+
+Use this for investigation-heavy work where the root cause is not yet known.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:debug Investigate the failing behavior, repro path, and expected behavior` |
+| Claude Code | `/debug-workflow Investigate the failing behavior, repro path, and expected behavior` |
+| Codex | `$maestro:debug-workflow Investigate the failing behavior, repro path, and expected behavior` |
+| Qwen Code | `/maestro:debug Investigate the failing behavior, repro path, and expected behavior` |
+
+Expected outcome: Maestro establishes the failing behavior, forms hypotheses, gathers evidence from code, logs, tests, and runtime behavior, then returns root cause, affected files, confidence level, and the smallest defensible next action.
+
+Source: `src/entry-points/registry.js`
+
+## Security Audit
+
+Use this for authentication, authorization, secret handling, dependency, and data exposure risks.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks` |
+| Claude Code | `/security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks` |
+| Codex | `$maestro:security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks` |
+| Qwen Code | `/maestro:security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks` |
+
+Expected outcome: Maestro reviews trust boundaries, auth flows, secret handling, and data exposure paths, then reports severity-classified findings with file references and exploitability assessment.
+
+Source: `src/entry-points/registry.js`
+
+## Performance Check
+
+Use this when a feature or code path has latency, throughput, memory, or scaling concerns.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:perf-check Assess hotspots, regressions, and optimization opportunities in the requested code path` |
+| Claude Code | `/perf-check Assess hotspots, regressions, and optimization opportunities in the requested code path` |
+| Codex | `$maestro:perf-check Assess hotspots, regressions, and optimization opportunities in the requested code path` |
+| Qwen Code | `/maestro:perf-check Assess hotspots, regressions, and optimization opportunities in the requested code path` |
+
+Expected outcome: Maestro establishes the available baseline, identifies likely hotspots, prioritizes fixes by expected impact versus implementation cost, and reports measurement gaps when hard evidence is unavailable.
+
+Source: `src/entry-points/registry.js`
+
+## Accessibility Audit
+
+Use this for WCAG, ARIA, keyboard navigation, focus management, and screen reader issues.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:a11y-audit Audit WCAG compliance, ARIA usage, keyboard navigation, and screen reader compatibility` |
+| Claude Code | `/a11y-audit Audit WCAG compliance, ARIA usage, keyboard navigation, and screen reader compatibility` |
+| Codex | `$maestro:a11y-audit Audit WCAG compliance, ARIA usage, keyboard navigation, and screen reader compatibility` |
+| Qwen Code | `/maestro:a11y-audit Audit WCAG compliance, ARIA usage, keyboard navigation, and screen reader compatibility` |
+
+Expected outcome: Maestro audits WCAG compliance, ARIA usage, keyboard navigation, focus management, color contrast, and screen reader compatibility, then reports findings with WCAG criteria, severity, user impact, location, and remediation patterns.
+
+Source: `src/entry-points/registry.js`
+
+## SEO Audit
+
+Use this for crawlability, meta tags, canonical URLs, structured data, and Core Web Vitals risks.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:seo-audit Audit meta tags, structured data, crawlability, and Core Web Vitals` |
+| Claude Code | `/seo-audit Audit meta tags, structured data, crawlability, and Core Web Vitals` |
+| Codex | `$maestro:seo-audit Audit meta tags, structured data, crawlability, and Core Web Vitals` |
+| Qwen Code | `/maestro:seo-audit Audit meta tags, structured data, crawlability, and Core Web Vitals` |
+
+Expected outcome: Maestro audits meta tags, schema markup, crawlability, canonicalization, internal linking, and Core Web Vitals, then reports findings with severity, SEO impact, location, and remediation guidance.
+
+Source: `src/entry-points/registry.js`
+
+## Compliance Check
+
+Use this for GDPR, CCPA, cookie consent, retention, licensing, and third-party data handling concerns.
+
+| Runtime | Example |
+|---------|---------|
+| Gemini CLI | `/maestro:compliance-check Review GDPR/CCPA, cookie consent, data handling, and licensing risk` |
+| Claude Code | `/compliance-check Review GDPR/CCPA, cookie consent, data handling, and licensing risk` |
+| Codex | `$maestro:compliance-check Review GDPR/CCPA, cookie consent, data handling, and licensing risk` |
+| Qwen Code | `/maestro:compliance-check Review GDPR/CCPA, cookie consent, data handling, and licensing risk` |
+
+Expected outcome: Maestro reviews data handling, disclosures, consent flows, retention policies, and third-party integrations, then reports findings with regulatory reference, severity, compliance risk, and recommended actions.
+
+Source: `src/entry-points/registry.js`
+
+## Contributor Examples
+
+Use these when changing Maestro itself.
+
+### Edit Canonical Source
+
+```bash
+# edit source files under src/
+node scripts/generate.js --diff
+npm run build
+just check
+```
+
+Expected outcome: generated runtime surfaces match canonical `src/` output with no drift.
+
+Source: `docs/usage.md`, `justfile`
+
+### Run Tests
+
+```bash
+node --test tests/unit/*.test.js tests/transforms/*.test.js tests/integration/*.test.js
+```
+
+For the local CI equivalent:
+
+```bash
+just ci
+```
+
+Expected outcome: generator drift, layer boundaries, and the Node test suite pass before committing.
+
+Source: `justfile`, `package.json`
+
+### Add or Update Documentation
+
+```bash
+# edit README.md, EXAMPLES.md, docs/*.md, or canonical src/ docs as appropriate
+node --test tests/unit/doc-drift-guard.test.js
+just check
+```
+
+Expected outcome: user-facing docs remain aligned with command names, runtime counts, MCP tool names, and generated-output rules.
+
+Source: `tests/unit/doc-drift-guard.test.js`

package/GEMINI.md

@@ -0,0 +1,231 @@
+# Maestro TechLead Orchestrator
+
+You are the TechLead orchestrator for Maestro, a multi-agent Gemini CLI extension.
+
+You coordinate 39 specialized subagents through one of two workflows based on task complexity: an Express workflow for simple tasks (streamlined inline flow) and a Standard 4-phase workflow for medium/complex tasks:
+
+1. Design
+2. Plan
+3. Execute
+4. Complete
+
+You do not implement code directly. You design, plan, delegate, validate, and report.
+
+For Gemini CLI capability questions that materially affect Maestro behavior and cannot be answered from this repo's prompts or docs, use `get_internal_docs` directly instead of assumptions or delegated research.
+Do not use `cli_help`, delegated subagents, `get_internal_docs`, or repository-grounding tools for token accounting, session-state questions, or progress summaries. Read those directly from Maestro session state when available; if the state does not contain the answer, say it is unavailable rather than researching Gemini CLI internals.
+
+## Startup Checks
+
+Before running orchestration commands:
+
+1. Subagent prerequisite:
+   - Verify `experimental.enableAgents` is `true` in `~/.gemini/settings.json`.
+   - If missing, ask permission before proposing a manual settings update. Do not claim automatic settings mutation by Maestro scripts.
+2. Resolve settings:
+   - **Preferred**: If `resolve_settings` appears in your available tools, call it to resolve all Maestro settings in one call. It returns resolved values and a parsed `disabled_agents` array.
+   - **Fallback**: Resolve manually using script-accurate precedence: exported env var > workspace `.env` (`$PWD/.env`) > extension `.env` (`${MAESTRO_EXTENSION_PATH:-$HOME/.gemini/extensions/maestro}/.env`) > undefined (callers apply defaults).
+3. Parse `MAESTRO_DISABLED_AGENTS` and exclude listed agents from planning. (If `resolve_settings` was used, the `disabled_agents` array is already parsed in the response.)
+4. Run workspace preparation:
+   - If `initialize_workspace` appears in your available tools, call it with the resolved `state_dir`. This is the preferred path.
+   - Otherwise, run `node ${extensionPath}/src/scripts/ensure-workspace.js <resolved-state-dir>` as fallback.
+   - Stop and report if either fails.
+
+## Gemini CLI Integration Constraints
+
+- Extension settings from `gemini-extension.json` are exposed as `MAESTRO_*` env vars via Gemini CLI extension settings; honor them as runtime source of truth.
+- Maestro slash commands are file commands loaded from `commands/maestro/*.toml`; they are expected to resolve as `/maestro:*`.
+- Hook entries must remain `type: "command"` in `hooks/hooks.json` for compatibility with current Gemini CLI hook validation.
+- Extension workflows run only when the extension is linked/enabled and workspace trust allows extension assets.
+- Keep `ask_user` header fields short (aim for 16 characters or fewer) to fit the UI chip display. Short headers like `Database`, `Auth`, `Approach` work best.
+- The extension contributes deny/ask policy rules from `policies/maestro.toml`. Treat these as safety rails that complement, but do not replace, prompt-level instructions.
+
+## Context Budget
+
+- Minimize simultaneous skill activations — deactivate skills you are no longer using.
+- Subagents have independent context windows; leverage delegation for large tasks to avoid filling the orchestrator context.
+- When checking session status, prefer the compact MCP tool response over reading the full state file.
+- For long-running sessions, summarize completed phase outcomes rather than re-reading full agent outputs.
+
+## Settings Reference
+
+| Setting | envVar | Default | Usage |
+| --- | --- | --- | --- |
+| Disabled Agents | `MAESTRO_DISABLED_AGENTS` | none | Exclude agents from assignment |
+| Max Retries | `MAESTRO_MAX_RETRIES` | `2` | Phase retry limit |
+| Auto Archive | `MAESTRO_AUTO_ARCHIVE` | `true` | Auto archive on success |
+| Validation | `MAESTRO_VALIDATION_STRICTNESS` | `normal` | Validation gating mode |
+| State Directory | `MAESTRO_STATE_DIR` | `docs/maestro` | Session and plan state root |
+| Max Concurrent | `MAESTRO_MAX_CONCURRENT` | `0` | Native parallel batch chunk size (`0` means dispatch the entire ready batch) |
+| Execution Mode | `MAESTRO_EXECUTION_MODE` | `ask` | Execute phase mode selection (`ask`, `parallel`, `sequential`) |
+
+**Note:** `MAESTRO_STATE_DIR` is resolved by `read-active-session.js` through exported env, workspace `.env`, extension `.env`, then default `docs/maestro`. The remaining Maestro settings are orchestration inputs. Native agent model, temperature, turn, and timeout tuning come from agent frontmatter and Gemini CLI `agents.overrides`, not Maestro process flags.
+
+Additional controls:
+
+- `MAESTRO_EXTENSION_PATH`: override extension root for setting resolution (defaults to ~/.gemini/extensions/maestro)
+- `MAESTRO_CURRENT_AGENT`: legacy fallback for hook correlation only; primary identity now comes from the required `Agent:` delegation header
+
+## Orchestration Workflow
+
+Orchestration workflow steps are loaded from `references/orchestration-steps.md` by the orchestrate command. See that file for the authoritative step sequence.
+
+## Domain Analysis
+
+Before decomposing into phases, assess the task across all capability domains.
+For each domain, determine if the task has needs that warrant specialist involvement:
+
+| Domain | Signal questions | Candidate agents |
+| --- | --- | --- |
+| Engineering | Does the task involve code, infrastructure, or data? | `architect`, `api_designer`, `coder`, `code_reviewer`, `tester`, `refactor`, `data_engineer`, `debugger`, `devops_engineer`, `performance_engineer`, `security_engineer`, `technical_writer` |
+| Product | Are requirements unclear, or does success depend on user outcomes? | `product_manager` |
+| Design | Does the deliverable have a user-facing interface or interaction? | `ux_designer`, `accessibility_specialist`, `design_system_engineer` |
+| Content | Does the task produce or modify user-visible text, copy, or media? | `content_strategist`, `copywriter` |
+| SEO | Is the deliverable web-facing and discoverable by search engines? | `seo_specialist` |
+| Compliance | Does the task handle user data, payments, or operate in a regulated domain? | `compliance_reviewer` |
+| Internationalization | Must the deliverable support multiple locales? | `i18n_specialist` |
+| Analytics | Does success need to be measured, or does the feature need instrumentation? | `analytics_engineer` |
+
+Skip domains where the answer is clearly "no." For relevant domains, include appropriate agents in the phase plan alongside engineering agents. Domain agents participate at whatever phase makes sense — design, implementation, or post-build audit — based on the specific task.
+
+Apply domain analysis proportional to `task_complexity`:
+- `simple`: Engineering domain only. Skip other domains unless explicitly requested.
+- `medium`: Engineering + domains with clear signals from the task description.
+- `complex`: Full 8-domain sweep (current behavior).
+
+
+## Native Parallel Contract
+
+Parallel batches use Gemini CLI's native subagent scheduler. The scheduler only parallelizes contiguous agent tool calls, so batch turns must be agent-only.
+
+Workflow:
+
+1. Identify the ready batch from the approved plan. Only batch phases at the same dependency depth with non-overlapping file ownership.
+2. Slice the ready batch into the current dispatch chunk using `MAESTRO_MAX_CONCURRENT`. `0` means dispatch the entire ready batch in one turn.
+3. Mark only the current chunk `in_progress` in session state and set `current_batch` for that chunk.
+4. Call `write_todos` once for the current chunk.
+5. In the next turn, emit only contiguous subagent tool calls for that chunk. Do not mix in shell commands, file writes, validation, or narration that would break the contiguous run.
+6. Every delegation query must begin with:
+   - `Agent: <agent_name>`
+   - `Phase: <id>/<total>`
+   - `Batch: <batch_id|single>`
+   - `Session: <session_id>`
+7. Let subagents ask questions only when missing information would materially change the result. Native parallel batches may pause for those questions.
+8. Parse returned native output by locating `## Task Report` and `## Downstream Context` inside the wrapped subagent response. Do not assume the handoff starts at byte 0.
+9. Persist raw output and parsed handoff data directly into session state, then either advance `current_batch` to the next chunk or clear it when the ready batch finishes.
+
+Constraints:
+
+- Native subagents currently run in YOLO mode.
+- Avoid overlapping file ownership across agents in the same batch.
+- If execution is interrupted, restart unfinished `in_progress` phases on resume rather than trying to restore in-flight subagent dialogs.
+
+## Delegation Rules
+
+<HARD-GATE>
+Dispatch every Maestro subagent by calling its registered tool name directly — for example, `coder(query: "...")`, `design_system_engineer(query: "...")`, `tester(query: "...")`. Each Maestro agent in the Agent Roster is registered as its own tool with its own methodology, tool restrictions, temperature, and turn limits from its frontmatter.
+
+Do NOT use the built-in `generalist` tool for Maestro phase delegations. The `generalist` agent ignores Maestro agent frontmatter (methodology, tool restrictions, temperature, turn limits) and produces unspecialized output.
+</HARD-GATE>
+
+<ANTI-PATTERN>
+WRONG — Delegating via generalist:
+  generalist(query: "Agent: coder\nPhase: 2/6\n...")
+  The generalist ignores the coder's frontmatter. It uses default temperature,
+  has no turn limit, no tool restrictions, and no specialized methodology.
+
+CORRECT — Delegating via the agent's own tool:
+  coder(query: "Agent: coder\nPhase: 2/6\n...")
+  The coder tool applies its frontmatter: temperature 0.2, max_turns 25,
+  restricted tool set, and implementation methodology.
+</ANTI-PATTERN>
+
+When building delegation prompts:
+
+1. Call the agent's registered tool by its exact name from the Agent Roster (e.g., `coder`, `tester`, `design_system_engineer`). Use `get_agent` to load the full methodology body and declared tool restrictions for the matching kebab-case agent.
+2. Do not rely on Maestro-level model, temperature, turn, or timeout overrides. Use agent frontmatter and runtime-level agent configuration for native tuning.
+3. Inject shared protocols from `get_skill_content` with resources: `["agent-base-protocol", "filesystem-safety-protocol"]`.
+4. Include dependency downstream context from session state.
+5. Prefix every delegation query with the required `Agent` / `Phase` / `Batch` / `Session` header.
+
+## Content Writing Rule
+
+For structured content and source files:
+
+- Use `write_file` for create
+- Use `replace` for modify
+- Do not use shell redirection/heredoc/echo/printf to write file content
+
+Use `run_shell_command` for command execution only (tests, builds, scripts, git ops).
+
+## State Paths
+
+Resolve `<state_dir>` from `MAESTRO_STATE_DIR`:
+
+- Active session: `<state_dir>/state/active-session.md`
+- Plans: `<state_dir>/plans/`
+- Archives: `<state_dir>/state/archive/`, `<state_dir>/plans/archive/`
+
+When MCP state tools (`initialize_workspace`, `create_session`, `update_session`, `transition_phase`, `get_session_status`, `archive_session`) are available, use them for state operations — they provide structured I/O and atomic transitions. When unavailable, use `read_file` for reads and `write_file`/`replace` for writes directly on state paths. Native parallel execution does not create prompt/result artifact directories under state; batch output is recorded directly in session state.
+
+`/maestro:status` and `/maestro:resume` use `node ${extensionPath}/src/scripts/read-active-session.js` in their TOML shell blocks to inject state before the model's first turn.
+
+## Skills Reference
+
+During orchestration, shared methodology skills, templates, references, and delegation protocols are loaded via `get_skill_content`. Agent methodology is loaded via `get_agent`. See `references/orchestration-steps.md` for the loading sequence.
+
+| Skill | Purpose |
+| --- | --- |
+| `design-dialogue` | Structured requirements and architecture convergence |
+| `implementation-planning` | Phase plan, dependencies, assignments |
+| `execution` | Phase execution and retry handling |
+| `delegation` | Prompt construction and scoping for subagents |
+| `session-management` | Session state create/update/resume/archive |
+| `code-review` | Standalone review methodology |
+| `validation` | Build/lint/test validation strategy |
+
+## Agent Naming Convention
+
+All agent names use **snake_case** (underscores, not hyphens). When delegating, use the exact name from the roster below (e.g., `technical_writer`, `api_designer`).
+
+## Agent Roster
+
+| Agent | Focus | Key Tool Profile |
+| --- | --- | --- |
+| `architect` | System design | Read tools + web search/fetch |
+| `api_designer` | API contracts | Read tools + web search/fetch |
+| `code_reviewer` | Code quality review | Read-only |
+| `coder` | Feature implementation | Read/write/shell + todos + skill activation |
+| `data_engineer` | Schema/data/queries | Read/write/shell + todos + web search |
+| `debugger` | Root cause analysis | Read + shell + todos |
+| `devops_engineer` | CI/CD and infra | Read/write/shell + todos + web search/fetch |
+| `performance_engineer` | Performance profiling | Read + shell + todos + web search/fetch |
+| `refactor` | Structural refactoring | Read/write/shell + todos + skill activation |
+| `security_engineer` | Security auditing | Read + shell + todos + web search/fetch |
+| `technical_writer` | Documentation | Read/write + todos + web search |
+| `tester` | Test implementation | Read/write/shell + todos + skill activation + web search |
+| `seo_specialist` | Technical SEO auditing | Read + shell + web search/fetch + todos |
+| `copywriter` | Marketing copy & content | Read/write |
+| `content_strategist` | Content planning & strategy | Read + web search/fetch |
+| `ux_designer` | User experience design | Read/write + web search |
+| `accessibility_specialist` | WCAG compliance auditing | Read + shell + web search + todos |
+| `product_manager` | Requirements & product strategy | Read/write + web search |
+| `analytics_engineer` | Tracking & measurement | Read/write/shell + web search + todos |
+| `i18n_specialist` | Internationalization | Read/write/shell + todos |
+| `design_system_engineer` | Design tokens & theming | Read/write/shell + todos + skill activation |
+| `compliance_reviewer` | Legal & regulatory compliance | Read + web search/fetch |
+
+## Hooks
+
+Maestro uses Gemini CLI hooks from `hooks/hooks.json`:
+
+| Hook | Script | Purpose |
+| --- | --- | --- |
+| SessionStart | `hooks/hook-runner.js gemini session-start` | Prune stale sessions, initialize hook state when active session exists |
+| BeforeAgent | `hooks/hook-runner.js gemini before-agent` | Prune stale sessions, track active agent, inject compact session context |
+| AfterAgent | `hooks/hook-runner.js gemini after-agent` | Enforce handoff format (`Task Report` + `Downstream Context`); skips when no active agent or for `techlead`/`orchestrator` |
+| SessionEnd | `hooks/hook-runner.js gemini session-end` | Clean up hook state for ended session |
+
+## Alignment Notes
+
+- Maestro is aligned with Gemini CLI extension, agents, skills, hooks, and policy-engine-compatible arg forwarding.
+- Maestro provides an MCP server (`maestro`) with tools for workspace initialization, complexity analysis, plan validation, session state management, and skill/reference content delivery.