@josstei/maestro 1.6.4-rc.1

package/docs/runtime-claude.md

@@ -0,0 +1,190 @@
+# Claude Runtime
+
+The Claude Code plugin lives in the `claude/` subdirectory.
+
+## Configuration
+
+**Manifest**: `claude/.claude-plugin/plugin.json`
+**Version**: generated from `package.json`
+**Hooks**: `claude/hooks/claude-hooks.json`
+**MCP Config**: `claude/.mcp.json`
+
+### MCP Server
+
+```json
+{
+  "mcpServers": {
+    "maestro": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/maestro-server.js"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}"
+    }
+  }
+}
+```
+
+The public server at `claude/mcp/maestro-server.js` is a thin adapter. It sets `MAESTRO_RUNTIME=claude`, prefers canonical repo `src/mcp/maestro-server.js` when the plugin is loaded from a checkout, and falls back to bundled `claude/src/mcp/maestro-server.js` for detached marketplace or copied installs. Claude declares `primary: filesystem` and `fallback: none`.
+
+## Agent Naming
+
+Claude uses **kebab-case** for agent names: `code-reviewer`, `api-designer`, `accessibility-specialist`.
+
+Agent files are generated at `claude/agents/*.md` with kebab-case filenames.
+
+## Delegation
+
+Claude Code Agent subagent syntax:
+
+```
+Agent(subagent_type: "maestro:coder", prompt: "...")
+Agent(subagent_type: "maestro:architect", prompt: "...")
+```
+
+## Skills
+
+19 Markdown skills in `claude/skills/`:
+
+**Core (3)** — generated public entry points from the core command registry:
+- `orchestrate/SKILL.md`
+- `execute/SKILL.md`
+- `resume-session/SKILL.md`
+
+**Entry-point (9)** — from registry (`review`, `debug`, `resume` are remapped to `review-code`, `debug-workflow`, `resume-session` because they collide with Claude Code built-in commands; see `src/generator/entry-point-expander.js` `HOST_RESERVED_NAMES`):
+- `review-code/SKILL.md`, `debug-workflow/SKILL.md`, `archive/SKILL.md`, `status/SKILL.md`
+- `security-audit/SKILL.md`, `perf-check/SKILL.md`, `seo-audit/SKILL.md`
+- `a11y-audit/SKILL.md`, `compliance-check/SKILL.md`
+
+**Infrastructure (7)** — discovery stubs for shared skills:
+- `code-review/SKILL.md`, `delegation/SKILL.md`, `design-dialogue/SKILL.md`
+- `execution/SKILL.md`, `implementation-planning/SKILL.md`
+- `session-management/SKILL.md`, `validation/SKILL.md`
+
+Infrastructure skills have `user-invocable: false` — they surface in Claude's skill picker but delegate to MCP for content.
+
+## Hooks
+
+4 hook entries across 3 event types (2 with matchers):
+
+| Event | Matcher | Script | Timeout |
+|-------|---------|--------|---------|
+| `SessionStart` | — | `scripts/hook-runner.js claude session-start` | 10s |
+| `PreToolUse` | `Agent` | `scripts/hook-runner.js claude before-agent` | 10s |
+| `PreToolUse` | `Bash` | scripts/policy-enforcer.js | 5s |
+| `SessionEnd` | — | `scripts/hook-runner.js claude session-end` | 10s |
+
+### Key Differences from Gemini
+
+- Uses `PreToolUse` with matchers instead of `BeforeAgent`/`AfterAgent`
+- **No AfterAgent hook** — Claude does not validate handoff report format via hooks
+- Same effective timeouts (10s) but Claude config uses seconds, Gemini uses milliseconds (10000ms)
+- Policy enforcement via hook script, not TOML
+
+### Hook Adapter
+
+`claude/scripts/adapters/claude-adapter.js` normalizes Claude Code stdin:
+
+| Claude Field | Internal Field |
+|-------------|----------------|
+| `session_id` | `sessionId` |
+| `cwd` | `cwd` |
+| `hook_event_name` | `event` |
+| `tool_input.subagent_type` | `agentName` |
+| `tool_input.prompt` | `agentInput` |
+| `tool_result` | `agentResult` |
+| (hardcoded false) | `stopHookActive` |
+
+Output format: `{ continue: boolean, decision: "approve"|"block", systemMessage?: string, reason?: string }`
+
+## Policy Enforcement
+
+`claude/scripts/policy-enforcer.js` — JavaScript-based, triggered on Bash tool use:
+
+**Deny rules** (blocks command):
+- `rm -rf`, `rm -fr`, `sudo rm -rf`, `sudo rm -fr`
+- `git reset --hard`, `git checkout --`
+- `git clean -fd`, `git clean -df`, `git clean -xfd`, `git clean -xdf`
+- Heredocs (`<<`)
+
+**Ask rules** (requires user confirmation):
+- `tee` commands
+- Output redirection (`>`, `>>`)
+
+Parses compound commands (`;`, `&&`, `||`, `|`) and recursively checks subshells (`$(...)`, backticks).
+
+## Tool Mapping
+
+| Canonical | Claude |
+|-----------|--------|
+| `read_file` / `read_many_files` | `Read` |
+| `write_file` | `Write` |
+| `replace` | `Edit` |
+| `list_directory` / `glob` | `Glob` |
+| `grep_search` | `Grep` |
+| `google_web_search` | `WebSearch` |
+| `web_fetch` | `WebFetch` |
+| `run_shell_command` | `Bash` |
+| `ask_user` | `AskUserQuestion` |
+| `write_todos` | `TaskCreate`, `TaskUpdate`, `TaskList` |
+| `activate_skill` | `Skill` |
+| `enter_plan_mode` | `EnterPlanMode` |
+| `exit_plan_mode` | `ExitPlanMode` |
+| `codebase_investigator` | `Agent (Explore)` / `Grep` / `Glob` |
+
+## Feature Flags
+
+The canonical feature set (same 4 flags across all runtimes, values per runtime):
+
+```
+exampleBlocks:             true   (examples embedded in description)
+claudeStateContract:       true   (Claude-specific session-state contract)
+scriptBasedStateContract:  false
+codexStateContract:        false
+```
+
+See `src/platforms/claude/runtime-config.js` for the authoritative values.
+
+## Agent Frontmatter
+
+Claude agent stubs include example blocks in the description and use camelCase for turns:
+
+```yaml
+---
+name: coder
+description: |
+  Implementation specialist...
+  
+  <example>
+  Context: User needs a new feature implemented.
+  user: "Implement the login flow"
+  assistant: "I'll follow existing patterns..."
+  </example>
+model: inherit
+color: green
+maxTurns: 25
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+---
+```
+
+Fields: `model` (always "inherit"), `color`, `maxTurns` (camelCase). No temperature or timeout.
+
+## Generated Files
+
+```
+claude/
+├── agents/                39 agent stubs (kebab-case)
+├── skills/                19 skill directories
+├── hooks/                 1 hook config (claude-hooks.json)
+├── scripts/               thin hook wrapper, adapter wrapper, policy enforcer
+├── mcp/                   thin MCP entrypoint
+├── src/                   generated detached runtime payload for isolated installs
+├── .claude-plugin/        1 plugin manifest
+├── .mcp.json
+├── mcp-config.example.json
+└── README.md
+```

