@josstei/maestro 1.6.4-rc.1

package/docs/flow.md

@@ -0,0 +1,255 @@
+# Maestro Orchestration Flow
+
+The orchestration workflow is defined by 41 steps (numbered 0 through 40) in `src/references/orchestration-steps.md`. Two modes exist: **Standard** (medium/complex tasks) and **Express** (simple tasks).
+
+## Standard Workflow
+
+```
+┌─────────────────────────────────────────────────┐
+│                   STARTUP                       │
+│  Turn 1: get_runtime_context → resolve_settings │
+│          → initialize_workspace → check session │
+│          → assess_task_complexity                │
+│          → parse MAESTRO_DISABLED_AGENTS         │
+│          → STOP (no output in Turn 1)           │
+└───────────────────────┬─────────────────────────┘
+                        ▼
+┌─────────────────────────────────────────────────┐
+│               CLASSIFICATION                    │
+│  Turn 2: Load architecture reference            │
+│          Classify: simple / medium / complex     │
+│          Route: simple → Express, else → Design │
+└───────────────────────┬─────────────────────────┘
+                        ▼
+┌─────────────────────────────────────────────────┐
+│            PHASE 1: DESIGN                      │
+│  Load design-dialogue skill                     │
+│  Structured conversation (depth: quick/std/deep)│
+│  Present sections one-at-a-time for approval    │
+│  Write design document to state_dir/plans/      │
+└───────────────────────┬─────────────────────────┘
+                        ▼
+┌─────────────────────────────────────────────────┐
+│            PHASE 2: PLANNING                    │
+│  Load implementation-planning skill             │
+│  Generate phased plan with dependencies         │
+│  HARD-GATE: validate_plan before presenting     │
+│  User approval: Approve / Revise / Abort        │
+│  Write plan to state_dir/plans/                 │
+└───────────────────────┬─────────────────────────┘
+                        ▼
+┌─────────────────────────────────────────────────┐
+│            PHASE 3: EXECUTION                   │
+│  Load execution + delegation skills             │
+│  Execution Mode Gate: parallel / sequential     │
+│  Create session via MCP                         │
+│  For each phase:                                │
+│    → get_agent for methodology                  │
+│    → Delegate with protocols + context chain    │
+│    → Parse Task Report + Downstream Context     │
+│    → transition_phase (HARD-GATE per phase)     │
+└───────────────────────┬─────────────────────────┘
+                        ▼
+┌─────────────────────────────────────────────────┐
+│            PHASE 4: COMPLETION                  │
+│  Load code-review skill                         │
+│  Delegate to code-reviewer (if non-doc changes) │
+│  HARD-GATE: Block on Critical/Major findings    │
+│  Archive session (if MAESTRO_AUTO_ARCHIVE)      │
+│  Present final summary                          │
+└─────────────────────────────────────────────────┘
+```
+
+## Express Workflow
+
+For simple tasks (1 phase, 1 agent):
+
+```
+CLASSIFICATION → simple
+  │
+  ▼
+Ask 1-2 clarifying questions
+  │
+  ▼
+Present structured brief → User approval (HARD-GATE)
+  │
+  ▼
+Create session (workflow_mode="express", 1 phase)
+  │
+  ▼
+Delegate to single agent
+  │
+  ▼
+Parse Task Report → transition_phase (HARD-GATE)
+  │
+  ▼
+Code review → HARD-GATE on Critical/Major
+  │
+  ▼
+Archive session → Present summary
+```
+
+## Execution Modes
+
+### Sequential
+
+Phases execute one at a time in dependency order:
+
+1. Verify blocked_by dependencies completed
+2. Mark phase in_progress
+3. Delegate to assigned agent
+4. Parse handoff → update state
+5. Mark completed → advance to next
+
+### Parallel (Native)
+
+Phases at the same dependency depth execute concurrently:
+
+1. Compute dependency DAG → identify parallel batches
+2. For each batch:
+   - Verify all blocking phases complete
+   - Slice by `MAESTRO_MAX_CONCURRENT` (0 = all)
+   - Emit contiguous agent calls in single turn
+   - Runtime parallelizes the calls
+3. All batch members must complete before next batch
+
+### Execution Mode Gate
+
+Determines parallel vs. sequential:
+
+1. If `MAESTRO_EXECUTION_MODE=parallel/sequential` → use directly
+2. If `MAESTRO_EXECUTION_MODE=ask` (default):
+   - If ≤1 parallel-eligible phase → auto-select sequential
+   - If >50% parallel → recommend parallel
+   - Otherwise → recommend sequential
+   - Prompt user with recommendation
+
+## Delegation Flow
+
+```
+Orchestrator                          Agent
+    │                                   │
+    ├── get_agent("coder") ──────────►  │
+    │◄── methodology + tools ──────────┤
+    │                                   │
+    ├── Construct prompt:               │
+    │   - agent-base-protocol           │
+    │   - filesystem-safety-protocol    │
+    │   - Task description              │
+    │   - Progress context              │
+    │   - File lists (create/modify)    │
+    │   - Downstream consumer info      │
+    │   - Tool restrictions             │
+    │   - Validation commands           │
+    │                                   │
+    ├── Delegate ──────────────────────►│
+    │                                   │
+    │                                   ├── Step 1: Anchor to project
+    │                                   ├── Step 2: Scope verification
+    │                                   ├── Step 3: Convention extraction
+    │                                   ├── ... (task work) ...
+    │                                   ├── Run validation
+    │                                   │
+    │◄── ## Task Report ───────────────┤
+    │◄── ## Downstream Context ────────┤
+    │                                   │
+    ├── Parse handoff                   │
+    ├── transition_phase()              │
+    └── Feed context to next phase      │
+```
+
+## Context Chain
+
+Information flows between phases via the Downstream Context:
+
+```
+Phase 1 (architect)
+  └── Downstream Context:
+      - Key Interfaces: UserService interface at src/services/user.ts
+      - Patterns: Repository pattern for data access
+      - Integration Points: /api/users endpoint
+      │
+      ▼
+Phase 2 (coder) receives:
+  - Phase 1's downstream context in prompt
+  - Files created by Phase 1
+  - Accumulated patterns
+```
+
+Each agent's handoff report contains:
+
+**Task Report**: status, files created/modified/deleted, decisions, validation result, errors, scope deviations
+
+**Downstream Context**: key interfaces introduced, patterns established, integration points, assumptions, warnings
+
+## Session Lifecycle
+
+```
+                ┌──────────┐
+                │  (none)  │
+                └────┬─────┘
+                     │ create_session
+                     ▼
+                ┌──────────┐
+         ┌──────│ active   │──────┐
+         │      └────┬─────┘      │
+         │           │            │
+    resume│    transition_phase   │ archive
+         │           │            │
+         │      ┌────▼─────┐      │
+         └──────│ active   │──────┤
+                └──────────┘      │
+                                  ▼
+                           ┌──────────┐
+                           │ archived │
+                           └──────────┘
+```
+
+## Hard Gates
+
+Non-negotiable checkpoints that block progression:
+
+| Gate | Location | Condition |
+|------|----------|-----------|
+| Tech recommendations | Step 11 | Must recommend vanilla HTML/CSS/JS for static delivery unless framework explicitly required |
+| Design sections | Step 12 | Each section presented individually and approved |
+| validate_plan | Step 16 | Plan must pass validation before user sees it |
+| Execution mode | Step 19 | Must present only Parallel and Sequential options |
+| Agent dispatch | Step 23 | Must dispatch by agent's registered tool directly |
+| transition_phase | Step 25 | Must be called individually for EVERY completed phase |
+| Code review | Step 28 | Critical/Major findings block completion |
+| Express 1-phase | Step 31 | Express sessions must have exactly one phase |
+| Express questions | Step 32 | Each question must use user prompt tool |
+| Express brief | Step 33 | Must present as plain text + separate approval prompt |
+| Express agent | Step 36 | Must delegate by specific agent tool, not generalist |
+| Express transition_phase | Step 37 | Must call transition_phase after implementing agent returns |
+| Express review | Step 38 | Re-delegate on Critical/Major findings (1 retry) |
+
+## Error Handling
+
+- Max retries per phase: `MAESTRO_MAX_RETRIES` (default: 2)
+- First failure: analyze, adjust context, retry automatically
+- Limit exceeded: mark failed, escalate to user
+- File conflicts: stop immediately, ask user
+- Timeout/termination: record partial output, retry or escalate
+
+## Recovery
+
+When flow breaks:
+- Moved too fast → return to most recent unanswered gate
+- User asks for implementation before approval → remind them Maestro requires approval first
+- User asks to skip execution-mode → remind them it's required
+- Answer invalidates prior choice → restate assumption, re-run gate
+- Delegation collapses → return to execution setup or re-scope
+
+## Resume
+
+When resuming an interrupted session:
+1. Read active session state
+2. Identify: last completed phase, current phase, failed phases
+3. Check for unresolved errors
+4. Present summary to user
+5. Handle errors: retry/skip/abort/adjust
+6. Continue from pending/failed phase
+
+Express resume follows the same pattern but maps to Express steps based on phase status.

