# Cross-Platform Handoff Patterns

Guide for seamless handoff between Claude Code and GitHub Copilot agent environments when performing document accessibility audits.

## Platform Comparison

| Capability | Claude Code | GitHub Copilot |
|-----------|------------|----------------|
| Agent format | `.claude/agents/*.md` | `.github/agents/*.agent.md` |
| Frontmatter | `maxTurns`, `memory` | `tools`, `agents`, `model`, `handoffs` |
| Sub-agents | Parallel via `Task` tool | Via `agent` tool + `agents` frontmatter |
| Hidden helpers | N/A (all agents user-invokable) | `user-invokable: false` in frontmatter |
| Skills | N/A | `.github/skills/*/SKILL.md` |
| Memory | `memory: project` in frontmatter | Via Agent Skills (SKILL.md files) |
| Interactive UI | Terminal prompts | `askQuestions` tool |

## Handoff Scenarios

### Scenario 1: Start in Claude Code, Continue in Copilot

**When:** You start a document audit in the terminal with Claude Code but need to continue editing or remediation in VS Code.

**Steps:**

1. In Claude Code, run the document-accessibility-wizard
2. The wizard generates `DOCUMENT-ACCESSIBILITY-AUDIT.md`
3. Open the project in VS Code
4. In Copilot Chat, select `@document-accessibility-wizard`
5. Say: "Continue the audit from the existing report"
6. The Copilot agent reads the existing report and picks up where Claude left off

**What transfers automatically:**

- The audit report file (`DOCUMENT-ACCESSIBILITY-AUDIT.md`)
- Scan configuration files (`.a11y-office-config.json`, `.a11y-pdf-config.json`)
- SARIF output (if generated)

**What does NOT transfer:**

- In-memory session state (conversation history)
- Partial scan progress (if interrupted mid-scan)

### Scenario 2: Start in Copilot, Continue in Claude Code

**When:** You start an audit in VS Code but need CLI-level access for batch operations.

**Steps:**

1. In Copilot Chat, run `@document-accessibility-wizard`
2. Generate the audit report
3. Switch to terminal with Claude Code
4. Say: `/document-accessibility-wizard Re-scan with comparison against the existing report`
5. Claude Code reads the previous report and runs a delta comparison

### Scenario 3: Parallel Platform Scanning

**When:** Large document libraries benefit from splitting work across platforms.

**Steps:**

1. In Claude Code: scan PDFs (better for binary parsing in terminal)
2. In Copilot: scan Office documents (better with VS Code file explorer integration)
3. Both write to separate report files
4. In either platform: "Compare and merge these two audit reports"

## Shared Artifacts

These files are platform-agnostic and work identically in both environments:

| Artifact | Path | Purpose |
|----------|------|---------|
| Audit report | `DOCUMENT-ACCESSIBILITY-AUDIT.md` | Main audit output |
| Office config | `.a11y-office-config.json` | Scan rule configuration |
| PDF config | `.a11y-pdf-config.json` | PDF scan rules |
| SARIF output | `*.sarif.json` | CI/CD integration |
| Scan templates | `templates/*.json` | Profile presets |
| Batch scripts | `*.ps1` / `*.sh` | Remediation automation |

## Report Format Compatibility

Both platforms generate reports in the same markdown format with identical sections:

1. Audit Information
2. Executive Summary
3. Accessibility Scorecard
4. Cross-Document Patterns
5. Findings by File
6. Remediation Priority
7. Confidence Summary
8. Template Analysis
9. Comparison Report (if re-scan)

This means any report generated by one platform can be:

- Read and continued by the other platform
- Used as a baseline for comparison scans on either platform
- Parsed by CI/CD pipelines regardless of which platform generated it

## Agent Skills as Shared Knowledge

The Agent Skills in `.github/skills/` serve as platform-independent knowledge:

- **document-scanning** - File discovery patterns, delta detection commands
- **accessibility-rules** - Rule reference with WCAG 2.2 mapping
- **report-generation** - Scoring formulas, report structure, compliance formats

Claude Code agents access this knowledge through their agent instructions.
Copilot agents access it through the Skills framework (auto-resolved from `SKILL.md` descriptions).
