# Agent Control Surface Matrix

Cross-vendor comparison of control surfaces supported by each AI coding agent.
Used for gzkit sync parity planning and vendor-alignment ADR scoping.

**Last updated:** 2026-03-15

## Surface Comparison

| Capability | Claude Code | GitHub Copilot | OpenAI Codex | gzkit syncs? |
|------------|-------------|----------------|--------------|--------------|
| **Instructions file** | `CLAUDE.md` | `.github/copilot-instructions.md` | `AGENTS.md` (shared) | Yes (all three) |
| **Behavioral rules** | `.claude/rules/*.md` | `.github/instructions/*.md` + `**/.instructions.md` (path-scoped) | None (reads AGENTS.md) | Yes (Copilot canonical, Claude mirrored) |
| **Skills** | `.claude/skills/` | `.github/skills/` | `.agents/skills/` | Yes (canonical `.gzkit/skills/`, mirrored to all three) |
| **Settings/config** | `.claude/settings.json` | `.vscode/settings.json` (Copilot keys) | `.codex/config.toml` | Partial (Claude only) |
| **Hooks** | `.claude/hooks/` | `.github/copilot/hooks/` | Not shipped (PR in progress) | Yes (Claude + Copilot) |
| **Agent environment** | N/A | `.github/workflows/copilot-setup-steps.yml` | N/A | No |
| **Custom agents/profiles** | N/A | `.github/agents/<name>.md` | `[agents]` in config.toml | No |
| **MCP servers** | `.claude/mcp.json` | In agent `.md` files | `[mcp_servers]` in config.toml | No |
| **Exec policy** | N/A | N/A | `.codex/rules/*.rules` (Starlark) | No |
| **Content exclusion** | N/A | GitHub.com admin settings (not file-based) | `.codexignore` (unreliable) | No |
| **Discovery index** | N/A | N/A | N/A | Yes (`.github/discovery-index.json`, gzkit-native) |

## Key Architecture Decisions

- **AGENTS.md is the canonical shared surface.** Codex reads it natively. Claude and Copilot get adapter surfaces generated from templates.
- **`.gzkit/rules/` is canonical for behavioral rules.** Mirrored to `.claude/rules/` and `.github/instructions/`. Codex has no equivalent text-based rules surface.
- **`.gzkit/skills/` is canonical for skills.** Mirrored to all three vendor skill paths.
- **Codex exec policy (`.codex/rules/`)** is a distinct concept from behavioral rules. It gates command execution (allow/prompt/forbid), not agent behavior.

## Vendor-Specific Notes

### Claude Code

- Richest gzkit integration: instructions, rules, skills, settings, hooks, MCP all synced
- `.claude/rules/` derived from `.github/instructions/` via `sync_claude_rules()`
- Settings generated by `generate_claude_settings()`

### GitHub Copilot

- Broadest native surface: path-scoped instructions, agent profiles, setup-steps workflow
- `**/.instructions.md` files with `applyTo` frontmatter enable per-path rules (unique to Copilot)
- Agent profiles (`.github/agents/<name>.md`) define custom agents with MCP tool access
- Content exclusion is admin-only (GitHub.com settings), not file-based

### OpenAI Codex

- Thinnest gzkit touchpoint: only AGENTS.md + `.agents/skills/`
- Rich native config (`config.toml`) with layered precedence (CLI > profile > project > user > system > defaults)
- Starlark exec policy is unique — only vendor with enforceable command-level gates
- Multi-agent roles configurable in `config.toml`
- Hooks not shipped yet (community PR in progress)
- `.codexignore` exists but unreliable upstream

## Related ADRs

- `ADR-pool.vendor-alignment-claude-code` — Claude Code surface alignment
- `ADR-pool.vendor-alignment-codex` — Codex CLI surface alignment
- `ADR-pool.vendor-alignment-copilot` — Copilot surface alignment
- `ADR-pool.vendor-alignment-gemini-cli` — Gemini CLI surface alignment
- `ADR-pool.vendor-alignment-opencode` — OpenCode surface alignment
- `ADR-pool.universal-agent-onboarding` — Vendor-neutral `gz onboard` command
- `ADR-0.14.0` — Multi-agent instruction architecture unification (active)

## Sync Gap Summary

Unsynced surfaces that could be governed:

| Gap | Vendor | Complexity | Notes |
|-----|--------|------------|-------|
| Project config | Codex (`.codex/config.toml`) | Medium | Sandbox mode, approval policy, MCP |
| Project config | Copilot (`.vscode/settings.json`) | Low | Copilot-specific keys only |
| Agent profiles | Copilot (`.github/agents/`) | Medium | Custom agent definitions |
| Agent environment | Copilot (`copilot-setup-steps.yml`) | Low | Workflow template |
| MCP servers | All three (different formats) | High | No common schema |
| Exec policy | Codex (`.codex/rules/`) | Medium | Unique concept, no cross-vendor equivalent |