package/docs/maestro-cheatsheet.md

@@ -0,0 +1,199 @@
+# Maestro Cheatsheet
+
+This document summarizes the minimum commands and concepts for using Maestro across the supported runtimes.
+
+## 1. Runtime Matrix
+
+| Runtime | Install | Entry Point |
+|---|---|---|
+| Gemini CLI | `gemini extensions install https://github.com/josstei/maestro-orchestrate` | `/maestro:*` |
+| Claude Code | `claude plugin marketplace add josstei/maestro-orchestrate` + `claude plugin install maestro@maestro-orchestrator --scope user` | `/orchestrate`, `/review-code`, `/status`, ... |
+| Codex CLI | `codex plugin marketplace add josstei/maestro-orchestrate`, then install Maestro inside Codex via `/plugins` | `$maestro:*` |
+| Qwen Code | `qwen extensions install https://github.com/josstei/maestro-orchestrate` | `/maestro:*` |
+
+## 2. Most Common Commands
+
+| Capability | Gemini CLI | Claude Code | Codex CLI | Qwen Code |
+|---|---|---|---|---|
+| Start the full workflow | `/maestro:orchestrate <task>` | `/orchestrate <task>` | `$maestro:orchestrate <task>` | `/maestro:orchestrate <task>` |
+| Run an existing plan | `/maestro:execute` | `/execute` | `$maestro:execute` | `/maestro:execute` |
+| Check status | `/maestro:status` | `/status` | `$maestro:status` | `/maestro:status` |
+| Resume a session | `/maestro:resume` | `/resume-session` | `$maestro:resume-session` | `/maestro:resume` |
+| Archive | `/maestro:archive` | `/archive` | `$maestro:archive` | `/maestro:archive` |
+| Code review | `/maestro:review` | `/review-code` | `$maestro:review-code` | `/maestro:review` |
+| Debug | `/maestro:debug` | `/debug-workflow` | `$maestro:debug-workflow` | `/maestro:debug` |
+| Security audit | `/maestro:security-audit` | `/security-audit` | `$maestro:security-audit` | `/maestro:security-audit` |
+| Perf check | `/maestro:perf-check` | `/perf-check` | `$maestro:perf-check` | `/maestro:perf-check` |
+| SEO audit | `/maestro:seo-audit` | `/seo-audit` | `$maestro:seo-audit` | `/maestro:seo-audit` |
+| A11y audit | `/maestro:a11y-audit` | `/a11y-audit` | `$maestro:a11y-audit` | `/maestro:a11y-audit` |
+| Compliance check | `/maestro:compliance-check` | `/compliance-check` | `$maestro:compliance-check` | `/maestro:compliance-check` |
+
+## 3. Minimal Usage Examples
+
+### Start a new task
+
+```text
+/maestro:orchestrate Build a REST API with authentication
+```
+
+Claude Code:
+
+```text
+/orchestrate Build a REST API with authentication
+```
+
+Codex CLI:
+
+```text
+$maestro:orchestrate Build a REST API with authentication
+```
+
+### Check the current session
+
+```text
+/maestro:status
+```
+
+Claude Code:
+
+```text
+/status
+```
+
+Codex CLI:
+
+```text
+$maestro:status
+```
+
+## 4. Workflow Mental Model
+
+Maestro first classifies task complexity, then follows one of two modes:
+
+### Express
+
+Best for simple tasks:
+
+1. Ask 1–2 clarifying questions
+2. Produce a brief
+3. Run a single specialist
+4. Code review
+5. Archive the session
+
+### Standard
+
+Best for medium to complex tasks:
+
+1. **Design**
+2. **Plan**
+3. **Execute**
+4. **Complete**
+
+Key gates:
+
+- design approval
+- `validate_plan`
+- execution mode gate
+- `transition_phase`
+- code review blocks unresolved Critical / Major findings
+
+## 5. Session State Location
+
+Maestro stores session state inside the workspace:
+
+```text
+docs/maestro/
+```
+
+Common paths:
+
+- `docs/maestro/state/active-session.md`
+- `docs/maestro/plans/`
+- `docs/maestro/state/archive/`
+- `docs/maestro/plans/archive/`
+
+## 6. Runtime Differences at a Glance
+
+### Gemini CLI
+
+- Command entry point: `/maestro:*`
+- Supports hooks
+- Uses TOML policy files
+- Agent naming: `snake_case`
+
+### Claude Code
+
+- Command entry point: `/orchestrate`, `/review-code`, `/status`, ...
+- Supports hooks
+- Uses `PreToolUse` matchers and policy enforcement
+- Agent naming: `kebab-case`
+
+### Codex CLI
+
+- Command entry point: `$maestro:*`
+- **No runtime hooks**
+- Uses plugin skills + `spawn_agent`
+- Built-in `/review`, `/debug`, and `/resume` conflict with the host, so Maestro uses:
+  - `$maestro:review-code`
+  - `$maestro:debug-workflow`
+  - `$maestro:resume-session`
+
+### Qwen Code
+
+- Command entry point: `/maestro:*`
+- Same command surface as Gemini CLI
+
+## 7. Hook Reference
+
+### Gemini CLI
+
+- `SessionStart`
+- `BeforeAgent`
+- `AfterAgent`
+- `SessionEnd`
+
+### Claude Code
+
+- `SessionStart`
+- `PreToolUse` + `Agent`
+- `PreToolUse` + `Bash`
+- `SessionEnd`
+
+### Codex CLI
+
+- No runtime hooks
+
+## 8. Common Notes
+
+### Codex CLI
+
+- Use `$maestro:...`, not `/maestro:...`
+- Because `review/debug/resume` names conflict with built-in host commands, use:
+  - `$maestro:review-code`
+  - `$maestro:debug-workflow`
+  - `$maestro:resume-session`
+
+### Gemini / Qwen
+
+- Experimental subagents must be enabled
+- The config should include:
+
+```json
+{
+  "experimental": {
+    "enableAgents": true
+  }
+}
+```
+
+## 9. Suggested Reading Order
+
+If you want to go deeper:
+
+1. `README.md`
+2. `EXAMPLES.md`
+3. `docs/flow.md`
+4. `docs/architecture.md`
+5. `docs/runtime-gemini.md`
+6. `docs/runtime-claude.md`
+7. `docs/runtime-codex.md`

