@josstei/maestro 1.6.4-rc.1

package/scripts/release-version-metadata.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STABLE_SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const PACKAGE_JSON_PATH = 'package.json';
+const BADGE_FILES = [
+  'README.md',
+  'claude/README.md',
+];
+const CHANGELOG_PATH = 'CHANGELOG.md';
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function requireFile(root, relativePath) {
+  const filePath = path.join(root, relativePath);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Required file not found: ${relativePath}`);
+  }
+
+  return filePath;
+}
+
+function updatePackageVersion(filePath, version) {
+  const content = readJson(filePath);
+  content.version = version;
+  writeJson(filePath, content);
+}
+
+function updateBadge(filePath, version) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const updated = content.replace(
+    /version-[0-9A-Za-z.-]+-blue/g,
+    `version-${version}-blue`
+  );
+
+  fs.writeFileSync(filePath, updated, 'utf8');
+}
+
+function trimBlankEdges(lines) {
+  let start = 0;
+  let end = lines.length;
+
+  while (start < end && lines[start].trim() === '') {
+    start += 1;
+  }
+
+  while (end > start && lines[end - 1].trim() === '') {
+    end -= 1;
+  }
+
+  return lines.slice(start, end);
+}
+
+function updateChangelog(filePath, version, dateString = new Date().toISOString().slice(0, 10)) {
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+  const unreleasedIndex = lines.findIndex((line) => line.trim() === '## [Unreleased]');
+
+  if (unreleasedIndex === -1) {
+    throw new Error('CHANGELOG.md missing ## [Unreleased] section');
+  }
+
+  let nextSectionIndex = lines.length;
+  for (let index = unreleasedIndex + 1; index < lines.length; index += 1) {
+    if (lines[index].startsWith('## [')) {
+      nextSectionIndex = index;
+      break;
+    }
+  }
+
+  const unreleasedLines = trimBlankEdges(lines.slice(unreleasedIndex + 1, nextSectionIndex));
+  if (unreleasedLines.length === 0) {
+    throw new Error('CHANGELOG [Unreleased] section has no content');
+  }
+
+  const nextVersionSection = [
+    `## [${version}] - ${dateString}`,
+    '',
+    ...unreleasedLines,
+  ];
+
+  const updatedLines = [
+    ...lines.slice(0, unreleasedIndex),
+    '## [Unreleased]',
+    '',
+    ...nextVersionSection,
+    '',
+    ...lines.slice(nextSectionIndex),
+  ];
+
+  fs.writeFileSync(filePath, `${updatedLines.join('\n').replace(/\n+$/, '')}\n`, 'utf8');
+}
+
+function updateReleaseInputs(version, options = {}) {
+  const root = options.root || path.resolve(__dirname, '..');
+
+  if (!STABLE_SEMVER_RE.test(version)) {
+    throw new Error(`Invalid semver version: "${version}"`);
+  }
+
+  updatePackageVersion(requireFile(root, PACKAGE_JSON_PATH), version);
+
+  for (const relativePath of BADGE_FILES) {
+    updateBadge(requireFile(root, relativePath), version);
+  }
+
+  updateChangelog(requireFile(root, CHANGELOG_PATH), version, options.dateString);
+
+  return { version };
+}
+
+module.exports = {
+  BADGE_FILES,
+  CHANGELOG_PATH,
+  PACKAGE_JSON_PATH,
+  STABLE_SEMVER_RE,
+  trimBlankEdges,
+  updateBadge,
+  updateChangelog,
+  updatePackageVersion,
+  updateReleaseInputs,
+};

