@josstei/maestro 1.6.4-rc.1

package/qwen/agents/technical_writer.md

@@ -0,0 +1,19 @@
+---
+name: technical_writer
+kind: local
+description: "Technical writing specialist for documentation, API references, and architectural diagrams. Use when the task requires writing README files, API documentation, architecture decision records, or inline documentation. For example: writing an OpenAPI description, creating a getting-started guide, or documenting module interfaces."
+max_turns: 15
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - write_file
+  - edit
+  - read_many_files
+  - web_search
+  - ask_user_question
+  - todo_write
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["technical-writer"])` to read the full methodology at delegation time.

package/qwen/agents/tester.md

@@ -0,0 +1,21 @@
+---
+name: tester
+kind: local
+description: "Testing specialist for unit tests, integration tests, test coverage analysis, and TDD workflows. Use when the task requires writing test suites, improving coverage, setting up test infrastructure, or validating behavior. For example: writing unit tests for a service class, setting up integration test fixtures, or creating end-to-end test scenarios."
+max_turns: 25
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - write_file
+  - edit
+  - run_shell_command
+  - todo_write
+  - skill
+  - read_many_files
+  - ask_user_question
+  - web_search
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["tester"])` to read the full methodology at delegation time.

package/qwen/agents/ux_designer.md

@@ -0,0 +1,18 @@
+---
+name: ux_designer
+kind: local
+description: "UX designer for user flow design, interaction patterns, wireframe descriptions, and usability evaluation. Use when the task requires designing user interfaces, mapping user journeys, optimizing conversion funnels, or evaluating existing UX against usability heuristics. For example: designing an onboarding flow, wireframing a dashboard layout, or auditing checkout abandonment."
+max_turns: 20
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - write_file
+  - edit
+  - web_search
+  - read_many_files
+  - ask_user_question
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["ux-designer"])` to read the full methodology at delegation time.

package/qwen/agents/zos_sysprog.md

@@ -0,0 +1,19 @@
+---
+name: zos_sysprog
+kind: local
+description: "z/OS systems programming specialist for JCL, USS, SMP/E, RACF, subsystem diagnostics, and batch scheduling. Use when the task requires JCL authoring or review, z/OS Unix System Services setup, SMP/E maintenance, RACF profile review, or diagnosing SYSLOG/OPERLOG issues. For example: writing a JCL restart procedure, planning an SMP/E PTF install, or reviewing RACF dataset profiles for least privilege."
+max_turns: 20
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - run_shell_command
+  - web_search
+  - read_many_files
+  - todo_write
+  - ask_user_question
+  - web_fetch
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["zos-sysprog"])` to read the full methodology at delegation time.

package/qwen/hooks.json

@@ -0,0 +1,56 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${extensionPath}/hooks/hook-runner.js qwen session-start",
+            "name": "maestro-session-start-qwen",
+            "description": "Initialize hook state and prune stale sessions (Qwen Code)",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${extensionPath}/hooks/hook-runner.js qwen before-agent",
+            "name": "maestro-before-agent-qwen",
+            "description": "Inject session context into agent turns (Qwen Code)",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${extensionPath}/hooks/hook-runner.js qwen after-agent",
+            "name": "maestro-after-agent-qwen",
+            "description": "Validate handoff report format with retry on malformed output (Qwen Code)",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${extensionPath}/hooks/hook-runner.js qwen session-end",
+            "name": "maestro-session-end-qwen",
+            "description": "Clean up hook state for ended session (Qwen Code)",
+            "timeout": 10000
+          }
+        ]
+      }
+    ]
+  }
+}

package/qwen-extension.json

@@ -0,0 +1,55 @@
+{
+  "name": "maestro",
+  "version": "1.6.4-rc.1",
+  "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",
+  "contextFileName": "QWEN.md",
+  "settings": [
+    {
+      "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"
+    }
+  ],
+  "mcpServers": {
+    "maestro": {
+      "command": "node",
+      "args": [
+        "${extensionPath}/mcp/maestro-server.js"
+      ],
+      "cwd": "${extensionPath}",
+      "env": {
+        "MAESTRO_WORKSPACE_PATH": "${workspacePath}"
+      }
+    }
+  }
+}

