@josstei/maestro 1.6.4-rc.1

package/claude/hooks/claude-hooks.json

@@ -0,0 +1,48 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.js claude session-end",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.js claude session-start",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.js claude before-agent",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Agent"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/policy-enforcer.js",
+            "timeout": 5
+          }
+        ],
+        "matcher": "Bash"
+      }
+    ]
+  }
+}

package/claude/mcp/maestro-server.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+process.env.MAESTRO_RUNTIME = process.env.MAESTRO_RUNTIME || 'claude';
+const repoEntry = path.resolve(__dirname, '../../src/mcp/maestro-server.js');
+const bundledEntry = path.resolve(__dirname, '../src/mcp/maestro-server.js');
+require(fs.existsSync(repoEntry) ? repoEntry : bundledEntry).main();

package/claude/mcp-config.example.json

@@ -0,0 +1,9 @@
+{
+  "maestro": {
+    "command": "node",
+    "args": [
+      "./mcp/maestro-server.js"
+    ],
+    "cwd": "<path-to-maestro-plugin>"
+  }
+}

package/claude/scripts/adapters/claude-adapter.js

@@ -0,0 +1,7 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoEntry = path.resolve(__dirname, '../../../src/platforms/shared/adapters/claude-adapter.js');
+const bundledEntry = path.resolve(__dirname, '../../src/platforms/shared/adapters/claude-adapter.js');
+module.exports = require(fs.existsSync(repoEntry) ? repoEntry : bundledEntry);

package/claude/scripts/hook-runner.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoEntry = path.resolve(__dirname, '../../src/platforms/shared/hook-runner.js');
+const bundledEntry = path.resolve(__dirname, '../src/platforms/shared/hook-runner.js');
+require(fs.existsSync(repoEntry) ? repoEntry : bundledEntry);

package/claude/scripts/policy-enforcer.js

