@josstei/maestro 1.6.4-nightly.20260430

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.

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

@@ -0,0 +1,27 @@
+---
+name: review-code
+description: Perform a Maestro-style code review with findings ordered by severity and concrete file references
+---
+
+
+# Maestro Review Code
+
+Call `get_skill_content` with resources: ["architecture"].
+
+## Protocol
+
+Before delegating, call `get_skill_content` with resources: ["delegation"] and follow the returned methodology.
+
+## Workflow
+
+1. Determine review scope: explicit user-provided paths, staged changes, or last commit diff
+2. Delegate to the code-reviewer agent with the diff content and file paths
+3. Review for correctness, regressions, security, maintainability risk, and missing tests
+4. Classify findings by severity (Critical, Major, Minor, Suggestion) with concrete file and line references
+5. Present findings first, ordered by severity; keep the closing summary brief and only after findings
+
+## Constraints
+
+- Do not bury findings behind a long overview
+- Every finding must reference a specific file and line number -- no speculative issues
+- If no findings exist, say so explicitly and note residual testing gaps

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

@@ -0,0 +1,28 @@
+---
+name: security-audit
+description: Run a Maestro-style security assessment for authentication, authorization, data exposure, secret handling, and exploitability risks
+---
+
+
+# Maestro Security 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 audit scope from the user request and relevant code paths
+2. Trace trust boundaries, auth flows, secret handling, and data exposure paths
+3. Review for exploitable flaws, unsafe defaults, OWASP Top 10 vulnerabilities, and high-risk dependencies
+4. Classify findings by severity (CVSS-aligned) with file references and exploitability assessment
+5. Provide remediation guidance with the highest-risk issues first
+
+## Constraints
+
+- Prefer actionable findings over generic security advice
+- Present findings before proposing remediation
+- State clearly when the review is limited by unavailable runtime context
+- Do not modify code without explicit user approval

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

@@ -0,0 +1,26 @@
+---
+name: seo-audit
+description: Run a Maestro-style SEO assessment for meta tags, structured data, crawlability, and Core Web Vitals
+---
+
+
+# Maestro SEO 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 SEO audit scope (page or site)
+2. Identify web-facing output files (HTML, templates, routes)
+3. Audit meta tags, schema markup, crawlability, canonicalization, internal linking, and Core Web Vitals
+4. Present findings with severity, SEO impact, location, and remediation guidance
+5. Note any checks that require live-site verification if the current environment cannot provide it
+
+## Constraints
+
+- Present findings before proposing remediation
+- Do not modify code without explicit user approval

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

@@ -0,0 +1,7 @@
+---
+name: session-management
+description: Manages orchestration session state, tracking, and resumption
+user-invocable: false
+---
+
+Methodology loaded via MCP. Call `get_skill_content(resources: ["session-management"])`.