@josstei/maestro 1.6.4-rc.1

package/src/platforms/codex/metadata.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const {
+  buildAuthor,
+  renderJson,
+} = require('../metadata-shared');
+
+function buildCodexMarketplace() {
+  return {
+    name: 'maestro-orchestrator',
+    interface: {
+      displayName: 'Maestro Orchestrator',
+    },
+    plugins: [
+      {
+        name: 'maestro',
+        source: {
+          source: 'local',
+          path: './plugins/maestro',
+        },
+        policy: {
+          installation: 'AVAILABLE',
+          authentication: 'ON_INSTALL',
+        },
+        category: 'Coding',
+      },
+    ],
+  };
+}
+
+function buildCodexPluginManifest(context) {
+  return {
+    name: 'maestro',
+    version: context.version,
+    description: "Generated Codex runtime for Maestro's multi-agent design, planning, execution, and review workflows.",
+    author: buildAuthor(context),
+    homepage: context.homepage,
+    repository: context.repository,
+    license: context.license,
+    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: context.author.name,
+      category: 'Coding',
+      capabilities: [
+        'Interactive',
+        'Write',
+      ],
+      websiteURL: context.homepage,
+      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',
+    },
+  };
+}
+
+function buildCodexMcpConfig(context) {
+  return {
+    mcpServers: {
+      maestro: {
+        command: 'npx',
+        args: ['-y', '-p', `${context.packageName}@${context.version}`, 'maestro-mcp-server'],
+        env: {
+          MAESTRO_RUNTIME: 'codex',
+        },
+      },
+    },
+  };
+}
+
+function buildMetadataOutputs(context) {
+  return [
+    {
+      outputPath: '.agents/plugins/marketplace.json',
+      content: renderJson(buildCodexMarketplace(context)),
+    },
+    {
+      outputPath: 'plugins/maestro/.codex-plugin/plugin.json',
+      content: renderJson(buildCodexPluginManifest(context)),
+    },
+    {
+      outputPath: 'plugins/maestro/.mcp.json',
+      content: renderJson(buildCodexMcpConfig(context)),
+    },
+  ];
+}
+
+module.exports = {
+  buildCodexMarketplace,
+  buildCodexMcpConfig,
+  buildCodexPluginManifest,
+  buildMetadataOutputs,
+};

package/src/platforms/codex/runtime-config.js

@@ -0,0 +1,58 @@
+module.exports = {
+  name: 'codex',
+  outputDir: 'plugins/maestro/',
+
+  agentNaming: 'kebab-case',
+
+  env: {
+    extensionPath: '.',
+    workspacePath: 'MAESTRO_WORKSPACE_PATH',
+  },
+
+  relativeExtensionPath: true,
+
+  content: {
+    primary: 'filesystem',
+    fallback: 'none',
+  },
+
+  tools: {
+    read_file: 'direct file reads',
+    list_directory: 'exec_command (`rg --files` or `ls`)',
+    glob: 'exec_command (`rg --files` or `find`)',
+    grep_search: 'exec_command (`rg`)',
+    google_web_search: 'web search',
+    web_fetch: 'web fetch',
+    write_file: 'apply_patch',
+    replace: 'apply_patch',
+    run_shell_command: 'exec_command',
+    ask_user: 'request_user_input',
+    read_many_files: 'direct file reads',
+    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',
+  },
+
+  delegation: {
+    pattern: 'spawn_agent(...)',
+    constraints: {
+      fork_full_context_incompatible_with: ['agent_type', 'model', 'reasoning_effort'],
+      result_surface: 'deferred',
+      child_cannot_prompt_user: true,
+    },
+  },
+
+  features: {
+    exampleBlocks: false,
+    claudeStateContract: false,
+    scriptBasedStateContract: false,
+    codexStateContract: true,
+  },
+
+  paths: {
+    skills: './skills/',
+    hooks: './scripts/',
+  },
+};

package/src/platforms/gemini/metadata.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const {
+  buildExtensionManifest,
+  renderJson,
+} = require('../metadata-shared');
+
+function buildGeminiExtensionManifest(context) {
+  return buildExtensionManifest(context, {
+    contextFileName: 'GEMINI.md',
+    runtime: 'gemini',
+  });
+}
+
+function buildMetadataOutputs(context) {
+  return [
+    {
+      outputPath: 'gemini-extension.json',
+      content: renderJson(buildGeminiExtensionManifest(context)),
+    },
+  ];
+}
+
+module.exports = {
+  buildGeminiExtensionManifest,
+  buildMetadataOutputs,
+};

package/src/platforms/gemini/runtime-config.js