package/scripts/check-layer-boundaries.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LIB_DIR = path.resolve(__dirname, '..', 'src', 'lib');
+
+function collectJsFiles(dir) {
+  const results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectJsFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function scanFile(filepath) {
+  const content = fs.readFileSync(filepath, 'utf8');
+  const requirePattern = /require\(['"]([^'"]+)['"]\)/g;
+  const violations = [];
+  let match;
+
+  while ((match = requirePattern.exec(content)) !== null) {
+    const modPath = match[1];
+
+    if (modPath.startsWith('node:')) {
+      continue;
+    }
+
+    if (modPath.startsWith('.')) {
+      const resolved = path.resolve(path.dirname(filepath), modPath);
+      if (!resolved.startsWith(LIB_DIR)) {
+        violations.push({
+          file: path.relative(process.cwd(), filepath),
+          import: modPath,
+          resolved: path.relative(process.cwd(), resolved),
+        });
+      }
+      continue;
+    }
+
+    violations.push({
+      file: path.relative(process.cwd(), filepath),
+      import: modPath,
+      reason: 'non-relative, non-node import',
+    });
+  }
+
+  return violations;
+}
+
+const files = collectJsFiles(LIB_DIR);
+const allViolations = [];
+
+for (const file of files) {
+  allViolations.push(...scanFile(file));
+}
+
+if (allViolations.length > 0) {
+  console.error('Layer boundary violations in src/lib/:');
+  for (const v of allViolations) {
+    const detail = v.reason || `resolves to ${v.resolved}`;
+    console.error(`  ${v.file}: require('${v.import}') — ${detail}`);
+  }
+  process.exit(1);
+} else {
+  console.log(`Layer boundaries clean: ${files.length} files scanned, 0 violations.`);
+}

package/scripts/generate.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { resolve: resolveTransform } = require('../src/transforms');
+const { createGenerationSession } = require('../src/generator/generation-session');
+const { expandManifest, assertNoMirroredSharedOutputs, buildRuntimeOutputPath } = require('../src/generator/manifest-expander');
+const { pruneStaleFiles } = require('../src/generator/stale-pruner');
+const { buildDetachedPayload, stampVersion, buildPayloadAllowlist, shouldIncludeInPayload, shouldDescendInto } = require('../src/generator/payload-builder');
+const { collectRegistryOutputs } = require('../src/generator/registry-scanner');
+const { expandEntryPoints, expandCoreCommands } = require('../src/generator/entry-point-expander');
+const { collectManifestPaths } = require('../src/generator/manifest-curator');
+const { buildPlatformMetadataOutputs } = require('../src/platforms/metadata');
+
+const ROOT = path.resolve(__dirname, '..');
+const SRC = path.join(ROOT, 'src');
+const OWNED_DIRS = ['agents', 'claude/agents', 'claude/skills', 'plugins/maestro/skills', 'commands'];
+const ENTRY_POINT_EXPANDERS = [expandEntryPoints, expandCoreCommands];
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const diffMode = args.includes('--diff');
+const cleanMode = args.includes('--clean');
+
+function loadRuntimes() {
+  const runtimes = {};
+  const configs = fs.readdirSync(path.join(SRC, 'platforms'), { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== 'shared')
+    .map((e) => path.join(e.name, 'runtime-config.js'))
+    .filter((rel) => fs.existsSync(path.join(SRC, 'platforms', rel)));
+  for (const file of configs) {
+    const config = require(path.join(SRC, 'platforms', file));
+    runtimes[config.name] = config;
+  }
+  return runtimes;
+}
+
+function processManifestEntry(entry, runtimes, session) {
+  const srcPath = path.join(SRC, entry.src);
+  if (!fs.existsSync(srcPath)) {
+    session.reportError(`Source not found: ${entry.src}`);
+    return;
+  }
+
+  const sourceContent = fs.readFileSync(srcPath, 'utf8');
+  for (const [runtimeName, outputPath] of Object.entries(entry.outputs)) {
+    const runtime = runtimes[runtimeName];
+    if (!runtime) {
+      session.reportError(`Unknown runtime "${runtimeName}" for ${entry.src}`);
+      continue;
+    }
+
+    try {
+      let content = sourceContent;
+      const state = {};
+      for (const transformName of entry.transforms) {
+        const { fn, param } = resolveTransform(transformName);
+        content = fn(content, runtime, { src: entry.src, param, outputPath, state });
+      }
+      session.write(outputPath, content);
+    } catch (err) {
+      session.reportError(`processing ${entry.src} -> ${outputPath}`, err);
+    }
+  }
+}
+
+function processEntryPoints(runtimes, session) {
+  for (const fn of ENTRY_POINT_EXPANDERS) {
+    for (const runtimeName of Object.keys(runtimes)) {
+      for (const { outputPath, content } of fn(runtimeName, SRC)) {
+        session.write(outputPath, content);
+      }
+    }
+  }
+}
+
+function readPackageMetadata() {
+  return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+}
+
+async function main() {
+  const runtimes = loadRuntimes();
+  const packageMetadata = readPackageMetadata();
+  const manifestRules = require(path.join(SRC, 'manifest'));
+  const manifest = expandManifest(manifestRules, runtimes, SRC);
+  assertNoMirroredSharedOutputs(manifest);
+
+  const session = createGenerationSession({ rootDir: ROOT, dryRun, diffMode });
+  session.writeAll(collectRegistryOutputs(SRC, ROOT));
+
+  if (cleanMode) {
+    session.clean(manifest.flatMap((entry) => Object.values(entry.outputs)));
+  }
+
+  if (cleanMode && !session.isReadOnlyMode()) {
+    console.log('Cleaned all generator-owned files.');
+  }
+
+  for (const entry of manifest) {
+    processManifestEntry(entry, runtimes, session);
+  }
+
+  processEntryPoints(runtimes, session);
+  session.writeAll(buildPlatformMetadataOutputs(runtimes, packageMetadata));
+
+  const stats = session.getStats();
+
+  if (dryRun) {
+    console.log('\n(dry-run — no files written)');
+  } else if (!diffMode) {
+    console.log(`\nGeneration complete: ${stats.written} written, ${stats.unchanged} unchanged, ${stats.errors} errors`);
+  }
+
+  if (!session.isReadOnlyMode()) {
+    const manifestPaths = collectManifestPaths(manifest, runtimes, SRC, ENTRY_POINT_EXPANDERS);
+    const { pruned } = pruneStaleFiles({ rootDir: ROOT, manifestPaths, ownedDirs: OWNED_DIRS });
+    if (pruned.length > 0) {
+      console.log('\nPruning stale files (not in manifest):');
+      for (const f of pruned) console.log(`  PRUNED: ${f}`);
+    }
+
+    const claudePayloadDir = path.join(ROOT, 'claude', 'src');
+    const codexPayloadDir = path.join(ROOT, 'plugins', 'maestro', 'src');
+    const claudeStats = buildDetachedPayload(SRC, claudePayloadDir, 'claude');
+    const codexStats = buildDetachedPayload(SRC, codexPayloadDir, 'codex');
+    stampVersion([claudePayloadDir, codexPayloadDir], packageMetadata.version);
+    console.log(
+      `\nDetached payloads: claude/src (${claudeStats.copied} updated, ${claudeStats.removed} removed), ` +
+      `plugins/maestro/src (${codexStats.copied} updated, ${codexStats.removed} removed)`
+    );
+  }
+
+  if (stats.errors > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('Generator failed:', err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  assertNoMirroredSharedOutputs,
+  buildPayloadAllowlist,
+  buildRuntimeOutputPath,
+  buildDetachedPayload,
+  expandCoreCommands,
+  buildPlatformMetadataOutputs,
+  expandManifest,
+  expandEntryPoints,
+  shouldDescendInto,
+  shouldIncludeInPayload,
+};

package/scripts/install-codex-plugin.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..');
+const SOURCE_PLUGIN_DIR = path.join(ROOT, 'plugins', 'maestro');
+const TARGET_PLUGIN_DIR = path.join(os.homedir(), '.codex', 'plugins', 'maestro');
+const MARKETPLACE_FILE = path.join(os.homedir(), '.agents', 'plugins', 'marketplace.json');
+
+const DEFAULT_MARKETPLACE = {
+  name: 'maestro-orchestrator',
+  interface: {
+    displayName: 'Maestro Orchestrator',
+  },
+  plugins: [],
+};
+
+const PLUGIN_ENTRY = {
+  name: 'maestro',
+  source: {
+    source: 'local',
+    path: './.codex/plugins/maestro',
+  },
+  policy: {
+    installation: 'AVAILABLE',
+    authentication: 'ON_INSTALL',
+  },
+  category: 'Coding',
+};
+
+function printHelp() {
+  console.log(`Install Maestro into Codex's personal plugin marketplace.
+
+Usage:
+  node scripts/install-codex-plugin.js [--dry-run]
+
+Options:
+  --dry-run   Show planned changes without writing files
+  --help      Show this help text
+`);
+}
+
+function parseArgs(argv) {
+  const args = new Set(argv);
+
+  if (args.has('--help') || args.has('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  for (const arg of args) {
+    if (!['--dry-run', '--help', '-h'].includes(arg)) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return {
+    dryRun: args.has('--dry-run'),
+  };
+}
+
+function assertSourcePlugin() {
+  const manifestPath = path.join(SOURCE_PLUGIN_DIR, '.codex-plugin', 'plugin.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`Source plugin manifest not found: ${manifestPath}`);
+  }
+}
+
+function readMarketplace() {
+  if (!fs.existsSync(MARKETPLACE_FILE)) {
+    return {
+      marketplace: JSON.parse(JSON.stringify(DEFAULT_MARKETPLACE)),
+      existed: false,
+    };
+  }
+
+  const raw = fs.readFileSync(MARKETPLACE_FILE, 'utf8');
+  let marketplace;
+  try {
+    marketplace = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Failed to parse ${MARKETPLACE_FILE}: ${error.message}`);
+  }
+
+  if (!marketplace || typeof marketplace !== 'object' || Array.isArray(marketplace)) {
+    throw new Error(`Expected ${MARKETPLACE_FILE} to contain a JSON object`);
+  }
+
+  if (!Array.isArray(marketplace.plugins)) {
+    throw new Error(`Expected ${MARKETPLACE_FILE} to contain a plugins array`);
+  }
+
+  if (!marketplace.name) {
+    marketplace.name = DEFAULT_MARKETPLACE.name;
+  }
+
+  if (!marketplace.interface || typeof marketplace.interface !== 'object') {
+    marketplace.interface = { ...DEFAULT_MARKETPLACE.interface };
+  } else if (!marketplace.interface.displayName) {
+    marketplace.interface.displayName = DEFAULT_MARKETPLACE.interface.displayName;
+  }
+
+  return {
+    marketplace,
+    existed: true,
+  };
+}
+
+function upsertPluginEntry(marketplace) {
+  const nextEntry = JSON.parse(JSON.stringify(PLUGIN_ENTRY));
+  const existingIndex = marketplace.plugins.findIndex((plugin) => plugin && plugin.name === 'maestro');
+
+  if (existingIndex >= 0) {
+    marketplace.plugins[existingIndex] = nextEntry;
+  } else {
+    marketplace.plugins.push(nextEntry);
+  }
+
+  return existingIndex >= 0 ? 'updated' : 'added';
+}
+
+function writeMarketplace(marketplace) {
+  fs.mkdirSync(path.dirname(MARKETPLACE_FILE), { recursive: true });
+  fs.writeFileSync(MARKETPLACE_FILE, `${JSON.stringify(marketplace, null, 2)}\n`);
+}
+
+function installPluginCopy() {
+  fs.mkdirSync(path.dirname(TARGET_PLUGIN_DIR), { recursive: true });
+  fs.rmSync(TARGET_PLUGIN_DIR, { recursive: true, force: true });
+  fs.cpSync(SOURCE_PLUGIN_DIR, TARGET_PLUGIN_DIR, { recursive: true });
+}
+
+function printSummary({ dryRun, marketplaceExisted, pluginAction }) {
+  const mode = dryRun ? 'Dry run complete.' : 'Maestro installed for Codex.';
+  const marketplaceStatus = marketplaceExisted ? 'updated' : 'created';
+
+  console.log(mode);
+  console.log(`Plugin source: ${SOURCE_PLUGIN_DIR}`);
+  console.log(`Plugin target: ${TARGET_PLUGIN_DIR}`);
+  console.log(`Marketplace: ${MARKETPLACE_FILE} (${marketplaceStatus}, plugin ${pluginAction})`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('1. Start Codex or restart it if already open.');
+  console.log('2. Run `/plugins`.');
+  console.log('3. Search for `Maestro` and select `Install plugin`.');
+}
+
+function main() {
+  const { dryRun } = parseArgs(process.argv.slice(2));
+
+  assertSourcePlugin();
+
+  const { marketplace, existed: marketplaceExisted } = readMarketplace();
+  const pluginAction = upsertPluginEntry(marketplace);
+
+  if (!dryRun) {
+    installPluginCopy();
+    writeMarketplace(marketplace);
+  }
+
+  printSummary({ dryRun, marketplaceExisted, pluginAction });
+}
+
+main();

package/scripts/install-git-hooks.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Postinstall step that activates the repo-local git hooks under .githooks/.
+ *
+ * Activation conditions (all must hold):
+ *   1. Current directory contains .githooks/ — i.e. we are in the maestro
+ *      source tree, not a downstream npm consumer's node_modules entry
+ *      (.githooks is intentionally excluded from the published `files:` list).
+ *   2. `git rev-parse --show-toplevel` resolves to the current directory —
+ *      this is true in the main checkout AND in any git worktree pointing
+ *      at it. False outside a git checkout entirely.
+ *
+ * If either condition fails, the script exits 0 with no side effect.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const HOOKS_DIR = '.githooks';
+
+if (!fs.existsSync(HOOKS_DIR)) {
+  process.exit(0);
+}
+
+let topLevel;
+try {
+  topLevel = execSync('git rev-parse --show-toplevel', {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+} catch {
+  process.exit(0);
+}
+
+if (path.resolve(topLevel) !== path.resolve('.')) {
+  process.exit(0);
+}
+
+execSync(`git config core.hooksPath ${HOOKS_DIR}`, { stdio: 'inherit' });
+console.log(`postinstall: git hooks activated (${HOOKS_DIR}/)`);