{"id":45283433,"url":"https://github.com/josstei/maestro-gemini","last_synced_at":"2026-02-21T02:41:50.506Z","repository":{"id":337377849,"uuid":"1153318872","full_name":"josstei/maestro-gemini","owner":"josstei","description":"Turn Gemini CLI into a multi-agent platform — 12 specialized subagents, parallel dispatch, 4-phase orchestration, and standalone dev tools for code review, debugging, security, and performance","archived":false,"fork":false,"pushed_at":"2026-02-18T06:29:08.000Z","size":378,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T11:19:01.002Z","etag":null,"topics":["agentic","ai-agents","ai-coding","cli-extension","code-review","developer-tools","gemini","gemini-cli","gemini-extension","multi-agent","orchestration","subagents"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josstei.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T06:49:37.000Z","updated_at":"2026-02-18T06:27:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/josstei/maestro-gemini","commit_stats":null,"previous_names":["josstei/maestro-gemini"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/josstei/maestro-gemini","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josstei%2Fmaestro-gemini","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josstei%2Fmaestro-gemini/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josstei%2Fmaestro-gemini/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josstei%2Fmaestro-gemini/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josstei","download_url":"https://codeload.github.com/josstei/maestro-gemini/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josstei%2Fmaestro-gemini/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29671821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"online","status_checked_at":"2026-02-21T02:00:07.432Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-agents","ai-coding","cli-extension","code-review","developer-tools","gemini","gemini-cli","gemini-extension","multi-agent","orchestration","subagents"],"created_at":"2026-02-21T02:41:49.970Z","updated_at":"2026-02-21T02:41:50.497Z","avatar_url":"https://github.com/josstei.png","language":"Shell","readme":"# Maestro\n\n[![Version](https://img.shields.io/badge/version-1.2.0-blue)](https://github.com/josstei/maestro-gemini/releases)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-extension-orange)](https://geminicli.com)\n\nMulti-agent orchestration extension for Gemini CLI. Maestro delegates work to 12 specialized subagents — with support for parallel dispatch of independent phases — coordinated by a TechLead orchestrator through structured design, planning, and execution workflows.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Quick Start](#quick-start)\n- [Commands](#commands)\n  - [Orchestration](#orchestration)\n  - [Standalone Tools](#standalone-tools)\n  - [Session Management](#session-management)\n- [Configuration](#configuration)\n  - [Environment Variables](#environment-variables)\n  - [Model Configuration](#model-configuration)\n- [Architecture](#architecture)\n  - [Orchestration Flow](#orchestration-flow)\n  - [Component Model](#component-model)\n  - [Workflow Phases](#workflow-phases)\n- [Agents](#agents)\n  - [Agent Roster](#agent-roster)\n  - [Tool Access Philosophy](#tool-access-philosophy)\n- [Skills](#skills)\n- [Parallel Execution](#parallel-execution)\n  - [How It Works](#how-it-works)\n  - [When to Use Each Mode](#when-to-use-each-mode)\n  - [Dispatch Directory Structure](#dispatch-directory-structure)\n  - [Constraints](#constraints)\n- [Session State \u0026 Project Output](#session-state--project-output)\n- [Documentation](#documentation)\n  - [Usage Guide](USAGE.md)\n  - [Architecture](docs/architecture/)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nMaestro transforms Gemini CLI into a multi-agent orchestration platform. Instead of a single AI session handling everything, Maestro delegates work to 12 specialized subagents — each with its own context, tools, and expertise — coordinated by a TechLead orchestrator through a structured 4-phase workflow: Design, Plan, Execute, Complete.\n\n## Features\n\n- **Guided Design Dialogue** — Structured requirements gathering with multiple-choice questions and architectural approach proposals\n- **Automated Planning** — Generates implementation plans with phase dependencies, agent assignments, and parallelization opportunities\n- **Parallel Execution** — Independent phases run concurrently through shell-based parallel dispatch\n- **Session Persistence** — All orchestration state tracked in YAML+Markdown files for reliable resumption\n- **Hooks-Based Lifecycle Middleware** — Lifecycle hooks for active-agent tracking and handoff validation\n- **Least-Privilege Security** — Each subagent receives only the tools required for its role\n- **Standalone Commands** — Direct access to code review, debugging, security audit, and performance analysis without full orchestration\n- **Configurable Settings** — 14 environment-variable-driven parameters for model selection, timeouts, validation strictness, and dispatch behavior\n\n## Getting Started\n\n### Prerequisites\n\nMaestro relies on Gemini CLI's experimental subagent system. Enable it in your Gemini CLI settings:\n\n```json\n{\n  \"experimental\": {\n    \"enableAgents\": true\n  }\n}\n```\n\n\u003e **Warning**: Parallel-dispatched agents run in autonomous mode (`--approval-mode=yolo`). Sequential delegation uses your current Gemini CLI approval mode. Review the [subagents documentation](https://geminicli.com/docs/core/subagents/) for details.\n\nThe `settings.json` file is located at:\n- **macOS/Linux**: `~/.gemini/settings.json`\n- **Windows**: `%USERPROFILE%\\.gemini\\settings.json`\n\nMaestro does not auto-edit `settings.json`. Enable `experimental.enableAgents` manually before running orchestration commands.\n\n### Installation\n\n**From Git Repository:**\n\n```bash\ngemini extensions install https://github.com/josstei/maestro-gemini\n```\n\n**Local Development:**\n\n```bash\ngit clone https://github.com/josstei/maestro-gemini\ncd maestro-gemini\ngemini extensions link .\n```\n\nRestart Gemini CLI after installation for the extension to load.\n\n### Quick Start\n\n```\n/maestro:orchestrate Build a REST API for a task management system with user authentication\n```\n\nMaestro will:\n1. Engage you in a structured design dialogue\n2. Present 2-3 architectural approaches with trade-offs\n3. Generate a design document for your approval\n4. Create a detailed implementation plan with agent assignments\n5. Execute the plan phase by phase, delegating to specialized agents\n6. Track all progress in session state files\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| [`/maestro:orchestrate`](#maestroOrchestrate) | Full orchestration workflow (design → plan → execute → complete) |\n| [`/maestro:execute`](#maestroexecute) | Execute an existing implementation plan |\n| [`/maestro:resume`](#maestroresume) | Resume an interrupted session |\n| [`/maestro:review`](#maestroreview) | Standalone code review |\n| [`/maestro:debug`](#maestrodebug) | Standalone debugging session |\n| [`/maestro:security-audit`](#maestrosecurity-audit) | Standalone security assessment |\n| [`/maestro:perf-check`](#maestroperf-check) | Standalone performance analysis |\n| [`/maestro:status`](#maestrostatus) | View current session status |\n| [`/maestro:archive`](#maestroarchive) | Archive the active session |\n\n### Orchestration\n\n#### /maestro:orchestrate\n\nInitiates the full Maestro orchestration workflow.\n\n**Usage**: `/maestro:orchestrate \u003ctask description\u003e`\n\n**Behavior**:\n1. Checks for existing active sessions in `\u003cMAESTRO_STATE_DIR\u003e/state/` (default: `.gemini/state/`)\n2. If an active session exists, offers to resume or archive it\n3. Begins the four-phase orchestration workflow:\n   - Phase 1: Design Dialogue\n   - Phase 2: Team Assembly \u0026 Planning\n   - Phase 3: Execution\n   - Phase 4: Completion \u0026 Archival\n\n#### /maestro:execute\n\nExecutes an existing implementation plan, skipping design and planning phases.\n\n**Usage**: `/maestro:execute \u003cpath-to-implementation-plan\u003e`\n\n**Behavior**:\n1. Reads the specified implementation plan file\n2. Creates a session state file for tracking\n3. Presents an execution summary for user confirmation\n4. Executes phases according to the plan with full progress tracking\n5. Archives the session on completion\n\n#### /maestro:resume\n\nResumes an interrupted orchestration session.\n\n**Usage**: `/maestro:resume`\n\n**Behavior**:\n1. Reads active session state through `scripts/read-active-session.sh` (default path: `.gemini/state/active-session.md`)\n2. Parses session metadata and phase statuses\n3. Presents a status summary with completed/pending/failed phases\n4. If errors exist from the previous run, presents them and asks for guidance\n5. Continues execution from the last active phase using the execution and delegation skills\n\n### Standalone Tools\n\n#### /maestro:review\n\nRuns a standalone code review on staged changes, last commit, or specified paths.\n\n**Usage**: `/maestro:review [file paths or glob patterns]`\n\n**Behavior**:\n1. Auto-detects review scope: user-specified paths \u003e staged changes \u003e last commit diff\n2. Confirms detected scope with the user\n3. Delegates to the code-reviewer agent\n4. Presents findings classified by severity (Critical, Major, Minor, Suggestion)\n5. Every finding references a specific file and line number\n\n#### /maestro:debug\n\nFocused debugging session to investigate and diagnose an issue.\n\n**Usage**: `/maestro:debug \u003cissue description\u003e`\n\n**Behavior**:\n1. Delegates to the debugger agent with the issue description\n2. Follows systematic methodology: reproduce, hypothesize, investigate, isolate, verify\n3. Presents root cause analysis with evidence, execution trace, and recommended fix\n\n#### /maestro:security-audit\n\nRuns a security assessment on the specified scope.\n\n**Usage**: `/maestro:security-audit \u003cscope\u003e`\n\n**Behavior**:\n1. Delegates to the security-engineer agent\n2. Reviews for OWASP Top 10 vulnerabilities, traces data flow, audits authentication/authorization\n3. Presents findings with CVSS-aligned severity, proof of concept, and remediation steps\n\n#### /maestro:perf-check\n\nRuns a performance analysis on the specified scope.\n\n**Usage**: `/maestro:perf-check \u003cscope\u003e`\n\n**Behavior**:\n1. Delegates to the performance-engineer agent\n2. Establishes baseline, profiles hotspots, analyzes bottlenecks\n3. Presents optimization recommendations ranked by impact-to-effort ratio\n\n### Session Management\n\n#### /maestro:status\n\nDisplays the current orchestration session status.\n\n**Usage**: `/maestro:status`\n\n**Behavior**:\n1. Reads the active session state via file injection\n2. Presents phase-by-phase status, file manifest, token usage, and errors\n3. Read-only — does not modify state or continue execution\n\n#### /maestro:archive\n\nArchives the current active orchestration session.\n\n**Usage**: `/maestro:archive`\n\n**Behavior**:\n1. Checks for an active session\n2. Presents a summary and asks for confirmation\n3. Moves design document, implementation plan, and session state to archive directories\n4. Verifies archival was successful\n\n## Configuration\n\n### Environment Variables\n\nMaestro works out of the box with sensible defaults. To customize behavior, set any of these environment variables in your shell profile or project `.env` file:\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MAESTRO_DEFAULT_MODEL` | _(inherit)_ | Model used by all agents unless individually overridden |\n| `MAESTRO_WRITER_MODEL` | _(inherit)_ | Model for technical-writer agent |\n| `MAESTRO_DEFAULT_TEMPERATURE` | `0.2` | Temperature for all agents (0.0-1.0) |\n| `MAESTRO_MAX_TURNS` | `25` | Maximum turns per subagent execution |\n| `MAESTRO_AGENT_TIMEOUT` | `10` | Timeout in minutes per subagent |\n| `MAESTRO_DISABLED_AGENTS` | _(none)_ | Comma-separated list of agents to exclude |\n| `MAESTRO_MAX_RETRIES` | `2` | Retry attempts per phase before escalation |\n| `MAESTRO_AUTO_ARCHIVE` | `true` | Archive sessions on completion |\n| `MAESTRO_VALIDATION_STRICTNESS` | `normal` | `strict` / `normal` / `lenient` |\n| `MAESTRO_STATE_DIR` | `.gemini` | Directory for session state and plans |\n| `MAESTRO_MAX_CONCURRENT` | `0` (unlimited) | Max simultaneous agents in parallel dispatch |\n| `MAESTRO_STAGGER_DELAY` | `5` | Seconds between parallel agent launches |\n| `MAESTRO_GEMINI_EXTRA_ARGS` | _(none)_ | Extra Gemini CLI args forwarded to each parallel dispatch process (prefer `--policy`) |\n| `MAESTRO_EXECUTION_MODE` | `ask` | Phase 3 dispatch: `parallel` / `sequential` / `ask` |\n\nAll settings are optional. The orchestrator uses the defaults shown above when a variable is not set.\nScript-backed setting precedence is: exported env var -\u003e workspace `.env` -\u003e extension `.env` -\u003e default.\nYou can configure extension-scoped settings interactively with `gemini extensions config maestro`.\n\n### Model Configuration\n\n| Role | Model | Purpose |\n|------|-------|---------|\n| Inherited | _(main session model)_ | All agents inherit the model from the main Gemini CLI session |\n| Override | `MAESTRO_DEFAULT_MODEL` | Set to a specific model (e.g., `gemini-2.5-pro`) to override all agents |\n\nAll agents omit the `model` field by default, inheriting the main session's model selection. Override via `MAESTRO_DEFAULT_MODEL` or `MAESTRO_WRITER_MODEL` environment variables. These overrides apply to parallel dispatch only — sequentially delegated subagents always inherit the main session model.\n\n### Hooks\n\nMaestro uses Gemini CLI's hooks system for lifecycle middleware. Tool permissions are enforced natively via agent frontmatter `tools:` declarations — hooks handle supplementary lifecycle concerns:\n\n| Hook | Purpose |\n|------|---------|\n| BeforeAgent | Track active agent identity, inject session context |\n| AfterAgent | Validate handoff report format, clear agent tracking |\n\nHook handlers are in `hooks/` and registered via `hooks/hooks.json`.\n\n## Architecture\n\n### Orchestration Flow\n\n```mermaid\ngraph TB\n    User([User]) --\u003e|/maestro:orchestrate| TL[TechLead Orchestrator]\n\n    TL --\u003e|Phase 1| DD[Design Dialogue]\n    TL --\u003e|Phase 2| IP[Implementation Planning]\n    TL --\u003e|Phase 3| EX[Execution]\n    TL --\u003e|Phase 4| CO[Completion]\n\n    EX --\u003e|Sequential| DA[Subagent Tools]\n    EX --\u003e|Parallel| PD[parallel-dispatch.sh]\n\n    DA --\u003e Agents\n    PD --\u003e Agents\n\n    subgraph Agents [Specialized Subagents]\n        direction LR\n        A1[architect]\n        A2[coder]\n        A3[tester]\n        A4[debugger]\n        A5[+ 8 more]\n    end\n\n    Agents --\u003e|Results| TL\n    TL --\u003e|State| SS[(Session State)]\n```\n\n### Component Model\n\nMaestro is built from seven layers, each with a distinct responsibility:\n\n| Layer | Directory | Format | Purpose |\n|-------|-----------|--------|---------|\n| **Orchestrator** | `GEMINI.md` | Markdown | TechLead persona, phase transitions, delegation rules |\n| **Commands** | `commands/` | TOML | CLI command definitions mapping user commands to prompts/skills |\n| **Agents** | `agents/` | Markdown + YAML frontmatter | 12 subagent persona definitions with tool permissions and model config |\n| **Skills** | `skills/` | Markdown (`SKILL.md` per directory) | Reusable methodology modules with embedded protocols |\n| **Scripts** | `scripts/` | Shell | Execution infrastructure (parallel dispatch) |\n| **Hooks** | `hooks/` | JSON + Shell | Lifecycle middleware for active-agent tracking and handoff validation |\n| **Templates** | `templates/` | Markdown | Structure templates for generated artifacts (designs, plans, sessions) |\n\n### Workflow Phases\n\n#### Phase 1: Design Dialogue\n\nThe TechLead engages you in a structured conversation to understand requirements:\n- Asks one question at a time, preferring multiple-choice format\n- Covers problem scope, constraints, technology preferences, quality requirements, and deployment context\n- Presents 2-3 architectural approaches with pros, cons, and recommendations\n- Builds the design document section by section, validating each with you\n\n#### Phase 2: Team Assembly \u0026 Planning\n\nAfter design approval, the TechLead:\n- Analyzes the design for components, interfaces, and dependencies\n- Assigns phases to specialized agents based on task domain\n- Identifies parallel execution opportunities\n- Generates a detailed implementation plan for your approval\n\n#### Phase 3: Execution\n\nWith plan approval, the TechLead:\n- Delegates work to subagents phase by phase\n- Runs parallel phases concurrently when dependencies allow\n- Updates session state after each phase completion\n- Handles errors with up to 2 automatic retries before escalating\n\n#### Phase 4: Completion\n\nAfter all phases complete:\n- Final review of all deliverables\n- Session state marked as completed\n- Plans and state files archived to `archive/` subdirectories\n- Summary delivered with files changed, token usage, and next steps\n\n## Agents\n\n### Agent Roster\n\nMaestro coordinates 12 specialized subagents:\n\n| Agent | Specialization | Tools | Model |\n|-------|---------------|-------|-------|\n| architect | System design, technology selection, component design | read, glob, search, web search/fetch | inherit |\n| api-designer | REST/GraphQL endpoint design, API contracts | read, glob, search, web search/fetch | inherit |\n| coder | Feature implementation, clean code, SOLID principles | read, glob, search, write, replace, shell | inherit |\n| code-reviewer | Code quality review, best practices, security | read, glob, search | inherit |\n| data-engineer | Schema design, query optimization, ETL pipelines | read, glob, search, write, replace, shell, web search | inherit |\n| debugger | Root cause analysis, log analysis, execution tracing | read, glob, search, shell | inherit |\n| devops-engineer | CI/CD pipelines, containerization, infrastructure | read, glob, search, write, replace, shell, web search/fetch | inherit |\n| performance-engineer | Profiling, bottleneck identification, optimization | read, glob, search, shell, web search/fetch | inherit |\n| refactor | Code modernization, technical debt, design patterns | read, glob, search, write, replace | inherit |\n| security-engineer | Vulnerability assessment, OWASP, threat modeling | read, glob, search, shell, web search/fetch | inherit |\n| tester | Unit/integration/E2E tests, TDD, coverage analysis | read, glob, search, write, replace, shell, web search | inherit |\n| technical-writer | API docs, READMEs, architecture documentation | read, glob, search, write, replace, web search | inherit |\n\n### Tool Access Philosophy\n\n- **Read-only agents** (architect, api-designer, code-reviewer): Produce analysis and recommendations\n- **Read + Shell agents** (debugger, performance-engineer, security-engineer): Investigate without modifying files\n- **Read + Write agents** (refactor, technical-writer): Modify code/docs without shell access\n- **Full access agents** (coder, data-engineer, devops-engineer, tester): Complete implementation capabilities\n\n## Skills\n\nMaestro uses skills to encapsulate detailed methodologies that are activated on demand, keeping the base context lean.\n\n| Skill | Purpose | Activated By |\n|-------|---------|-------------|\n| `design-dialogue` | Structured requirements gathering and architectural design convergence | `/maestro:orchestrate` (Phase 1) |\n| `implementation-planning` | Phase decomposition, agent assignment, and plan generation | `/maestro:orchestrate` (Phase 2) |\n| `execution` | Phase execution protocols, error handling, and completion workflows | `/maestro:orchestrate` (Phase 3), `/maestro:execute`, `/maestro:resume` |\n| `delegation` | Subagent prompt construction, scope boundaries, and parallel delegation | Any phase involving subagent delegation |\n| `session-management` | Session creation, state updates, resume protocol, and archival | `/maestro:orchestrate`, `/maestro:resume`, `/maestro:archive`, `/maestro:status` |\n| `code-review` | Scope detection, severity classification, and structured review output | `/maestro:review` |\n| `validation` | Build/lint/test pipeline, project type detection, and result interpretation | Post-phase validation during execution |\n\n## Parallel Execution\n\nMaestro uses shell-based parallel dispatch, enabling independent implementation phases to run concurrently instead of sequentially.\n\n### How It Works\n\nThe TechLead orchestrator uses `scripts/parallel-dispatch.sh` to spawn concurrent Gemini CLI processes that execute independently. This bypasses the sequential subagent tool invocation pattern, which processes one delegation at a time.\n\n**Dispatch flow:**\n1. The orchestrator writes self-contained delegation prompts to a dispatch directory\n2. Invokes `parallel-dispatch.sh` via shell\n3. The script spawns one `gemini --approval-mode=yolo --output-format json` process per prompt file, streaming prompt content over stdin\n4. All agents execute concurrently as independent OS processes\n5. Results are collected with exit codes, logs, and structured JSON output\n6. The orchestrator reads results and updates session state\n\n### When to Use Each Mode\n\n| Use Parallel Dispatch | Use Sequential Delegation |\n|---|---|\n| Phases at the same dependency depth | Phases with shared file dependencies |\n| Non-overlapping file ownership | Phases that may need interactive clarification |\n| Fully self-contained prompts | Single-phase execution |\n| Batch size of 2-4 agents | Fallback when parallel dispatch fails |\n\n### Dispatch Directory Structure\n\n```\n\u003cstate_dir\u003e/parallel/\u003cbatch-id\u003e/\n├── prompts/\n│   ├── agent-a.txt          # Full delegation prompt\n│   └── agent-b.txt\n└── results/\n    ├── agent-a.json          # Structured JSON output\n    ├── agent-a.exit          # Exit code (0=success, 124=timeout)\n    ├── agent-a.log           # stderr/debug output\n    ├── agent-b.json\n    ├── agent-b.exit\n    ├── agent-b.log\n    └── summary.json          # Batch summary with status per agent\n```\n\n### Constraints\n\nParallel agents run as independent CLI processes with no shared context. Each prompt must be complete and self-contained — agents cannot ask follow-up questions or access results from other agents in the same batch.\n\n## Session State \u0026 Project Output\n\nMaestro creates the following directories in your project:\n\n```\n\u003cyour-project\u003e/\n└── .gemini/\n    ├── plans/                          # Active design docs and implementation plans\n    │   ├── archive/                    # Completed plans\n    │   ├── YYYY-MM-DD-\u003ctopic\u003e-design.md\n    │   └── YYYY-MM-DD-\u003ctopic\u003e-impl-plan.md\n    └── state/                          # Session tracking\n        ├── archive/                    # Completed sessions\n        └── active-session.md           # Current orchestration state\n```\n\nMaestro tracks orchestration progress in `\u003cMAESTRO_STATE_DIR\u003e/state/active-session.md` (default: `.gemini/state/active-session.md`) with:\n\n- **Phase status tracking**: pending, in_progress, completed, failed, skipped\n- **File manifest**: Files created, modified, and deleted per phase\n- **Error tracking**: Per-phase error logs with retry counts and resolution records\n- **Token usage**: Per-agent, per-phase token consumption metrics\n\nAll state files use YAML frontmatter for machine-readable metadata and Markdown body for human-readable logs.\n\n## Documentation\n\n- **[Usage Guide](USAGE.md)** — Comprehensive guide to installing, configuring, and using Maestro\n- **[System Overview](docs/architecture/system-overview.md)** — Extension entry point, component model, and configuration system\n- **[Agent System](docs/architecture/agent-system.md)** — Agent definitions, tool permissions, model assignment, and delegation\n- **[Skills \u0026 Commands](docs/architecture/skills-and-commands.md)** — Skill activation, command definitions, and protocol contracts\n- **[State Management \u0026 Scripts](docs/architecture/state-management-and-scripts.md)** — Session state, parallel dispatch, and execution infrastructure\n\n## Troubleshooting\n\n### Extension Not Loading\n\n1. Verify the extension is linked: `gemini extensions list`\n2. Restart Gemini CLI after installation or linking\n3. Check `gemini-extension.json` exists in the maestro directory\n\n### /maestro:orchestrate Not Responding\n\n1. Ensure GEMINI.md is present in the maestro directory\n2. Check that `commands/maestro/orchestrate.toml` exists\n3. Restart Gemini CLI\n\n### Session Resume Fails\n\n1. Verify `active-session.md` exists under your configured state directory (`.gemini/state/` by default)\n2. Check the YAML frontmatter is valid (no syntax errors)\n3. If corrupted, manually fix the YAML or delete and start fresh with `/maestro:orchestrate`\n\n### Subagent Errors\n\n- Maestro automatically retries failed phases up to 2 times\n- If retries are exhausted, you'll be asked for guidance\n- Check the session state file for detailed error logs\n- Common causes: file conflicts, missing dependencies, validation failures\n\n### Parallel Dispatch Issues\n\n**Agents timing out:**\n- Check `MAESTRO_AGENT_TIMEOUT` setting (default: 10 minutes)\n- Review agent logs in `\u003cdispatch-dir\u003e/results/\u003cagent\u003e.log`\n- Reduce batch size to 2 agents if system resources are constrained\n\n**Empty or missing results:**\n- Verify prompt files are non-empty in `\u003cdispatch-dir\u003e/prompts/`\n- Check that `gemini` CLI is on PATH and accessible\n- Review `summary.json` for per-agent status and exit codes\n\n**Parallel dispatch script not found:**\n- Verify `scripts/parallel-dispatch.sh` exists and is executable\n- Run `chmod +x scripts/parallel-dispatch.sh` if permissions are missing\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feat/your-feature`\n3. Make your changes\n4. Test manually by linking the extension: `gemini extensions link .`\n5. Verify commands work in Gemini CLI\n6. Submit a pull request\n\nRun the hooks integration tests with `bash tests/run-all.sh`. All other changes are validated manually via Gemini CLI.\n\n## License\n\nMIT\n","funding_links":[],"categories":[":tada: New","Development"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosstei%2Fmaestro-gemini","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosstei%2Fmaestro-gemini","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosstei%2Fmaestro-gemini/lists"}