# Accessibility Agents 5.0 Release Plan

**Status:** Planning  
**Target:** Major version release  
**Author:** Release planning session, 2026-03-28  
**Last Updated:** 2026-03-27

---

## Executive Summary

Version 5.0 is a major release that transitions Accessibility Agents from a **detection-focused advisory tool** to a **full remediation and compliance platform**. The release centers on three pillars:

1. **Fix, not just find** -- automated remediation across web, document, and PDF content
2. **Ship as a product** -- VS Code Marketplace extension, npm package, Anthropic Connectors Directory listing
3. **Enterprise-grade compliance** -- organizational dashboards, multi-repo scanning, VPAT generation from live data, and audit trail persistence

The jump from 4.x to 5.0 reflects breaking changes in the MCP tool surface (new tools, renamed parameters, remediation tool safety model) and the addition of a first-class distribution channel (VS Code Marketplace).

---

## Release Themes

### Theme 1: Remediation Engine

**Why it matters:** Every accessibility audit produces a report. Teams read the report, then manually fix every issue. The gap between "here are your 47 findings" and "your 47 findings are fixed" is where most accessibility work stalls. 5.0 closes that gap.

**What ships:**

| Deliverable | Description | Open Issue |
|-------------|-------------|------------|
| MCP remediation tools for Office documents | python-docx / openpyxl / python-pptx scripts generated and executed via MCP | [#11](https://github.com/Community-Access/accessibility-agents/issues/11) |
| MCP remediation tools for PDF | pdf-lib / qpdf fix scripts for tag structure, metadata, alt text, language | [#11](https://github.com/Community-Access/accessibility-agents/issues/11) |
| Web auto-fix pipeline | web-issue-fixer upgraded from sub-agent to full MCP tool with file write capability | -- |
| Markdown auto-fix tool | markdown-fixer exposed as MCP tool for CI pipelines | -- |
| Fix verification loop | Apply fix, re-scan affected element, confirm resolution, roll back on regression | -- |
| Safety model | All remediation tools require explicit user confirmation before writing; dry-run mode by default | -- |

**Success metric:** A user can run a full audit and fix more than 60% of findings without leaving the editor.

### Theme 2: Ship as a Product

**Why it matters:** Today, installing Accessibility Agents means cloning a repo and running a script. That works for early adopters but blocks mainstream adoption. 5.0 makes installation a one-click operation on every supported platform.

**What ships:**

| Deliverable | Description | Open Issue |
|-------------|-------------|------------|
| ~~VS Code Marketplace extension~~ | ~~Chat participant, commands, diagnostics, settings~~ | Folded into 5.0.0 |
| ~~npm package for MCP server~~ | ~~`npm install -g @a11y-agent-team/mcp-server` with zero-config startup~~ | Folded into 5.0.0 |
| Anthropic Connectors Directory | Listed in the Claude connectors directory for one-click Claude Desktop install | [#9](https://github.com/Community-Access/accessibility-agents/issues/9) |
| `npx` quickstart | `npx @a11y-agent-team/mcp-server` launches the server without global install | -- |
| GitHub Marketplace action | `community-access/a11y-scan` reusable action for CI pipelines | -- |

**Success metric:** A new user can go from zero to running their first accessibility scan in under 2 minutes on any supported platform.

### Theme 3: Enterprise Compliance

**Why it matters:** Individual developers catch bugs. Organizations need to prove compliance. 5.0 adds the data layer that turns point-in-time audits into continuous compliance evidence.

**What ships:**

| Deliverable | Description | Open Issue |
|-------------|-------------|------------|
| ~~Audit persistence~~ | ~~Scan results stored in `.a11y-history/` with timestamps, enabling trend tracking~~ | Folded into 5.0.0 |
| Organizational dashboard | Aggregate scores across repos, teams, and time periods | -- |
| VPAT generation from live data | `generate_vpat` MCP tool pulls from stored audit history instead of manual input | -- |
| Multi-repo scanning | Scan all repos in a GitHub org with a single prompt | -- |
| Compliance export | Section 508, EN 301 549, EAA mapping with evidence links | -- |
| Audit trail | Immutable log of who scanned what, when, and what was fixed | -- |

**Success metric:** A compliance officer can generate a current VPAT for any product in the organization without running a new scan.

---

## Feature Breakdown

### P1: Remediation MCP Tools (Theme 1)

**Priority:** Critical -- this is the headline feature.

#### P1.1: Office Document Remediation Tool

New MCP tool: `fix_office_document`

- **Input:** `filePath`, `fixes[]` (array of rule IDs to fix), `dryRun` (boolean, default true)
- **Behavior:** Generates and optionally executes python-docx / openpyxl / python-pptx fix scripts
- **Fixes covered:** Missing alt text (placeholder prompt), missing title, missing language, table headers, heading structure, hyperlink text
- **Safety:** Dry-run shows diff before applying. User confirms each fix or batch-approves.
- **Dependency:** Python 3.10+ with python-docx, openpyxl, python-pptx

#### P1.2: PDF Remediation Tool

New MCP tool: `fix_pdf_document`

- **Input:** `filePath`, `fixes[]`, `dryRun` (boolean, default true)
- **Behavior:** Generates pdf-lib / qpdf scripts for metadata, structure, and tag fixes
- **Fixes covered:** Missing title, missing language, DisplayDocTitle, tag structure corrections, alt text injection
- **Safety:** Same dry-run model as Office tool
- **Dependency:** Node.js pdf-lib (no external binary needed for basic fixes); qpdf for advanced structure changes

#### P1.3: Web Remediation Tool

New MCP tool: `fix_web_issue`

- **Input:** `filePath`, `ruleId`, `element` (CSS selector), `fix` (suggested code), `dryRun`
- **Behavior:** Applies source-level fixes to HTML/JSX/TSX/Vue/Svelte files
- **Fixes covered:** Missing alt text, missing labels, lang attribute, tabindex cleanup, ARIA corrections, heading level fixes
- **Safety:** Shows before/after diff. Framework-aware (React vs Vue vs vanilla HTML).
- **Dependency:** None (source text manipulation)

#### P1.4: Fix Verification Loop

Upgrade playwright-verifier from hidden sub-agent to orchestration step:

1. Apply fix via P1.1/P1.2/P1.3
2. Re-scan the fixed element (targeted scan, not full page)
3. Compare results -- PASS (finding gone), FAIL (finding persists), REGRESSION (new finding introduced)
4. On REGRESSION: automatic rollback, surface to user

### P2: npm Package and Anthropic Directory (Theme 2)

**Priority:** High

#### P2.1: npm Package (Folded into 5.0.0)

- ~~Publish `@a11y-agent-team/mcp-server` to npm~~
- ~~`npx @a11y-agent-team/mcp-server` for zero-install quickstart~~
- ~~`npm install -g @a11y-agent-team/mcp-server` for persistent install~~
- ~~Semantic versioning aligned with repo tags~~

Package is publish-ready in 5.0.0 with `publishConfig`, `bin`, `files`, `engines`, and `prepublishOnly` all configured.

#### P2.2: Anthropic Connectors Directory (Partially Folded into 5.0.0)

- ~~Update `anthropic-directory.json` with all tools and resources~~
- Submit to Anthropic's connectors/integrations directory
- One-click install for Claude Desktop users
- Auto-update via npm when new versions publish
- Resolves [#9](https://github.com/Community-Access/accessibility-agents/issues/9)

The directory manifest (`anthropic-directory.json`) is fully synced with all 37 tools and 4 resources in 5.0.0. Actual submission to Anthropic's directory remains a 5.0 task.

#### P2.3: GitHub Marketplace Action (Folded into 5.0.0)

- ~~`community-access/a11y-scan` reusable GitHub Action~~
- ~~Inputs: scan type (web/office/pdf/all), config profile, fail threshold~~
- ~~Outputs: SARIF upload, PR annotations, badge generation~~
- ~~Minimal config: add one line to a workflow file~~

Shipped as composite GitHub Action (`action/`) in 5.0.0 with web static analysis (9 rules), MCP-powered document scanning, SARIF v2.1.0 output, PR annotations, and configurable severity thresholds. Actual Marketplace listing remains a 5.0 task.

### P3: Enterprise Compliance Features (Theme 3)

**Priority:** Medium

#### P3.1: Audit Persistence (Folded into 5.0.0)

- ~~Store scan results in `.a11y-history/{timestamp}-{type}-{target}.json`~~
- ~~Git-trackable (can commit audit history for evidence)~~
- ~~Configurable retention (default: keep last 30 scans per target)~~

Shipped with 4 tools in 5.0.0: `save_audit_result`, `list_audit_history`, `get_audit_result`, `prune_audit_history`. Uses JSON format (not SARIF) for simplicity; SARIF export can be added later if needed.

#### P3.2: Trend Dashboard (Folded into 5.0.0)

- ~~New MCP resource: `a11y://dashboard/summary`~~
- ~~Score progression over time (per-target and aggregate)~~
- ~~Issue velocity: new findings vs fixed findings per scan~~
- WebView panel in VS Code extension (P2.2) -- deferred; data layer shipped

Shipped as `get_audit_trend` tool and `a11y://dashboard/summary` MCP resource in 5.0.0. The VS Code WebView visualization is deferred to a later 5.x update.

#### P3.3: VPAT from Live Data

- `generate_vpat` tool enhanced to pull from `.a11y-history/`
- Auto-populate conformance levels based on last scan
- Highlight criteria with findings vs criteria that pass
- Still supports manual override for criteria that require human judgment

### P4: veraPDF Installer Helper (Folded into 5.0.0)

**Priority:** Medium

- ~~Guided installation via MCP server health check~~
- ~~Auto-detect veraPDF CLI location~~
- ~~Platform-specific install guidance (Windows, macOS, Linux)~~

Shipped as `check_verapdf_installation` tool with Java dependency check and platform-specific install commands.

### P5: Multi-Language Support

**Priority:** Low -- resolves open issue [#14](https://github.com/Community-Access/accessibility-agents/issues/14).

Internationalization of agent instructions and remediation guidance:

- Spanish, French, German, Japanese, Chinese (Simplified) as initial targets
- Locale-specific remediation guidance
- Translated VPAT templates
- Detection of document language for localized rule descriptions

---

## Breaking Changes (Justifying Major Version)

The following changes justify a semver major version bump:

| Change | Impact | Migration |
|--------|--------|-----------|
| MCP tool surface expansion | New tools change the tool registry; clients that enumerate tools will see new entries | No action needed -- additive |
| `generate_vpat` parameter changes | `findings[]` becomes `auditPath` (reads from `.a11y-history/`) | Old parameter still accepted with deprecation warning |
| Remediation tool safety model | New `dryRun` parameter defaults to `true` -- scripts that assume immediate execution break | Add `--no-dry-run` flag for CI scripts that need auto-apply |
| VS Code extension replaces manual agent copy | Extension bundles agents; manually copied agents may conflict | Uninstall old agents before installing extension, or set extension to workspace-only mode |
| Audit history directory (`.a11y-history/`) | New directory created in workspace root on first scan | Add to `.gitignore` if audit history should not be tracked |
| npm package replaces local-only MCP server | Global install changes binary name from `node server.js` to `a11y-mcp-server` | Update MCP config entries to use new binary name |

---

## Folded into 5.0.0 (Previously Tracked Separately)

The following features were originally planned separately but are now part of the 5.0.0 release scope:

| Feature | Original 5.0 Section | 5.0.0 Delivery |
|---------|----------------------|-----------------|
| veraPDF SARIF output | P5.1 | `run_verapdf_sarif` MCP tool |
| EPUB MCP scanning tools | P6.1 | `scan_epub`, `scan_epub_reading_order`, `check_epub_metadata` |
| Markdown MCP scanning tools | P6.2 | `scan_markdown`, `scan_markdown_links` |
| Component audit caching | P4.4 | SHA-256 content hashing, configurable TTL, severity tracking |
| Runtime sub-agent delegation | P7 | Claude Code Task tool added to 5 orchestrators |
| Security and code quality review | P8 | 5 hardening fixes (XSS, ZIP bomb, CORS, sessions, SSRF) |
| VS Code chat participant + slash commands | P2.1 | `@a11y` participant with 41 slash commands routing to all agents |
| Extension commands (Quick Scan, Contrast, Dashboard) | P2.2 | 5 new commands: quickScan, importSarif, clearDiagnostics, checkContrast, showDashboard |
| SARIF diagnostics + Code Actions | P2.3 | Problems panel integration, Quick Fix for image-alt, label, ARIA violations |
| Extension settings | P2.4 | scanProfile, autoScanOnSave, mcpServerUrl, mcpTransport settings |
| Audit persistence | P3.1 | save_audit_result, list_audit_history, get_audit_result, prune_audit_history |
| veraPDF installer helper | P4 | check_verapdf_installation with Java check and platform-specific guidance |
| npm publish readiness | P2.1 | publishConfig, author, bin, files, engines, prepublishOnly configured |
| Trend dashboard (data layer) | P3.2 | `get_audit_trend` tool + `a11y://dashboard/summary` MCP resource |
| APCA contrast (experimental) | P5 stretch | `check_apca_contrast` tool (WCAG 3.0 draft APCA-W3 0.0.98G-4g) |
| Anthropic directory manifest | P2.2 | `anthropic-directory.json` synced with all 37 tools and 4 resources |

---

## Release Milestones

### Milestone 1: Foundation (Weeks 1-3)

- [ ] P1.3: Web remediation tool (simplest fix surface)
- [x] ~~P3.1: Audit persistence (`.a11y-history/`)~~ -- Included in 5.0.0

### Milestone 2: Document Remediation (Weeks 4-6)

- [ ] P1.1: Office document remediation tool
- [ ] P1.2: PDF remediation tool
- [ ] P1.4: Fix verification loop

### Milestone 3: Distribution (Weeks 7-9)

- [x] ~~P2.1: npm package publish~~ -- Included in 5.0.0
- [x] ~~P2.2: Anthropic Connectors Directory manifest~~ -- Included in 5.0.0
- [ ] P2.2: Anthropic Connectors Directory submission (to Anthropic)

### Milestone 4: Enterprise and Polish (Weeks 10-12)

- [ ] P2.3: GitHub Marketplace action
- [x] ~~P3.2: Trend dashboard (data layer)~~ -- Included in 5.0.0
- [ ] P3.2: Trend dashboard (VS Code WebView visualization) -- deferred
- [ ] P3.3: VPAT from live data

### Milestone 5: Stretch Goals

- [x] ~~P4: veraPDF installer helper~~ -- Included in 5.0.0
- [ ] P5: Multi-language support (begin with Spanish)
- [x] ~~WCAG 3.0 APCA contrast tool (preview/experimental)~~ -- Included in 5.0.0

---

## Open Issues Resolved by 5.0

| Issue | Title | Resolution |
|-------|-------|------------|
| [#9](https://github.com/Community-Access/accessibility-agents/issues/9) | Anthropic Connectors Directory listing | P2.2 |
| [#10](https://github.com/Community-Access/accessibility-agents/issues/10) | veraPDF integration for PDF/UA validation | Included in 5.0.0; P4 installer helper also included in 5.0.0 |
| [#11](https://github.com/Community-Access/accessibility-agents/issues/11) | Document remediation tools (fix, not just detect) | P1.1, P1.2 |
| [#14](https://github.com/Community-Access/accessibility-agents/issues/14) | Multi-language support | P5 |
| [#19](https://github.com/Community-Access/accessibility-agents/issues/19) | Full Code and Security Review | Included in 5.0.0 |
| [#83](https://github.com/Community-Access/accessibility-agents/issues/83) | Orchestrator agents cannot delegate to sub-agents | Included in 5.0.0 |

---

## PRD Updates Required

The following sections of prd.md need updates for 5.0:

| Section | Change |
|---------|--------|
| Executive Summary | Update agent count, MCP tool count, platform count |
| MCP Tool Specifications | Add remediation tools (fix_office_document, fix_pdf_document, fix_web_issue) |
| Output Formats | Add audit history format, trend dashboard format |
| Installation and Distribution | Add VS Code Marketplace, npm, Anthropic Directory, GitHub Action |
| Configuration System | Add audit persistence config, cache config |
| Future Roadmap | Move completed items to "Completed" list |
| Non-Functional Requirements | Add performance targets for remediation tools |
| Dependencies | Add python-docx, openpyxl, python-pptx, pdf-lib as optional dependencies |
| Quantitative Summary | Update all counts |

---

## Success Criteria

### Adoption

- VS Code Marketplace: 500 installs in first month
- npm: 200 weekly downloads in first month
- GitHub stars: 100 net new within 60 days

### Quality

- Zero critical or high-severity security findings in release audit
- MCP server test suite: 80+ tests passing
- VS Code extension: all chat commands functional across Windows and macOS

### Impact

- Remediation tools fix more than 60% of detected issues automatically
- Time from first install to first scan under 2 minutes for Marketplace install
- At least 3 enterprise pilot users running multi-repo compliance workflows

---

## Communication Plan

| Channel | Timing | Content |
|---------|--------|---------|
| GitHub Release | Release day | Full release notes with migration guide |
| GitHub Discussion | Release day | Announcement with Q and A thread |
| VS Code Marketplace | Release day | Extension listing with screenshots and demo GIF |
| npm | Release day | Package publish with README |
| Anthropic Directory | Release day | Connector listing submission |
| Blog post | Release day + 1 | "From Detection to Remediation: Accessibility Agents 5.0" |
| Social (X, LinkedIn) | Release day | Thread highlighting top 3 new capabilities |
| Community Access website | Release week | Updated product page |

---

## Risk Register

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|-----------|
| VS Code Marketplace review delays | Medium | Delays distribution launch | Submit early; have npm/Anthropic as parallel channels |
| Remediation tools break user files | Low | High | Dry-run default; backup before write; fix verification loop |
| veraPDF dependency complicates install | Medium | Medium | Keep as optional; built-in scanner covers baseline |
| Multi-language translation quality | Medium | Medium | Start with one language (Spanish); use native speakers for review |
| Enterprise features scope creep | High | Medium | Time-box to Milestone 4; defer anything not code-complete by week 12 |
| Sub-agent delegation platform differences | High | Medium | Document per-platform patterns; accept that some platforms have limitations |
