Repository navigation
2026 09 Modernization
Version target: 7.0.0 Written: 2026-09-21 Status: complete. Phases 0 through 6 applied 2026-09-21. Section 11 records the impact; docs/MODERNIZATION-CONFORMANCE.md holds the evidence. Scope: replace every harness-specific surface this repo ships (Claude plugin, Codex plugin, Gemini extension, Copilot agents, prompts and instructions, VS Code extension) with one package built on the open agent standards, and cut per-turn and per-dispatch context cost by an order of magnitude on every harness.
Companion documents: docs/MODERNIZATION-CONFORMANCE.md (standards, gates, measured results, defects found), docs/CONFORMANCE-AUDIT-2026-09.md (the audit that preceded this work).
Ship one standards-based package that every harness reads natively:
-
AGENTS.mdfor always-on instructions (agents.md standard). -
skills/for every agent, orchestrator and specialist alike (Agent Skills standard, agentskills.io). -
plugin.jsonfor packaging (Agent Plugins 1.0, agent-plugins.org). -
mcp.jsonplus the MCP server on the 2026-07-28 protocol.
No per-harness agent bodies, no per-harness instruction files, no per-harness copies. The only client-specific files left are hook manifests (event names differ per client) and two thin manifests that point at the same skills/ directory. Token cost is measured and budgeted in CI.
Figures are from the working tree at commit 161c60c plus today's uncommitted conformance fixes. Token estimates use chars/4.
Each harness, with its item and approx tokens.
| Harness | Item | Approx tokens |
|---|---|---|
| Claude Code (repo) | CLAUDE.md |
5,400 |
| Claude Code (plugin) | 80 registered agent descriptions | 6,200 |
| Codex | 80 agents/*.toml descriptions + AGENTS.md
|
7,600 |
| Copilot |
copilot-instructions.md + 85 agent descriptions |
11,800 |
| Gemini |
GEMINI.md + 101 skill descriptions |
2,300 + catalog |
- Orchestrators read a specialist body into their own context, then paste it into the subagent prompt. A 19 KB specialist costs about 5k tokens to read and 5k to send before any work starts.
- Every spawned Claude subagent loads the project
CLAUDE.md(5.4k tokens). A ten-specialist audit spends about 54k tokens loading the same file. -
web-accessibility-wizard.mdis 78 KB (about 20k tokens) and loads whole on every run.document-accessibility-wizard.mdis 46 KB,pr-review.md54 KB,daily-briefing.md37 KB,issue-tracker.md35 KB. - Reports are typed by the model from a 400-line template. A 60-finding report costs about 15k output tokens that a script can render from JSON for free.
The same specialist body exists in five or six hand-maintained copies that have already drifted (six distinct content hashes for aria-specialist across .claude/specialists, claude-code-plugin/agents, codex-skills, codex-plugin/references/specialists, .gemini/.../skills, .github/agents). About 6.6 MB of agent text is in git for about 1.1 MB of unique content. scripts/check-platform-parity.js checks that files exist per platform, not that they match.
-
.claude/agents/accessibility-lead.mdcontains its opening paragraph twice. -
.claude/hooks/hooks-consolidated.jsonuses Copilot matcher keys and is not a Claude Code hooks file..claude/settings.jsonis{}, so the repo itself has no active Claude Code hooks. - Root clutter every harness listing pays for:
.history/,markdownlint-output.txt(88 KB),source-validation-results.json(282 KB),tmp-*.json, a stray file namedC, two sample audit outputs, sevenRELEASE-*.md. - MCP server: 38 tools, none with
annotationsoroutputSchema.
Each standard, with its spec, claude code, codex, copilot (vs code, CLI, cloud) and gemini CLI or antigravity.
| Standard | Spec | Claude Code | Codex | Copilot (VS Code, CLI, cloud) | Gemini CLI / Antigravity |
|---|---|---|---|---|---|
| AGENTS.md | agents.md | via CLAUDE.md containing @AGENTS.md
|
native, root down to cwd, 32 KiB cap | native, nearest wins | via context.fileName or extension contextFileName
|
| Agent Skills | agentskills.io/specification |
.claude/skills, .agents/skills, plugin skills/
|
.agents/skills, ~/.agents/skills
|
.github/skills, .claude/skills, .agents/skills
|
.agents/skills, .gemini/skills
|
| Agent Plugins 1.0 | agent-plugins.org | reads .claude-plugin/plugin.json
|
reads .codex-plugin/plugin.json (has not adopted 1.0 yet) |
native 1.0 plugin.json, also reads .claude-plugin/plugin.json
|
extensions carry over as Antigravity plugins |
| MCP 2026-07-28 | modelcontextprotocol.io | yes | yes | yes | yes |
Facts that shape the design:
- Every client loads only skill name and description at startup and the body on activation. Codex caps the catalog at 2 percent of the context window (about 8,000 chars) and shortens descriptions under pressure, so descriptions must be short and front-loaded.
- Skill spec limits: name 64 chars matching the directory, description 1,024 chars, body under 5,000 tokens and 500 lines,
references/one level deep,scripts/for deterministic work. - Codex
AGENTS.mddiscovery stops at 32 KiB combined. Copilot asks for under two pages. - Claude Code and VS Code honour
disable-model-invocation: true(skill is user-only and its description leaves the model's context). Codex has the equivalentagents/openai.yamlwithpolicy.allow_implicit_invocation: false. Gemini has neither but only pays about 25 tokens per catalog entry. - Gemini CLI stopped serving individual users on 2026-06-18 in favour of Antigravity CLI, which reads the same skills and
AGENTS.md. The Gemini extension format is a legacy target. - VS Code, Copilot CLI and the Copilot app install Agent Plugins 1.0 natively as of 2026-08-12, which removes the reason for a separate VS Code extension.
- MCP 2026-07-28 is stateless,
tools/listreturnsttlMsandcacheScope, and servers should return tools in deterministic order to keep prompt caches warm. Tool annotations andoutputSchemaare how clients auto-approve read-only scanners and parse results.
- One package, zero copies. Everything lives once at the repo root in standard locations. Anything a client needs in a different path is created by the installer at install time, never committed.
- Skills are the unit of everything. Orchestrators are router skills; specialists are skills with
references/; helpers are hidden skills. No harness-native subagent definitions. - Tiered catalog. Six router skills are model-invocable. Every other skill is user-invocable only, so it costs the model nothing until a router dispatches it.
- Pointer dispatch. A router spawns the client's generic subagent with a 300-token prompt that names the skill to activate. The router never reads specialist bodies.
- Structured findings, scripted reports. Specialists emit JSON matching one schema;
scripts/render reports, CSV, VPAT and statements. - Enforcement stays. The three-hook gate (detect, block edit, mark reviewed) survives on every client that supports hooks, driven by one guard script.
- Budgets in CI. Numbers in
budgets.json, checked on every pull request.
AGENTS.md always-on contract, <= 1,200 tokens
CLAUDE.md one line: @AGENTS.md
plugin.json Agent Plugins 1.0 manifest
mcp.json MCP server registration (stdio, npx)
.claude-plugin/plugin.json thin: name, version, description (VS Code and Claude read it)
.codex-plugin/plugin.json thin: name, version, skills: ./skills/, hooks (until Codex adopts 1.0)
skills/
a11y-core/ shared assets, never dispatched
SKILL.md what the pack is, output contract, dispatch contract
references/sources.md the one "Authoritative Sources" list
references/report-requirements.md
schemas/findings.schema.json
scripts/render-report.mjs
scripts/merge-findings.mjs
scripts/measure-context.mjs
accessibility-lead/ router (model-invocable)
SKILL.md <= 4 KB
references/dispatch-matrix.md
web-accessibility-wizard/ router
SKILL.md <= 6 KB: phases, gates, outputs
references/phase-0-discovery.md
references/framework-intelligence.md
references/severity-scoring.md
references/ci-integration.md
references/edge-cases.md
document-accessibility-wizard/ router
markdown-a11y-assistant/ router
developer-hub/ router
github-hub/ router (nexus becomes an alias line in AGENTS.md)
aria-specialist/ specialist (user-invocable only)
SKILL.md <= 4 KB core checklist
references/apg-patterns.md
references/violations.md
agents/openai.yaml policy.allow_implicit_invocation: false
... (about 60 more specialists and helpers, same shape)
hooks/
guard.mjs one script, all events, all clients
claude.hooks.json event names for Claude Code
codex.hooks.json event names for Codex
copilot.hooks.json event names for Copilot (version 1 format)
gemini.hooks.json event names for Gemini / Antigravity
mcp-server/ unchanged location, protocol 2026-07-28
templates/ scan config profiles, unchanged
docs/
example/
scripts/ build, validate, install, release
budgets.json
Removed after cutover: .claude/agents, .claude/specialists, .claude/hooks, .claude/AGENTS.md, claude-code-plugin/, codex-plugin/, codex-skills/, .codex/, .gemini/, gemini-extension.json, GEMINI.md, .github/agents, .github/skills, .github/prompts, .github/instructions, .github/copilot-instructions.md, plugin.yaml, vscode-extension/, .a11y-agent-manifest.
Only spec fields plus the two extension fields that Claude Code and VS Code both honour. Everything else goes in metadata, which the spec allows and clients ignore.
---
name: aria-specialist
description: ARIA roles, states and properties for custom widgets, dialogs, tabs, comboboxes and live regions. Use when building or checking interactive web components.
disable-model-invocation: true
metadata:
tier: specialist
domain: web
output: findings
effort: medium
---Router skills omit disable-model-invocation and keep descriptions under 160 chars with the trigger first: "Web UI accessibility lead. Use before editing HTML, JSX, TSX, Vue, Svelte, CSS or templates; picks specialists and merges findings."
A router dispatches with the client's generic subagent primitive (Claude Code: Agent tool; Codex: spawn a worker; Copilot: subagent; Gemini: generalist). The prompt is fixed at under 300 tokens:
Activate the skill "aria-specialist" (if activation is unavailable, read skills/aria-specialist/SKILL.md) and follow it.
Task: <one paragraph>
Scope: <file list or glob>
Rules: semantic HTML before ARIA; report, do not edit.
Return ONLY JSON matching skills/a11y-core/schemas/findings.schema.json.
The specialist reads its own instructions in its own context. The router receives JSON, not prose. The dispatch matrix (accessibility-lead/references/dispatch-matrix.md) is the only place the model learns which specialists exist, since their descriptions are out of its catalog.
skills/a11y-core/schemas/findings.schema.json (JSON Schema 2020-12):
{
"type": "object",
"required": ["skill", "scope", "findings"],
"properties": {
"skill": { "type": "string" },
"scope": { "type": "array", "items": { "type": "string" } },
"findings": {
"type": "array",
"items": {
"type": "object",
"required": ["rule", "wcag", "severity", "location", "summary", "fix"],
"properties": {
"rule": { "type": "string" },
"wcag": { "type": "string" },
"severity": { "enum": ["critical", "serious", "moderate", "minor"] },
"confidence": { "enum": ["high", "medium", "low"] },
"location": { "type": "string" },
"summary": { "type": "string", "maxLength": 240 },
"fix": { "type": "string", "maxLength": 480 },
"evidence": { "type": "string", "maxLength": 480 }
}
}
},
"passed": { "type": "array", "items": { "type": "string" } }
}
}node skills/a11y-core/scripts/render-report.mjs .a11y-history/<run>/*.json --template web --out WEB-ACCESSIBILITY-AUDIT.md renders every section required by references/report-requirements.md and embeds the merged JSON in a fenced block at the end so delta tracking never re-parses prose. CSV, VPAT and statement generators consume the same JSON. The MCP server exposes the same renderer as render_accessibility_report so clients without a shell reach it.
- What the pack enforces, in one paragraph.
- The rule: before editing UI files, dispatch
accessibility-lead; before touching Office or PDF, dispatchdocument-accessibility-wizard; markdown,markdown-a11y-assistant. - The six router names with one line each.
- The non-negotiable standards list (eight lines).
- Pointer: full agent reference in
docs/agents/, report requirements inskills/a11y-core/references/report-requirements.md.
Everything else in today's CLAUDE.md (agent tables, knowledge domains, VS Code feature notes, scan configuration, report requirements) moves to docs/ or to a11y-core/references/.
hooks/guard.mjs handles every event by reading the event name from stdin JSON and dispatching to one of four behaviours: detect (inject the delegation reminder once per session, capped at 60 words), gate (deny UI edits until a marker exists, reason capped at 40 words), mark (write the marker when the lead subagent stops), persist (write phase and findings path before compaction, re-inject a 100-word state line after). Four manifests map client event names to the same script:
| Behaviour | Claude Code | Codex | Copilot | Gemini |
|---|---|---|---|---|
| detect | UserPromptSubmit | UserPromptSubmit | userPromptSubmitted | BeforeAgent |
| gate | PreToolUse (Edit, Write) | PreToolUse (apply_patch, Edit, Write) | preToolUse | BeforeTool (write_file, replace) |
| mark | SubagentStop (accessibility-lead) | SubagentStop | postToolUse | AfterAgent |
| persist | PreCompact, SessionStart | PreCompact, SessionStart | none | PreCompress, SessionStart |
| finalize | Stop | Stop | none | AfterAgent |
Copilot has no Stop event, so the edit gate is the enforcement point there.
Each budget, with its now, target and check.
| Budget | Now | Target | Check |
|---|---|---|---|
| Always-on, Claude Code (AGENTS.md + 6 router descriptions) | ~11,600 | 1,500 | measure-context --client claude |
| Always-on, Codex (AGENTS.md + catalog) | ~7,600 | 1,500 | measure-context --client codex |
| Always-on, Copilot | ~11,800 | 1,500 | measure-context --client copilot |
| Always-on, Gemini / Antigravity (AGENTS.md + catalog names) | ~2,300 + catalog | 3,000 | measure-context --client gemini |
| Router-side cost per specialist dispatch | ~10,000 | 300 | measure-context --dispatch |
Largest SKILL.md
|
78 KB | 6 KB | validate-skills --max-body 6144 |
| Copies of any agent body in git | 5-6 | 1 | validate-skills --no-shadow-trees |
| Skill catalog under Codex 2 percent cap (about 8,000 chars for 66 skills) | over | under | measure-context --client codex |
Files: create skills/a11y-core/scripts/measure-context.mjs, budgets.json; modify .github/workflows/validate-agents.yml.
-
measure-context.mjssums, per client: instruction files the client loads (AGENTS.md, plus legacyCLAUDE.md,GEMINI.md,copilot-instructions.mdwhile they exist), model-invocable skill descriptions, registered agent descriptions in legacy trees, and the literal strings the hook scripts inject. Output is a table and JSON. The estimator is one function (chars/4) so it can be replaced with a tokenizer later. -
budgets.jsonstarts at the "Now" numbers plus 5 percent so CI passes today and fails on regression. - Commit
docs/context-baseline-2026-09.json.
Verify: node skills/a11y-core/scripts/measure-context.mjs --check budgets.json exits 0.
Shipped. measure-context.mjs reports per client a current column (the
standard package) and a legacy column (the per-harness trees Phase 6 removes),
so the transition is visible rather than averaged away. --dispatch prices
router-side dispatch by naming the specialist that costs the most. Baseline in
docs/context-baseline-2026-09.json, ceilings in budgets.json, CI step added
to .github/workflows/validate-agents.yml.
Files: create skills/ (all 80 agents as skills), AGENTS.md (new), plugin.json, mcp.json, thin .claude-plugin/plugin.json and .codex-plugin/plugin.json; create scripts/migrate-agents-to-skills.mjs (one-shot), scripts/validate-skills.mjs; modify CLAUDE.md to @AGENTS.md.
- Migration script, run once against the
.claude/agentsand.claude/specialistscopies (the most-edited tree). For each agent: frontmatter to spec fields, tier from.claude/AGENTS.md(registered means router), body split at the first##heading intoSKILL.mdcore andreferences/<slug>.mdfor any section over 1.5 KB that is not part of the core loop, with a one-line pointer left in place. The script also diffs the six legacy copies and writesbuild/drift-report.mdlisting lines present in one copy only, for hand review of the web team and the three wizards. -
validate-skills.mjs: wrapsskills-ref validate(agentskills.io reference validator), then checks body size, description length, router count equals six, every specialist hasdisable-model-invocation: trueandagents/openai.yaml, every specialist appears in at least one router's dispatch matrix, and no legacy tree shadows a skill name. -
plugin.json:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "accessibility-agents",
"version": "7.0.0",
"description": "WCAG 2.2 AA enforcement: router and specialist skills, hooks, MCP scanners.",
"skills": "./skills/",
"mcp": "./mcp.json"
}Thin .claude-plugin/plugin.json and .codex-plugin/plugin.json carry name, version, description and point at ./skills/ and the matching hook manifest.
4. AGENTS.md per section 5.4; CLAUDE.md becomes the single line @AGENTS.md.
5. Run every existing validator that still applies, then claude plugin validate ., skills-ref validate skills/*, and a Copilot plugin install from the local path.
Verify: node scripts/validate-skills.mjs exits 0; the six routers appear in the Claude Code skill list and the specialists do not; /aria-specialist works as a user command; Codex $aria-specialist works and the catalog is under its cap.
Shipped, with four decisions made during the work.
-
Knowledge domains became skills too. The 26 files in
.github/skillswere cited by agents as../skills/<name>/SKILL.md, a path that resolved to nothing from either the old location or the new one. They migrated asskills/kb-*at a fourth tier,reference: neither user- nor model-invocable, so they cost no catalog, and exempt from the 6 KiB body budget because splitting a lookup table makes it slower to use. Thekb-prefix keepscognitive-accessibilitythe knowledge base distinct fromcognitive-accessibilitythe specialist. 47 dead links repointed. -
Authoritative Sources blocks were pulled out early. Every agent opened
with the same shape of specification list, about 400 bytes each. They now
live in
skills/a11y-core/references/sources.md, grouped by skill, which bought back budget the mechanical split spends on real instructions. The identity paragraph that shared those sections was preserved. -
Dispatch matrices were generated, not deferred. Splitting routers
mechanically left 34 specialists named by nobody, and specialists are
invisible to the model by design, so that would have made them unreachable.
Each router now carries a pinned dispatch block and a generated
references/dispatch-matrix.mdcovering its domains. The validator fails if a specialist appears in no matrix. -
Duplicate content was collapsed. 21 agents carried a paragraph verbatim
twice, including
accessibility-leadand its opening statement. Whole sections were duplicated too, usually a title block pasted twice with the two link spellings the old trees used; those are dropped when the repeat says nothing the first did not. Sections containing a fence are left alone.
Then the package was held to this project's own accessibility rules, which
it had never been subject to: the Claude tree is excluded from markdownlint, and
markdown-a11y-lint.mjs had never been pointed at it. Running it found real
defects in the migrated output and one in the linter.
- 16 multiple-H1 errors. A skill's title is its frontmatter name, so the body must start at H2. Every body H1 is now demoted, fence-aware, and the validator fails on any that come back.
-
278 bare URLs. The source lists were
**Name** - https://url. They are now[Name](https://url), which also removes the em-dash separators this project's own markdown rules flag. One remaining case was an examplelocalhostaddress, now in code formatting rather than presented as a link. -
Dead and misdirected links. Reference files sit one directory deeper than
the SKILL.md they came from, so their relative links were one level short;
they are now reparented on write. Citations of
../skills/<name>/and../../.github/skills/<name>/resolved to nothing from either the old or the new location and now point at the migratedkb-skills.shared-instructions.md, cited 25 times and 22 KB of real shared behaviour, migrated askb-github-shared-instructionsrather than being left behind. -
A bug in the linter.
md-table-descchecked only the line immediately above a table, so the only way to satisfy it was to delete the blank line between the description and the table. GitHub Flavored Markdown does not recognise a table that interrupts a paragraph, so that markdown would not have rendered as a table at all. The rule now looks back past blank lines. This cut the repository-wide count from 2,251 to 1,312 without touching a single document, and two unit tests now hold the behaviour in place.
What remains is 191 table-description warnings in the skills tree, one or two per file across about 150 files, inherited from agent content. Each needs a sentence written for it, which is content work rather than migration work, so it is scoped to Phase 2. Everything this migration generates is clean.
Results: 107 skills (6 routers, 57 specialists, 16 helpers, 28 references).
Catalog 5,995 chars against the Codex 8,000 cap. Largest dispatchable body 6,131
bytes, none over budget. Always-on cost, Claude Code, fell from 15,924 tokens to
9,166 with the legacy trees still present, and the standard package alone costs
1,620. claude plugin validate skills --strict passes, every existing validator
still passes, and both check-skill-conformance.mjs and the conformance workflow
now cover skills/. Drift across the six legacy copies is catalogued in
build/drift-report.md for hand review before Phase 6 deletes them.
Not run, because they need a live client rather than a script: confirming in a
running session that the six routers appear in the skill list and the
specialists do not, that /aria-specialist resolves as a user command, and that
Codex accepts $aria-specialist. The static equivalents pass. skills-ref validate from the specification authors was also not run; it is not installed
here and installing it was not in scope.
Two items deliberately left to Phase 2, and reported by the validator as
backlog rather than hidden: accessibility-lead and developer-hub still
mention the legacy .claude/specialists/ path in prose, and the routers' phase
structure is still the mechanical split rather than a semantic one.
Files: modify the six router SKILL.md files and the five largest specialist skills; modify accessibility-lead/references/dispatch-matrix.md; rewrite scripts/validate-orchestrator-dispatch.js as part of validate-skills.mjs.
- Split every
SKILL.mdover 6 KB. Routers keep role, the question gate, one line per phase, which reference to read per phase, output path, handoffs. Phase instructions say "Read references/phase-0-discovery.md now" so only the active phase is in context. - Replace every "Authoritative Sources" block with one pointer line to
a11y-core/references/sources.md. - Fix the duplicated intro paragraph in accessibility-lead while splitting.
- Rewrite every dispatch to the section 5.2 form. The validator fails on any
Read(".claude/specialists/..."), any inline body paste, and any router that names a skill missing from the matrix. - Effort and model hints go in
metadata(effort: lowfor inventory, csv and scan-config helpers;mediumfor checklist specialists;highfor routers). Routers pass the hint through in the dispatch prompt where the client supports it; nothing depends on it.
Verify: no SKILL.md over 6 KB; measure-context --dispatch reports 300 tokens or less; a wizard run on example/ shows specialists starting without the router's history.
Files: create skills/a11y-core/schemas/findings.schema.json, scripts/render-report.mjs, scripts/merge-findings.mjs, scripts/test-findings-contract.mjs, example findings under skills/<name>/examples/; modify every specialist SKILL.md ending; modify csv, statement and compliance skills to consume JSON; add MCP tool render_accessibility_report.
- Every specialist ends with "Return only JSON matching the findings schema."
test-findings-contract.mjsvalidates each skill's examples against the schema. -
render-report.mjsmerges, dedupes by rule plus location, scores with the formula indocs/skills/web-severity-scoring, computes delta against the embedded JSON block of a previous report, and renders all required sections.--self-testchecks its own output againstreport-requirements.md. - Wizards write findings to
.a11y-history/<timestamp>/and call the renderer through the shell or the MCP tool. Only the merged summary (about 500 tokens) returns to the wizard's context.
Verify: contract test passes; render-report.mjs --self-test passes; a wizard run on example/ finishes with the wizard's own context under 40k tokens.
Files: create hooks/guard.mjs and the four manifests; delete .claude/hooks/, claude-code-plugin/hooks, claude-code-plugin/scripts/a11y-*.sh, codex-plugin/hooks, .gemini/.../hooks, .github/hooks/scripts; create .claude/settings.json for repo development that references hooks/claude.hooks.json.
- Port the marker logic from
codex-plugin/hooks/a11y-codex-dispatch-guard.mjs(it already handles child session and parent thread ids) intoguard.mjswith a client adapter per event-name set. - Inject the detect reminder once per session, not every prompt.
- Mark on lead completion, not lead start.
- Persist and restore across compaction on clients that expose the events.
Verify: the test matrix in docs/hooks-guide.md executed on Claude Code and Codex with example/: edit blocked before lead, allowed after, reminder appears once, compaction resumes with state.
Files: modify mcp-server/server-core.js, mcp-server/tools/*.js, mcp-server/package.json; create root mcp.json.
- Add
annotations(readOnlyHint: trueon the 29 scanners,destructiveHint: trueonprune_audit_history,idempotentHintwhere true). - Add
outputSchemato all 38 tools; scanners return findings in the section 5.3 shape. - Set
_meta["anthropic/maxResultSizeChars"]on tools that return whole documents; cap every tool description at one sentence. - Upgrade the SDK and move to protocol 2026-07-28: stateless transport,
tools/listwithttlMsandcacheScope, deterministic tool order. - Retire the SSE fallback and Roots, Sampling, Logging usage (deprecated in 2026-07-28).
Verify: conformance audit section 4 reads zero gaps; mcp-server/server-core.test.js passes; Claude Code, Codex and Copilot auto-approve a scanner call without a prompt.
Files: delete every tree listed under "Removed after cutover" in section 5; rewrite install.sh, install.ps1, scripts/installer-common.sh, scripts/Installer.Common.ps1; modify go-cli/ (health, repair, hooks commands) to know only the new layout; update docs/, README.md, CONTRIBUTING.md, CHANGELOG.md, UNINSTALL.md.
- Installer behaviour: prefer native plugin install (Claude marketplace, Copilot
copilot plugin install, Codex/plugins); otherwise copyskills/to~/.agents/skills(read by Codex, Copilot, Gemini and Antigravity) and register the client's hook manifest. No harness-specific agent files are written anywhere. - VS Code extension: deprecate. VS Code installs Agent Plugins natively; the
@a11yparticipant is replaced by/accessibility-leadand friends. Publish a final extension version whose only action is to point users at the plugin. - Gemini: drop the extension. Document
context.fileName: ["AGENTS.md"]and~/.agents/skillsfor enterprise Gemini CLI and Antigravity. - Repo hygiene: move
RELEASE-*.mdtodocs/releases/, delete the clutter listed in section 2.4, gitignore generated output. - Release 7.0.0 with before and after numbers from
measure-contextinCHANGELOG.md.
Verify: scripts/release-readiness-check.mjs passes; fresh installs on Windows and macOS for Claude Code, Codex and Copilot CLI; budgets in section 6 met.
- Router set. Recommendation: six (accessibility-lead, web-accessibility-wizard, document-accessibility-wizard, markdown-a11y-assistant, developer-hub, github-hub).
nexusbecomes an alias line inAGENTS.md, not a skill. - Canonical copy when the six drifted copies disagree. Recommendation:
.claude/copies, with the drift report reviewed by hand for the twelve web-team skills and the three wizards. - Native subagent definitions. Recommendation: none. Tool restriction and model pinning per specialist are given up in exchange for zero harness-specific files; the dispatch prompt carries the two rules a specialist needs.
- VS Code extension. Recommendation: deprecate in 7.0 as described in Phase 6.
- Reports embedding the findings JSON block. Recommendation: yes; it is what makes delta tracking and regression detection cheap.
- Mechanical splitting will misplace some sections. Mitigation: the drift report plus hand review of the fifteen high-traffic skills before cutover.
- Specialists are invisible to the model on Claude Code and VS Code by design. Mitigation: the validator requires every specialist to be named in a router's dispatch matrix.
- Codex catalog cap. Sixty-six skills at 120 chars each is under 8,000 chars;
agents/openai.yamldisables implicit invocation for specialists so the cap only matters for the six routers. Mitigation:measure-context --client codexfails CI if the catalog exceeds the cap. - Loss of per-specialist tool restriction. Mitigation: the dispatch prompt says "report, do not edit" for reviewers; the edit gate still blocks UI writes until the lead completes.
- Hook event coverage differs per client (Copilot has no Stop or compaction events). Mitigation: the edit gate is the floor on every client; the table in section 5.5 is the documented contract.
- Users who customized generated harness trees lose those edits. Mitigation: the 6.0 extension manifests remain the supported customization path; 7.0 release notes say so.
Each check, with its command.
| Check | Command |
|---|---|
| Budgets | node skills/a11y-core/scripts/measure-context.mjs --check budgets.json |
| Skill spec, sizes, tiers, dispatch matrix, no shadow trees | node scripts/validate-skills.mjs |
| Skill spec reference validator | skills-ref validate skills/* |
| Findings contract | node skills/a11y-core/scripts/test-findings-contract.mjs |
| Report sections | node skills/a11y-core/scripts/render-report.mjs --self-test |
| Claude plugin | claude plugin validate . |
| MCP | node --test mcp-server/server-core.test.js |
| Release | node scripts/release-readiness-check.mjs |
Written 2026-09-21, after phases 1 through 6 completed. Every number here is
reproducible with npm run verify and npm run measure; the evidence is in
docs/MODERNIZATION-CONFORMANCE.md.
Each before, with its after.
| Before | After | |
|---|---|---|
| Source of truth | six hand-maintained trees, already drifted | one skills/ directory |
| Agent format | five: Claude markdown, Copilot agent files, Codex TOML, Gemini skills, plugin copies | one: Agent Skills, the open standard |
| Instruction files |
CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md, ten path-scoped files |
AGENTS.md, imported by CLAUDE.md
|
| Hook scripts | four, in three languages, with different marker logic | one guard.mjs, four thin manifests |
| Installers | 215 KB of shell and PowerShell covering six layouts | 8 KB of JavaScript covering one |
| Validation | 29 scripts and workflows, several scanning nothing | 11 gates, one workflow, one command |
| Reports | typed by the model from a 400-line template | rendered from findings JSON by a script |
The thing this was for. Always-on cost is what the package charges before the user has said anything.
| Client | Before | After | Reduction |
|---|---|---|---|
| Claude Code | 15,924 | 1,136 | 93% |
| Codex | 15,074 | 2,417 | 84% |
| Copilot | 17,347 | 1,136 | 93% |
| Gemini and Antigravity | 12,848 | 1,136 | 91% |
Three other costs fell with it:
- Dispatching a specialist went from 26,929 tokens to 100. A router used to read a specialist's body into its own context and paste it into the prompt, paying for it twice; it now sends the skill's name.
- Hook injection went from roughly 570 tokens on every prompt to 87 tokens once per session. On a forty-turn session that alone is about 22,000 tokens.
- Writing a report went from roughly 15,000 output tokens for a sixty-finding audit to zero, because a script renders it from JSON.
A ten-specialist audit that previously spent around 320,000 tokens on coordination before any analysis now spends under 5,000.
Claude Code. Six skills in the picker instead of eighty agents. The other
102 are reachable by name and cost nothing until one is dispatched. CLAUDE.md
is one line importing AGENTS.md. Hooks come from one manifest, and the edit
gate now opens on the lead's completion rather than its launch, which closes the
gap where a cancelled review unlocked every edit for the rest of the session.
Codex. The skill catalog is 5,995 characters against the 8,000 cap, so
descriptions are no longer silently shortened under pressure and routing stays
reliable. An agents/openai.yaml in each non-router skill turns off implicit
invocation, so the model sees six choices rather than 108. The child-session and
parent-thread identifier mismatch that made valid reviews invisible to the edit
gate is fixed in the shared guard.
Copilot. One AGENTS.md instead of a 6,700-token instructions file plus 85
agent descriptions. The ten path-scoped instruction files survive as
kb-path-instructions, one reference each, opened only when working on a
matching file. Copilot exposes no stop or compaction event, so the edit gate is
the enforcement point there; that limit is documented rather than papered over.
Gemini and Antigravity. The extension is gone, along with the 70 byte-order
marks and 64 non-slug names it had accumulated unchecked. Both read
~/.agents/skills and AGENTS.md natively.
VS Code. The extension is deprecated rather than deleted. VS Code installs Agent Plugins natively, so the chat participant is replaced by the skills themselves appearing in the slash menu with nothing in between.
Things the package could not do before.
- Findings are structured. Every scanning skill returns JSON against one schema. Reports, CSV exports, conformance statements and VPATs are rendered from it, and a malformed finding is rejected before it reaches a compliance document.
- Criteria are validated. A finding citing a WCAG criterion that does not exist, or claiming the wrong conformance level, now fails a test. The obsoleted 4.1.1 Parsing is caught specifically.
- Delta tracking is free. Each report embeds its merged findings, so the next run reports fixed, new, persistent and regressed without re-parsing prose.
- Repeated defects are grouped. A defect appearing in forty places under one component is reported as one job, not forty findings.
- Scanners can be auto-approved. Twenty-nine read-only tools say so, so a bulk scan of forty documents no longer asks the user forty times.
- Results are machine-readable. All 39 tools declare an output schema, so they work from a script rather than only from a conversation.
- Audits survive compaction. The guard saves review state before compaction and restores it after, so a wizard does not restart and ask the same questions twice.
-
Cost is measured and budgeted.
npm run measurereports what the package costs per client, and continuous integration fails when it regresses.
What a person actually notices.
- Choosing is easier. Six named entry points rather than eighty agents whose descriptions blur together. Someone who does not know which they want gets routed by describing the problem.
- Reports are complete and comparable. Every report carries all seven required sections because a script writes them, not because the model remembered. Two runs compare because both embed their data.
- Fewer interruptions. Read-only scans no longer prompt for approval, and the reminder appears once per session rather than on every turn.
- Refusals are actionable. The edit gate says what to run next in forty words rather than restating the policy.
- Output is readable aloud. No emoji, no decorative Unicode, no bare URLs read out character by character. The package passes the markdown accessibility standard it enforces on everyone else.
-
One install.
npm installthennode scripts/install.mjscovers every client, detects which are present, and refuses to overwrite a hooks file or a skill the user has edited.
- Specialists are invisible to the model by design. If a router's dispatch matrix omits one, nothing can reach it. The validator fails when a specialist is named by no router, which is the mitigation.
- Two frontmatter fields sit outside the specification. Documented in section 2 of the conformance dossier, checked explicitly, and reversible with one flag if the specification adopts an alternative.
- Per-specialist tool restriction is gone. The old agent formats could restrict tools per agent; the Agent Skills standard does not. The dispatch prompt carries "report, do not edit", and the edit gate still blocks writes to user-facing files until the lead completes.
- Hook coverage differs by client. Copilot has no stop or compaction event. The edit gate is the floor everywhere; the per-client table is in the conformance dossier.
-
Users who customised a per-client tree lose those edits. Everything
removed is in git history, and
build/drift-report.mdlists what differed between the six copies.
Both items listed here when section 11 was written have been resolved.
Table descriptions. 1,028 warnings became zero. Three things caused them:
- 228 were in the editor's local history directory, a gitignored private record of the user's keystrokes that the linter should never have scanned. Every one was a duplicate of a file already checked at its real path.
- 939 were the linter's own fault. Its table rule checked only the line immediately above a table, so the only way to satisfy it was to delete the blank line between the description and the table, which GitHub does not render as a table at all. Fixing the rule cleared them without editing a document.
- 707 were real.
scripts/describe-tables.mjswrote a sentence for each, derived from the table's own column headers rather than from a template bank, so each one says what a row is and what is recorded about it. Two of the six hundred read badly enough to write by hand.
Alongside them, 24 headings carrying emoji were cleaned, keeping the meaning as a word where the emoji carried status, and 63 malformed code fences were repaired: several documents closed a block with ```text, which opens a new block rather than closing the old one, so everything after it was read as code.
The repository now reports no markdown accessibility issues across 509 files.
Live client checks. npm run verify:live is now a gate. It loads the
package into a real Claude Code session and measures two things the file-based
checks cannot:
| Measurement | Result |
|---|---|
| Model-facing skill listing, without this package | 38 skills, 11,664 characters |
| Model-facing skill listing, with it | 44 skills, 12,674 characters |
| This package's contribution to the model's context | 6 skills, 1,010 characters |
| User-invocable skills reachable by name | 63 of 63 |
| Helpers and reference skills kept out of the menu | 45 |
Exactly the six routers reach the model and the other 102 do not, measured in a running client rather than inferred from frontmatter. An earlier version of this check asked the session to describe its own skills; that answer depended on the model and on whatever hooks replied first, so it was replaced by reading the two numbers the client emits itself.
The run also surfaced something worth knowing for anyone installing this: the test environment was already over Claude Code's 8,000-character skill budget before this package loaded, at 38 skills and 11,664 characters. A package that added 63 descriptions to that would have pushed every skill's description into truncation. Adding six costs 1,010 characters.
- Agents Overview
- Accessibility Lead
- Web Accessibility Wizard
- Document Accessibility Wizard
- Markdown Assistant
- Developer Hub
- GitHub Hub