@josstei/maestro 1.6.4-rc.1

package/src/mcp/validation/agent-checker.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const {
+  KNOWN_AGENTS,
+  normalizeAgentName,
+  getAgentCapability,
+  canCreateFiles,
+} = require('../../core/agent-registry');
+
+const CREATION_SIGNAL_PATTERNS =
+  /\b(implement|create|build|scaffold|write|generate|set\s*up|develop)\b/i;
+
+/**
+ * Verify each phase's declared agent is known to the registry.
+ */
+function checkUnknownAgents(phases) {
+  const violations = [];
+  for (const phase of phases) {
+    const normalizedAgent = normalizeAgentName(phase.agent);
+    if (normalizedAgent && !KNOWN_AGENTS.includes(normalizedAgent)) {
+      violations.push({
+        rule: 'unknown_agent',
+        detail: `Phase ${phase.id}: unknown agent "${phase.agent}" (normalized: "${normalizedAgent}")`,
+        severity: 'error',
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Catch mismatches between an agent's write capability and a phase's
+ * file-touching workload. Read-only agents assigned to phases that
+ * declare `files` (planning-time), `files_created`, or `files_modified`
+ * emit an error; read-only agents assigned to phases whose name hints
+ * at creation emit a warning.
+ */
+function checkAgentCapabilities(phases) {
+  const violations = [];
+  for (const phase of phases) {
+    const normalizedAgent = normalizeAgentName(phase.agent);
+    if (!normalizedAgent) {
+      continue;
+    }
+
+    const touchesFiles =
+      (Array.isArray(phase.files) && phase.files.length > 0) ||
+      (Array.isArray(phase.files_created) && phase.files_created.length > 0) ||
+      (Array.isArray(phase.files_modified) && phase.files_modified.length > 0);
+
+    if (touchesFiles && !canCreateFiles(normalizedAgent)) {
+      violations.push({
+        rule: 'agent_capability_mismatch',
+        detail: `Phase ${phase.id}: agent '${phase.agent}' (${getAgentCapability(
+          normalizedAgent
+        )}) cannot deliver file-creating tasks. Use a write-capable agent (coder, data_engineer, etc.) or split into analysis + implementation phases.`,
+        severity: 'error',
+      });
+      continue;
+    }
+
+    if (
+      !touchesFiles &&
+      getAgentCapability(normalizedAgent) === 'read_only' &&
+      phase.name &&
+      CREATION_SIGNAL_PATTERNS.test(phase.name)
+    ) {
+      violations.push({
+        rule: 'agent_capability_mismatch',
+        detail: `Phase ${phase.id}: agent '${phase.agent}' (read_only) assigned to phase '${phase.name}' which may require file creation. Verify this agent can deliver the phase's requirements.`,
+        severity: 'warning',
+      });
+    }
+  }
+  return violations;
+}
+
+module.exports = {
+  checkUnknownAgents,
+  checkAgentCapabilities,
+};

package/src/mcp/validation/dag-checker.js

@@ -0,0 +1,214 @@
+'use strict';
+
+const { StateError } = require('../../lib/errors');
+
+/**
+ * Compute the topological depth (longest incoming dependency chain) for
+ * each phase. Throws if a cycle is reached — callers should run cycle
+ * detection first.
+ *
+ * @returns {Record<string|number, number>} phase id -> depth (root phases have depth 0)
+ */
+function computeDepths(phases, phaseById) {
+  const depthMap = {};
+
+  function getDepth(id) {
+    if (depthMap[id] !== undefined) {
+      return depthMap[id];
+    }
+
+    const phase = phaseById.get(id);
+    if (!phase || !phase.blocked_by || phase.blocked_by.length === 0) {
+      depthMap[id] = 0;
+      return 0;
+    }
+
+    depthMap[id] = -1;
+    const maxBlockerDepth = Math.max(
+      ...phase.blocked_by.map((blockedPhaseId) => {
+        const depth = getDepth(blockedPhaseId);
+        if (depth === -1) {
+          throw new StateError('computeDepths: unexpected cycle detected');
+        }
+        return depth;
+      })
+    );
+    depthMap[id] = maxBlockerDepth + 1;
+    return depthMap[id];
+  }
+
+  for (const phase of phases) {
+    getDepth(phase.id);
+  }
+
+  return depthMap;
+}
+
+/**
+ * Compute the transitive closure of phase dependencies (reachable blockers).
+ * Memoized via the optional `memo` parameter so repeated callers share state.
+ */
+function getTransitiveDependencies(phaseId, phaseById, memo = {}) {
+  if (memo[phaseId]) {
+    return memo[phaseId];
+  }
+
+  const phase = phaseById.get(phaseId);
+  if (!phase || !phase.blocked_by || phase.blocked_by.length === 0) {
+    memo[phaseId] = new Set();
+    return memo[phaseId];
+  }
+
+  const result = new Set();
+  for (const dependencyId of phase.blocked_by) {
+    result.add(dependencyId);
+    for (const transitiveDependency of getTransitiveDependencies(
+      dependencyId,
+      phaseById,
+      memo
+    )) {
+      result.add(transitiveDependency);
+    }
+  }
+
+  memo[phaseId] = result;
+  return result;
+}
+
+/**
+ * Depth-first cycle detection. Emits a single `cyclic_dependency`
+ * violation identifying the first phase at which a back-edge was found.
+ */
+function checkCycles(phases, phaseById) {
+  const violations = [];
+  const visited = new Set();
+  const inStack = new Set();
+
+  function hasCycle(id) {
+    if (inStack.has(id)) {
+      return true;
+    }
+
+    if (visited.has(id)) {
+      return false;
+    }
+
+    visited.add(id);
+    inStack.add(id);
+
+    const phase = phaseById.get(id);
+    if (phase) {
+      for (const dependencyId of phase.blocked_by || []) {
+        if (hasCycle(dependencyId)) {
+          return true;
+        }
+      }
+    }
+
+    inStack.delete(id);
+    return false;
+  }
+
+  for (const phase of phases) {
+    if (hasCycle(phase.id)) {
+      violations.push({
+        rule: 'cyclic_dependency',
+        detail: `Cycle detected involving phase ${phase.id}`,
+        severity: 'error',
+      });
+      break;
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Flag a blocked_by edge as redundant when the same blocker is already
+ * reachable transitively through a sibling dependency.
+ */
+function checkRedundantDependencies(phases, phaseById) {
+  const violations = [];
+  const memo = {};
+
+  for (const phase of phases) {
+    if (!phase.blocked_by || phase.blocked_by.length < 2) {
+      continue;
+    }
+
+    for (const dependencyId of phase.blocked_by) {
+      const otherDependencies = phase.blocked_by.filter(
+        (id) => id !== dependencyId
+      );
+      let redundant = false;
+
+      for (const otherDependencyId of otherDependencies) {
+        const transitiveDependencies = getTransitiveDependencies(
+          otherDependencyId,
+          phaseById,
+          memo
+        );
+        if (transitiveDependencies.has(dependencyId)) {
+          violations.push({
+            rule: 'redundant_dependency',
+            detail: `Phase ${phase.id}: dependency on phase ${dependencyId} is redundant (already reachable via phase ${otherDependencyId})`,
+            severity: 'warning',
+          });
+          redundant = true;
+          break;
+        }
+      }
+
+      if (redundant) {
+        break;
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Build the parallelization profile (depth-based batches, eligible count,
+ * maximum batch size) for the plan.
+ */
+function buildParallelizationProfile(phases, phaseById) {
+  const depths = computeDepths(phases, phaseById);
+  const batches = Object.entries(
+    phases.reduce((acc, phase) => {
+      const depth = depths[phase.id] || 0;
+      acc[depth] = acc[depth] || [];
+      acc[depth].push(phase.id);
+      return acc;
+    }, {})
+  )
+    .sort(([a], [b]) => Number(a) - Number(b))
+    .map(([depth, phaseIds]) => ({
+      depth: Number(depth),
+      phase_ids: phaseIds,
+    }));
+
+  let parallelEligible = 0;
+  for (const batch of batches) {
+    if (batch.phase_ids.length > 1) {
+      parallelEligible += batch.phase_ids.length;
+    }
+  }
+
+  return {
+    total_phases: phases.length,
+    depth_map: depths,
+    batches,
+    max_batch_size: Math.max(...batches.map((batch) => batch.phase_ids.length)),
+    parallel_eligible: parallelEligible,
+    effective_batches: batches.length,
+  };
+}
+
+module.exports = {
+  computeDepths,
+  getTransitiveDependencies,
+  checkCycles,
+  checkRedundantDependencies,
+  buildParallelizationProfile,
+};

package/src/mcp/validation/file-overlap-checker.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * Emit `file_overlap` violations when two phases marked `parallel` at
+ * the same dependency depth both declare ownership of the same file.
+ * Phases at different depths can safely touch the same file because
+ * they run sequentially.
+ *
+ * Ownership is the union of:
+ *   - `files` — the planning-time manifest (canonical plan input)
+ *   - `files_created` / `files_modified` — runtime-populated manifests
+ *     from previous executions of the plan (included for plans that
+ *     were already executed and are being re-validated against updated
+ *     rules).
+ */
+function checkFileOverlap(phases, depths) {
+  const parallelPhases = phases.filter((phase) => phase.parallel);
+  if (parallelPhases.length === 0) {
+    return [];
+  }
+
+  const violations = [];
+  const batchesByDepth = {};
+
+  for (const phase of parallelPhases) {
+    const depth = depths[phase.id] || 0;
+    batchesByDepth[depth] = batchesByDepth[depth] || [];
+    batchesByDepth[depth].push(phase);
+  }
+
+  for (const batch of Object.values(batchesByDepth)) {
+    if (batch.length < 2) {
+      continue;
+    }
+
+    const fileOwners = {};
+    for (const phase of batch) {
+      const files = [
+        ...(phase.files || []),
+        ...(phase.files_created || []),
+        ...(phase.files_modified || []),
+      ];
+
+      for (const file of files) {
+        if (fileOwners[file]) {
+          violations.push({
+            rule: 'file_overlap',
+            detail: `Parallel phases ${fileOwners[file]} and ${phase.id} both touch "${file}"`,
+            severity: 'error',
+          });
+        } else {
+          fileOwners[file] = phase.id;
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+module.exports = {
+  checkFileOverlap,
+};

package/src/mcp/validation/schema-checker.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const { validatePhases } = require('../contracts/plan-schema');
+
+const PHASE_LIMITS = {
+  simple: 3,
+  medium: 5,
+  complex: Infinity,
+};
+
+/**
+ * Lightweight shape validation: guard against non-object plans or
+ * missing `phases` arrays so downstream checkers can assume a phase list.
+ * Returns a single `invalid_plan` violation when the structure is wrong.
+ */
+function checkPlanShape(plan) {
+  if (!plan || typeof plan !== 'object' || !Array.isArray(plan.phases)) {
+    return [
+      {
+        rule: 'invalid_plan',
+        detail: 'plan must be an object with a phases array',
+        severity: 'error',
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * Enforce task-complexity phase budgets: simple<=3, medium<=5, complex unlimited.
+ */
+function checkPhaseCount(phases, taskComplexity) {
+  const limit = PHASE_LIMITS[taskComplexity] || Infinity;
+  if (phases.length > limit) {
+    return [
+      {
+        rule: 'phase_count',
+        detail: `${taskComplexity} tasks allow max ${limit} phases, got ${phases.length}`,
+        severity: 'error',
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * Flag duplicate phase IDs. Emits one violation per duplicate occurrence
+ * (matches the original loop behavior).
+ */
+function checkDuplicateIds(phases) {
+  const violations = [];
+  const seenIds = new Set();
+  for (const phase of phases) {
+    if (seenIds.has(phase.id)) {
+      violations.push({
+        rule: 'duplicate_id',
+        detail: `Duplicate phase ID: ${phase.id}`,
+        severity: 'error',
+      });
+    }
+    seenIds.add(phase.id);
+  }
+  return violations;
+}
+
+/**
+ * Flag blocked_by entries that reference non-existent phase IDs.
+ */
+function checkDanglingDependencies(phases) {
+  const violations = [];
+  const allIds = new Set(phases.map((phase) => phase.id));
+  for (const phase of phases) {
+    for (const dependencyId of phase.blocked_by || []) {
+      if (!allIds.has(dependencyId)) {
+        violations.push({
+          rule: 'dangling_dependency',
+          detail: `Phase ${phase.id} references non-existent dependency: ${dependencyId}`,
+          severity: 'error',
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * Delegate per-phase field validation to the shared `validatePhases` contract.
+ * Maps contract violations to the schema-checker violation shape.
+ */
+function checkPhaseFieldSchema(phases) {
+  const result = validatePhases(phases);
+  if (result.valid) return [];
+  return result.violations.map((violation) => ({
+    rule: violation.rule,
+    detail: `Phase ${violation.phase_id ?? '?'} field "${violation.field}" ${violation.rule.replace('_', ' ')}`,
+    severity: 'error',
+    phase_id: violation.phase_id,
+    field: violation.field,
+  }));
+}
+
+module.exports = {
+  checkPlanShape,
+  checkPhaseCount,
+  checkDuplicateIds,
+  checkDanglingDependencies,
+  checkPhaseFieldSchema,
+};

package/src/platforms/claude/metadata.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const {
+  RUNTIME_DESCRIPTION,
+  buildAuthor,
+  renderJson,
+} = require('../metadata-shared');
+
+function buildClaudeMarketplace(context) {
+  return {
+    name: 'maestro-orchestrator',
+    owner: {
+      name: context.author.name,
+    },
+    metadata: {
+      description: 'Maestro multi-agent orchestration platform for Claude Code',
+      version: context.version,
+    },
+    plugins: [
+      {
+        name: 'maestro',
+        source: './claude',
+        description: RUNTIME_DESCRIPTION,
+        version: context.version,
+        author: buildAuthor(context),
+        homepage: context.homepage,
+        repository: context.repository,
+        license: context.license,
+        keywords: [
+          'orchestration',
+          'multi-agent',
+          'planning',
+          'execution',
+          'agents',
+        ],
+        category: 'productivity',
+      },
+    ],
+  };
+}
+
+function buildClaudePluginManifest(context) {
+  return {
+    name: 'maestro',
+    version: context.version,
+    description: RUNTIME_DESCRIPTION,
+    author: buildAuthor(context),
+    license: context.license,
+    hooks: './hooks/claude-hooks.json',
+    mcpServers: './.mcp.json',
+    homepage: context.homepage,
+    repository: context.repository,
+    keywords: [
+      'orchestration',
+      'multi-agent',
+      'planning',
+      'execution',
+    ],
+  };
+}
+
+function buildClaudeMcpConfig() {
+  return {
+    mcpServers: {
+      maestro: {
+        command: 'node',
+        args: ['${CLAUDE_PLUGIN_ROOT}/mcp/maestro-server.js'],
+        cwd: '${CLAUDE_PLUGIN_ROOT}',
+      },
+    },
+  };
+}
+
+function buildMetadataOutputs(context) {
+  return [
+    {
+      outputPath: '.claude-plugin/marketplace.json',
+      content: renderJson(buildClaudeMarketplace(context)),
+    },
+    {
+      outputPath: 'claude/.claude-plugin/plugin.json',
+      content: renderJson(buildClaudePluginManifest(context)),
+    },
+    {
+      outputPath: 'claude/.mcp.json',
+      content: renderJson(buildClaudeMcpConfig()),
+    },
+  ];
+}
+
+module.exports = {
+  buildClaudeMarketplace,
+  buildClaudeMcpConfig,
+  buildClaudePluginManifest,
+  buildMetadataOutputs,
+};

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

@@ -0,0 +1,60 @@
+module.exports = {
+  name: 'claude',
+  outputDir: 'claude/',
+
+  agentNaming: 'kebab-case',
+
+  env: {
+    extensionPath: 'CLAUDE_PLUGIN_ROOT',
+    workspacePath: 'CLAUDE_PROJECT_DIR',
+  },
+
+  content: {
+    primary: 'filesystem',
+    fallback: 'none',
+  },
+
+  tools: {
+    read_file: 'Read',
+    list_directory: 'Glob',
+    glob: 'Glob',
+    grep_search: 'Grep',
+    google_web_search: 'WebSearch',
+    web_fetch: 'WebFetch',
+    write_file: 'Write',
+    replace: 'Edit',
+    run_shell_command: 'Bash',
+    ask_user: 'AskUserQuestion',
+    read_many_files: 'Read',
+    write_todos: ['TaskCreate', 'TaskUpdate', 'TaskList'],
+    activate_skill: 'Skill',
+    enter_plan_mode: 'EnterPlanMode',
+    exit_plan_mode: 'ExitPlanMode',
+    codebase_investigator: 'Agent (Explore) / Grep / Glob',
+  },
+
+  agentFrontmatter: {
+    model: 'inherit',
+    turnsField: 'maxTurns',
+  },
+
+  delegation: {
+    pattern: 'Agent(subagent_type: "maestro:{{agent}}", prompt: "...")',
+    constraints: {
+      result_surface: 'synchronous',
+      child_cannot_prompt_user: false,
+    },
+  },
+
+  features: {
+    exampleBlocks: true,
+    claudeStateContract: true,
+    scriptBasedStateContract: false,
+    codexStateContract: false,
+  },
+
+  paths: {
+    skills: '${CLAUDE_PLUGIN_ROOT}/skills/',
+    hooks: '${CLAUDE_PLUGIN_ROOT}/scripts/',
+  },
+};