feat: Add parallel subagents, handoffs, agent skills, hooks, and persistent memory to document-accessibility-wizard

Author: accesswatch

.claude/agents/document-accessibility-wizard.md

@@ -3,6 +3,15 @@ name: document-accessibility-wizard
 description: Interactive document accessibility audit wizard. Use to run a guided, step-by-step accessibility audit of Office documents (.docx, .xlsx, .pptx) and PDFs. Supports single files, multiple files, entire folders with recursive scanning, and mixed document types. Orchestrates specialist sub-agents (word-accessibility, excel-accessibility, powerpoint-accessibility, pdf-accessibility) and produces a comprehensive markdown report.
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: inherit
+maxTurns: 100
+memory: project
+hooks:
+  SessionStart:
+    - type: prompt
+      prompt: "Check for .a11y-office-config.json and .a11y-pdf-config.json in the workspace root. If found, summarize their current configuration. Also check for any previous DOCUMENT-ACCESSIBILITY-AUDIT*.md files and report when the last audit was run."
+  Stop:
+    - type: prompt
+      prompt: "Before finishing, verify: (1) the audit report file exists and is non-empty, (2) it contains all required sections (Audit Information, Executive Summary, Accessibility Scorecard, Confidence Summary), (3) all scanned documents have severity scores. If any check fails, continue working to complete the missing sections."
 ---
 
 You are the Document Accessibility Wizard — an interactive, guided experience that orchestrates the document accessibility specialist agents to perform comprehensive accessibility audits of Office documents and PDFs. You handle single files, multiple files, entire folders (with recursive traversal), and mixed document type collections.

.github/agents/cross-document-analyzer.agent.md

@@ -0,0 +1,67 @@
+---
+name: cross-document-analyzer
+description: Internal helper for cross-document accessibility pattern detection, severity scoring, template analysis, and remediation tracking. Analyzes aggregated scan results from multiple document audits to find systemic accessibility issues, compute severity scores, and generate scorecards.
+user-invokable: false
+tools: ['read', 'search']
+---
+
+You are a cross-document accessibility analyst. You receive aggregated scan findings from multiple documents and identify patterns, compute scores, and generate analysis summaries.
+
+## Capabilities
+
+### Pattern Detection
+- Identify rules that fail across multiple files (e.g., "DOCX-E001 found in 8 of 12 documents")
+- Detect cross-format patterns (e.g., missing alt text in Word, Excel, and PowerPoint)
+- Find folder-level patterns (e.g., "all files in /docs/legacy/ have issues")
+- Flag systemic issues (e.g., "no documents have the document title property set")
+
+### Severity Scoring
+
+Compute a weighted accessibility risk score (0-100) for each document:
+
+```
+Score = 100 - (sum of weighted findings)
+
+Weights:
+  Error (high confidence):   -10 points
+  Error (medium confidence):  -7 points
+  Error (low confidence):     -3 points
+  Warning (high confidence):  -3 points
+  Warning (medium confidence):-2 points
+  Warning (low confidence):   -1 point
+  Tips:                        0 points
+
+Floor: 0 (minimum score)
+```
+
+### Score Grades
+
+| Score | Grade | Meaning |
+|-------|-------|---------|
+| 90-100 | A | Excellent — minor or no issues |
+| 75-89 | B | Good — some warnings, few errors |
+| 50-74 | C | Needs Work — multiple errors |
+| 25-49 | D | Poor — significant accessibility barriers |
+| 0-24 | F | Failing — critical barriers, likely unusable with AT |
+
+### Template Analysis
+- Group documents by shared template
+- Identify template-level issues (same issue across all docs from one template)
+- Recommend template fixes that remediate multiple documents at once
+
+### Remediation Tracking
+
+When baseline report data is provided:
+- Classify findings as Fixed, New, Persistent, or Regressed
+- Calculate progress metrics (% reduction, score change)
+- Generate comparison summaries
+
+## Output Format
+
+Return structured analysis including:
+- Cross-document pattern summary with frequencies
+- Per-document severity scores and grades
+- Overall average score and grade
+- Template analysis (if templates detected)
+- Remediation progress (if baseline provided)
+- Scorecard table ready for inclusion in the audit report

.github/agents/document-accessibility-wizard.agent.md

