@josstei/maestro 1.6.4-rc.1

package/plugins/maestro/.codex-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "maestro",
+  "version": "1.6.4-rc.1",
+  "description": "Generated Codex runtime for Maestro's multi-agent design, planning, execution, and review workflows.",
+  "author": {
+    "name": "josstei",
+    "email": "hello@josstei.dev",
+    "url": "https://github.com/josstei"
+  },
+  "homepage": "https://github.com/josstei/maestro-orchestrate",
+  "repository": "https://github.com/josstei/maestro-orchestrate",
+  "license": "Apache-2.0",
+  "keywords": [
+    "orchestration",
+    "multi-agent",
+    "planning",
+    "execution",
+    "coding"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Maestro",
+    "shortDescription": "Multi-agent coding orchestration for Codex",
+    "longDescription": "Generated Codex runtime for Maestro. Shared methodology, templates, references, and agent personas stay aligned with the Gemini CLI and Claude Code runtimes while Codex-specific delegation and state handling stay isolated to this plugin.",
+    "developerName": "josstei",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/josstei/maestro-orchestrate",
+    "defaultPrompt": [
+      "Use Maestro to orchestrate a feature from design through implementation and review.",
+      "Use Maestro to review my changes and block on critical or major findings.",
+      "Use Maestro to debug a failing workflow and route investigation to the right specialist."
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/plugins/maestro/.mcp.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@josstei/maestro@1.6.4-rc.1",
+        "maestro-mcp-server"
+      ],
+      "env": {
+        "MAESTRO_RUNTIME": "codex"
+      }
+    }
+  }
+}

package/plugins/maestro/README.md

@@ -0,0 +1,57 @@
+# Maestro for Codex
+
+This directory is the generated Codex runtime for Maestro.
+
+## Installation
+
+1. Register the marketplace:
+
+   ```bash
+   codex plugin marketplace add josstei/maestro-orchestrate
+   ```
+
+2. Start Codex (or restart if already open), run `/plugins` to browse, select **Maestro**, and choose **Install**.
+
+For local development (path must start with `./`, `../`, `/`, or `~/` — Codex otherwise treats bare `owner/repo` as a GitHub source):
+
+```bash
+git clone https://github.com/josstei/maestro-orchestrate
+codex plugin marketplace add /absolute/path/to/maestro-orchestrate
+# then: start Codex, run `/plugins`, select Maestro → Install
+```
+
+## Architecture
+
+Codex shares the same canonical `src/` source tree as the Gemini CLI and Claude Code outputs:
+- shared methodology, references, templates, hooks, and MCP server logic are authored only in `src/`
+- this plugin contains public entry skills, manifests, thin adapters, and a generated `./src/` runtime payload derived from canonical `src/`
+- Codex-specific behavior is isolated to this plugin's runtime guide and public entry skills, exposed under the plugin namespace as `$maestro:<skill>`
+- Codex does not consume plugin agent files; Maestro serves agent methodology through MCP `get_agent`
+
+## Public skills
+
+- `orchestrate`
+- `execute`
+- `resume-session`
+- `status`
+- `archive`
+- `review-code`
+- `debug-workflow`
+- `security-audit`
+- `perf-check`
+- `seo-audit`
+- `a11y-audit`
+- `compliance-check`
+
+## Runtime notes
+
+- Shared methodology, references, templates, and agent bodies are authored in root `src/` and mirrored into generated `./src/` for detached Codex installs.
+- Maestro session state lives in `docs/maestro` in the workspace root.
+- Codex resolves that workspace root from `MAESTRO_WORKSPACE_PATH` when available, otherwise from the MCP client `roots/list` response, before falling back to legacy env or `cwd` detection.
+- The plugin ships `.mcp.json` for MCP-first operation, but the generated skills also include direct filesystem fallbacks under `docs/maestro` when MCP tools are unavailable.
+- Custom Codex subagents normally live in `.codex/agents`. This plugin does not write there; `get_agent` serves the canonical methodology bodies directly.
+- Codex keeps its built-in `/review`, `/debug`, and `/resume` commands; Maestro exposes `$maestro:review-code`, `$maestro:debug-workflow`, and `$maestro:resume-session` to avoid those collisions.
+
+## Alignment goal
+
+Codex is treated as a third generated runtime, not a separate implementation. If behavior changes, update shared `src/` first and regenerate.

package/plugins/maestro/references/runtime-guide.md

