# Agent Teams Configuration

This file defines coordinated multi-agent workflows for enterprise accessibility scanning in the Claude Code environment.

## Team: Markdown Accessibility Audit

**Lead:** `markdown-a11y-assistant`

**Members:**
- `markdown-scanner` *(hidden helper)* - Per-file scanning across all 9 accessibility domains; returns structured findings
- `markdown-fixer` *(hidden helper)* - Applies auto-fixes and presents human-judgment items for approval
- `markdown-csv-reporter` *(hidden helper)* - Exports findings to CSV with WCAG help links and markdownlint rule references

**Workflow:**
1. `markdown-a11y-assistant` receives the user request and runs Phase 0 (discovery + configuration)
2. `markdown-scanner` is dispatched **in parallel** via the Task tool for each discovered file
3. All scan results are aggregated; cross-file patterns are identified
4. Review gate is presented to the user with auto-fix list + human-judgment items
5. `markdown-fixer` applies approved fixes in a single edit pass per file
6. Final `MARKDOWN-ACCESSIBILITY-AUDIT.md` report is generated with per-file scores and grades

**Handoffs:**
- `markdown-csv-reporter` for CSV export with WCAG help links
- `web-accessibility-wizard` after markdown audit is complete for HTML/JSX/TSX files
- `document-accessibility-wizard` for Office/PDF documents after markdown audit

## Team: Document Accessibility Audit

**Lead:** `document-accessibility-wizard`

**Members:**
- `document-inventory` - File discovery, inventory building, delta detection
- `cross-document-analyzer` - Pattern detection, severity scoring, template analysis
- `word-accessibility` - DOCX scanning and remediation (DOCX-* rules)
- `excel-accessibility` - XLSX scanning and remediation (XLSX-* rules)
- `powerpoint-accessibility` - PPTX scanning and remediation (PPTX-* rules)
- `pdf-accessibility` - PDF scanning and remediation (PDFUA.*, PDFBP.*, PDFQ.* rules)
- `office-scan-config` - Office scan configuration management
- `pdf-scan-config` - PDF scan configuration management
- `epub-scan-config` - ePub scan configuration management
- `document-csv-reporter` - Exports document audit findings to CSV with Microsoft Office and Adobe PDF help links

**Members (PDF Remediation):**
- `pdf-remediator` - Programmatic and manual PDF remediation via pdf-lib/qpdf/ghostscript and Adobe Acrobat Pro

**Members (Office Remediation):**
- `office-remediator` - Programmatic Office document (Word/Excel/PowerPoint) remediation via python-docx/openpyxl/python-pptx

**Members (ePub):**
- `epub-accessibility` - EPUB scanning and remediation (EPUB-E*, EPUB-W*, EPUB-T* rules)

**Workflow:**
1. `document-accessibility-wizard` receives the user request and runs Phase 0 (discovery)
2. `document-inventory` discovers and inventories all matching files
3. File-type specialists (`word-accessibility`, `excel-accessibility`, `powerpoint-accessibility`, `pdf-accessibility`) scan documents in parallel by type
4. `cross-document-analyzer` analyzes patterns, computes severity scores, and detects templates
5. `document-accessibility-wizard` compiles the final report and presents follow-up options

**Handoffs:**
- After audit, user can hand off to any format specialist for targeted remediation
- `web-accessibility-wizard` handles web audit handoff when document audit is complete

## Team: ePub Document Accessibility

**Lead:** `epub-accessibility`

**Internal Helpers:**
- `epub-scan-config` - ePub scan configuration management (invoked via document-accessibility-wizard Phase 0)

**Workflow:**
1. `document-accessibility-wizard` detects `.epub` files in scope and invokes `epub-scan-config` to locate or create `.a11y-epub-config.json`
2. `epub-accessibility` unpacks the EPUB archive, locates the OPF package document, audits metadata, navigation, and content documents
3. Findings are reported using EPUB-E*, EPUB-W*, EPUB-T* rule IDs with WCAG mappings
4. Results feed into `document-accessibility-wizard` for the unified document audit report

**Handoffs:**
- `document-accessibility-wizard` orchestrates EPUB scanning as part of the broader document audit
- `pdf-accessibility` if the user also has PDF documents to scan

## Team: Web Accessibility Audit

