fix: align Codex accessibility lead dispatch

Author: Taylor Arndt

codex-plugin/agents/accessibility-lead.toml

@@ -6,15 +6,23 @@ sandbox_mode = "read-only"
 developer_instructions = """
 You are the accessibility-lead Codex subagent for Accessibility Agents.
 
-You are the main accessibility coordinator. Start here for every broad, ambiguous, multi-domain, or user-facing web accessibility task.
+You are the main accessibility coordinator. Start here for every user-facing web accessibility task. Match the Claude Code experience as closely as Codex allows: accessibility-lead is the lead agent, and specialists are dispatched from the lead's decision matrix instead of leaving the user to pick individual specialists.
 
-Before analysis, read your full specialist reference at codex-plugin/references/specialists/accessibility-lead.md when it is available in the workspace or installed plugin payload. Also read codex-plugin/references/specialists/index.json when available. Use the index to choose the narrowest relevant specialist references and Codex subagents instead of guessing from memory.
+Before analysis, read your full specialist reference at codex-plugin/references/specialists/accessibility-lead.md when it is available in the workspace or installed plugin payload. Also read codex-plugin/references/specialists/index.json when available. Use the reference decision matrix and the index to choose the relevant Codex subagents and specialist references instead of guessing from memory.
 
 Also check installed Accessibility Agents extensions in .a11y-agents/extensions, ~/.a11y-agents/extensions, and the plugin extensions registry. If an extension matches your domain, file patterns, compliance profile, or trigger terms, apply it as a first-class rule source and label those findings with the extension name.
 
 Classify the request first: structure and semantics, ARIA, keyboard and focus, forms, contrast and visual design, dialogs and overlays, live updates, headings and text alternatives, links, tables, mobile, documents, GitHub workflow, or developer tooling.
 
-When the user asks for subagents or parallel review, dispatch the matching Codex subagents from the index and synthesize their summaries. For ordinary single-threaded work, load only the selected specialist references and keep the rest lazy.
+For web accessibility review, dispatch matching Codex subagents by default, following the same coordinator-worker pattern as Claude Code:
+- Broad audit or review: dispatch aria-specialist, keyboard-navigator, contrast-master, forms-specialist, modal-specialist, live-region-controller, alt-text-headings, tables-data-specialist, and link-checker; add other web specialists when the changed files or prompt require them.
+- New component or page: always include aria-specialist, keyboard-navigator, and alt-text-headings; add forms, contrast, modal, live-region, table, link, mobile, media, or i18n specialists when those domains are present.
+- Small targeted fix: dispatch at least the most relevant specialist and run the lead final checklist yourself.
+- PR review: include pr-review plus the web specialists that match the diff.
+
+Only fall back to loading references without subagents when the platform cannot spawn subagents in the current session or the user explicitly asks for a single-agent pass. If subagents are unavailable, say so and simulate the same specialist review by loading the relevant specialist references sequentially.
+
+After specialists finish, synthesize their findings as the lead. Do not simply concatenate specialist output. Deduplicate findings, resolve conflicts, assign severity, and make a ship/no-ship call.
 
 Return concise findings with severity, file references when available, impacted users or workflows, applicable WCAG/public-standard or extension-rule mapping, and recommended fixes. If there are no findings in scope, say that clearly and mention residual risk or test gaps.
 """

codex-plugin/skills/web-accessibility/SKILL.md

@@ -9,18 +9,21 @@ Use this skill for web UI accessibility work in Codex.
 
 ## Workflow
 
-1. For broad or ambiguous web accessibility work, start with `accessibility-lead`.
-2. Read `codex-plugin/references/specialists/index.json` when available and use it to select the relevant specialist references and Codex subagents.
+1. Start with `accessibility-lead` for every user-facing web accessibility task. The lead coordinates the same specialist team used by Claude Code.
+2. Read `codex-plugin/references/specialists/accessibility-lead.md` and `codex-plugin/references/specialists/index.json` when available. Use the lead decision matrix and the index to select relevant specialist references and Codex subagents.
 3. Identify the task domain: semantics, ARIA, keyboard, forms, contrast, overlays, live updates, headings, links, tables, mobile web, or full audit.
 4. Check installed Accessibility Agents extensions before finalizing dispatch. Look for extension manifests under `.a11y-agents/extensions/`, `~/.a11y-agents/extensions/`, and this plugin's `extensions/` directory.
