maestro-orchestrate

Added

• 5 new MCP tools (Session pack 5 → 10; total pack count 12 → 17):
  • enter_design_gate, record_design_approval, get_design_gate_status — server-side design-gate lifecycle; create_session now enforces approval before session creation
  • scan_phase_changes, reconcile_phase — post-hoc phase reconciliation when an agent's actual file manifest diverges from the plan
• 17 additional specialist agents — Expanded the roster from 22 to 39 specialists:
  • ML / AI: ml-engineer, mlops-engineer, prompt-engineer
  • Ops / reliability: site-reliability-engineer, observability-engineer, release-manager
  • Platform: cloud-architect, platform-engineer, solutions-architect, integration-engineer
  • Data / mobile: database-administrator, mobile-engineer
  • Mainframe / legacy: cobol-engineer, db2-dba, zos-sysprog, hlasm-assembler-specialist, ibm-i-specialist
• maestro-mcp-server bin (bin/maestro-mcp-server.js) — Thin Node entrypoint declared in package.json bin; sets MAESTRO_RUNTIME=codex and MAESTRO_EXTENSION_PATH, then delegates to src/mcp/maestro-server.js. Invoked by Codex via npx.
• Root-level Codex marketplace manifest (.agents/plugins/marketplace.json) — Makes the repo a valid marketplace target for codex marketplace add.
• Declarative requiresWorkspace tool contract — Tool schemas carry requiresWorkspace: true when they depend on an initialized workspace; the registry captures the metadata and the dispatcher enforces it before handler invocation, returning a typed WORKSPACE_NOT_INITIALIZED error that names initialize_workspace in the recovery message.
• Workspace marker file module — initialize_workspace now writes a canonical marker and requireExplicitWorkspaceRoot rejects extension-cache paths.
• Content variant for design-gate and implementation-plan submission — record_design_approval accepts design_document_content + design_document_filename; create_session accepts implementation_plan_content + implementation_plan_filename. Bytes are materialized atomically into <state_dir>/plans/ by the server. Motivation: Gemini Plan Mode resolves relative paths against ~/.gemini/tmp/<uuid>/, so a path the model hands back to MCP never resolves to the same file the server sees — the content variant bypasses runtime-specific path resolution.
• Shared plan-phase schema contract (src/mcp/contracts/plan-schema.js) — Single source of truth for phase shape consumed by both validate_plan and create_session. phase.files is recognized as the planning-time canonical file manifest and is checked by file_overlap and agent_capability_mismatch validators.
• downstream-context contract module (src/mcp/contracts/downstream-context.js) — Canonical handoff shape: accepts string or array, handles 'none'/'n/a'/empty-string sentinels, and embeds a human-readable shape description in the HANDOFF_INCOMPLETE error.
• Runtime delegation.constraints object — Per-runtime machine-readable constraints exposed via get_runtime_context. Codex declares deferred results and fork-incompatibility with agent_type/model/reasoning_effort; Claude, Gemini, and Qwen declare synchronous dispatch.
• Blocker parser for child-agent question surfacing — Agents emit a Blockers: section in their handoff report; the orchestrator surfaces unresolved blockers back to the user.
• workspace_suggestion in get_runtime_context — Server surfaces a recommended workspace path for runtimes that cannot auto-resolve one.
• Per-entry runtimeNames — Each entry-point registry entry owns its per-runtime rename declaratively; replaces the centralized ENTRY_POINT_NAME_OVERRIDES map.
• Host-reserved command protection extended to Claude — Entry-point generation now rejects names that would shadow Claude's built-in slash commands (review, debug, resume). Previously only Codex was guarded.

Added