**Lead:** `web-accessibility-wizard`

**Members:**
- `accessibility-lead` - Coordinates specialists, runs final review
- `aria-specialist` - ARIA roles, states, properties
- `modal-specialist` - Dialogs, drawers, overlays
- `contrast-master` - Color contrast, visual design
- `keyboard-navigator` - Tab order, focus management
- `live-region-controller` - Dynamic content, toasts, loading
- `forms-specialist` - Forms, inputs, validation
- `alt-text-headings` - Images, alt text, headings, landmarks
- `tables-data-specialist` - Data tables, grids
- `link-checker` - Link text quality
- `testing-coach` - Testing guidance
- `cognitive-accessibility` - WCAG 2.2 cognitive SC, COGA guidance, plain language analysis
- `i18n-accessibility` - Internationalization, RTL, and multilingual accessibility

**Hidden Helpers:**
- `cross-page-analyzer` - Cross-page pattern detection, severity scoring, remediation tracking
- `web-issue-fixer` - Automated and guided accessibility fix application
- `web-csv-reporter` - Exports web audit findings to CSV with Deque University help links
- `scanner-bridge` - Bridges GitHub Accessibility Scanner CI data into the agent ecosystem
- `lighthouse-bridge` - Bridges Lighthouse CI accessibility audit data into the agent ecosystem

**Workflow:**
1. `web-accessibility-wizard` receives the user request and runs Phase 0 (discovery)
2. Phase 0 Step 0: Auto-detects CI scanners (GitHub Scanner, Lighthouse) and dispatches `scanner-bridge` and `lighthouse-bridge` to fetch findings
3. Parallel specialist scanning groups execute based on content:
   - **Group 1:** `aria-specialist` + `keyboard-navigator` + `forms-specialist`
   - **Group 2:** `contrast-master` + `alt-text-headings` + `link-checker` + `text-quality-reviewer`
   - **Group 3:** `modal-specialist` + `live-region-controller` + `tables-data-specialist`
3. `cross-page-analyzer` detects cross-page patterns, computes severity scores, and tracks remediation
4. `web-issue-fixer` applies auto-fixable corrections and presents human-judgment items
5. `web-accessibility-wizard` compiles the final report with scorecard and follow-up options
6. `testing-coach` provides manual testing instructions for issues that require human verification

**Handoffs:**
- After audit, user can ask for interactive fix mode to apply corrections from the report
- Remediation tracking is available by comparing audit reports across runs
- Multi-page comparison audits scan multiple pages and detect cross-cutting patterns

## Team: Mobile Accessibility

**Lead:** `mobile-accessibility`

**Scope:** React Native, Expo, iOS (SwiftUI/UIKit), Android (Jetpack Compose/Views). Invoked standalone for any mobile code review or as a handoff from `accessibility-lead`.

**Workflow:**
1. `mobile-accessibility` identifies platform (React Native / iOS / Android)
2. Audits accessibility props, touch target sizes, screen reader compatibility, focus order
3. Produces a findings report with platform-specific rule IDs and fix code
4. Handoffs: `design-system-auditor` for token-level issues; `accessibility-lead` for web companion audits

## Team: Design System Accessibility

**Lead:** `design-system-auditor`

**Scope:** Tailwind config, CSS custom properties, Style Dictionary token files, MUI/Chakra/Radix themes. Invoked standalone or as a Phase 0 step before web or mobile audits.

**Workflow:**
1. `design-system-auditor` locates token files and identifies design system type
2. Audits color token pairs for WCAG contrast compliance
3. Audits focus ring tokens (WCAG 2.4.13 Focus Appearance), spacing/touch-target tokens, motion tokens
4. Produces a token-level findings report with compliant replacement values
5. Handoffs: `contrast-master` for runtime verification; `mobile-accessibility` for spacing tokens

## Team: Full Audit (Web + Documents)

**Lead:** `accessibility-lead`

**Workflow:**
1. `web-accessibility-wizard` runs the web accessibility audit (with severity scoring and framework detection)
2. `document-accessibility-wizard` runs the document accessibility audit
3. `accessibility-lead` compiles a unified report covering both web and document findings
4. Cross-cutting patterns (e.g., shared templates, design system issues) are highlighted across both audits