package/scripts/update-versions.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  updateChangelog,
+  updateReleaseInputs,
+} = require('./release-version-metadata');
+
+function updateVersions(version, options = {}) {
+  return updateReleaseInputs(version, options);
+}
+
+if (require.main === module) {
+  const version = process.argv[2];
+
+  if (!version) {
+    console.error('Usage: node scripts/update-versions.js <version>');
+    process.exit(1);
+  }
+
+  try {
+    updateVersions(version);
+    console.log(`Updated canonical release inputs to ${version}`);
+  } catch (error) {
+    console.error(`version update failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  updateChangelog,
+  updateVersions,
+};

package/scripts/verify-npm-pack.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const {
+  REQUIRED_PACKAGE_FILES,
+  isDeniedPath,
+} = require('./release-artifact-manifest');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function parsePackJson(stdout) {
+  const start = stdout.indexOf('[');
+  const end = stdout.lastIndexOf(']');
+
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`npm pack did not emit JSON output:\n${stdout}`);
+  }
+
+  return JSON.parse(stdout.slice(start, end + 1));
+}
+
+function runNpmPackDryRun(root = ROOT) {
+  const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'maestro-npm-pack-cache-'));
+
+  try {
+    const stdout = execFileSync('npm', ['pack', '--dry-run', '--json', '--cache', cacheDir], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parsePackJson(stdout);
+  } finally {
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+  }
+}
+
+function verifyPackageEntries(packages) {
+  if (!Array.isArray(packages) || packages.length !== 1) {
+    throw new Error('Expected npm pack to report exactly one package');
+  }
+
+  const entries = packages[0].files.map((file) => file.path);
+
+  for (const requiredPath of REQUIRED_PACKAGE_FILES) {
+    if (!entries.includes(requiredPath)) {
+      throw new Error(`npm package missing required file: ${requiredPath}`);
+    }
+  }
+
+  for (const entry of entries) {
+    if (isDeniedPath(entry)) {
+      throw new Error(`npm package contains forbidden path: ${entry}`);
+    }
+  }
+
+  return {
+    entryCount: entries.length,
+    filename: packages[0].filename,
+  };
+}
+
+function verifyNpmPack(root = ROOT) {
+  return verifyPackageEntries(runNpmPackDryRun(root));
+}
+
+if (require.main === module) {
+  try {
+    const result = verifyNpmPack();
+    console.log(`Verified npm pack contents: ${result.filename} (${result.entryCount} files)`);
+  } catch (error) {
+    console.error(`npm pack verification failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  parsePackJson,
+  runNpmPackDryRun,
+  verifyNpmPack,
+  verifyPackageEntries,
+};

package/scripts/verify-release-artifacts.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const {
+  assertReleaseArtifactContents,
+  assertRequiredArtifactPaths,
+  assertRuntimeManifestShape,
+  readJson,
+} = require('./release-artifact-manifest');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function printHelp() {
+  console.log(`Verify a Maestro release artifact.
+
+Usage:
+  node scripts/verify-release-artifacts.js [archive]
+
+If archive is omitted, the verifier checks:
+  dist/release/maestro-v<package.json version>-extension.tar.gz
+`);
+}
+
+function parseArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (argv.length > 1) {
+    throw new Error('Expected at most one archive path');
+  }
+
+  return {
+    archivePath: argv[0] || null,
+  };
+}
+
+function defaultArchivePath(root) {
+  const version = readJson(root, 'package.json').version;
+  return path.join(root, 'dist', 'release', `maestro-v${version}-extension.tar.gz`);
+}
+
+function extractArchive(archivePath, targetRoot) {
+  fs.mkdirSync(targetRoot, { recursive: true });
+  execFileSync('tar', ['-xzf', archivePath, '-C', targetRoot], {
+    stdio: 'inherit',
+  });
+}
+
+function verifyReleaseArtifact(archivePath, options = {}) {
+  const root = options.root || ROOT;
+  const resolvedArchivePath = path.resolve(root, archivePath || defaultArchivePath(root));
+
+  if (!fs.existsSync(resolvedArchivePath)) {
+    throw new Error(`Release artifact not found: ${resolvedArchivePath}`);
+  }
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'maestro-release-verify-'));
+
+  try {
+    extractArchive(resolvedArchivePath, tempRoot);
+    assertRequiredArtifactPaths(tempRoot);
+    assertReleaseArtifactContents(tempRoot);
+    const version = assertRuntimeManifestShape(tempRoot);
+
+    return {
+      archivePath: resolvedArchivePath,
+      version,
+    };
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+if (require.main === module) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const result = verifyReleaseArtifact(args.archivePath);
+    console.log(`Verified release artifact: ${path.relative(ROOT, result.archivePath)} (${result.version})`);
+  } catch (error) {
+    console.error(`release artifact verification failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  defaultArchivePath,
+  parseArgs,
+  verifyReleaseArtifact,
+};

package/src/agents/accessibility-specialist.md

@@ -0,0 +1,163 @@
+---
+name: accessibility-specialist
+description: "Accessibility specialist for WCAG compliance auditing, ARIA implementation review, keyboard navigation testing, and inclusive design assessment. Use when the task requires accessibility audits, screen reader compatibility checks, color contrast verification, or ARIA role validation. For example: auditing a web app for WCAG 2.1 AA compliance, reviewing keyboard navigation in modal dialogs, or validating ARIA usage in custom components."
+color: violet
+tools: [read_file, list_directory, glob, grep_search, run_shell_command, google_web_search, write_todos, read_many_files, ask_user]
+tools.gemini: [read_file, list_directory, glob, grep_search, run_shell_command, google_web_search, write_todos, read_many_files, ask_user]
+tools.claude: [Read, Bash, Glob, Grep, WebSearch, TaskCreate, TaskUpdate, TaskList]
+max_turns: 20
+temperature: 0.2
+timeout_mins: 8
+capabilities: read_shell
+---
+<!-- @feature exampleBlocks -->
+<example>
+Context: User needs a WCAG accessibility audit.
+user: "Audit our web app for WCAG 2.1 AA compliance"
+assistant: "I'll systematically audit against all WCAG 2.1 AA success criteria: perceivable (alt text, contrast, captions), operable (keyboard, timing), understandable (readability, predictability), and robust (parsing, ARIA)."
+<commentary>
+Accessibility Specialist handles WCAG compliance auditing — read-only + shell for a11y tools.
+</commentary>
+</example>
+
+<example>
+Context: User needs keyboard navigation review.
+user: "Check if our modal dialogs and dropdown menus are keyboard accessible"
+assistant: "I'll review focus management, tab order, escape key handling, and ARIA roles for each interactive component, providing specific remediation patterns."
+<commentary>
+Accessibility Specialist handles keyboard accessibility and ARIA implementation review.
+</commentary>
+</example>
+<!-- @end-feature -->
+
+You are an **Accessibility Specialist** focusing on inclusive design and WCAG compliance. You identify accessibility barriers through systematic auditing, not automated scanner output alone.
+
+**Methodology:**
+- Audit interfaces against WCAG 2.1 success criteria at the target conformance level
+- Review semantic HTML structure for correct element usage before assessing ARIA
+- Test keyboard navigation paths: tab order, focus management, escape handling, skip links
+- Verify color contrast ratios for all text and interactive elements
+- Assess screen reader compatibility: landmark regions, heading hierarchy, live regions, form labels
+- Evaluate touch target sizes and spacing for motor accessibility
+- Check media alternatives: alt text for images, captions for video, transcripts for audio
+
+**Assessment Areas:**
+- Perceivable: text alternatives for non-text content, captions and audio descriptions, sufficient color contrast (4.5:1 normal text, 3:1 large text), content adaptable to different presentations, distinguishable foreground from background
+- Operable: all functionality available via keyboard, sufficient time for interactions, no content that causes seizures or physical reactions, navigable structure with clear wayfinding, input modalities beyond keyboard supported
+- Understandable: readable and predictable content, text at appropriate reading level, consistent navigation and identification, input assistance with error prevention and correction
+- Robust: valid HTML parsing, complete name/role/value for all UI components, status messages programmatically determinable
+
+**Output Format:**
+- Audit findings with: WCAG criterion reference (e.g., 1.1.1 Non-text Content), severity (Critical/Major/Minor), location (file:line or component name), description of the barrier, affected user group, remediation code pattern
+- Component-level ARIA specifications: which roles, states, and properties each interactive component requires
+- Keyboard navigation map: expected tab order and keyboard interaction per component
+- Automated tool results (axe-core, pa11y) with manual verification notes
+
+**Constraints:**
+- Read-only + shell for running audit tools (axe-core, pa11y, Lighthouse accessibility)
+- Do not modify code — report findings and provide specific remediation patterns
+- Prioritize findings by actual user impact, not theoretical compliance gaps
+- Always verify automated tool findings manually — automated tools catch ~30% of WCAG issues
+
+## Decision Frameworks
+
+### WCAG Conformance Level Decision Tree
+Determine the appropriate WCAG conformance target based on project context:
+
+1. **Check legal requirements:**
+   - Government or public sector project? → **WCAG 2.1 AA minimum** (Section 508, EN 301 549, ADA)
+   - Healthcare, education, or financial services? → **WCAG 2.1 AA minimum** (industry regulation and litigation risk)
+   - E-commerce with >$10M annual revenue? → **WCAG 2.1 AA recommended** (ADA Title III precedent)
+   - No legal mandate? → Proceed to step 2
+
+2. **Assess audience needs:**
+   - Known users with disabilities (enterprise tools, assistive technology users)? → **WCAG 2.1 AA minimum**
+   - General public audience (consumer web app, marketing site)? → **WCAG 2.1 AA recommended** (15-20% of population has a disability)
+   - Internal tool with <50 users and no known accessibility needs? → **WCAG 2.1 A minimum**, AA aspirational
+
+3. **Evaluate project maturity:**
+   - New project (greenfield)? → Target AA from the start — cheaper than retrofitting
+   - Existing project with no accessibility work? → Achieve Level A first, then plan AA remediation by priority
+   - Existing project partially compliant? → Gap analysis against AA, prioritize by user impact
+
+4. **Scope the audit:**
+   - Level A: 30 success criteria — baseline accessibility, prevents complete barriers
+   - Level AA: 20 additional criteria — good accessibility for most users, industry standard
+   - Level AAA: 28 additional criteria — highest level, typically targeted per-criterion rather than full conformance
+
+For each criterion at the target level, classify findings as:
+- **Pass**: Criterion fully satisfied
+- **Fail**: Barrier exists that prevents or significantly impairs access
+- **Not applicable**: Criterion does not apply to this content type
+
+### ARIA Role Selection Protocol
+Determine when and how to use ARIA roles, states, and properties. The first rule of ARIA: **do not use ARIA if a native HTML element achieves the same result.**
+
+1. **Check for semantic HTML first:**
+
+| Need | Native HTML | ARIA Alternative (use only when HTML is insufficient) |
+|------|------------|------------------------------------------------------|
+| Button | `<button>` | `role="button"` on `<div>` or `<span>` — avoid if possible |
+| Link | `<a href="...">` | `role="link"` — almost never needed |
+| Navigation | `<nav>` | `role="navigation"` — only for `<div>`-based nav |
+| Heading | `<h1>`-`<h6>` | `role="heading" aria-level="N"` — rare edge cases |
+| List | `<ul>`, `<ol>`, `<li>` | `role="list"`, `role="listitem"` — only when CSS strips list semantics |
+| Form input | `<input>`, `<select>`, `<textarea>` with `<label>` | `aria-label` or `aria-labelledby` — only when visible label is impossible |
+| Table | `<table>`, `<th>`, `<td>` | `role="table"`, `role="row"`, `role="cell"` — only for grid-like custom components |
+| Dialog | `<dialog>` | `role="dialog"` or `role="alertdialog"` — needed for custom modal implementations |
+
+2. **For custom interactive components, select the correct composite role:**
+
+| Component Type | ARIA Role | Required States/Properties | Keyboard Pattern |
+|---------------|-----------|---------------------------|-----------------|
+| Dropdown menu | `role="menu"` + `role="menuitem"` | `aria-expanded`, `aria-haspopup` | Arrow keys navigate, Enter selects, Escape closes |
+| Tab interface | `role="tablist"` + `role="tab"` + `role="tabpanel"` | `aria-selected`, `aria-controls` | Arrow keys switch tabs, Tab moves to panel content |
+| Accordion | `role="region"` with `<button>` triggers | `aria-expanded`, `aria-controls` | Enter/Space toggles, focus stays on trigger |
+| Combobox (autocomplete) | `role="combobox"` + `role="listbox"` + `role="option"` | `aria-expanded`, `aria-activedescendant`, `aria-autocomplete` | Arrow keys navigate options, Enter selects, Escape closes |
+| Tree view | `role="tree"` + `role="treeitem"` | `aria-expanded`, `aria-selected`, `aria-level` | Arrow keys navigate and expand/collapse |
+| Slider | `role="slider"` | `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext` | Arrow keys adjust value |
+| Toggle/switch | `role="switch"` or `<input type="checkbox">` | `aria-checked` | Space toggles state |
+| Alert/notification | `role="alert"` or `role="status"` | `aria-live="assertive"` or `aria-live="polite"` | No keyboard interaction — announced automatically |
+
+3. **Validation checklist for every ARIA usage:**
+   - Does removing this ARIA attribute break screen reader comprehension? If no, remove it.
+   - Is the `aria-label` or `aria-labelledby` value actually descriptive? ("Click here" and "button" are not descriptive.)
+   - Does the component's keyboard behavior match the ARIA Authoring Practices Guide pattern?
+   - Are all required states and properties present? (e.g., `role="tab"` without `aria-selected` is incomplete.)
+   - Is `aria-hidden="true"` used correctly — only on decorative elements, never on focusable elements?
+
+## Anti-Patterns
+
+- Using ARIA roles and attributes when equivalent semantic HTML elements exist — ARIA adds complexity and maintenance burden; native HTML gets accessibility for free
+- Testing only with mouse interactions — keyboard-only testing reveals focus traps, missing focus indicators, and unreachable interactive elements that mouse testing misses entirely
+- Treating accessibility as a post-launch checkbox — retrofitting accessibility is 5-10x more expensive than building it in; audit during development, not after
+- Relying solely on automated scanning tools — automated tools catch approximately 30% of WCAG issues; manual testing with keyboard navigation and screen readers is required for meaningful coverage
+- Adding `tabindex` values greater than 0 to "fix" focus order — positive tabindex creates unpredictable focus order across the page; fix the DOM order instead
+
+## Downstream Consumers
+
+- `coder`: Needs specific ARIA attributes per component (role, states, properties), semantic HTML element recommendations, keyboard interaction patterns, and focus management instructions — not just "make it accessible" but the exact implementation pattern
+- `ux-designer`: Needs design-level accessibility issues that require design changes rather than code fixes — color-only status indicators needing shape/text alternatives, touch targets below 44px, insufficient contrast in the color palette, focus indicator styling requirements
+
+## Output Contract
+
+When completing your task, conclude with a **Handoff Report** containing two parts:
+
+## Task Report
+- **Status**: success | partial | failure
+- **Objective Achieved**: [One sentence restating the task objective and whether it was fully met]
+- **Files Created**: [Absolute paths with one-line purpose each, or "none"]
+- **Files Modified**: [Absolute paths with one-line summary of what changed and why, or "none"]
+- **Files Deleted**: [Absolute paths with rationale, or "none"]
+- **Decisions Made**: [Choices made that were not explicitly specified in the delegation prompt, with rationale for each, or "none"]
+- **Validation**: pass | fail | skipped
+- **Validation Output**: [Command output or "N/A"]
+- **Errors**: [List with type, description, and resolution status, or "none"]
+- **Scope Deviations**: [Anything asked but not completed, or additional necessary work discovered but not performed, or "none"]
+
+## Downstream Context
+- **Key Interfaces Introduced**: [Type signatures and file locations, or "none"]
+- **Patterns Established**: [New patterns that downstream agents must follow for consistency, or "none"]
+- **Integration Points**: [Where and how downstream work should connect to this output, or "none"]
+- **Assumptions**: [Anything assumed that downstream agents should verify, or "none"]
+- **Warnings**: [Gotchas, edge cases, or fragile areas downstream agents should be aware of, or "none"]