package/docs/overview.md

@@ -0,0 +1,141 @@
+# Maestro Overview
+
+Maestro is a multi-agent development orchestration platform that coordinates 39 specialized AI agents through structured workflows. It runs as four runtime targets from a single canonical source tree:
+
+- **Gemini CLI extension** (root directory — `GEMINI.md`, `gemini-extension.json`, shared `agents/`, `commands/maestro/`)
+- **Claude Code plugin** (`claude/` subdirectory)
+- **Codex plugin** (`plugins/maestro/` subdirectory)
+- **Qwen Code extension** (`qwen/` subdirectory — `qwen-extension.json` manifest + `QWEN.md` context file live at repo root; generated `qwen/agents/` and `qwen/hooks.json` live in the subdirectory)
+
+The orchestrator adopts a TechLead persona that designs, plans, delegates to agents, validates, and reports.
+
+## What Maestro Does
+
+Maestro takes a development task and orchestrates it through a structured workflow:
+
+1. **Classifies** the task as simple, medium, or complex
+2. **Designs** the solution through structured dialogue (standard mode)
+3. **Plans** the implementation with phased execution and dependency analysis
+4. **Delegates** work to specialized agents (coder, architect, tester, etc.)
+5. **Validates** each phase output with build/lint/test checks
+6. **Reviews** the final result with a code review agent
+7. **Archives** the session state for future reference
+
+Simple tasks use an **Express workflow** (1 agent, 1 phase), while medium/complex tasks use the full **Standard workflow** with multi-phase execution.
+
+## Key Numbers
+
+| Metric | Count |
+|--------|-------|
+| Specialized agents | 39 |
+| MCP tools | 17 |
+| Shared skills | 7 |
+| Entry-point commands | 9 (+ 3 core) |
+| Runtime targets | 4 |
+| Source transforms | 6 |
+| Test cases | see `just test` output (70+ files across unit, transforms, integration) |
+
+## Project Structure
+
+```
+maestro-orchestrate/
+├── src/                          # Canonical source (edit here)
+│   ├── agents/                   # 39 agent definitions
+│   ├── skills/shared/            # 7 shared methodology modules + protocols
+│   ├── templates/                # Session state, design doc, impl plan
+│   ├── references/               # Architecture ref, orchestration steps
+│   ├── transforms/               # Generator transform library
+│   ├── entry-points/             # 9 entry-point + 3 core-command registries, preamble builders, 6 templates
+│   ├── config/                   # Canonical config helpers
+│   ├── core/                     # Shared runtime helpers and resolvers
+│   ├── state/                    # Session-state helpers
+│   ├── hooks/                    # Shared hook logic modules
+│   │   └── logic/                # Hook implementations (session-start, before-agent, after-agent, session-end, hook-state)
+│   ├── mcp/                      # Canonical MCP server modules
+│   ├── platforms/                # Runtime adapters, manifests, and public shells
+│   ├── scripts/                  # Runtime helper scripts (workspace, session, settings)
+│   └── manifest.js               # Declarative file mapping rules
+├── scripts/
+│   └── generate.js               # Generator (manifest → output)
+├── tests/                        # 71 test files, 980 tests (see `just test` output)
+│
+├── agents/                       # [generated] Gemini agent stubs
+├── commands/maestro/             # [generated] Gemini TOML commands
+├── hooks/                        # [generated] Gemini hook adapters
+├── mcp/                          # [generated] Gemini MCP adapter
+├── policies/                     # [generated] Gemini shell policies
+│
+├── claude/                       # [generated] Claude Code plugin
+│   ├── agents/                   # Claude agent stubs
+│   ├── skills/                   # Claude skills (19)
+│   ├── hooks/                    # Hook config (claude-hooks.json)
+│   ├── scripts/                  # Claude hook scripts
+│   ├── mcp/                      # Claude MCP adapter
+│   ├── .claude-plugin/           # Plugin manifest
+│   └── .mcp.json                 # MCP server config
+│
+├── plugins/maestro/              # [generated] Codex plugin
+│   ├── skills/                   # Codex skills (19)
+│   ├── src/                      # generated detached runtime payload
+│   ├── references/               # Runtime guide
+│   ├── .codex-plugin/            # Plugin manifest
+│   ├── .mcp.json                 # MCP server config (spawns bin via npx)
+│   ├── .app.json                 # App config
+│   └── README.md
+│
+└── qwen/                         # [generated] Qwen Code extension
+    ├── agents/                   # Qwen agent stubs (39, snake_case, Qwen tool names)
+    └── hooks.json                # Qwen hook registration
+```
+
+## Core Concepts
+
+### Agents
+
+39 specialized agents, each with a defined methodology, tool restrictions, and capability tier:
+
+| Tier | Capability | Agents |
+|------|-----------|--------|
+| `read_only` | Read, search, analyze | architect, api-designer, code-reviewer, content-strategist, compliance-reviewer, cloud-architect, solutions-architect |
+| `read_shell` | Read + shell execution | debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist, database-administrator, site-reliability-engineer, db2-dba, zos-sysprog |
+| `read_write` | Read + create/modify files | technical-writer, product-manager, ux-designer, copywriter, release-manager, prompt-engineer |
+| `full` | All tools | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, ml-engineer, mlops-engineer, mobile-engineer, cobol-engineer, observability-engineer, platform-engineer, integration-engineer, hlasm-assembler-specialist, ibm-i-specialist |
+
+### MCP Server
+
+A bundled Model Context Protocol server providing 17 tools across 3 packs:
+
+- **Workspace** (4): initialize_workspace, assess_task_complexity, validate_plan, resolve_settings
+- **Session** (10): create_session, get_session_status, update_session, transition_phase, archive_session, enter_design_gate, record_design_approval, get_design_gate_status, scan_phase_changes, reconcile_phase
+- **Content** (3): get_skill_content, get_agent, get_runtime_context
+
+### Skills
+
+7 shared methodology modules loaded on-demand via MCP:
+
+- **delegation** — Agent dispatch rules, prompt templates, tool restrictions
+- **execution** — Phase execution with parallel/sequential modes
+- **validation** — Build/lint/test pipeline per project type
+- **session-management** — Session creation, tracking, archival, resume
+- **implementation-planning** — Phase decomposition from designs
+- **code-review** — Severity-classified review with deduplication
+- **design-dialogue** — Structured requirements gathering with depth levels
+
+### Generator
+
+A manifest-driven code generator (`scripts/generate.js`) transforms canonical source into runtime-specific adapter output. It applies frontmatter, stub, and metadata transforms, emits only the public files each runtime needs, and maintains a zero-drift guarantee enforced by CI.
+
+### State Management
+
+Session state lives in `docs/maestro/` (configurable via `MAESTRO_STATE_DIR`):
+
+```
+docs/maestro/
+├── state/
+│   ├── active-session.md          # Current session (YAML frontmatter + log)
+│   └── archive/                   # Completed sessions
+└── plans/
+    ├── *-design.md                # Design documents
+    ├── *-impl-plan.md             # Implementation plans
+    └── archive/                   # Archived plans
+```