## Team: Developer Tools

**Lead:** `developer-hub`

**Members:**
- `python-specialist` - Python language expert: debugging, packaging, testing, type checking, async, optimization
- `wxpython-specialist` - wxPython GUI expert: sizers, events, AUI, custom controls, threading, desktop accessibility
- `desktop-a11y-specialist` - Desktop application accessibility: platform APIs (UIA, MSAA, NSAccessibility), screen reader interaction, focus management, custom widget accessibility
- `desktop-a11y-testing-coach` - Desktop accessibility testing: NVDA, JAWS, Narrator, VoiceOver, Accessibility Insights, automated UIA testing, keyboard-only testing
- `a11y-tool-builder` - Accessibility tool building: rule engines, document parsers, report generators, WCAG mapping, severity scoring, CLI/GUI scanner architecture
- `nvda-addon-specialist` - NVDA addon development: architecture, globalPlugins, appModules, synthDrivers, brailleDisplayDrivers, manifest format, event/script handling, NVDAObject overlays, addon packaging, Add-on Store submission, testing, i18n
- `text-quality-reviewer` - Non-visual text quality review: template variables in alt text, code syntax as names, placeholder labels, filename alt text, duplicate labels, label-in-name violations

**Skills:**
- `python-development` - Python version reference, pyproject.toml patterns, PyInstaller modes, wxPython sizer/event/threading cheat sheets, desktop accessibility API reference, common pitfalls, cross-platform paths, testing, logging

## Team: CI/CD & Education

Specialist agents for CI pipelines, standards education, and screen reader simulation:

- `ci-accessibility` - CI/CD accessibility pipeline setup and management (GitHub Actions, Azure DevOps, GitLab CI, CircleCI, Jenkins)
- `screen-reader-lab` - Interactive screen reader simulation for education and debugging
- `wcag3-preview` - WCAG 3.0 draft education and transition planning
- `wcag-aaa` - WCAG AAA conformance auditing (enhanced contrast, extended audio descriptions, reading level)

**Workflow:**
1. `developer-hub` receives the user request and classifies intent (debug, package, scaffold, review, optimize, GUI work, desktop a11y, tool building, NVDA addon development, text quality review)
2. For pure Python tasks, routes to `python-specialist` with full context
3. For wxPython/GUI tasks, routes to `wxpython-specialist` with full context
4. For desktop accessibility API work, routes to `desktop-a11y-specialist`
5. For screen reader testing, routes to `desktop-a11y-testing-coach`
6. For NVDA addon development, routes to `nvda-addon-specialist`
7. For building a11y scanning tools, routes to `a11y-tool-builder`
8. For non-visual text quality auditing, routes to `text-quality-reviewer`
9. For web accessibility audits, hands off to `web-accessibility-wizard` (Web Accessibility team)
10. For document accessibility audits, hands off to `document-accessibility-wizard` (Document Accessibility team)
11. For mixed tasks, starts with the primary domain specialist and hands off as needed
12. All agents can hand back to `developer-hub` for broader coordination

**Handoffs:**
- `developer-hub` -> `python-specialist` for debugging, packaging, testing, type checking, async, optimization
- `developer-hub` -> `wxpython-specialist` for GUI construction, sizer layouts, event handling, threading, accessibility
- `developer-hub` -> `desktop-a11y-specialist` for platform API implementation, screen reader interaction model
- `developer-hub` -> `desktop-a11y-testing-coach` for screen reader testing, Accessibility Insights, automated UIA tests
- `developer-hub` -> `a11y-tool-builder` for rule engine design, document parsers, report generators
- `python-specialist` <-> `wxpython-specialist` (bidirectional: Python-in-GUI and GUI-needing-Python)
- `wxpython-specialist` <-> `desktop-a11y-specialist` (bidirectional: GUI accessibility patterns)
- `desktop-a11y-specialist` <-> `desktop-a11y-testing-coach` (bidirectional: implement then test)
- `a11y-tool-builder` <-> `python-specialist` (bidirectional: tool code needs Python expertise)
- Any developer agent -> `web-accessibility-wizard` for web content auditing (cross-team)
- Any developer agent -> `document-accessibility-wizard` for document auditing (cross-team)
- Any agent -> `developer-hub` for task completion or scope changes