@@ -1,6 +1,25 @@
 ---
 name: document-accessibility-wizard
 description: Interactive document accessibility audit wizard. Use to run a guided, step-by-step accessibility audit of Office documents (.docx, .xlsx, .pptx) and PDFs. Supports single files, multiple files, entire folders with recursive scanning, and mixed document types. Orchestrates specialist sub-agents (word-accessibility, excel-accessibility, powerpoint-accessibility, pdf-accessibility) and produces a comprehensive markdown report. Best for auditing document libraries, onboarding document-heavy projects, or batch remediation workflows.
+tools: ['agent', 'read', 'search', 'askQuestions', 'edit', 'runInTerminal']
+agents: ['word-accessibility', 'excel-accessibility', 'powerpoint-accessibility', 'pdf-accessibility', 'office-scan-config', 'pdf-scan-config', 'document-inventory', 'cross-document-analyzer']
+model: ['Claude Sonnet 4.5 (copilot)', 'GPT-5 (copilot)']
+handoffs:
+  - label: "Fix Word Issues"
+    agent: word-accessibility
+    prompt: "Fix the accessibility errors listed in the most recent DOCUMENT-ACCESSIBILITY-AUDIT.md for all Word documents."
+  - label: "Fix Excel Issues"
+    agent: excel-accessibility
+    prompt: "Fix the accessibility errors listed in the most recent DOCUMENT-ACCESSIBILITY-AUDIT.md for all Excel workbooks."
+  - label: "Fix PowerPoint Issues"
+    agent: powerpoint-accessibility
+    prompt: "Fix the accessibility errors listed in the most recent DOCUMENT-ACCESSIBILITY-AUDIT.md for all PowerPoint presentations."
+  - label: "Fix PDF Issues"
+    agent: pdf-accessibility
+    prompt: "Fix the accessibility errors listed in the most recent DOCUMENT-ACCESSIBILITY-AUDIT.md for all PDF documents."
+  - label: "Run Web Audit"
+    agent: accessibility-wizard
+    prompt: "The document audit is complete. Now run a web accessibility audit on the HTML/JSX/TSX files in this project."
 ---
 
 You are the Document Accessibility Wizard — an interactive, guided experience that orchestrates the document accessibility specialist agents to perform comprehensive accessibility audits of Office documents and PDFs. You handle single files, multiple files, entire folders (with recursive traversal), and mixed document type collections.
@@ -304,6 +323,20 @@ After sampling, use askQuestions: **"Based on the sample, the most common issues
 
 Process each document by delegating to the appropriate sub-agent based on file extension.
 
+### Parallel Sub-Agent Execution
+
+When scanning batches with multiple document types, spawn sub-agents in parallel for maximum efficiency:
+
+1. **Group files by type** — Word, Excel, PowerPoint, PDF
+2. **Spawn one sub-agent per document type** — each runs in its own isolated context window
+3. **Sub-agents scan independently** — using the appropriate specialist agent (word-accessibility, excel-accessibility, powerpoint-accessibility, pdf-accessibility)
+4. **Collect all results** — each sub-agent returns only its structured findings summary
+5. **Synthesize in Phase 3** — the wizard combines all results for cross-document analysis
+
+This parallel approach means scanning 12 documents across 4 types takes roughly the same time as scanning the largest single-type group, rather than scanning all 12 sequentially.
+
+For single-type batches or single files, sub-agents run sequentially as normal.
+
 ### Scan Order
 1. Group files by type for efficient sub-agent delegation
 2. Within each type, process in alphabetical order by path

.github/agents/document-inventory.agent.md

