---
name: add-agent-support
description: Create and ship AgentSessions support for a new or changed local AI agent/provider. Use when adding, reviewing, testing, documenting, or marketing a provider integration, session parser, transcript source, support-matrix entry, verified-version bump, or provider UI surface; drives the full loop from pre-support research through binary install, real session capture, fixture redaction, parser/discovery/search/UI integration, QA, review/fix loops, support records, PR/release notes, and conservative marketing claims.
---

# Add Agent Support

## Mission

Use this skill to deliver maintainable AgentSessions provider support, not just to block bad providers. The gate phase exists to prevent unsupported work from entering the repo; when gates pass, continue through implementation, QA, review, documentation, and release-ready communication.

Do not implement, merge, release, bump verified versions, or market provider support from docs, vendor claims, or synthetic fixtures alone.

Before coding, prove:
- The provider is usable from the user's region.
- The product/docs/UI are usable in English, unless the user explicitly accepts a non-English support burden.
- A free or existing plan can create enough real sessions for parser QA.
- Installation and auth are practical on this Mac.
- Real local transcript/session data can be generated or obtained.
- Redacted fixtures can preserve real keys, event names, timestamps, and content shape.

If a hard gate fails, reject or defer politely and clean up test-only installs/state before finishing.

## Required Workflow

1. Start a support plan.
   - Run `scripts/new_agent_support_plan.py` to create the plan scaffold.
   - Fill it with evidence, exact dates, URLs, command output, local paths, and blocker status.
   - Keep uncertainty labeled as `Hypothesis:` until verified.
   - Use `references/agent-provider-gates.md` for hard gates and binary lifecycle details.
   - Use `references/agent-support-implementation.md` for implementation, QA, review, and release details.

2. Classify the work.
   - `new_provider`: no current AgentSessions support. Run all gates, capture real sessions, then implement.
   - `existing_provider_update`: provider exists. Use `skills/agent-session-format-check/SKILL.md` and `skills/agent-support-matrix/SKILL.md` before parser or version changes.
   - `public_claim`: docs/release/social wording only. Verify implementation and test evidence before changing wording.

3. Prove the provider can be supported.
   - Confirm region, language, account, plan, install, auth, and local-data availability.
   - Ask before global installs, GUI app installs, browser extensions, logins, account linking, or networked agent runs.
   - Snapshot pre-install binary/app/package/state paths before changing anything.
   - Install or locate the official binary/app only after the research gate is plausible.
   - Verify binary path, version, help output, app bundle metadata, auth behavior, and cleanup path.

4. Generate real test sessions.
   - Use a disposable project under `/tmp/as-agent-lab/<agent>-project`.
   - Run safe read-only prompts against harmless files unless edit behavior is explicitly under test.
   - Capture at least one normal session and one follow-up/continued session when supported.
   - Capture tool-call/tool-result behavior when the free or existing plan allows it.
   - If the provider supports subagents or child sessions, create a small session that exercises them.
   - If auth/region/plan blocks full creation, record the exact failure and do not fake fixture confidence.

5. Learn the real format.
   - Locate session storage with scoped paths only; do not scan all of `$HOME` blindly.
   - Inspect JSONL, JSON, SQLite, or multi-file stores with structured tools.
   - Record root layout, file patterns, session ID fields, timestamp shapes, event names, role fields, content shapes, model/cwd fields, tool call/result shapes, usage/limits records, artifact-only directories, and subagent relationships.
   - Decide whether unsupported surfaces should remain unsupported rather than half-wired.

6. Redact and add fixtures.
   - Add redacted real fixtures under `Resources/Fixtures/stage0/agents/<agent>/`.
   - Preserve real schema, event names, timestamps, and representative event families.
   - Remove names, emails, tokens, cookies, auth headers, private prompts, proprietary content, and absolute user paths.
   - Keep raw captures private under `scripts/agent_captures/<timestamp>/<agent>/`; do not commit raw sessions.
   - Run the fixture secret/path scan before review.

7. Implement provider support.
   - Follow existing AgentSessions provider patterns before inventing abstractions.
   - Wire only surfaces backed by evidence: parser, discovery, search, settings/root overrides, unified sessions UI, analytics, resume/copy command, active/live status, and usage tracking.
   - Add visible Preferences controls when macOS app execution will not inherit shell environment overrides.
   - Keep stable app session IDs unless a format demands otherwise.
   - Treat unknown event types as metadata with raw JSON preserved where the model supports it.
   - Avoid feature flags unless the user explicitly asks for them.