package/docs/runtime-codex.md

@@ -0,0 +1,197 @@
+# Codex Runtime
+
+The Codex plugin lives in `plugins/maestro/`.
+
+## Configuration
+
+**Manifest**: `plugins/maestro/.codex-plugin/plugin.json`
+**Version**: generated from `package.json`
+**MCP Config**: `plugins/maestro/.mcp.json`
+**App Config**: `plugins/maestro/.app.json`
+**Runtime Guide**: `plugins/maestro/references/runtime-guide.md`
+
+### MCP Server
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "-p", "@josstei/maestro@<package version>", "maestro-mcp-server"],
+  "env": { "MAESTRO_RUNTIME": "codex" }
+}
+```
+
+Codex plugin manifests lack a plugin-root substitution variable (unlike Claude's `${CLAUDE_PLUGIN_ROOT}` or Gemini's `${extensionPath}`), so relative paths in `args` would resolve against the user's workspace rather than the plugin directory. Maestro invokes the server via `npx` using the versioned npm package for the current release. The `maestro-mcp-server` bin lives in `bin/maestro-mcp-server.js` and is declared in `package.json`; it sets `MAESTRO_RUNTIME=codex` and delegates to `src/mcp/maestro-server.js`.
+
+For workspace resolution, Codex follows the shared runtime contract:
+- use `MAESTRO_WORKSPACE_PATH` when the host exports it explicitly
+- otherwise fall back to the MCP client `roots/list` response
+- only then fall back to inherited env and `cwd` heuristics
+
+That keeps Maestro state rooted under the actual workspace `docs/maestro` path regardless of where `npx` materializes the package cache.
+
+### Plugin Manifest
+
+```json
+{
+  "name": "maestro",
+  "version": "<package version>",
+  "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. ...",
+    "developerName": "josstei",
+    "category": "Coding",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://github.com/josstei/maestro-orchestrate",
+    "defaultPrompt": ["Use Maestro to orchestrate a feature...", "..."],
+    "brandColor": "#2563EB"
+  }
+}
+```
+
+## Agent Naming
+
+Codex uses **kebab-case** agent identifiers in runtime context and MCP-served methodology content, matching Claude: `code-reviewer`, `api-designer`.
+
+## Delegation
+
+Codex-native `spawn_agent(...)`:
+
+```
+spawn_agent(...)
+```
+
+The runtime guide recommends mapping Maestro agents to Codex delegation modes:
+- Evidence gathering or repo mapping → `explorer`
+- Bounded implementation → `worker`
+- No clear benefit from delegation → stay local
+
+## Skills
+
+19 Markdown skills in `plugins/maestro/skills/`:
+
+Codex keeps 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.
+
+**Core (3)** — unprefixed in the plugin, invoked as `$maestro:<name>`:
+- `orchestrate/SKILL.md`
+- `execute/SKILL.md`
+- `resume-session/SKILL.md`
+
+**Entry-point (9)** — unprefixed in the plugin, invoked as `$maestro:<name>`:
+- `review-code/SKILL.md`, `debug-workflow/SKILL.md`, `archive/SKILL.md`
+- `status/SKILL.md`, `security-audit/SKILL.md`
+- `perf-check/SKILL.md`, `seo-audit/SKILL.md`
+- `a11y-audit/SKILL.md`, `compliance-check/SKILL.md`
+
+**Infrastructure (7)** — NOT prefixed:
+- `code-review/SKILL.md`, `delegation/SKILL.md`, `design-dialogue/SKILL.md`
+- `execution/SKILL.md`, `implementation-planning/SKILL.md`
+- `session-management/SKILL.md`, `validation/SKILL.md`
+
+## Hooks
+
+**Codex has no hooks.** No hook registration exists in the plugin manifest. Delegation tracking and policy enforcement are handled through inline methodology constraints.
+
+## Policies
+
+**No policy enforcement.** Codex relies on inline constraints within skill and agent methodologies rather than runtime-level policy rules.
+
+## MCP Behavior
+
+The runtime guide states:
+
+> If Maestro MCP tools are available, prefer them for stateful operations. 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.
+
+This MCP-first with direct filesystem fallback approach exists because spawned Codex agents may not have access to the parent plugin's MCP server. When MCP is available, shared methodology and agent bodies are resolved from generated local `plugins/maestro/src/`, which is produced from canonical root `src/`; there is no hand-maintained packaged registry copy and no plugin-level `agents/` directory.
+
+## Tool Mapping
+
+Codex tools use descriptive names rather than direct API mappings:
+
+| Canonical | Codex |
+|-----------|-------|
+| `read_file` / `read_many_files` | direct file reads |
+| `write_file` / `replace` | `apply_patch` |
+| `list_directory` / `glob` | `exec_command` (rg --files, ls, find) |
+| `grep_search` | `exec_command` (rg) |
+| `google_web_search` | web search |
+| `web_fetch` | web fetch |
+| `run_shell_command` | `exec_command` |
+| `ask_user` | `request_user_input` |
+| `write_todos` | `update_plan` |
+| `activate_skill` | open the referenced skill and follow it |
+| `enter_plan_mode` | `update_plan` |
+| `exit_plan_mode` | `request_user_input` approval |
+| `codebase_investigator` | local inspection or `spawn_agent` |
+
+## Feature Flags
+
+The canonical feature set (same 4 flags across all runtimes, values per runtime):
+
+```
+exampleBlocks:             false
+claudeStateContract:       false
+scriptBasedStateContract:  false
+codexStateContract:        true
+```
+
+See `src/platforms/codex/runtime-config.js` for the authoritative values.
+
+## Path Resolution
+
+Codex uses relative paths (`relativeExtensionPath: true`):
+
+- `env.extensionPath`: `.` (plugin root)
+- `env.workspacePath`: `MAESTRO_WORKSPACE_PATH` when available
+- Path references in generated content are computed relative to the output file's location
+
+This differs from Gemini (passthrough variables) and Claude (environment variable references).
+
+When `MAESTRO_WORKSPACE_PATH` is not set, the MCP server uses the first valid local `file://` root from the client `roots/list` response before falling back to legacy env and `cwd` detection.
+
+## Canonical Filesystem Content
+
+Codex follows the same source-of-truth model as the other runtimes:
+
+- shared skills, protocols, templates, references, and agent bodies are authored in canonical root `src/`
+- generated `plugins/maestro/src/` is the detached runtime payload for published Codex bundles
+- generated `plugins/maestro/skills/` files are public entrypoints or discovery stubs only
+- Codex does not consume plugin agent files; `get_agent` serves the canonical methodology bodies
+- no tracked `plugins/maestro/lib/` mirror or bundled content registry is part of the runtime
+
+## Generated Files
+
+```
+plugins/maestro/
+├── skills/                19 skill directories
+├── src/                   generated detached runtime payload
+├── references/            1 runtime guide
+├── .codex-plugin/         1 plugin manifest
+├── .mcp.json              npx-based spawn (no local wrapper)
+├── .app.json
+└── README.md
+```
+
+The runtime server is invoked via `npx` rather than a local wrapper file, so the plugin ships no local `mcp/` directory under `plugins/maestro/`. The bin entrypoint lives in the repo root `bin/maestro-mcp-server.js`; `node scripts/generate.js` derives `plugins/maestro/.mcp.json` from `package.json` so the plugin manifest and MCP package spec stay on the same version.
+
+## Differences from Gemini and Claude
+
+| Aspect | Gemini | Claude | Codex |
+|--------|--------|--------|-------|
+| Agent names | snake_case | kebab-case | kebab-case |
+| Delegation | Direct function call | Agent subagent | spawn_agent |
+| Hooks | 4 events, no matchers | SessionStart, SessionEnd, PreToolUse + matchers | None |
+| Policies | TOML rules | JS hook enforcer | None |
+| Skill surface | N/A (commands) | 19 skills | plugin namespace `$maestro:*` |
+| Path style | Variable passthrough | Env var refs | `npx` bin |
+| Extra files | TOML policy rules | policy-enforcer | runtime guide |
+| Runtime payload | thin entrypoint only | thin entrypoint + detached `src/` payload | npx bin + detached `src/` payload |