@@ -0,0 +1,125 @@
+# Maestro Codex Runtime Guide
+
+This guide explains how the shared Maestro methodology maps onto Codex.
+
+## Source of truth
+
+- Shared skills, references, templates, and agent bodies are authored in repository `src/`.
+- Published Codex bundles carry a generated local `src/` payload derived from that canonical source tree, so installs remain self-contained.
+- Codex content loading is filesystem-only and should resolve against the generated local `src/` in the plugin bundle.
+- Generated agent role references under `../agents/` are registration stubs only.
+
+Public Codex skills should load shared assets through MCP instead of duplicating methodology. Codex adds the plugin namespace at invocation time, so these surface as `$maestro:<skill>`.
+
+Codex also reserves built-in `/review`, `/debug`, and `/resume` commands, so Maestro exposes `$maestro:review-code`, `$maestro:debug-workflow`, and `$maestro:resume-session` instead of those bare names.
+
+## State contract
+
+Maestro state lives in `docs/maestro` in the workspace root:
+
+- active session: `docs/maestro/state/active-session.md`
+- plans: `docs/maestro/plans/`
+- archives: `docs/maestro/state/archive/`, `docs/maestro/plans/archive/`
+
+Resolve that workspace root in this order:
+
+1. `MAESTRO_WORKSPACE_PATH`, when the host exports it and it points to a real path
+2. the first valid local `file://` root returned by the MCP client `roots/list` request
+3. inherited env or `cwd` fallback heuristics from the shared resolver
+
+If MCP tools are unavailable, operate directly on the files under `docs/maestro` in the workspace root.
+
+## Tool mapping
+
+Translate bare tool references from shared skills as follows:
+
+| Shared reference | Codex equivalent |
+| --- | --- |
+| `activate_skill` | Read the referenced `SKILL.md` and follow it |
+| `ask_user` | `request_user_input`; use a direct question only when structured options do not fit |
+| `write_todos` | `update_plan` |
+| `enter_plan_mode` | `update_plan` plus direct document writing |
+| `exit_plan_mode` | explicit approval via `request_user_input` |
+| `run_shell_command` | `exec_command` |
+| `write_file` / `replace` | `apply_patch` |
+| `codebase_investigator` | local repo inspection first, then Codex-native delegation if needed |
+
+Prefer direct file reads for local content. When search is needed, use fast local commands such as `rg`, `rg --files`, `find`, `sed`, and `git diff` through `exec_command`.
+
+## MCP behavior
+
+If Maestro MCP tools are available, prefer them for stateful operations:
+
+- `initialize_workspace`
+- `resolve_settings`
+- `assess_task_complexity`
+- `create_session`
+- `get_session_status`
+- `update_session`
+- `transition_phase`
+- `archive_session`
+- `validate_plan`
+
+If the MCP server is unavailable in the current Codex environment, fall back to direct file operations under `docs/maestro` as described by the shared skills.
+
+## Delegation model
+
+Codex plugin bundles do not register Maestro custom subagents by themselves. Use Codex-native delegation and keep the generated agent references as the behavioral contract:
+
+1. Call `get_agent` with the kebab-case agent name to load the Maestro persona and declared tool restrictions.
+2. Map that Maestro persona onto the best built-in Codex delegation mode available.
+3. Preserve the Maestro agent name in the prompt header and handoff reporting.
+
+Recommended mapping:
+
+- evidence gathering or repo mapping: `explorer`
+- bounded implementation: `worker`
+- no clear benefit from delegation: stay local
+
+When delegating, include the relevant agent reference content or instructions from that file. Do not invent a separate Codex-only methodology for the same agent.
+
+## Public skill surface
+
+Use these entry points for user-facing workflows:
+
+- `orchestrate`
+- `execute`
+- `resume-session`
+- `status`
+- `archive`
+- `review-code`
+- `debug-workflow`
+- `security-audit`
+- `perf-check`
+- `seo-audit`
+- `a11y-audit`
+- `compliance-check`
+
+## Codex-specific constraints
+
+### spawn_agent fork incompatibility
+
+`spawn_agent` rejects full-history forks when any of `agent_type`, `model`, or `reasoning_effort` are supplied. This applies to both `fork_context: true` (v1) and `fork_turns: "all"` (v2).
+
+Exact error:
+
+    Full-history forked agents inherit the parent agent type, model, and reasoning effort; omit agent_type, model, and reasoning_effort, or spawn without fork_context/fork_turns=all.
+
+Resolution: read `delegation.constraints.fork_full_context_incompatible_with` from `get_runtime_context` and omit those fields when forking with full history. Alternatively, spawn without `fork_context`/`fork_turns=all` and pass self-contained prompts.
+
+### request_user_input availability
+
+`request_user_input` is Plan-mode-gated. Spawned child agents inherit their parent's mode, which is typically not Plan. Child agents therefore cannot call `request_user_input`.
+
+Consequence for Maestro: only the orchestrator agent can ask the user questions. Child agents must surface questions through the Blocker Protocol documented in the delegation skill (`## Blockers` section in the Task Report).
+
+### spawn_agent return surface
+
+`spawn_agent` returns `{agent_id, task_name, nickname}` only — no token usage, no assistant text, no structured error. To retrieve results:
+
+1. Call `wait_agent(agent_id, timeout)` to poll for completion.
+2. On timeout, invoke the Recovery Protocol (execution skill): `scan_phase_changes` → user confirmation → `reconcile_phase`.
+
+### Hooks
+
+Codex does not expose PreToolUse / BeforeAgent / AfterAgent hooks to plugins. Maestro does not rely on hooks under Codex; handoff-format enforcement, design-gate tracking, and reconciliation are all enforced by the MCP server.

