Agents standard — multi-model AI tooling configuration
Standard scope
Applies to: all HCS-governed repos (scope: hcs base — this standard is never scope-split; identical for tierpoint-prodtech and azurelocal) Domain: agents (AI tooling configuration) Status: Active
This standard defines how AI coding tools are configured across every Hybrid Cloud Solutions (HCS) repository. It replaces the earlier Claude-Code-only configuration standard.
The owner works across several AI coding tools — Claude Code, OpenAI Codex CLI, Google Gemini CLI, Cursor, and Visual Studio Code with GitHub Copilot. The goal of this standard is one set of conventions that every tool honours, rather than a separate setup per tool. Any of these tools can open any HCS repo, read the same instructions, share the same repo-local memory, and connect to the same governance service.
The standard is deliberately never scope-split: there is one agents.md for all scopes and all models. It adapts by client capability (what a given tool can do), not by which estate the repo belongs to.
The three-layer delivery model
Every HCS repo receives its governance from three layers, in priority order:
- The HCS Governance Model Context Protocol (MCP) server — the machine-readable source of truth. Any client on any machine bootstraps from it at session start and receives scope-resolved, token-efficient guidance. This is the authoritative layer.
- The public standards site — https://platform.hybridsolutions.cloud — human-readable reference and offline fallback. Serves the
hcsbase scope only. Requires no authentication, so it works from any machine or tool. - The in-repo
AGENTS.mdfallback digest — a minimal, committed copy of the hard rules plus links to layers 1 and 2. This is what a tool reads when it cannot reach the MCP server.
When these disagree, the MCP server wins over the site, and the site wins over the in-repo digest. A tool should always prefer a live MCP answer to the static in-repo file.
Canonical file layout
Every repo carries a small set of instruction files. AGENTS.md is the canonical, cross-tool file; every other tool-specific file either imports it or points at it.
repo/
├─ AGENTS.md ← canonical cross-tool instructions (source of truth in-repo)
├─ CLAUDE.md ← thin shim: imports AGENTS.md + Claude-only notes
├─ GEMINI.md ← optional; only if not pointing Gemini at AGENTS.md via config
├─ .github/copilot-instructions.md ← two-line pointer to AGENTS.md
├─ .ai/ ← authoritative, git-versioned, cross-tool workspace (see ai-workspace standard)
│ ├─ state/
│ ├─ memory/
│ └─ mcp/
├─ .claude/ ← Claude Code native layer (settings, agents, skills, hooks)
├─ .codex/config.toml ← Codex project config (MCP servers, profiles — real options only)
├─ .cursor/ ← Cursor rules + project MCP config
│ ├─ rules/
│ └─ mcp.json
├─ .vscode/mcp.json ← VS Code Copilot MCP config
└─ .mcp.json ← Claude Code MCP configAGENTS.md is canonical
AGENTS.md is an open, cross-tool convention that Codex CLI, Cursor, and VS Code Copilot read natively, and that Gemini CLI can be pointed at through configuration. It holds the repo's identity, hard rules digest, the MCP-first bootstrap instruction, the session protocol, and a key-facts table. Keep it thin and token-efficient — it is a bootstrap and a fallback, not a full standards library.
CLAUDE.md is a thin shim
Claude Code reads CLAUDE.md, not AGENTS.md, at session start. Rather than duplicating content, CLAUDE.md imports AGENTS.md using Claude Code's @path import syntax and adds only Claude-specific notes.
# Repo instructions — Claude Code
@AGENTS.md
## Claude-only notes
- Subagents, skills, and hooks for this repo live in `.claude/`.
- See the [agents standard](https://platform.hybridsolutions.cloud/standards/agents/).The @path import is a verified Claude Code feature
Claude Code resolves @path/to/file references inside CLAUDE.md at session launch and inlines the target file's content. Both relative paths (@AGENTS.md) and absolute/home paths (@~/.claude/notes.md) work, with recursive imports supported up to five levels deep. Imported files load at launch and do consume context, so keep AGENTS.md concise.
Gemini context file
Gemini CLI reads a context file whose name is configurable via contextFileName in .gemini/settings.json. Two acceptable patterns:
- Preferred: set
"contextFileName": "AGENTS.md"so Gemini reads the canonical file directly and noGEMINI.mdis committed. - Alternative: commit a thin
GEMINI.mdthat restates the MCP-first block and points toAGENTS.md, if a repo needs Gemini-specific phrasing.
Copilot instructions
.github/copilot-instructions.md is a two-line pointer to AGENTS.md. Recent VS Code Copilot also reads AGENTS.md natively, but the pointer file guarantees the instruction is picked up regardless of version.
Per-tool configuration matrix
| Tool | User-level config | Repo-level config | Native memory / plan feature | Agent / subagent support | Hooks support | MCP config location |
|---|---|---|---|---|---|---|
| Claude Code | ~/.claude/ (CLAUDE.md, settings.json) | CLAUDE.md shim + .claude/settings.json | Auto memory (per-project memory dir); plan mode | Yes — native subagents, parallel agent teams | Yes — lifecycle hooks (PreToolUse, PostToolUse, Stop, UserPromptSubmit) | .mcp.json (repo), plus ~/.claude user MCP config |
| Codex CLI | ~/.codex/config.toml | .codex/config.toml (trusted projects) + AGENTS.md | ~/.codex/memories/ (local generated state) | No native subagent files | No hook system | [mcp_servers.<name>] tables in config.toml |
| Gemini CLI | ~/.gemini/settings.json | .gemini/settings.json + context file (GEMINI.md/AGENTS.md) | Context file only; no separate auto-memory store | No native subagent files | No hook system | mcpServers block in .gemini/settings.json |
| Cursor | ~/.cursor/mcp.json, global rules | AGENTS.md and/or .cursor/rules/*.mdc | Rules files; no separate auto-memory store | Emerging (agent/plugins); treat as single-agent today | No general hook system | .cursor/mcp.json (repo), ~/.cursor/mcp.json (global) |
| VS Code Copilot | User settings / profile | .github/copilot-instructions.md (+ AGENTS.md) | No committed auto-memory store | No native subagent files | No hook system | .vscode/mcp.json (repo) |
Codex has no agent files and no hooks
Codex CLI configuration is a single TOML file (~/.codex/config.toml for the user, .codex/config.toml for a trusted project). It supports MCP server tables, named profiles, and model/provider settings — but it has no per-agent definition files and no lifecycle-hook system. Do not create Codex "agent TOMLs" or a hooks.json for Codex; those features do not exist. Codex follows workstream logic sequentially through AGENTS.md and MCP guidance instead.
MCP wiring per client
Every tool connects to the same HCS Governance MCP server (this repo's mcp-server/). Only the config surface differs. The human-readable inventory of which MCP servers a repo uses lives in .ai/mcp/mcp-servers.md (see the AI workspace standard).
| Tool | Where the MCP server is declared |
|---|---|
| Claude Code | .mcp.json at the repo root |
| Codex CLI | [mcp_servers.hcs-governance] table in .codex/config.toml (or user ~/.codex/config.toml) |
| Gemini CLI | mcpServers object in .gemini/settings.json |
| Cursor | .cursor/mcp.json (repo) or ~/.cursor/mcp.json (global) |
| VS Code Copilot | .vscode/mcp.json at the repo root |
At session start, every client should call the MCP bootstrap tool with the repo name and its own client identity. The server returns the repo's scope, the applicable hard rules, the index of applicable standards, and orchestration guidance shaped for that client's capability tier. This single call replaces reading several static files and keeps session-start context small.
Memory model
There are two kinds of memory, and only one of them is authoritative.
- Tool-native memory is a local cache. Claude Code's per-project auto-memory directory and Codex's
~/.codex/memories/are machine-local generated state. They speed a tool up on the machine where they were written, but they are not committed, not shared, and not portable between tools or machines. - The repo's
.ai/directory is the source of truth. It is committed to git, readable by every tool, and portable across machines. This is what lets Codex write a handoff on one machine and Claude Code read it on another.
If tool-native memory and .ai/ ever disagree, .ai/ wins. Full contract in the AI workspace standard.
Session model override
Each tool pins or overrides the active model in its own way. There is no cross-tool magic command — use the tool's own mechanism.
| Tool | Override the model for a session |
|---|---|
| Claude Code | /model <name> inside the session |
| Codex CLI | codex -m <model> (or --model) at launch; /model mid-session; -c inline config override; or a named --profile |
| Gemini CLI | gemini -m <model> (or --model) at launch |
| Cursor | model picker in the composer/agent UI |
| VS Code Copilot | model picker in the Copilot chat UI |
Optional model hint in CURRENT_TASK.md
.ai/state/CURRENT_TASK.md may carry a suggested-model hint (for example, a line such as suggested-model: opus when the current task needs deep reasoning). This is advisory. Any tool's agents should honour the hint if present and the model is available, but the hint never overrides an explicit per-session flag the operator has set. It is a suggestion for continuity across tools, not a hard constraint.
The one-line convention for "just use model X for this session" is therefore per-tool: use /model X in Claude Code, codex -m X in Codex, gemini -m X in Gemini, or the UI picker in Cursor / Copilot. Document the choice in CURRENT_TASK.md if it should carry over to the next session.
Agent, skill, and hook strategy by client tier
Tools split into two capability tiers. Both follow the same workstream logic; they differ in how they execute it.
Tier A — subagent-capable
Example: Claude Code. These tools can spawn parallel subagents, run lifecycle hooks, and load reusable skills. They get the full native layer under .claude/:
.claude/agents/— repo-specific and pipeline agents (planner, coder, reviewer, investigator, operator, and so on).claude/skills/— workstream orchestration (build, review, refactor, test, document, investigate, operate).claude/hooks/— safety and audit hooks (block secrets, validate paths, log tool usage, session summaries).claude/settings.json— pre-approved tool patterns and hook wiring
Tier A runs workstreams as orchestrated pipelines with fan-out to specialised subagents and human approval gates.
Tier B — single-agent
Examples today: Codex CLI, Gemini CLI, Cursor, VS Code Copilot. These tools drive a single agent and cannot fan out to parallel subagents or run a hook system. They follow the same workstream logic sequentially, driven by AGENTS.md plus MCP get_guidance calls. Instead of spawning a reviewer subagent, a Tier B tool performs the review step itself, in sequence, guided by the workstream digest the MCP server returns for its tier.
Tier B does not receive the .claude/ native layer, and it must not be given invented equivalents (no fabricated Codex agent files or hook systems). Its "orchestration" is the sequence of steps described in the guidance the MCP server serves for single-agent clients.
Tier is about capability, not scope
A tool moves between tiers only when its own capabilities change (for example, if Cursor's agent/plugin features mature into true subagent fan-out). The repo's scope — hcs, tierpoint-prodtech, or azurelocal — never changes a tool's tier. Orchestration guidance is served by client capability, identically across all scopes.
Never in any instruction or config file
- Secret values, tokens, API keys, passwords
- Subscription, tenant, or client IDs (the platform repo's own
CLAUDE.mdis the single documented exception, as the source of truth) - Connection strings
- Any value that would cause harm if the repo were made public
Machine-specific override files (for example, Claude Code's gitignored .claude/settings.local.json) may hold machine-specific paths, but never credentials.
Related standards
- AI workspace standard — the
.ai/directory contract - Documentation standard — Markdown, diagrams, commit prose
- Governance standard — required files, branch strategy, commit format