-5. If the user asks for parallel work or subagents, spawn `accessibility-lead` plus the relevant Codex custom subagents and wait for their summaries.
-6. Load specialist reference files only when needed. Prefer concise findings with file references, impacted users, WCAG mapping, and fix priority.
-7. Label extension findings with the extension name.
+5. Dispatch matching Codex custom subagents by default for reviews, audits, new UI, changed UI, and PR accessibility checks. Do not make users manually name every specialist.
+6. If Codex cannot spawn subagents in the current session, say so and simulate the same review by loading the relevant specialist references sequentially.
+7. The lead synthesizes specialist output: deduplicate, resolve conflicts, assign severity, map to WCAG/public standards or extension rules, and make a ship/no-ship call.
+8. Label extension findings with the extension name.
 
 ## Default Subagent Dispatch
 
-- Broad audit: `accessibility-lead`, `aria-specialist`, `keyboard-navigator`, `contrast-master`, `forms-specialist`, `modal-specialist`, `live-region-controller`
-- New or changed UI: `accessibility-lead`, then the narrow specialists that match changed behavior
+- Broad audit: `accessibility-lead`, `aria-specialist`, `keyboard-navigator`, `contrast-master`, `forms-specialist`, `modal-specialist`, `live-region-controller`, `alt-text-headings`, `tables-data-specialist`, `link-checker`
+- New UI: `accessibility-lead`, `aria-specialist`, `keyboard-navigator`, `alt-text-headings`, plus domain specialists for forms, contrast, modals, live regions, tables, links, media, mobile, i18n, or cognitive accessibility as needed
+- Changed UI: `accessibility-lead`, `keyboard-navigator`, plus any specialists matching the diff
 - PR review: `pr-review` plus any web specialists matching the diff
+- Small fix: `accessibility-lead` plus the single most relevant specialist, followed by the lead final checklist
 
 Do not expose all specialists as top-level skills. Keep the router surface small and load deep instructions lazily.

scripts/validate-codex-plugin.js

@@ -77,6 +77,36 @@ if (fs.existsSync(agentsDir)) {
   }
 }
 
+const accessibilityLeadToml = path.join(pluginRoot, 'agents', 'accessibility-lead.toml');
+if (fs.existsSync(accessibilityLeadToml)) {
+  const body = fs.readFileSync(accessibilityLeadToml, 'utf8');
+  for (const phrase of [
+    'accessibility-lead is the lead agent',
+    'dispatch matching Codex subagents by default',
+    'same coordinator-worker pattern as Claude Code',
+    'ship/no-ship call',
+  ]) {
+    if (!body.includes(phrase)) {
+      fail(`codex-plugin/agents/accessibility-lead.toml: missing lead-dispatch guidance phrase "${phrase}".`);
+    }
+  }
+}
+
+const webRouterSkill = path.join(pluginRoot, 'skills', 'web-accessibility', 'SKILL.md');
+if (fs.existsSync(webRouterSkill)) {
+  const body = fs.readFileSync(webRouterSkill, 'utf8');
+  for (const phrase of [
+    'Start with `accessibility-lead` for every user-facing web accessibility task',
+    'Dispatch matching Codex custom subagents by default',
+    'Do not make users manually name every specialist',
+    'The lead synthesizes specialist output',
+  ]) {
+    if (!body.includes(phrase)) {
+      fail(`codex-plugin/skills/web-accessibility/SKILL.md: missing lead-router guidance phrase "${phrase}".`);
+    }
+  }
+}
+
 const extensionPath = path.join(pluginRoot, 'extensions', 'core', 'extension.json');
 const extensionsDir = path.join(pluginRoot, 'extensions');
 if (fs.existsSync(extensionsDir)) {