@@ -0,0 +1,62 @@
+module.exports = {
+  name: 'gemini',
+  outputDir: './',
+
+  agentNaming: 'snake_case',
+
+  env: {
+    extensionPath: 'extensionPath',
+    workspacePath: null,
+  },
+
+  content: {
+    primary: 'filesystem',
+    fallback: 'none',
+  },
+
+  tools: {
+    read_file: 'read_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',
+    read_many_files: 'read_file (called per-file)',
+    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',
+  },
+
+  agentFrontmatter: {
+    kind: 'local',
+    turnsField: 'max_turns',
+    hasTemperature: true,
+    hasTimeout: true,
+  },
+
+  delegation: {
+    pattern: '{{agent}}(query: "...")',
+    constraints: {
+      result_surface: 'synchronous',
+      child_cannot_prompt_user: false,
+    },
+  },
+
+  features: {
+    exampleBlocks: false,
+    claudeStateContract: false,
+    scriptBasedStateContract: true,
+    codexStateContract: false,
+  },
+
+  paths: {
+    skills: '${extensionPath}/skills/',
+    hooks: '${extensionPath}/hooks/',
+  },
+};

package/src/platforms/metadata-shared.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const RUNTIME_DESCRIPTION = 'Multi-agent development orchestration platform — 39 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands';
+
+function renderJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function normalizeRepositoryUrl(repository) {
+  if (!repository) {
+    return null;
+  }
+
+  const url = typeof repository === 'string' ? repository : repository.url;
+  if (typeof url !== 'string' || url.length === 0) {
+    return null;
+  }
+
+  return url.replace(/\.git$/, '');
+}
+
+function requirePackageField(pkg, field) {
+  if (!pkg || typeof pkg[field] !== 'string' || pkg[field].length === 0) {
+    throw new Error(`package.json missing ${field}`);
+  }
+
+  return pkg[field];
+}
+
+function buildMetadataContext(pkg) {
+  const repository = normalizeRepositoryUrl(pkg.repository);
+
+  if (!repository) {
+    throw new Error('package.json missing repository URL');
+  }
+
+  return {
+    packageName: requirePackageField(pkg, 'name'),
+    version: requirePackageField(pkg, 'version'),
+    author: pkg.author || {},
+    homepage: requirePackageField(pkg, 'homepage'),
+    repository,
+    license: requirePackageField(pkg, 'license'),
+  };
+}
+
+function buildSettings() {
+  return [
+    {
+      name: 'Disabled Agents',
+      description: 'Comma-separated list of agent names to exclude from implementation planning.',
+      envVar: 'MAESTRO_DISABLED_AGENTS',
+    },
+    {
+      name: 'Max Retries',
+      description: 'Maximum retry attempts per phase before escalating to user.',
+      envVar: 'MAESTRO_MAX_RETRIES',
+    },
+    {
+      name: 'Auto Archive',
+      description: 'Automatically archive session state on successful completion (true/false).',
+      envVar: 'MAESTRO_AUTO_ARCHIVE',
+    },
+    {
+      name: 'Validation',
+      description: 'Post-phase validation strictness level (strict/normal/lenient).',
+      envVar: 'MAESTRO_VALIDATION_STRICTNESS',
+    },
+    {
+      name: 'State Directory',
+      description: 'Base directory for session state and plans (default: docs/maestro).',
+      envVar: 'MAESTRO_STATE_DIR',
+    },
+    {
+      name: 'Max Concurrent',
+      description: 'Maximum subagents emitted in one native parallel batch turn (0 = dispatch the entire ready batch).',
+      envVar: 'MAESTRO_MAX_CONCURRENT',
+    },
+    {
+      name: 'Execution Mode',
+      description: "Phase 3 execution mode: 'parallel' (native concurrent subagents), 'sequential' (one at a time), or 'ask' (prompt each time). Default: ask.",
+      envVar: 'MAESTRO_EXECUTION_MODE',
+    },
+  ];
+}
+
+function buildExtensionMcpServer(runtime) {
+  const env = {};
+
+  if (runtime === 'qwen' || runtime === 'gemini') {
+    env.MAESTRO_WORKSPACE_PATH = '${workspacePath}';
+  }
+
+  return {
+    command: 'node',
+    args: ['${extensionPath}/mcp/maestro-server.js'],
+    cwd: '${extensionPath}',
+    env,
+  };
+}
+
+function buildExtensionManifest(context, options) {
+  return {
+    name: 'maestro',
+    version: context.version,
+    description: RUNTIME_DESCRIPTION,
+    contextFileName: options.contextFileName,
+    settings: buildSettings(),
+    mcpServers: {
+      maestro: buildExtensionMcpServer(options.runtime),
+    },
+  };
+}
+
+function buildAuthor(context) {
+  return {
+    name: context.author.name,
+    email: context.author.email,
+    url: context.author.url,
+  };
+}
+
+module.exports = {
+  RUNTIME_DESCRIPTION,
+  buildAuthor,
+  buildExtensionManifest,
+  buildMetadataContext,
+  buildSettings,
+  normalizeRepositoryUrl,
+  renderJson,
+};