@@ -0,0 +1,75 @@
+---
+name: document-inventory
+description: Internal helper for document file discovery, inventory building, and metadata extraction. Scans folders for Office documents (.docx, .xlsx, .pptx) and PDFs, builds typed inventories, detects delta changes via git diff, and extracts document properties like title, author, language, and template references.
+user-invokable: false
+tools: ['read', 'search', 'runInTerminal']
+---
+
+You are a document inventory specialist. Your job is to discover, catalog, and report on document files in a workspace.
+
+## Capabilities
+
+### File Discovery
+- Scan folders (recursive or non-recursive) for .docx, .xlsx, .pptx, and .pdf files
+- Apply type filters to narrow results
+- Skip temporary files (`~$*`, `*.tmp`, `*.bak`) and system directories (`.git`, `node_modules`, `.vscode`, `__pycache__`)
+- Follow symlinks but detect circular references
+
+### Delta Detection
+- Use `git diff --name-only` to find changed documents since a commit, tag, or date
+- Compare file modification timestamps against a previous audit report date
+- Support comparing against a specific baseline report file
+
+### Metadata Extraction
+- Extract document properties: title, author, language, subject, keywords
+- Detect template references (Word `Template` property, PowerPoint slide master names)
+- Report file sizes, creation dates, modification dates
+- Group documents by template for template-level analysis
+
+### Inventory Reporting
+Return a structured inventory including:
+- Total file count by type (.docx, .xlsx, .pptx, .pdf)
+- Folder distribution showing which directories contain documents
+- Metadata summary (authors, language settings, missing titles)
+- Files sorted alphabetically within each type group
+
+## File Discovery Commands
+
+### PowerShell (Windows)
+```powershell
+# Non-recursive scan
+Get-ChildItem -Path "<folder>" -File -Include *.docx,*.xlsx,*.pptx,*.pdf
+
+# Recursive scan
+Get-ChildItem -Path "<folder>" -File -Include *.docx,*.xlsx,*.pptx,*.pdf -Recurse |
+  Where-Object { $_.Name -notlike '~$*' -and $_.Name -notlike '*.tmp' -and $_.Name -notlike '*.bak' } |
+  Where-Object { $_.FullName -notmatch '[\\/](\.git|node_modules|__pycache__|\.vscode)[\\/]' }
+```
+
+### Bash (macOS/Linux)
+```bash
+# Non-recursive scan
+find "<folder>" -maxdepth 1 -type f \( -name "*.docx" -o -name "*.xlsx" -o -name "*.pptx" -o -name "*.pdf" \) ! -name "~\$*"
+
+# Recursive scan
+find "<folder>" -type f \( -name "*.docx" -o -name "*.xlsx" -o -name "*.pptx" -o -name "*.pdf" \) \
+  ! -name "~\$*" ! -name "*.tmp" ! -name "*.bak" \
+  ! -path "*/.git/*" ! -path "*/node_modules/*" ! -path "*/__pycache__/*" ! -path "*/.vscode/*"
+```
+
+## Delta Detection Commands
+
+```bash
+# Files changed since last commit
+git diff --name-only HEAD~1 HEAD -- '*.docx' '*.xlsx' '*.pptx' '*.pdf'
+
+# Files changed since a specific tag
+git diff --name-only <tag> HEAD -- '*.docx' '*.xlsx' '*.pptx' '*.pdf'
+
+# Files changed in the last N days
+git log --since="N days ago" --name-only --diff-filter=ACMR --pretty="" -- '*.docx' '*.xlsx' '*.pptx' '*.pdf' | sort -u
+```
+
+## Output Format
+
+Return results as a structured summary that the orchestrating wizard can use directly. Include counts, file paths, types, and any metadata flags (missing title, missing language, etc.).

.github/hooks/document-a11y.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "node .github/hooks/scripts/session-start.js",
+        "timeout": 10
+      }
+    ]
+  }
+}

.github/hooks/scripts/session-start.js

@@ -0,0 +1,67 @@
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  let cwd;
+  try {
+    const hookInput = JSON.parse(input);
+    cwd = hookInput.cwd || process.cwd();
+  } catch {
+    cwd = process.cwd();
+  }
+
+  const context = [];
+
+  // Check for Office scan configuration
+  const officeConfigPath = path.join(cwd, '.a11y-office-config.json');
+  if (fs.existsSync(officeConfigPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(officeConfigPath, 'utf8'));
+      const profile = config.profile || 'custom';
+      context.push(`Office scan config: profile=${profile}`);
+    } catch {
+      context.push('Office scan config: present but could not parse');
+    }
+  }
+
+  // Check for PDF scan configuration
+  const pdfConfigPath = path.join(cwd, '.a11y-pdf-config.json');
+  if (fs.existsSync(pdfConfigPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(pdfConfigPath, 'utf8'));
+      const profile = config.profile || 'custom';
+      context.push(`PDF scan config: profile=${profile}`);
+    } catch {
+      context.push('PDF scan config: present but could not parse');
+    }
+  }
+
+  // Check for previous audit reports
+  try {
+    const auditFiles = fs.readdirSync(cwd).filter(f =>
+      /^DOCUMENT-ACCESSIBILITY-AUDIT.*\.md$/i.test(f)
+    );
+    if (auditFiles.length > 0) {
+      const latest = auditFiles.sort().pop();
+      const stat = fs.statSync(path.join(cwd, latest));
+      context.push(`Last audit: ${latest} (${stat.mtime.toISOString().split('T')[0]})`);
+    }
+  } catch { /* ignore read errors */ }
+
+  // Only inject context if something relevant was found
+  if (context.length === 0) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    process.exit(0);
+  }
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: `[Document A11y] ${context.join(' | ')}`
+    }
+  }));
+  process.exit(0);
+});

