ADR 0016: Copilot Adapter in v1.0

Summary

@aidokit/adapter-copilot is added to v1.0 scope as a third first-party adapter targeting GitHub Copilot CLI at Minimum conformance. The original v1.0 ROADMAP scoped only claude-code and codex; Copilot is added during the same release window. Standard and Strict conformance remain out of reach until Copilot CLI exposes a hook mechanism; the gap is documented in the adapter manifest rather than papered over.

Context

The original v1.0 ROADMAP scoped Codex as the second first-party adapter. After Codex landed and multi-adapter project support shipped (commits 67f9f05…03f661b), four factors made expanding scope cheap and valuable:

1. The Adapter contract was just exercised by a second adapter, and the friction points were fresh in mind.
2. Multi-adapter project support already landed. Three adapters surface design issues that two cannot — particularly around shared docs/ / agent-artifacts/ deduplication and per-adapter state reconstruction.
3. Copilot CLI adoption is large enough that a v1.0 launch story of "supports Claude Code AND Codex AND Copilot" is materially stronger than "supports Claude Code AND Codex".
4. Implementation effort was bounded: ~1 day, ~1000 LOC, by direct analogy to the Codex adapter (which mirrors adapter-claude-code but without hooks).

Copilot CLI's surface differs from Codex's in two ways material to aidokit:

• The agent-rules file is .github/copilot-instructions.md (auto-loaded workspace-wide), not the root AGENTS.md. If both exist, Copilot prefers the former.
• There is no native sandbox / approval primitive equivalent to Codex's sandbox: read-only. Role separation is prose-enforced.

Decision

1. Ship @aidokit/adapter-copilot in v1.0 at Minimum conformance

Mirror the @aidokit/adapter-codex package shape (no hook directory, inline templates, fs-only doctor) and adapt paths:

• adapterName: 'copilot'
• engineDirectoryPath: '.copilot'
• agentRulesFilePath: '.github/copilot-instructions.md'

2. Declare gaps explicitly in manifest.gaps

Four gaps are documented at v1.0 ship:

1. No hook mechanism — watchdog enforcement is prompt-level only.
2. No output-style mechanism — Strict's AD-STR-02 unreachable.
3. No native skill auto-discovery — .copilot/skills/<id>/SKILL.md files are referenced from the instructions file as documentation.
4. Partial MCP support — installMCP / removeMCP / listInstalledMCPs are stubbed pending upstream stabilisation.

3. Path to Standard deferred

Standard conformance requires deterministic watchdog enforcement, which requires a runtime hook primitive Copilot CLI does not currently expose. This adapter will graduate to Standard in a v1.x patch once GitHub adds a suitable mechanism (or aidokit identifies an acceptable workaround such as instruction-side enforcement primitives).

Consequences

Positive

• Stronger launch story: three first-party adapters at GA cover the three largest agentic CLIs in the ecosystem.
• Contract exercised by a third independent adapter: any remaining hidden coupling in the Adapter interface or CLI dispatch table surfaces now, while we can still fix it pre-GA.
• Multi-adapter integration test extended to three adapters: the shared-docs deduplication path is now exercised at N=3, not just N=2.

Negative

• Adapter at Minimum, not Standard: users get the kit content, but watchdog stop conditions are prose-only and rely on model cooperation. Documented in manifest.gaps; users can read it. Mitigation: clear in-product messaging plus a tracked v1.x graduation path.
• MCP is stubbed: users with Copilot CLI cannot register MCP servers through aidokit mcp add until upstream stabilises. Mitigation: documented as a gap; fall-through to direct .copilot/mcps.json edit.
• CI surface grows: the multi-adapter integration test now covers three adapter trees, increasing build time. Acceptable cost.

Neutral

• Adapter count is now three: any docs that enumerated "the two first-party adapters" need updating (CLAUDE.md §3, ROADMAP §v1.0, SECURITY.md capability declarations).

Alternatives considered

Alternative 1: Defer Copilot adapter to v1.1

Ship v1.0 with claude-code + codex only; release Copilot in a follow-up.

Pros

• Smaller v1.0 surface.
• Less last-minute churn before GA.

Cons

• Weaker GA launch story.
• Loses the opportunity to validate the Adapter contract against a third adapter before freezing v1.0 semantics.

Reason rejected: The implementation effort was bounded (~1 day), and the contract-validation value of a third adapter pre-GA is high.

Alternative 2: Ship Copilot at Standard with simulated watchdog

Emit instruction-side watchdog stop conditions and claim Standard conformance.

Pros

• Visibility of "Standard" badge.

Cons

• Misleading. Standard's AD-STD-watchdog-* checks require deterministic enforcement. Prose is not deterministic. The conformance harness would either need to relax its checks (breaking the contract for everyone) or accept a known-false claim.

Reason rejected: Conformance levels exist to be honest about what ships. Declaring Standard while shipping prose enforcement undermines the contract for all adapters.

Alternative 3: Ship Copilot adapter as third-party / community

Leave Copilot to a community-maintained npm package outside the monorepo.

Pros

• Validates the third-party adapter story.

Cons

• No community contributor has volunteered.
• A first-party Copilot adapter is the simplest way to keep the dogfood-gate honest across three adapter trees.

Reason rejected: First-party is faster and lets us own the gap declaration directly.

Implementation notes

The adapter mirrors @aidokit/adapter-codex structure exactly. Files that differ in substance (not just renames):

• src/manifest.ts — capabilities.writesOutsideEngine includes .github/copilot-instructions.md rather than AGENTS.md.
• src/emit/agent-rules.ts — template includes a seven-phase workflow prose block since there is no hook-side enforcement.
• src/emit/skills.ts — emits .copilot/skills/<id>/SKILL.md (directory-per-skill, like Claude Code) rather than the flat .codex/skills/<id>.md layout. This is cosmetic — Copilot CLI auto- loads neither — and chosen for alignment with the Claude Code adapter in case Copilot adds skill discovery later.
• src/lifecycle.ts — doctor adds an engine-config-parseable check not present in Codex.

CLI wiring follows the established pattern:

• packages/cli/src/init/selections.ts — adds 'copilot' to V10_ADAPTERS.
• packages/cli/src/init/resolve-adapter-instance.ts — registers copilotAdapter in the dispatch map.
• packages/cli/src/init/manifest-reader.ts and packages/cli/src/commands/init.ts — extend ADAPTER_PATHS and ALL_KNOWN_ADAPTERS.

Validation

This decision is validated when:

• [ ] @aidokit/adapter-copilot passes Minimum conformance.
• [ ] Multi-adapter integration test exercises --adapter claude-code,codex,copilot and asserts the shared docs/ and agent-artifacts/ skeletons are emitted exactly once.
• [ ] A user can run aidokit init --adapter copilot against a fresh project and have Copilot CLI auto-load the emitted .github/copilot-instructions.md.

References

Internal

• ADR 0005 — adapter contract shape (Adapter interface signature)
• ADR 0008 — prereq install policy (no auto-install of Copilot CLI)
• docs/specs/adapter-contract.md — Adapter contract
• docs/specs/conformance-levels.md — Why Minimum was selected