package/src/platforms/metadata.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const path = require('node:path');
+const { buildMetadataContext } = require('./metadata-shared');
+
+function loadMetadataBuilder(runtimeName) {
+  return require(path.join(__dirname, runtimeName, 'metadata.js'));
+}
+
+function buildPlatformMetadataOutputs(runtimes, pkg) {
+  const context = buildMetadataContext(pkg);
+  const outputs = [];
+
+  for (const runtimeName of Object.keys(runtimes).sort()) {
+    const metadata = loadMetadataBuilder(runtimeName);
+    if (typeof metadata.buildMetadataOutputs !== 'function') {
+      continue;
+    }
+
+    outputs.push(...metadata.buildMetadataOutputs(context));
+  }
+
+  return outputs;
+}
+
+module.exports = {
+  buildPlatformMetadataOutputs,
+  loadMetadataBuilder,
+};

package/src/platforms/qwen/metadata.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const {
+  buildExtensionManifest,
+  renderJson,
+} = require('../metadata-shared');
+
+function buildQwenExtensionManifest(context) {
+  return buildExtensionManifest(context, {
+    contextFileName: 'QWEN.md',
+    runtime: 'qwen',
+  });
+}
+
+function buildMetadataOutputs(context) {
+  return [
+    {
+      outputPath: 'qwen-extension.json',
+      content: renderJson(buildQwenExtensionManifest(context)),
+    },
+  ];
+}
+
+module.exports = {
+  buildMetadataOutputs,
+  buildQwenExtensionManifest,
+};

package/src/platforms/qwen/runtime-config.js

@@ -0,0 +1,62 @@
+module.exports = {
+  name: 'qwen',
+  outputDir: 'qwen/',
+
+  agentNaming: 'snake_case',
+
+  env: {
+    extensionPath: 'extensionPath',
+    workspacePath: 'workspacePath',
+  },
+
+  content: {
+    primary: 'filesystem',
+    fallback: 'none',
+  },
+
+  tools: {
+    read_file: 'read_file',
+    list_directory: 'list_directory',
+    glob: 'glob',
+    grep_search: 'grep_search',
+    google_web_search: 'web_search',
+    web_fetch: 'web_fetch',
+    write_file: 'write_file',
+    replace: 'edit',
+    run_shell_command: 'run_shell_command',
+    ask_user: 'ask_user_question',
+    read_many_files: 'read_many_files',
+    write_todos: 'todo_write',
+    activate_skill: 'skill',
+    enter_plan_mode: 'enter_plan_mode',
+    exit_plan_mode: 'exit_plan_mode',
+    codebase_investigator: 'codebase_investigator',
+  },
+
+  agentFrontmatter: {
+    kind: 'local',
+    turnsField: 'max_turns',
+    hasTemperature: true,
+    hasTimeout: true,
+  },
+
+  delegation: {
+    pattern: '{{agent}}(query: "...")',
+    constraints: {
+      result_surface: 'synchronous',
+      child_cannot_prompt_user: false,
+    },
+  },
+
+  features: {
+    exampleBlocks: false,
+    claudeStateContract: false,
+    scriptBasedStateContract: true,
+    codexStateContract: false,
+  },
+
+  paths: {
+    skills: '${extensionPath}/skills/',
+    hooks: '${extensionPath}/hooks/',
+  },
+};

package/src/platforms/shared/adapters/claude-adapter.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { defineAdapter } = require('./factory');
+
+/**
+ * Claude Code hook I/O adapter.
+ * Normalizes Claude Code stdin JSON to the internal context contract
+ * and formats internal responses for Claude Code stdout.
+ */
+
+function normalizeInput(raw) {
+  return {
+    sessionId: raw.session_id || '',
+    cwd: raw.cwd || '',
+    event: raw.hook_event_name || '',
+    agentName: raw.tool_input?.subagent_type || null,
+    agentInput: raw.tool_input?.prompt || null,
+    agentResult: raw.tool_result || null,
+    stopHookActive: false,
+  };
+}
+
+function formatOutput(result) {
+  return {
+    continue: result.action !== 'deny',
+    systemMessage: result.message || result.reason || undefined,
+    decision: result.action === 'deny' ? 'block' : 'approve',
+    reason: result.reason || undefined,
+  };
+}
+
+function errorFallback() {
+  return { continue: false, decision: 'block' };
+}
+
+module.exports = defineAdapter({ normalizeInput, formatOutput, errorFallback });