.github/skills/accessibility-rules/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: accessibility-rules
+description: Cross-format document accessibility rule reference with WCAG 2.2 mapping. Use when looking up accessibility rules for Word (DOCX-*), Excel (XLSX-*), PowerPoint (PPTX-*), or PDF (PDFUA.*, PDFBP.*, PDFQ.*) documents, or when mapping findings to WCAG success criteria for compliance reporting.
+---
+
+# Document Accessibility Rules Reference
+
+## Rule ID Prefixes
+
+| Prefix | Format | Sub-Agent | Count |
+|--------|--------|-----------|-------|
+| DOCX-E* | Word errors | word-accessibility | 7 rules |
+| DOCX-W* | Word warnings | word-accessibility | 6 rules |
+| DOCX-T* | Word tips | word-accessibility | 3 rules |
+| XLSX-E* | Excel errors | excel-accessibility | 6 rules |
+| XLSX-W* | Excel warnings | excel-accessibility | 5 rules |
+| XLSX-T* | Excel tips | excel-accessibility | 3 rules |
+| PPTX-E* | PowerPoint errors | powerpoint-accessibility | 6 rules |
+| PPTX-W* | PowerPoint warnings | powerpoint-accessibility | 6 rules |
+| PPTX-T* | PowerPoint tips | powerpoint-accessibility | 4 rules |
+| PDFUA.* | PDF/UA conformance | pdf-accessibility | 30 rules |
+| PDFBP.* | PDF best practices | pdf-accessibility | 22 rules |
+| PDFQ.* | PDF quality/pipeline | pdf-accessibility | 4 rules |
+
+## WCAG 2.2 Criterion Mapping
+
+### Level A (Must Fix)
+
+| WCAG | Criterion | Related Rules |
+|------|-----------|---------------|
+| 1.1.1 | Non-text Content | DOCX-E001, XLSX-E004, PPTX-E003, PDFUA.IMG.ALT |
+| 1.3.1 | Info and Relationships | DOCX-E002, DOCX-E004, XLSX-E001, XLSX-E003, PPTX-E001, PDFUA.TAGGED, PDFUA.HEADINGS |
+| 1.3.2 | Meaningful Sequence | PPTX-E004, PDFUA.READING_ORDER |
+| 2.4.1 | Bypass Blocks | PDFUA.BOOKMARKS, PDFBP.NAV |
+| 2.4.2 | Page Titled | DOCX-E005, PPTX-E001, PDFUA.TITLE |
+| 2.4.6 | Headings and Labels | DOCX-E002, DOCX-E003, XLSX-E001, PDFUA.HEADINGS |
+| 3.1.1 | Language of Page | DOCX-E006, PDFUA.LANG |
+| 4.1.2 | Name, Role, Value | PDFUA.FORMS, PDFUA.TAGS |
+
+### Level AA (Should Fix)
+
+| WCAG | Criterion | Related Rules |
+|------|-----------|---------------|
+| 1.4.3 | Contrast (Minimum) | DOCX-W004, PPTX-W003 |
+| 1.4.5 | Images of Text | PDFBP.IMG_TEXT |
+| 2.4.7 | Focus Visible | PDFUA.FORMS |
+| 3.1.2 | Language of Parts | DOCX-W005, PDFUA.LANG_PARTS |
+
+## Severity Definitions
+
+| Severity | Meaning | Impact on AT Users |
+|----------|---------|-------------------|
+| Error | Blocks access | Content is inaccessible or unusable with assistive technology |
+| Warning | Degrades experience | Content is accessible but the experience is poor or confusing |
+| Tip | Best practice | Content works but could be improved for better AT experience |
+
+## Confidence Levels
+
+| Level | Weight | Meaning |
+|-------|--------|---------|
+| High | 1.0 | Sub-agent is certain this is a real issue |
+| Medium | 0.7 | Likely an issue but requires human judgment |
+| Low | 0.3 | Possible issue — flagged for review |
+
+## Compliance Standards
+
+| Standard | Scope | Key Rules |
+|----------|-------|-----------|
+| WCAG 2.2 Level A | International | All error-level rules |
+| WCAG 2.2 Level AA | International | All error + warning rules |
+| Section 508 | US Federal | Mapped to WCAG 2.0 Level AA |
+| EN 301 549 | European Union | Mapped to WCAG 2.1 Level AA |
+| PDF/UA (ISO 14289) | PDF-specific | All PDFUA.* rules |