/add-agent-support

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,