package/src/platforms/shared/adapters/conventions.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/** @type {string} */
+const ADAPTER_SUFFIX = '-adapter.js';
+
+/**
+ * Determine whether a filename follows the adapter naming convention.
+ * Accepts bare filenames only — paths with directory separators return false.
+ * @param {string} filename - Base filename (no directory components)
+ * @returns {boolean} True when filename matches the {runtime}-adapter.js pattern
+ */
+function isAdapterFile(filename) {
+  return filename.endsWith(ADAPTER_SUFFIX) && !filename.includes('/');
+}
+
+/**
+ * Extract the runtime name from an adapter filename.
+ * @param {string} filename - Base filename matching the adapter convention
+ * @returns {string|null} Runtime name (e.g. 'claude'), or null if filename
+ *   does not match the adapter convention
+ */
+function extractRuntime(filename) {
+  if (!isAdapterFile(filename)) {
+    return null;
+  }
+  return filename.slice(0, -ADAPTER_SUFFIX.length);
+}
+
+module.exports = { ADAPTER_SUFFIX, isAdapterFile, extractRuntime };

package/src/platforms/shared/adapters/exit-codes.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const EXIT_SUCCESS = 0;
+const EXIT_BLOCK = 2;
+
+module.exports = { EXIT_SUCCESS, EXIT_BLOCK };

package/src/platforms/shared/adapters/factory.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const { readBoundedJson } = require('../../../core/stdin-reader');
+const { EXIT_SUCCESS } = require('./exit-codes');
+
+/**
+ * Adapter contract expected by `hook-runner.js`:
+ *   normalizeInput(raw)  -> ctx       (runtime stdin -> internal context)
+ *   formatOutput(result) -> object    (internal result -> runtime stdout)
+ *   errorFallback()      -> object    (emitted on uncaught adapter errors)
+ *   readBoundedStdin()   -> Promise   (parse stdin as JSON, bounded size)
+ *   getExitCode(result)  -> number    (process exit code; defaults to 0)
+ *
+ * `defineAdapter` is a spec-assembler: it validates a caller-provided
+ * spec and fills in shared defaults (stdin reader, success-exit fallback)
+ * so each runtime adapter only declares its protocol-specific
+ * normalize/format/fallback/exit logic. Registry dispatch by runtime
+ * name is done separately by `hook-runner.js`.
+ */
+function defineAdapter(spec) {
+  if (!spec || typeof spec.normalizeInput !== 'function') {
+    throw new TypeError('Adapter spec must provide normalizeInput(raw)');
+  }
+  if (typeof spec.formatOutput !== 'function') {
+    throw new TypeError('Adapter spec must provide formatOutput(result)');
+  }
+  if (typeof spec.errorFallback !== 'function') {
+    throw new TypeError('Adapter spec must provide errorFallback()');
+  }
+
+  return {
+    normalizeInput: spec.normalizeInput,
+    formatOutput: spec.formatOutput,
+    errorFallback: spec.errorFallback,
+    readBoundedStdin: spec.readBoundedStdin || readBoundedJson,
+    getExitCode: spec.getExitCode || (() => EXIT_SUCCESS),
+  };
+}
+
+module.exports = { defineAdapter };

package/src/platforms/shared/adapters/gemini-adapter.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { defineAdapter } = require('./factory');
+
+/**
+ * Gemini hook I/O adapter.
+ * Normalizes Gemini stdin JSON to the internal context contract
+ * and formats internal responses for Gemini stdout.
+ */
+
+function normalizeInput(raw) {
+  return {
+    sessionId: raw.session_id || '',
+    cwd: raw.cwd || '',
+    event: raw.hook_event_name || '',
+    agentName: null,
+    agentInput: raw.prompt || '',
+    agentResult: raw.prompt_response || '',
+    stopHookActive: raw.stop_hook_active === true || raw.stop_hook_active === 'true',
+  };
+}
+
+function formatOutput(result) {
+  return {
+    continue: result.action !== 'deny',
+    systemMessage: result.message || result.reason || undefined,
+  };
+}
+
+function errorFallback() {
+  return { continue: false };
+}
+
+module.exports = defineAdapter({ normalizeInput, formatOutput, errorFallback });