package/plugins/maestro/skills/a11y-audit/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: a11y-audit
+description: Run a Maestro-style accessibility audit for WCAG compliance, ARIA usage, keyboard navigation, and screen reader compatibility
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "delegation"].
+Call `get_agent` with agents: ["accessibility-specialist"].
+
+## Workflow
+
+1. Define the accessibility audit scope and target conformance level (A, AA, AAA)
+2. Identify UI components, pages, and interactive elements
+3. Audit WCAG compliance: ARIA usage, keyboard navigation, focus management, color contrast, screen reader compatibility
+4. Present findings with WCAG criterion reference, severity, user impact, location, and remediation code patterns
+5. Note any manual verification gaps if the environment cannot exercise the UI directly

package/plugins/maestro/skills/archive/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: archive
+description: Archive the active Maestro session while preserving the shared state layout
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "session-management"].
+
+## Workflow
+
+1. Check for an active session; if none exists, inform the user there is nothing to archive
+2. Present a brief summary of what will be archived (session ID, task, phase progress)
+3. Ask the user to confirm archival (the session may have incomplete phases)
+4. Move the active session file into the state archive directory
+5. Move the associated design and implementation plan files into the plans archive directory
+6. Verify that no active-session file remains and report the archived paths

package/plugins/maestro/skills/code-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: code-review
+description: Standalone code review methodology for structured, severity-classified code assessment
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["code-review"])`.

package/plugins/maestro/skills/compliance-check/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: compliance-check
+description: Run a Maestro-style regulatory compliance review for GDPR/CCPA, cookie consent, data handling, and licensing
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "delegation"].
+Call `get_agent` with agents: ["compliance-reviewer"].
+
+## Workflow
+
+1. Identify applicable regulations and define audit scope
+2. Review data handling patterns, user disclosures, consent flows, retention policies, and third-party integrations
+3. Audit regulatory compliance: GDPR/CCPA, cookie consent, data residency, licensing, and open-source obligations
+4. Present findings with regulatory reference, severity, compliance risk, and recommended actions
+5. Distinguish legal-risk observations from code-level bugs

package/plugins/maestro/skills/debug-workflow/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: debug-workflow
+description: Run the Maestro debugging workflow for investigation-heavy tasks
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "delegation"].
+Call `get_agent` with agents: ["debugger"].
+
+## Workflow
+
+1. Establish the failing behavior, repro path, and expected behavior
+2. Form concrete hypotheses (2-3 likely root causes)
+3. Gather evidence from code, logs, tests, and runtime behavior before proposing fixes
+4. Isolate the most likely root cause and trace the execution path from trigger to failure
+5. Verify the conclusion explains all symptoms and present the recommended fix with specific code location

package/plugins/maestro/skills/delegation/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: delegation
+description: Agent delegation best practices for constructing effective subagent prompts with proper scoping
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["delegation"])`.

package/plugins/maestro/skills/design-dialogue/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: design-dialogue
+description: Guides structured design conversations for complex engineering tasks
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["design-dialogue"])`.

package/plugins/maestro/skills/execute/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: execute
+description: Execute an approved Maestro implementation plan using the shared session-state contract
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["execution", "delegation", "session-management", "validation"].
+
+## Startup
+
+1. If `get_runtime_context` appears in your available tools, call it first.
+2. Prefer Maestro MCP tools for settings, workspace initialization, session status, planning validation, and session transitions.
+3. If MCP tools are unavailable, use direct file operations under `docs/maestro`.
+4. Treat `docs/maestro` as the workspace state root.
+
+Read the approved implementation plan at the user-provided path (or check `docs/maestro/plans/` for the most recent plan). Resolve the execution mode gate, create or resume session state, then execute phases through child agents following the loaded methodology.

package/plugins/maestro/skills/execution/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: execution
+description: Phase execution methodology for orchestration workflows with error handling and completion protocols
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["execution"])`.