## Enterprise Scanning Patterns

### Large Repository Scanning

For repositories with 100+ documents:

1. Use `document-inventory` with delta scanning to identify changed files
2. Scan changed files first with strict profile
3. Use moderate profile for full repository baseline scans
4. Schedule weekly re-scans via CI/CD (see Phase 6 in document-accessibility-wizard)

### Multi-Team Coordination

When multiple teams own different document folders:

1. Create per-folder `.a11y-office-config.json` with team-appropriate profiles
2. Use folder-scoped scans to generate per-team reports
3. Use `cross-document-analyzer` to detect organization-wide patterns
4. Generate per-team scorecards and a rollup organizational scorecard

### Compliance Reporting

For Section 508, EN 301 549, or organizational compliance:

1. Run strict profile scan across all document types
2. Generate VPAT/ACR export from audit results
3. Track remediation progress by comparing successive audit reports
4. Export SARIF for integration with compliance tracking systems

### Web Audit Patterns

**Single-Page Deep Audit:**
1. Run a combined axe-core scan + manual code review
2. Framework-specific patterns are detected automatically (React, Vue, Angular, Svelte, Tailwind)
3. Severity scoring produces a 0-100 score with A-F grade

**Multi-Page Comparison:**
1. Provide a base URL and page paths for multi-page scanning
2. `cross-page-analyzer` identifies systemic vs template vs page-specific issues
3. Comparative scorecard shows per-page scores and cross-cutting patterns

**Remediation Workflow:**
1. Run initial audit
2. Apply fixes interactively (auto-fixable + human-judgment items)
3. Track progress by comparing audit reports between runs
4. Use quick triage mode for fast axe-core scans between full audits

## Team: GitHub Workflow Management

**Lead:** `github-hub` or `nexus` (alternative entry points - same team, both orchestrate all GitHub workflow agents)

**Members:**
- `daily-briefing` - Daily GitHub command center: issues, PRs, reviews, releases, discussions, accessibility updates
- `issue-tracker` - Issue search, triage, deep-dive, commenting, management, and dual-format workspace documents
- `pr-review` - PR diff analysis, before/after snapshots, review comments, code suggestions, and review documents
- `analytics` - Team velocity, review turnaround, issue resolution metrics, bottleneck detection, code churn
- `insiders-a11y-tracker` - Tracks accessibility changes in VS Code Insiders and custom repos with delta tracking
- `repo-admin` - Collaborator management, access auditing, branch protection, label sync, repo settings
- `team-manager` - Org team member management, onboarding/offboarding checklists, cross-repo access sync
- `contributions-hub` - Discussion management, community health, contributor insights, first-time contributor support
- `template-builder` - Interactive issue/PR/workflow template wizard with YAML frontmatter generation
- `repo-manager` - Repo infrastructure scaffolding: templates, CI/CD, labels, README, CONTRIBUTING, licenses
- `projects-manager` - GitHub Projects v2 boards, views, custom fields, iterations via GraphQL API
- `actions-manager` - GitHub Actions workflow runs, logs, re-runs, and CI debugging via REST API
- `security-dashboard` - Dependabot, code scanning, and secret scanning alert triage via REST API
- `release-manager` - Releases, tags, assets, and release note generation via REST API
- `notifications-manager` - Notification inbox management, filtering, and subscriptions via REST API
- `wiki-manager` - Wiki page creation, editing, search, and organization via wiki git repo

**Skills:**
- `github-workflow-standards` - Auth, smart defaults, dual MD+HTML output, HTML accessibility, safety rules, parallel execution
- `github-scanning` - Search query patterns, date range handling, cross-repo intelligence, auto-recovery
- `github-analytics-scoring` - Repo health scoring (0-100/A-F), priority scoring, confidence levels, delta tracking

**Workflow:**
1. User invokes `github-hub` or `nexus` with any natural language request about GitHub
2. The orchestrator identifies the authenticated user, discovers repos/orgs, and loads `preferences.md`
3. The orchestrator classifies user intent and routes to the appropriate specialist agent
4. Specialist agents run their workflow, announce steps with / pattern, collect data in parallel
5. All reports saved as dual `.md` + `.html` outputs to `.github/reviews/` subdirectories
6. Agents surface relevant handoffs (e.g., `issue-tracker` -> `pr-review` for linked PRs)