• Qwen Code runtime support (#26) — Fourth runtime target with hook adapter, extension manifest (qwen-extension.json), context file (QWEN.md), 22 agent stubs, and hooks.json for SubagentStart/SubagentStop lifecycle events
• getExitCode(result) adapter contract (#42) — Each hook adapter now owns its exit code semantics; shared exit-codes.js constants (EXIT_SUCCESS, EXIT_BLOCK) verified against Gemini CLI, Claude Code, and Codex CLI source
• npm publishing workflows — Nightly (cron), preview (PR label), RC (release PR), and stable release pipelines with NPM_TOKEN gating
• Community standards — Code of Conduct (Contributor Covenant v2.1), Contributing Guide, Security Policy, issue/PR templates
• CI/CD pipeline documentation (docs/cicd.md) — Mermaid workflow diagrams, job breakdowns, release pipeline chain, and cross-references from existing docs
• lib/ foundation layer — 6 shared modules (errors, io, naming, frontmatter, validation, discovery) extracted from duplicated implementations across the codebase
• Exhaustive test coverage — 121 tests across 22 files wired into CI; previously only transforms and integration tests ran in CI
• Build-time auto-discovered registries — agent-registry.json, resource-registry.json, hook-registry.json scanned at generate time, replacing hardcoded allowlists

Changed

• Thin multi-runtime entrypoints — Replaced generated canonical-source.js, MCP entrypoint, hook-runner, and adapter copies with hand-authored wrappers that default MAESTRO_RUNTIME per runtime and use bounded repo-first / bundled-fallback resolution for detached Claude and Codex installs
• Generator architecture (src/manifest.js, scripts/generate.js) — Simplified the manifest to 2 discovery rules, reduced the generation-time transform registry from 10 entries to 4, and added an explicit detached-payload pack step for claude/src/ and plugins/maestro/src/
• Generator decomposed — 807-line monolith split into focused modules: file-writer, manifest-expander, stale-pruner, payload-builder, registry-scanner, entry-point-expander
• Codex plugin packaging — Removed unused plugins/maestro/agents/ stubs; Codex now relies on skills, MCP tools, and get_agent for methodology instead of plugin-level agent files
• Centralized policy rules — Claude policy-enforcer imports from canonical src/core/policy-rules.js with bundled fallback; deduplicated readBoundedStdin into core/stdin-reader.js
• Lazy-loaded runtime configs — Runtime configs loaded on demand with per-runtime detached payload filtering
• Minimum Node.js version — Raised to 20 (Node 18 EOL); engines field declared in package.json
• Package renamed — From @maestro-orchestrator/gemini-extension to @maestro-orchestrator/maestro
• Runtime documentation — Updated Gemini, Claude, and Codex runtime docs to describe thin entrypoints plus detached payloads rather than generated helper copies
• Documentation aligned — All docs updated to match post-consolidation codebase state

Fixed

• Codex public skill naming collisions — Renamed the public Codex skills to $maestro:review-code, $maestro:debug-workflow, and $maestro:resume-session so installing Maestro does not shadow or break Codex's built-in /review, /debug, and /resume commands
• LLM string-to-integer coercion — Phase IDs sent as strings by LLMs in transition_phase now parsed correctly before phase lookups

Added

• Self-contained Claude runtime payload (src/manifest.js) — Added 'claude' to the self-contained runtime payload manifest rule (already used by Codex) so the full src/ tree is bundled into claude/src/; canonical-source resolution now succeeds from plugin caches outside the repo tree
• withIsolatedClaudePlugin test helper (tests/integration/helpers.js) — Copies the generated claude/ directory into an isolated temp directory for testing plugin behavior outside the repo tree; mirrors the existing withIsolatedCodexPlugin helper
• Isolated Claude bundle integration tests — Hook entrypoint boot test, MCP server startup test, MCP tool listing and content serving tests, all running against an isolated plugin bundle

Fixed

• Claude plugin canonical-source resolution from plugin cache — requireFromCanonicalSrc(__dirname) in hook scripts (session-start.js, before-agent.js, session-end.js) and MCP entry-point walked up from ~/.claude/plugins/cache/ looking for src/mcp/maestro-server.js but never found it because the Claude runtime did not bundle src/; resolved by the self-contained payload rule above

Added

• Codex runtime target (plugins/maestro/) — Complete third runtime for OpenAI Codex with plugin manifest, 22 agent stubs, 19 skills, MCP entry-point, and runtime guide; agents use kebab-case names and spawn_agent(...) delegation
• Canonical source architecture — Single src/ tree serves all three runtimes (Gemini, Claude, Codex) via requireFromCanonicalSrc() dynamic resolution, eliminating verbatim lib copies and runtime-specific source directories
• get_agent MCP tool — Returns agent methodology content by name, enabling runtime access to agent definitions without filesystem reads
• get_runtime_context MCP tool — Returns runtime-specific configuration (delegation patterns, tool mappings, environment variables) for the active platform
• Entry-point generation system (src/entry-points/) — Registry of 9 entry-point commands with 3 per-runtime templates (Gemini TOML, Claude SKILL.md, Codex SKILL.md); entry-point commands are now generated rather than hand-maintained
• 4 new transforms — agent-stub (generates lightweight stubs that load methodology via MCP), inline-runtime (injects runtime-specific content blocks), skill-discovery-stub (generates skill stubs that load content via MCP), copy (verbatim file copy)
• canonical-source.js utility (src/core/) — requireFromCanonicalSrc() resolves the canonical src/ directory from any runtime entry-point by walking parent directories; deployed as thin shims in each runtime's mcp/ and scripts/ directories
• project-root-resolver.js rewrite (src/core/) — Multi-strategy workspace resolution supporting all three runtimes: env vars (MAESTRO_WORKSPACE_PATH, CLAUDE_PROJECT_DIR), git root detection, and cwd fallback
• Justfile — Development commands: just test, just check, just test-transforms, just test-integration; replaces ad-hoc npm scripts
• Documentation suite (docs/) — 7 focused docs replacing old plans/specs: overview.md, architecture.md, flow.md, usage.md, runtime-gemini.md, runtime-claude.md, runtime-codex.md
• 27 new test files — MCP handler tests (content provider, runtime context, kernel, session pack, workspace pack, content pack, pack composition), transform tests (copy, index, project-root-resolver), integration tests (entry-point templates, hook entry-points, glob manifest, source of truth, MCP server bundle behavior, MCP server entry-point, MCP stdio client helper)
• CI release workflow (.github/workflows/release.yml) — Automated GitHub releases from version tags using CHANGELOG.md content

Changed

• MCP server decomposed — Monolithic ~38k-line bundles (mcp/maestro-server.js, claude/mcp/maestro-server.js) replaced by ~14-line entry-points delegating to modular src/mcp/ tree: 8 handlers, 3 tool-packs (workspace, session, content), core modules (server creation, tool registry, recovery hints), and utilities (extension root resolution)
• Generator rewrite (scripts/generate.js) — Updated to support manifest expansion with glob patterns, transform pipeline across three runtimes, entry-point rendering from templates, platform file mapping, and stale file pruning
• src/manifest.js expanded — Glob patterns, per-runtime platform file mappings, entry-point generation rules, and self-contained Codex src/ payload rules
• Codex skill names — Dropped maestro- prefix from all skill names; skills use plugin namespace directly ($maestro:orchestrate instead of $maestro:maestro-orchestrate)
• Shared skills restructured — All 7 methodology skills (delegation, design-dialogue, execution, implementation-planning, session-management, code-review, validation) updated to load protocols and references via get_skill_content MCP tool instead of filesystem reads
• Agent methodologies — All 22 agents updated with explicit tool access declarations in frontmatter; Claude and Codex runtimes serve methodology content via MCP at runtime ra