package/plugins/maestro/skills/implementation-planning/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: implementation-planning
+description: Generates detailed implementation plans from finalized designs
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["implementation-planning"])`.

package/plugins/maestro/skills/orchestrate/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: orchestrate
+description: Run the full Maestro workflow for complex engineering tasks that need a mandatory design dialogue, approved implementation plan, and then execution with shared session state
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["orchestration-steps"].
+
+## Startup
+
+1. If `get_runtime_context` appears in your available tools, call it first.
+2. Prefer Maestro MCP tools for settings, workspace initialization, session status, planning validation, and session transitions.
+3. If MCP tools are unavailable, use direct file operations under `docs/maestro`.
+4. Treat `docs/maestro` as the workspace state root.
+
+Follow the returned step sequence exactly. The steps are the sole procedural authority — do not improvise, skip, or reorder them.

package/plugins/maestro/skills/perf-check/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: perf-check
+description: Run a Maestro-style performance assessment for hotspots, regressions, and optimization planning
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "delegation"].
+Call `get_agent` with agents: ["performance-engineer"].
+
+## Workflow
+
+1. Define the performance target or pain point
+2. Establish the current baseline from available code, metrics, or reproducible commands
+3. Identify likely hotspots, structural bottlenecks, and hot loops through code analysis
+4. Prioritize fixes by expected impact versus implementation cost
+5. Report measurement gaps when hard evidence is unavailable and propose a validation plan

package/plugins/maestro/skills/resume-session/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: resume-session
+description: Resume an interrupted Maestro session using the existing active-session file and shared phase tracking
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["session-management", "execution", "delegation", "validation"].
+
+## Startup
+
+1. If `get_runtime_context` appears in your available tools, call it first.
+2. Prefer Maestro MCP tools for settings, workspace initialization, session status, planning validation, and session transitions.
+3. If MCP tools are unavailable, use direct file operations under `docs/maestro`.
+4. Treat `docs/maestro` as the workspace state root.
+
+Read the active session state, summarize completed and pending phases, then resume from the first pending or failed phase following the loaded methodology.

package/plugins/maestro/skills/review-code/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: review-code
+description: Perform a Maestro-style code review with findings ordered by severity and concrete file references
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "delegation", "code-review"].
+Call `get_agent` with agents: ["code-reviewer"].
+
+## Workflow
+
+1. Determine review scope: explicit user-provided paths, staged changes, or last commit diff
+2. Delegate to the code-reviewer agent with the diff content and file paths
+3. Review for correctness, regressions, security, maintainability risk, and missing tests
+4. Classify findings by severity (Critical, Major, Minor, Suggestion) with concrete file and line references
+5. Present findings first, ordered by severity; keep the closing summary brief and only after findings

package/plugins/maestro/skills/security-audit/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: security-audit
+description: Run a Maestro-style security assessment for authentication, authorization, data exposure, secret handling, and exploitability risks
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "delegation"].
+Call `get_agent` with agents: ["security-engineer"].
+
+## Workflow
+
+1. Define the audit scope from the user request and relevant code paths
+2. Trace trust boundaries, auth flows, secret handling, and data exposure paths
+3. Review for exploitable flaws, unsafe defaults, OWASP Top 10 vulnerabilities, and high-risk dependencies
+4. Classify findings by severity (CVSS-aligned) with file references and exploitability assessment
+5. Provide remediation guidance with the highest-risk issues first

package/plugins/maestro/skills/seo-audit/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: seo-audit
+description: Run a Maestro-style SEO assessment for meta tags, structured data, crawlability, and Core Web Vitals
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "delegation"].
+Call `get_agent` with agents: ["seo-specialist"].
+
+## Workflow
+
+1. Define the SEO audit scope (page or site)
+2. Identify web-facing output files (HTML, templates, routes)
+3. Audit meta tags, schema markup, crawlability, canonicalization, internal linking, and Core Web Vitals
+4. Present findings with severity, SEO impact, location, and remediation guidance
+5. Note any checks that require live-site verification if the current environment cannot provide it

package/plugins/maestro/skills/session-management/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: session-management
+description: Manages orchestration session state, tracking, and resumption
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["session-management"])`.

package/plugins/maestro/skills/status/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: status
+description: Summarize the active Maestro session without mutating state
+---
+
+Read `../../references/runtime-guide.md`.
+Call `get_skill_content` with resources: ["architecture", "session-management"].
+
+## Workflow
+
+1. Read the active session using MCP state tools if available; otherwise fall back to scripts or direct file read
+2. Report session ID, creation timestamp, workflow mode, and overall status
+3. Show phase breakdown: completed phases with timestamps, current active phase, pending phases, and failed phases with error summaries
+4. Report file manifest (files created, modified, deleted), token usage by agent, and unresolved errors

package/plugins/maestro/skills/validation/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: validation
+description: Cross-cutting validation methodology for verifying phase outputs and project integrity
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["validation"])`.