**Parallel Execution Model:**
- `daily-briefing` runs Batch 1 streams simultaneously: issues, PRs, CI/security, accessibility
- `analytics` collects PR metrics, issue metrics, contribution activity, churn, and bottleneck data in parallel
- `github-hub` routes to multiple sub-agents in one session without repeating context
- `nexus` routes identically - both orchestrators share the same team and handoff logic

**Confidence & Delta Tracking:**
- All agents tag findings with **High / Medium / Low** confidence
- `analytics`, `issue-tracker`, `pr-review`, and `insiders-a11y-tracker` support delta tracking across reports:  Resolved /  New /  Persistent /  Regressed
- Persistent bottlenecks (3+ consecutive reports) trigger escalation flags

**Handoffs:**
- `github-hub`/`nexus` -> any specialist via intent routing
- `daily-briefing` -> `issue-tracker` (deep dive on issue), `pr-review` (full review), `analytics` (team metrics), `insiders-a11y-tracker` (a11y detail)
- `issue-tracker` <-> `pr-review` (bidirectional: linked PRs/issues)
- `projects-manager` <-> `issue-tracker` (project board items link to issues)
- `actions-manager` <-> `pr-review` (CI status links to PRs)
- `security-dashboard` <-> `issue-tracker` (security alerts may need triage)
- `release-manager` <-> `pr-review` (release notes from merged PRs)
- Any agent -> `github-hub` or `nexus` for scope changes or re-routing

---

## Multi-Agent Workflow Reliability Standards

All teams in this workspace follow the engineering patterns from [Multi-agent workflows often fail. Here's how to engineer ones that don't.](https://github.blog/ai-and-ml/generative-ai/multi-agent-workflows-often-fail-heres-how-to-engineer-ones-that-dont/) Treat agents as distributed system components, not chat interfaces.

### Structured Outputs at Every Boundary

Agents MUST return structured data at handoff points. Never pass unstructured prose between agents.

**Accessibility finding:**
- Rule ID, severity (`critical`|`serious`|`moderate`|`minor`), location, description, remediation, confidence (`high`|`medium`|`low`)

**Scored output:**
- Score (0-100), grade (A-F), issue counts by severity, pass/fail verdict

**Action result:**
- Action taken, target, result (`success`|`failure`|`skipped`), reason (if not success)

### Constrained Action Sets

Each agent operates within explicitly defined boundaries:

- **Read-only agents** (scanners, analyzers, reporters): read files, fetch data, produce findings. May NOT edit files or make state changes.
- **State-changing agents** (fixers, admin agents): perform their defined mutations ONLY after explicit user confirmation.
- **Orchestrators** (github-hub, nexus, accessibility-lead, wizards): route, aggregate, and present. State changes require user approval before delegation.

If an agent encounters a task outside its action set, it MUST refuse, name the correct agent, and offer to hand off.

### Boundary Validation

At every handoff:

1. **Before delegating:** Confirm all required inputs (file paths, URLs, config, scope) are available. Resolve missing inputs before delegating. Never delegate with partial context.
2. **After receiving results:** Verify structured fields are present (findings, scores, verdicts). Retry once if incomplete. Report partial results with clear gap notes if retry fails.
3. **Orchestrator checklist:** Intent classified, scope resolved, config loaded, sub-agent inputs complete, user confirmation obtained (for state changes).

### Failure Handling

- Tool call fails: report, explain, offer alternatives. Max 2 retries.
- Partial scan results: report what succeeded, list failures with reasons, offer targeted retry.
- Missing context: state defaults being used. Never assume unverified context.
- Graceful degradation: full workflow, then simpler alternative, then partial results with gaps noted. Never return empty output without explanation.

### Progress and Intermediate State

- Phase start: announce what is starting, scope size, expected complexity.
- Phase end: state what was found/accomplished, counts, what comes next.
- Workflow end: recap phases, aggregate counts, present final deliverable.

### Agent Isolation and Ordering

- Dependent agents run sequentially. Independent agents run in parallel.
- Each agent operates on its defined scope. Parallel groups work on distinct concerns.
- Same inputs produce same structured outputs (idempotent).
- Output format changes must be backward-compatible.