@@ -0,0 +1,294 @@
+'use strict';
+
+/**
+ * Maestro policy enforcer for Claude Code.
+ * Reads stdin (Claude Code PreToolUse hook input for Bash),
+ * checks tool_input.command against deny and ask patterns,
+ * and outputs a decision JSON to stdout.
+ *
+ * Rules are loaded from the canonical source (src/core/policy-rules.js)
+ * with a fallback to the bundled copy for detached installs.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoRules = path.resolve(__dirname, '../../src/core/policy-rules.js');
+const bundledRules = path.resolve(__dirname, '../src/core/policy-rules.js');
+const { DENY_RULES, ASK_RULES } = require(fs.existsSync(repoRules) ? repoRules : bundledRules);
+
+function splitCommands(command) {
+  const parts = [];
+  let depth = 0;
+  let current = '';
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === '\\' && !inSingle) {
+      current += ch;
+      escaped = true;
+      continue;
+    }
+    if (ch === "'" && !inDouble) { inSingle = !inSingle; current += ch; continue; }
+    if (ch === '"' && !inSingle) { inDouble = !inDouble; current += ch; continue; }
+
+    if (!inSingle && ch === '$' && command[i + 1] === '(') {
+      const parsed = readDollarSubshell(command, i + 2);
+      current += '$(' + parsed.content + ')';
+      i = parsed.end;
+      continue;
+    }
+    if (!inSingle && ch === '`') {
+      const parsed = readBacktickSubshell(command, i + 1);
+      current += '`' + parsed.content + '`';
+      i = parsed.end;
+      continue;
+    }
+
+    if (inSingle || inDouble) {
+      current += ch;
+      continue;
+    }
+
+    if (ch === '(' || ch === '{') { depth++; current += ch; continue; }
+    if (ch === ')') {
+      if (depth > 0) {
+        depth--;
+      }
+      current += ch;
+      continue;
+    }
+    if (ch === '}') { depth--; current += ch; continue; }
+
+    if (depth === 0) {
+      if (ch === ';') {
+        parts.push(current);
+        current = '';
+        continue;
+      }
+      if (ch === '&' && command[i + 1] === '&') {
+        parts.push(current);
+        current = '';
+        i++;
+        continue;
+      }
+      if (ch === '|' && command[i + 1] === '|') {
+        parts.push(current);
+        current = '';
+        i++;
+        continue;
+      }
+      if (ch === '|') {
+        parts.push(current);
+        current = '';
+        continue;
+      }
+    }
+    current += ch;
+  }
+  if (current) parts.push(current);
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+function readBacktickSubshell(command, startIndex) {
+  let content = '';
+
+  for (let i = startIndex; i < command.length; i++) {
+    const ch = command[i];
+    if (ch === '\\') {
+      const next = command[i + 1];
+      if (next === '`') {
+        content += '`';
+        i++;
+        continue;
+      }
+      content += ch;
+      continue;
+    }
+    if (ch === '`') {
+      return { content, end: i };
+    }
+    content += ch;
+  }
+
+  throw new Error('Unterminated backtick command substitution');
+}
+
+function readDollarSubshell(command, startIndex) {
+  let content = '';
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+
+  for (let i = startIndex; i < command.length; i++) {
+    const ch = command[i];
+
+    if (escaped) {
+      content += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === '\\' && !inSingle) {
+      if (command[i + 1] === '`') {
+        content += '`';
+        i++;
+        continue;
+      }
+      content += ch;
+      escaped = true;
+      continue;
+    }
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+      content += ch;
+      continue;
+    }
+    if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+      content += ch;
+      continue;
+    }
+    if (inSingle) {
+      content += ch;
+      continue;
+    }
+    if (ch === '$' && command[i + 1] === '(') {
+      const parsed = readDollarSubshell(command, i + 2);
+      content += '$(' + parsed.content + ')';
+      i = parsed.end;
+      continue;
+    }
+    if (ch === '`') {
+      const parsed = readBacktickSubshell(command, i + 1);
+      content += '`' + parsed.content + '`';
+      i = parsed.end;
+      continue;
+    }
+    if (!inSingle && ch === ')') {
+      return { content, end: i };
+    }
+
+    content += ch;
+  }
+
+  throw new Error('Unterminated $(...) command substitution');
+}
+
+function extractSubshells(command) {
+  const patterns = [];
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === '\\' && !inSingle) {
+      escaped = true;
+      continue;
+    }
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+      continue;
+    }
+    if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+    if (inSingle) continue;
+
+    if (ch === '$' && command[i + 1] === '(') {
+      const parsed = readDollarSubshell(command, i + 2);
+      const content = parsed.content.trim();
+      if (content) {
+        patterns.push(content, ...extractSubshells(content));
+      }
+      i = parsed.end;
+      continue;
+    }
+
+    if (ch === '`') {
+      const parsed = readBacktickSubshell(command, i + 1);
+      const content = parsed.content.trim();
+      if (content) {
+        patterns.push(content, ...extractSubshells(content));
+      }
+      i = parsed.end;
+    }
+  }
+
+  return patterns;
+}
+
+function checkCommand(command) {
+  const segments = splitCommands(command);
+  const subshells = extractSubshells(command);
+  const allParts = [...new Set([...segments, ...subshells, ...subshells.flatMap((s) => splitCommands(s))])];
+
+  for (const part of allParts) {
+    for (const rule of DENY_RULES) {
+      if (matchRule(rule, part)) {
+        return { decision: 'block', reason: rule.reason };
+      }
+    }
+  }
+  for (const part of allParts) {
+    for (const rule of ASK_RULES) {
+      if (matchRule(rule, part)) {
+        return { decision: 'ask', reason: rule.reason };
+      }
+    }
+  }
+  return { decision: 'approve' };
+}
+
+function matchRule(rule, command) {
+  const trimmed = command.trimStart();
+  switch (rule.matchType) {
+    case 'prefix':
+      return trimmed.startsWith(rule.pattern);
+    case 'regex':
+      return new RegExp(rule.pattern).test(trimmed);
+    case 'word':
+      return new RegExp('\\b' + rule.pattern + '\\b').test(trimmed);
+    default:
+      return false;
+  }
+}
+
+const MAX_STDIN_BYTES = 1024 * 1024;
+const chunks = [];
+let totalBytes = 0;
+process.stdin.on('data', (chunk) => {
+  totalBytes += chunk.length;
+  if (totalBytes > MAX_STDIN_BYTES) {
+    process.stderr.write('Policy enforcer: stdin payload too large\n');
+    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Payload too large' }) + '\n');
+    process.exit(1);
+  }
+  chunks.push(chunk);
+});
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(Buffer.concat(chunks).toString());
+    const command = (input.tool_input && input.tool_input.command) || '';
+    const result = checkCommand(command);
+    process.stdout.write(JSON.stringify(result) + '\n');
+  } catch (err) {
+    process.stderr.write('Policy enforcer error: ' + err.message + '\n');
+    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Policy enforcer internal error' }) + '\n');
+  }
+});

package/claude/skills/a11y-audit/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: a11y-audit
+description: Run a Maestro-style accessibility audit for WCAG compliance, ARIA usage, keyboard navigation, and screen reader compatibility
+---
+
+
+# Maestro Accessibility Audit
+
+Call `get_skill_content` with resources: ["architecture"].
+
+## Protocol
+
+Before delegating, call `get_skill_content` with resources: ["delegation"] and follow the returned methodology.
+
+## 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
+
+## Constraints
+
+- Present findings before proposing remediation
+- Do not modify code without explicit user approval

package/claude/skills/archive/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: archive
+description: Archive the active Maestro session while preserving the shared state layout
+---
+
+
+# Maestro Archive
+
+Call `get_skill_content` with resources: ["architecture"].
+
+
+## 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
+
+## Constraints
+
+- Do not delete plan or session history
+- Preserve the existing archive directory structure

package/claude/skills/code-review/SKILL.md

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

package/claude/skills/compliance-check/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: compliance-check
+description: Run a Maestro-style regulatory compliance review for GDPR/CCPA, cookie consent, data handling, and licensing
+---
+
+
+# Maestro Compliance Check
+
+Call `get_skill_content` with resources: ["architecture"].
+
+## Protocol
+
+Before delegating, call `get_skill_content` with resources: ["delegation"] and follow the returned methodology.
+
+## 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
+
+## Constraints
+
+- Present findings before proposing remediation
+- Do not modify code without explicit user approval

package/claude/skills/debug-workflow/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: debug-workflow
+description: Run the Maestro debugging workflow for investigation-heavy tasks
+---
+
+
+# Maestro Debug Workflow
+
+Call `get_skill_content` with resources: ["architecture"].
+
+## Protocol
+
+Before delegating, call `get_skill_content` with resources: ["delegation"] and follow the returned methodology.
+
+## 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
+
+## Constraints
+
+- Prefer evidence over speculation
+- Make uncertainty explicit when the issue cannot be reproduced
+- Return root cause, affected files, confidence level, and the smallest defensible next action

package/claude/skills/delegation/SKILL.md

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

package/claude/skills/design-dialogue/SKILL.md

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

package/claude/skills/execute/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: execute
+description: Execute an approved Maestro implementation plan using the shared session-state contract
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Agent
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - Skill
+  - EnterPlanMode
+  - ExitPlanMode
+---
+
+## Setup
+
+1. Call `get_runtime_context` if it appears in your available tools. Use the returned tool mappings,
+   agent dispatch syntax, MCP prefix, and paths throughout this session.
+2. If `get_runtime_context` is unavailable, use this compact fallback:
+   - Core tools: read_file=Read, write_file=Write, replace=Edit, run_shell_command=Bash, glob=Glob, grep_search=Grep, activate_skill=Skill, ask_user=AskUserQuestion, enter_plan_mode=EnterPlanMode, exit_plan_mode=ExitPlanMode
+   - Extended tools: google_web_search=WebSearch, web_fetch=WebFetch, write_todos=[TaskCreate,TaskUpdate,TaskList], read_many_files=Read, list_directory=Glob, codebase_investigator=Agent (Explore) / Grep / Glob
+   - Agent dispatch: Agent(subagent_type: "maestro:<name>", prompt: "...")
+   - MCP prefix: mcp__plugin_maestro_maestro__
+   - Shared skills/templates/references/protocols: call `get_skill_content(resources: ["<name>"])`
+
+## Execute
+
+Call `get_skill_content` with resources: ["execution", "delegation", "session-management", "validation"].
+
+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/claude/skills/execution/SKILL.md

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

package/claude/skills/implementation-planning/SKILL.md

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

package/claude/skills/orchestrate/SKILL.md

@@ -0,0 +1,38 @@
+---
+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
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Agent
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - Skill
+  - EnterPlanMode
+  - ExitPlanMode
+---
+
+## Setup
+
+1. Call `get_runtime_context` if it appears in your available tools. Use the returned tool mappings,
+   agent dispatch syntax, MCP prefix, and paths throughout this session.
+2. If `get_runtime_context` is unavailable, use this compact fallback:
+   - Core tools: read_file=Read, write_file=Write, replace=Edit, run_shell_command=Bash, glob=Glob, grep_search=Grep, activate_skill=Skill, ask_user=AskUserQuestion, enter_plan_mode=EnterPlanMode, exit_plan_mode=ExitPlanMode
+   - Extended tools: google_web_search=WebSearch, web_fetch=WebFetch, write_todos=[TaskCreate,TaskUpdate,TaskList], read_many_files=Read, list_directory=Glob, codebase_investigator=Agent (Explore) / Grep / Glob
+   - Agent dispatch: Agent(subagent_type: "maestro:<name>", prompt: "...")
+   - MCP prefix: mcp__plugin_maestro_maestro__
+   - Shared skills/templates/references/protocols: call `get_skill_content(resources: ["<name>"])`
+
+## Execute
+
+Call `get_skill_content` with resources: ["orchestration-steps"].
+
+Follow the returned step sequence exactly. The steps are the sole procedural authority — do not improvise, skip, or reorder them.

package/claude/skills/perf-check/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: perf-check
+description: Run a Maestro-style performance assessment for hotspots, regressions, and optimization planning
+---
+
+
+# Maestro Perf Check
+
+Call `get_skill_content` with resources: ["architecture"].
+
+## Protocol
+
+Before delegating, call `get_skill_content` with resources: ["delegation"] and follow the returned methodology.
+
+## 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
+
+## Constraints
+
+- Avoid optimization advice that is disconnected from the observed bottleneck
+- Distinguish measured issues from inferred ones

package/claude/skills/resume-session/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: resume-session
+description: Resume an interrupted Maestro session using the existing active-session file and shared phase tracking
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Agent
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - Skill
+  - EnterPlanMode
+  - ExitPlanMode
+---
+
+## Setup
+
+1. Call `get_runtime_context` if it appears in your available tools. Use the returned tool mappings,
+   agent dispatch syntax, MCP prefix, and paths throughout this session.
+2. If `get_runtime_context` is unavailable, use this compact fallback:
+   - Core tools: read_file=Read, write_file=Write, replace=Edit, run_shell_command=Bash, glob=Glob, grep_search=Grep, activate_skill=Skill, ask_user=AskUserQuestion, enter_plan_mode=EnterPlanMode, exit_plan_mode=ExitPlanMode
+   - Extended tools: google_web_search=WebSearch, web_fetch=WebFetch, write_todos=[TaskCreate,TaskUpdate,TaskList], read_many_files=Read, list_directory=Glob, codebase_investigator=Agent (Explore) / Grep / Glob
+   - Agent dispatch: Agent(subagent_type: "maestro:<name>", prompt: "...")
+   - MCP prefix: mcp__plugin_maestro_maestro__
+   - Shared skills/templates/references/protocols: call `get_skill_content(resources: ["<name>"])`
+
+## Execute
+
+Call `get_skill_content` with resources: ["session-management", "execution", "delegation", "validation"].
+
+Read the active session state, summarize completed and pending phases, then resume from the first pending or failed phase following the loaded methodology.