Maestro Usage

April 30, 2026 · View on GitHub

For detailed CI/CD pipeline documentation including workflow diagrams, the release process, and npm publishing strategy, see docs/cicd.md.

Development Commands

# Regenerate runtime files from source
node scripts/generate.js

# Generate runtime adapters using package scripts
npm run build

# Run all tests across unit, transform, and integration suites
node --test tests/unit/*.test.js tests/transforms/*.test.js tests/integration/*.test.js

# Show unified diff of changes
node scripts/generate.js --diff

# Delete all generated files and regenerate
node scripts/generate.js --clean

# Run CI test subset (see justfile for current file list)
just test

# Run only transform unit tests
just test-transforms

# Run only integration tests
just test-integration

# Generate + verify zero drift in a clean worktree/CI checkout
just check

# Full CI equivalent in a clean worktree/CI checkout (check + check-layers + test)
just ci

# Verify lib/ import-boundary rules
just check-layers

# Delete local branches whose remotes are gone
just cleanup-branches

Editing Workflow

  1. Edit canonical source in src/. Maintain hand-authored root docs (README.md, EXAMPLES.md, USAGE.md, OVERVIEW.md, ARCHITECTURE.md, CONTRIBUTING.md, SECURITY.md) directly. Do not edit generated runtime stubs, command files, hook adapters, detached payloads, or generated skill copies directly.
  2. Run node scripts/generate.js or npm run build to regenerate runtime adapters
  3. Run node scripts/generate.js --diff to confirm the generator has no additional pending output
  4. Run node --test tests/unit/*.test.js tests/transforms/*.test.js tests/integration/*.test.js (or just test) before committing
  5. Commit canonical source, directly owned root docs, and generated adapter output together
  6. CI will fail if runtime adapters drift from canonical src/; just check and just ci are designed for clean worktrees because they end with git diff --exit-code

Configuration

Settings

All settings are resolved with precedence: environment variable > workspace .env > extension .env > default.

SettingDefaultValuesPurpose
MAESTRO_STATE_DIRdocs/maestropathSession state directory
MAESTRO_DISABLED_AGENTS(none)comma-separated namesExclude agents from assignment
MAESTRO_EXECUTION_MODEaskparallel, sequential, askExecution strategy
MAESTRO_VALIDATION_STRICTNESSnormalstrict, normal, lenientValidation mode
MAESTRO_AUTO_ARCHIVEtruetrue, falseAuto-archive on completion
MAESTRO_MAX_RETRIES2integerMax retries per phase
MAESTRO_MAX_CONCURRENT0integerMax parallel agents (0 = unlimited)

Runtime-Specific Environment Variables

VariableRuntimePurpose
MAESTRO_EXTENSION_PATHGeminiOverride extension root path
MAESTRO_WORKSPACE_PATHGeminiWorkspace root (set by Gemini CLI)
MAESTRO_EXTENSION_PATHQwenOverride extension root path
MAESTRO_WORKSPACE_PATHQwenWorkspace root (set by Qwen Code)
MAESTRO_WORKSPACE_PATHCodexOptional workspace root override; otherwise Codex uses MCP roots/list
CLAUDE_PLUGIN_ROOTClaudePlugin root (set by Claude Code)
CLAUDE_PROJECT_DIRClaudeProject directory (set by Claude Code)

Invoking Maestro

Gemini CLI

Commands are TOML-based slash commands:

CommandPurpose
/maestro:orchestrateFull orchestration workflow
/maestro:executeExecute an approved plan
/maestro:resumeResume interrupted session
/maestro:reviewCode review
/maestro:debugDebugging workflow
/maestro:archiveArchive active session
/maestro:statusShow session status
/maestro:security-auditSecurity assessment
/maestro:perf-checkPerformance assessment
/maestro:seo-auditSEO audit
/maestro:a11y-auditAccessibility audit
/maestro:compliance-checkCompliance review

Claude Code

Skills are Markdown-based slash commands:

CommandPurpose
/orchestrateFull orchestration workflow
/executeExecute an approved plan
/resume-sessionResume interrupted session
/review-codeCode review
/debug-workflowDebugging workflow
/archiveArchive active session
/statusShow session status
/security-auditSecurity assessment
/perf-checkPerformance assessment
/seo-auditSEO audit
/a11y-auditAccessibility audit
/compliance-checkCompliance review

Codex

Skills are invoked through the plugin namespace:

CommandPurpose
$maestro:orchestrateFull orchestration workflow
$maestro:executeExecute an approved plan
$maestro:resume-sessionResume interrupted session
$maestro:review-codeCode review
$maestro:debug-workflowDebugging workflow
$maestro:archiveArchive active session
$maestro:statusShow session status
$maestro:security-auditSecurity assessment
$maestro:perf-checkPerformance assessment
$maestro:seo-auditSEO audit
$maestro:a11y-auditAccessibility audit
$maestro:compliance-checkCompliance review

Codex keeps its built-in /review, /debug, and /resume commands. Maestro exposes $maestro:review-code, $maestro:debug-workflow, and $maestro:resume-session to avoid colliding with those host commands.

State Directory Structure

After running Maestro, the state directory (default: docs/maestro/) contains:

docs/maestro/
├── state/
│   ├── active-session.md         # Current session
│   └── archive/
│       └── <session-id>.md       # Archived sessions
└── plans/
    ├── <date>-<topic>-design.md  # Design documents
    ├── <date>-<topic>-impl-plan.md # Implementation plans
    └── archive/
        └── ...                   # Archived plans

Session State Format

Active sessions use YAML frontmatter + Markdown body:

---
session_id: "2024-03-15-auth-system"
task: "Implement user authentication"
created: "2024-03-15T10:00:00Z"
updated: "2024-03-15T11:30:00Z"
status: "in_progress"
workflow_mode: "standard"
design_document: "docs/maestro/plans/2024-03-15-auth-system-design.md"
implementation_plan: "docs/maestro/plans/2024-03-15-auth-system-impl-plan.md"
current_phase: 2
total_phases: 4
execution_mode: "sequential"
execution_backend: null
current_batch: null
task_complexity: "medium"

token_usage:
  total_input: 0
  total_output: 0
  total_cached: 0
  by_agent: {}

phases:
  - id: 1
    name: "Foundation"
    status: "completed"
    agents: ["architect"]
    parallel: false
    started: "2024-03-15T10:05:00Z"
    completed: "2024-03-15T10:45:00Z"
    blocked_by: []
    files_created: ["src/services/user.ts"]
    files_modified: []
    files_deleted: []
    downstream_context:
      key_interfaces_introduced: ["UserService"]
      patterns_established: ["Repository pattern"]
      integration_points: ["/api/users"]
      assumptions: []
      warnings: []
    errors: []
    retry_count: 0
  - id: 2
    name: "Implementation"
    status: "in_progress"
    agents: ["coder"]
    parallel: false
    started: "2024-03-15T10:50:00Z"
    completed: null
    blocked_by: [1]
    files_created: []
    files_modified: []
    files_deleted: []
    downstream_context:
      key_interfaces_introduced: []
      patterns_established: []
      integration_points: []
      assumptions: []
      warnings: []
    errors: []
    retry_count: 0
---

# Auth System Orchestration Log

## Phase 1: Foundation
...

Agent Catalog

Read-Only Agents (analysis, no code changes)

AgentSpecialtyTurnsTemp
architectSystem design, technology selection150.3
api-designerEndpoint design, API contracts150.3
cloud-architectAWS/GCP/Azure topology, IaC, multi-region design150.3
code-reviewerBug detection, quality assessment150.2
compliance-reviewerGDPR/CCPA, license auditing150.3
content-strategistContent planning, editorial calendars150.3
solutions-architectEnterprise integration, cross-team architecture150.3

Read + Shell Agents (investigation, profiling)

AgentSpecialtyTurnsTemp
accessibility-specialistWCAG compliance, ARIA review200.2
database-administratorRDBMS tuning, indexes, migration safety200.2
db2-dbaDB2 for z/OS and LUW, REORG/RUNSTATS/bind200.2
debuggerRoot cause analysis, execution tracing200.2
performance-engineerProfiling, optimization200.2
security-engineerVulnerability assessment, threat modeling200.2
seo-specialistTechnical SEO, structured data200.2
site-reliability-engineerSLOs, error budgets, runbooks, postmortems200.2
zos-sysprogz/OS systems programming, JCL, USS, RACF200.2

Read + Write Agents (documentation, design)

AgentSpecialtyTurnsTemp
copywriterMarketing copy, landing pages200.3
product-managerPRDs, user stories, prioritization200.2
prompt-engineerLLM prompt design, few-shot, RAG tuning150.3
release-managerRelease notes, changelogs, rollout planning150.3
technical-writerDocumentation, API references150.3
ux-designerUser flows, wireframes, heuristics200.2

Full Access Agents (implementation)

AgentSpecialtyTurnsTemp
analytics-engineerEvent tracking, A/B testing, funnels250.2
cobol-engineerMainframe COBOL, JCL, CICS/IMS on z/OS250.2
coderFeature implementation, SOLID principles250.2
data-engineerSchema design, ETL, migrations200.2
design-system-engineerDesign tokens, theming, component APIs250.2
devops-engineerCI/CD, containerization, infrastructure200.2
hlasm-assembler-specialistIBM HLASM for z/OS, macros, SVCs250.2
i18n-specialistInternationalization, RTL, locales200.2
ibm-i-specialistIBM i RPG/CL, DB2 for i, OS/400250.2
integration-engineerB2B APIs, ETL, message brokers (Kafka, MQ)250.2
ml-engineerModel training, feature pipelines, evaluation250.2
mlops-engineerModel registry, CI/CD for models, drift detection250.2
mobile-engineeriOS/Android/React Native/Flutter platform work250.2
observability-engineerMetrics, logs, traces, OpenTelemetry, dashboards250.2
platform-engineerInternal developer platforms, paved paths250.2
refactorCode restructuring, debt reduction250.2
testerUnit/integration/E2E tests, TDD250.2

MCP Tools Quick Reference

ToolPackPurpose
initialize_workspaceWorkspaceCreate state directories
assess_task_complexityWorkspaceRepo analysis signals
validate_planWorkspacePlan validation + dependency DAG
resolve_settingsWorkspaceSetting resolution with precedence
create_sessionSessionCreate active session
get_session_statusSessionRead session state
update_sessionSessionUpdate execution metadata
transition_phaseSessionComplete phase + start next
archive_sessionSessionMove to archive
enter_design_gateSessionMark session as entering design phase (idempotent)
record_design_approvalSessionRecord user approval of design document
get_design_gate_statusSessionRead design gate status for a session
scan_phase_changesSessionScan workspace for files changed since phase start
reconcile_phaseSessionRecord file manifests for un-handed-off phase
get_skill_contentContentServe skills/templates/references
get_agentContentServe agent methodologies
get_runtime_contextContentRuntime config snapshot