HCS Platform Engineering

Appearance

AI workspace standard — the .ai/ directory contract ​

Standard scope

Applies to: all HCS-governed repos (scope: hcs base — this standard is never scope-split; identical for tierpoint-prodtech and azurelocal) Domain: ai-workspace Status: Active

Every Hybrid Cloud Solutions (HCS) repository carries a committed .ai/ directory. It is the repo-local, git-versioned, cross-tool shared memory and handoff mechanism for AI coding tools. Because it lives in the repo and travels with every clone, one tool can write to it on one machine and a different tool can read it on another. This is what makes work portable across Claude Code, OpenAI Codex CLI, Google Gemini CLI, Cursor, and Visual Studio Code with GitHub Copilot.

.ai/ complements each tool's own native memory but sits above it in authority. A tool's native memory (for example, Claude Code's per-project auto-memory or Codex's ~/.codex/memories/) is a local performance cache, not committed and not shared. .ai/ is the source of truth. When the two disagree, .ai/ wins.

Directory structure ​

text
.ai/
├─ state/
│  ├─ CURRENT_TASK.md       — what is being worked on right now (optionally a suggested-model hint)
│  ├─ HANDOFF.md            — end-of-session record: what changed, files touched, commands run, branch, blockers, next steps
│  └─ OPEN_QUESTIONS.md     — unresolved questions for the next session or tool to pick up
├─ memory/
│  ├─ PROJECT_CONTEXT.md    — durable project knowledge; rarely changes
│  ├─ DECISIONS.md          — architecture and design decisions with their reasoning
│  ├─ COMMANDS.md           — how to build, test, and run this specific repo
│  └─ GOTCHAS.md            — non-obvious traps and workarounds
└─ mcp/
   └─ mcp-servers.md        — human-readable inventory of the MCP servers this repo uses

state/ — the moving parts ​

The state/ files change frequently, often within a single session.

  • CURRENT_TASK.md — a short statement of what is being worked on right now. It may include an optional suggested-model: hint (for example suggested-model: opus for a task that needs deep reasoning). The hint is advisory: a tool's agents should honour it if present and available, but it never overrides an explicit per-session model flag the operator has set.
  • HANDOFF.md — the single most important file for cross-tool work. It is written at the end of every session by whichever tool was used, and it records: what changed, which files were touched, which commands and tests were run and their results, the active branch, any blockers, and the exact next steps. The next session — possibly in a different tool — starts by reading this.
  • OPEN_QUESTIONS.md — things a session got stuck on or deferred. This is where a tool parks a question it could not resolve so the next session or a different tool can pick it up.

memory/ — the durable parts ​

The memory/ files change slowly and hold knowledge that outlives any one session.

  • PROJECT_CONTEXT.md — durable knowledge about what the project is and how it fits into the wider estate. Rarely changes.
  • DECISIONS.md — architecture and design decisions and, critically, the reasoning behind them, so a future session does not relitigate a settled choice.
  • COMMANDS.md — how to build, test, and run this specific repo (the exact commands, not generalities).
  • GOTCHAS.md — non-obvious traps, footguns, and workarounds that would otherwise cost the next session time to rediscover.

mcp/ — the connections ​

  • mcp-servers.md — a human-readable inventory of the MCP servers this repo uses, including the HCS Governance MCP server. This is the human-facing counterpart to the per-tool MCP config files (.mcp.json, .codex/config.toml, .gemini/settings.json, .cursor/mcp.json, .vscode/mcp.json). It documents what each server is for; it does not contain connection secrets.

Session-start read order ​

Before touching anything in a repo, a tool reads .ai/ in this order and forms a picture of the current state:

  1. .ai/state/ — read CURRENT_TASK.md, then HANDOFF.md, then OPEN_QUESTIONS.md. This tells you what the last session was doing, where it stopped, and what is unresolved.
  2. .ai/memory/ — read PROJECT_CONTEXT.md, DECISIONS.md, COMMANDS.md, and GOTCHAS.md for durable context.

After reading, the tool should summarise its believed state back to the operator — what it thinks is in progress, on which branch, and what the next step is — before making any change. This catches a stale or misread handoff before work begins.

MCP bootstrap and .ai/ are complementary

The MCP bootstrap call returns scope, hard rules, and applicable standards for the repo. .ai/ returns the live, repo-specific work state. Read both at session start: bootstrap tells you the rules, .ai/ tells you the situation.

Session-end update rule ​

Every tool updates HANDOFF.md before ending a session. This is the contract that makes cross-tool handoff work. A session that changed anything must leave HANDOFF.md reflecting:

  • what changed and why
  • which files were touched
  • which commands and tests were run, and their results (including failures)
  • the active branch and whether work was committed or pushed
  • any blockers
  • the exact next steps

If a session raised a question it could not resolve, it also appends to OPEN_QUESTIONS.md. If it made a design decision, it records it in memory/DECISIONS.md. If it discovered a trap or a build command, it updates GOTCHAS.md or COMMANDS.md.

Skipping the HANDOFF.md update breaks the chain: the next tool starts blind, and the whole point of .ai/ is lost.

No secrets, ever ​

Nothing sensitive goes in .ai/. It is committed to git and may be cloned to any machine. Do not put secret values, tokens, API keys, passwords, subscription or tenant or client IDs, or connection strings in any .ai/ file. Reference secrets the same way the rest of the estate does — by Key Vault name and secret name only, never the value. mcp-servers.md documents which servers exist and what they are for, never their credentials.

Commit conventions for .ai/ changes ​

.ai/ changes are committed like any other change in the repo, following the repository commit-message format type(scope): short description with an AB#<id> work-item reference where one applies.

  • Keep .ai/ commits small and explicit — a handoff update is its own commit, not folded silently into a large code change, so the history of the workspace stays readable.
  • Use the docs or chore type for pure workspace updates (for example, docs(ai): update HANDOFF after auth refactor).
  • Because HANDOFF.md changes every session, expect it to appear frequently in history — that is intended and healthy.

How .ai/ relates to native tool memory ​

Native tool memory.ai/ workspace
LocationMachine-local (e.g. Claude auto-memory dir, ~/.codex/memories/)In the repo, under .ai/
Committed to gitNoYes
Shared across toolsNoYes
Portable across machinesNoYes
RoleLocal performance cacheSource of truth
On conflictLosesWins

Native memory makes a single tool faster on a single machine. .ai/ is the durable, portable, shared record. Treat native memory as an optimisation and .ai/ as the truth: if a tool's cached notion of the repo disagrees with .ai/, trust .ai/ and correct the cache.

Copyright © Hybrid Cloud Solutions LLC — Kristopher Turner