package/docs/runtime-gemini.md

@@ -0,0 +1,170 @@
+# Gemini Runtime
+
+The Gemini CLI extension lives at the repository root. It is the primary runtime target.
+
+## Configuration
+
+**Manifest**: `gemini-extension.json`
+**Version**: generated from `package.json`
+**Context File**: `GEMINI.md`
+
+### MCP Server
+
+```json
+{
+  "command": "node",
+  "args": ["${extensionPath}/mcp/maestro-server.js"],
+  "cwd": "${extensionPath}",
+  "env": { "MAESTRO_WORKSPACE_PATH": "${workspacePath}" }
+}
+```
+
+The public server at `mcp/maestro-server.js` is a thin adapter. It sets `MAESTRO_RUNTIME=gemini`, requires canonical `src/mcp/maestro-server.js` directly, and runs the Gemini runtime against shared source in `src/`. Gemini declares `primary: filesystem` and `fallback: none`.
+
+## Agent Naming
+
+Gemini uses **snake_case** for agent names: `code_reviewer`, `api_designer`, `accessibility_specialist`.
+
+Agent files are generated at `agents/*.md` with snake_case filenames.
+
+## Delegation
+
+Direct function call syntax:
+
+```
+coder(query: "Implement the user service...")
+architect(query: "Design the auth system...")
+```
+
+## Commands
+
+12 TOML commands in `commands/maestro/`:
+
+| Command | Source |
+|---------|--------|
+| `orchestrate.toml` | Core command registry |
+| `execute.toml` | Core command registry |
+| `resume.toml` | Core command registry |
+| `review.toml` | Entry-point registry |
+| `debug.toml` | Entry-point registry |
+| `archive.toml` | Entry-point registry |
+| `status.toml` | Entry-point registry |
+| `security-audit.toml` | Entry-point registry |
+| `perf-check.toml` | Entry-point registry |
+| `seo-audit.toml` | Entry-point registry |
+| `a11y-audit.toml` | Entry-point registry |
+| `compliance-check.toml` | Entry-point registry |
+
+## Hooks
+
+4 hook events, no matchers, 10-second timeout:
+
+| Event | Script | Purpose |
+|-------|--------|---------|
+| `SessionStart` | `hooks/hook-runner.js gemini session-start` | Initialize hook state, prune stale sessions |
+| `BeforeAgent` | `hooks/hook-runner.js gemini before-agent` | Detect agent, inject session context |
+| `AfterAgent` | `hooks/hook-runner.js gemini after-agent` | Validate Task Report + Downstream Context |
+| `SessionEnd` | `hooks/hook-runner.js gemini session-end` | Clean up hook state |
+
+### AfterAgent Validation
+
+Gemini has a post-delegation validation hook that Claude lacks:
+
+- Checks for `## Task Report` (or `# Task Report`) and `## Downstream Context` headings
+- First failure: blocks and requests retry
+- Second failure (stopHookActive=true): allows through with warning
+
+### Hook Adapter
+
+`hooks/adapters/gemini-adapter.js` normalizes Gemini CLI JSON input:
+
+| Gemini Field | Internal Field |
+|-------------|----------------|
+| `session_id` | `sessionId` |
+| `cwd` | `cwd` |
+| `hook_event_name` | `event` |
+| (hardcoded null) | `agentName` |
+| `prompt` | `agentInput` |
+| `prompt_response` | `agentResult` |
+| `stop_hook_active` | `stopHookActive` |
+
+Output format: `{ continue: boolean, systemMessage?: string }`
+
+## Policies
+
+`policies/maestro.toml` — TOML-based shell guardrails evaluated by Gemini's native policy engine:
+
+**Deny (priority 950)**:
+- `rm -rf`, `rm -fr`, `sudo rm -rf`, `sudo rm -fr`
+- `git reset --hard`, `git checkout --`
+- `git clean -fd`, `git clean -df`, `git clean -xfd`, `git clean -xdf`
+- Heredocs (`<<`)
+
+**Ask User (priority 850)**:
+- `tee` commands
+- Output redirection (`>`, `>>`)
+
+## Tool Mapping
+
+Gemini tools use canonical names (identity mapping):
+
+| Canonical | Gemini |
+|-----------|--------|
+| `read_file` | `read_file` |
+| `read_many_files` | `read_file (called per-file)` |
+| `list_directory` | `list_directory` |
+| `glob` | `glob` |
+| `grep_search` | `grep_search` |
+| `google_web_search` | `google_web_search` |
+| `web_fetch` | `web_fetch` |
+| `write_file` | `write_file` |
+| `replace` | `replace` |
+| `run_shell_command` | `run_shell_command` |
+| `ask_user` | `ask_user` |
+| `write_todos` | `not available — track progress in model context` |
+| `activate_skill` | `activate_skill` |
+| `enter_plan_mode` | `enter_plan_mode` |
+| `exit_plan_mode` | `exit_plan_mode` |
+| `codebase_investigator` | `codebase_investigator` |
+
+## Feature Flags
+
+The canonical feature set (same 4 flags across all runtimes, values per runtime):
+
+```
+exampleBlocks:             false
+claudeStateContract:       false
+scriptBasedStateContract:  true
+codexStateContract:        false
+```
+
+See `src/platforms/gemini/runtime-config.js` for the authoritative values.
+
+## Agent Frontmatter
+
+Gemini agent stubs include:
+
+```yaml
+---
+name: coder
+kind: local
+description: "..."
+tools: [read_file, write_file, ...]
+temperature: 0.2
+max_turns: 25
+timeout_mins: 10
+---
+```
+
+Fields: `kind` (always "local"), `temperature`, `max_turns`, `timeout_mins`.
+
+## Generated Files
+
+```
+agents/                    39 agent stubs (snake_case)
+commands/maestro/          12 TOML commands
+hooks/                     thin hook runner, adapter wrapper, hooks.json
+mcp/                       thin MCP entrypoint
+policies/                  1 TOML policy file
+README.md, GEMINI.md, gemini-extension.json, .geminiignore
+```