8. Test and QA the integration.
   - Add focused parser, discovery, search, and discoverability tests.
   - Add golden/fixture harness coverage if that harness is intended to cover supported providers.
   - Run `git diff --check`.
   - Run focused tests first, then `./scripts/xcode_test_stable.sh` when Swift/project files changed.
   - Run a Debug build after Swift or project integration changes.
   - For UI changes, launch or render-check the app surface and verify filters, transcript rendering, settings, and search behavior.
   - Restore macOS Appearance to `System` if QA changes it.

9. Review and fix until release-ready.
   - Review the diff findings-first, focusing on fixture evidence, parser drift tolerance, secret leakage, unbounded scans, overclaiming, analytics mismatch, and performance.
   - If using automated review, run it after tests pass, fix actionable findings, and repeat until clean or only consciously accepted low-risk notes remain.
   - Re-run focused tests and the Debug build after substantive fixes.

10. Update support records and docs.
   - Update `docs/agent-support/agent-support-matrix.yml` only for verified behavior.
   - Append `docs/agent-support/agent-support-ledger.yml`.
   - Add `docs/agent-json-tracking.md` upstream-version evidence.
   - Add `[Unreleased]` changelog and `docs/summaries/YYYY-MM.md` bullets for user-visible support.
   - Update README/support matrix only for surfaces that tests and fixtures prove.

11. Prepare PR, release, and marketing wording.
   - Prefer a follow-up PR for hardening unless the user explicitly wants direct main work.
   - Credit contributors politely when relevant.
   - Use "browse/search local transcripts" unless resume, analytics, live status, or usage tracking are implemented and tested.
   - Say "transcripts stay local" only when indexing really reads local files and no cloud sync is involved.
   - Prepare release notes, screenshots/GIFs, and social copy only after implementation, fixtures, tests, and build pass.

12. Clean up rejected or deferred attempts.
   - Remove only test-created binaries/apps/state proven by the pre-install snapshot.
   - Close or comment on PRs/issues politely with the verified maintainability blocker.
   - Remove abandoned worktrees/branches when support is not planned.
   - Leave the repo clean or clearly report any remaining uncommitted work.

## Subagents

Use subagents only when the user explicitly authorizes subagent work or the current task already asks for parallel agents. Good splits are:
- Official-doc and market/access researcher.
- Local binary/session capture operator.
- Format/schema inspector.
- Parser/discovery implementation worker.
- Fixture redaction and secret-scan reviewer.
- UI/search/docs/marketing reviewer.

Do not delegate install/login approval, destructive cleanup approval, or the immediate blocker on the critical path.

## AgentSessions Standards

Use `/Users/alexm/Repository/Codex-History` as the normal repo root unless the user says otherwise.

Provider support must be based on real local data. A mergeable PR, green synthetic tests, or a plausible parser is not enough. If this Mac cannot install/auth/use the provider from the United States, or the product is not realistically usable in English, reject unless the user explicitly accepts that support burden.

Use repo-local skills/docs when present:
- `skills/agent-session-format-check/SKILL.md`: schema drift, usage/limits probes, storage backends, discovery path contracts, and prebump validation.
- `skills/agent-support-matrix/SKILL.md`: support matrix, ledger, and verified-version recording workflow.
- `docs/agent-support/monitoring.md`: severity model and monitoring cadence.

Known discovery contracts from the format-check workflow:
- Codex: `*/sessions/YYYY/MM/DD/rollout-*.jsonl`
- Claude: `~/.claude/projects/**/*.{jsonl,ndjson}`
- OpenCode: `*/opencode/storage/session/*/ses_*.json`
- Hermes: `~/.hermes/sessions/session_*.json`
- Copilot: `~/.copilot/session-state/*.jsonl`
- OpenClaw: `*/agents/<id>/sessions/*.jsonl`
- Cursor: `~/.cursor/projects/*/agent-transcripts/*/*.jsonl`

## Bundled Resources

- `scripts/new_agent_support_plan.py`: generates an end-to-end support plan with gates, install/session capture, fixture, implementation, QA, review, support-record, PR, and marketing sections.
- `references/agent-provider-gates.md`: hard gates, evidence checklist, binary lifecycle, existing-provider monitoring, discovery contracts, and rejection wording.
- `references/agent-support-implementation.md`: implementation surface map, fixture strategy, QA commands, review loops, support records, and marketing/release guidance.