Applied AI-Accelerated Government Development

The Reference App and Your Platform

Updated

Intermediate

What you'll learn

~30 min
  • Read the platform seam (identity, database credential, secrets, telemetry) and name the lesson, 34 to 37, that lands it on your cloud and code host
  • Read the dated baseline table and state which pin you adopt, which you defer, and why
  • Choose the project-memory file each AI CLI reads (an AGENTS.md that CLAUDE.md imports) and use the dated four-tool equivalents table
  • Write a version decision record (a dated ADR, an architecture decision record) and run the upgrade order: codemod, typecheck, test, axe, pipeline, rollback

The stack you already run

You are not learning a new framework. You are making an AI CLI tool AI CLI tool Claude Code, Antigravity CLI, or Codex CLI — a command-line AI that reads files, writes code, and runs commands. Full lesson → productive inside one you know, and that means the tool has to know the same constraints you do: which versions are pinned, which parts of the app depend on the platform underneath it, and which upgrades are decisions rather than chores.

The module teaches against one unnamed reference app: Next.js, any OIDC (OpenID Connect, the standard by which an identity provider signs users in) provider, SQL Server, and containers. It runs on your laptop first. Lessons 34 to 37 then land it on your cloud and code host. Its choices are examples to adapt. Where your agency chose differently, keep the pattern and change the pin.

This is the only lesson that carries version numbers, for the stack and for the four AI CLIs. Every other lesson says “the pinned major” and points back here, so a version change is one edit in one place.


The seam: what the app asks the platform for

Most of the app does not care which cloud it runs on. The parts that do (who signs users in, how the app proves itself to the database, where secrets live, where telemetry goes) sit behind one small interface, the platform seam. Core code imports the interface and one function, getPlatform(). Each platform lesson supplies one implementation, and the local one, which the worked example uses, runs on your laptop.

This is an excerpt of the reference app’s src/platform/types.ts, checked against the file by the site’s build:

REFERENCE CODE src/platform/types.ts (excerpt): platform seam types for identity, database credentials, secrets, and telemetry open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
// src/platform/types.ts (excerpt)
export interface Identity {
/** OIDC discovery issuer of the identity provider of record. */
issuer: string;
clientId: string;
/** Name of the secret holding the client secret; never the secret itself. */
clientSecretName: string;
scopes: string[];
/** The raw role names this provider puts in its tokens. Lesson 05 maps them to the closed set. */
rolesFrom(claims: Claims): string[];
}
// ...
export type DbAuth =
| {
kind: 'token';
/** Passed to the driver; the driver asks the server which scope to use. No scope string in app code. */
credential: TokenCredentialLike;
}
| {
kind: 'secret';
/** Fetches the current credential from the platform's secret store. */
get(): Promise<SecretCredential>;
/** A named owner, e.g. a team mailbox, who answers for rotation. */
rotationOwner: string;
maxAgeDays: number;
/**
* 'runtime': the app can fetch a fresh copy after a rotation.
* 'startup': the platform injects it once when the container starts, so a
* rotation reaches the app only through a redeploy (the runbook says who does it).
*/
delivery: 'runtime' | 'startup';
};
// ...
export interface Platform {
name: 'local' | 'azure' | 'aws' | 'google';
identity: Identity;
db: { target: DbTarget; auth: DbAuth };
secrets: { get(name: string): Promise<string> };
telemetry: { start(serviceName: string): Promise<void> };
}

Two kinds of database credential carry the most weight. A token is short-lived and handed to the driver, which asks the server which scope to use, so no scope string lives in your code. A secret is fetched from the platform’s secret store and has a named rotation owner, a maximum age, and a delivery mode that says whether a rotation can reach the running app or only a redeploy can. Which kind your platform allows is a fact about the platform, not a preference, and the platform lessons say which.

The function that picks the implementation is the only place that knows which one is running, and it refuses a name it does not know:

REFERENCE CODE src/platform/index.ts: platform selector that refuses unknown values open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
src/platform/index.ts
// The only place that knows which platform is running. PLATFORM is set by the
// deployment (lesson 18); anything else fails at startup instead of guessing.
import type { Platform } from './types.ts';
import { localPlatform } from './local/index.ts';
const loaders: Record<string, () => Promise<Platform>> = {
local: async () => localPlatform,
azure: () => import('./azure/index.ts').then((m) => m.azurePlatform), // lesson 34
aws: () => import('./aws/index.ts').then((m) => m.awsPlatform), // lesson 35
google: () => import('./google/index.ts').then((m) => m.googlePlatform), // lesson 36
};
export async function getPlatform(name = process.env.PLATFORM): Promise<Platform> {
const load = name ? loaders[name] : undefined;
if (!load) throw new Error(`PLATFORM must be one of: ${Object.keys(loaders).join(', ')} (got ${name ?? 'nothing'})`);
return load();
}

Where your platform lesson lands each part

LessonLands the seam onWhat it supplies
34Azure GovernmentEntra sign-in, a database token from a managed identity, Key Vault secrets, Azure Monitor telemetry
35AWS GovCloudsign-in through your OIDC provider at the load balancer, a database secret in Secrets Manager with rotation, traces through X-Ray
36Google Cloud with Assured Workloadssign-in through workforce federation or the app’s own OIDC library, a database secret in Secret Manager, telemetry through a collector
37Your code host and pipelineGitHub, GitLab, Azure DevOps or Bitbucket: owner-approval rules and a pipeline that signs in to your cloud without a stored key

Complete lesson 37 and one of 34, 35 or 36 for your platform. The others are there when your agency changes platform or you support a second one.


The baseline: checked 2026-11-04

ℹChecked 2026-11-04

Versions below were read from the npm registry, the Node.js release schedule, and the Next.js support policy on 2026-11-04. The rows marked “reference app” come from the reference app’s package.json as reviewed on 2026-11-05. Support horizons are what the publisher states; where it states nothing, the cell says so. Re-check the source link before you copy a pin into a new project, and date your own copy.

PackagePinSupport horizonSource link
Node.js26 (Active LTS since 2026-10-28); fallback 2426: Maintenance from 2027-10-20, end of life 2029-04-30. 24: end of life 2028-04-30Node.js release schedule
next16.4.x16.x is Active LTS. 15.x gets security fixes through 2027-01-31Next.js support policy
react, react-dom19.3.xNext 16 accepts React 18.2 or 19 as peersreact on npm
@mui/material, @mui/material-nextjs9.5.xmaterial-nextjs peers cover Next 13 through 16@mui/material on npm
@mui/x-data-grid9.xPeer @mui/material 7.3 or 9@mui/x-data-grid on npm
zod4.6.x3.x last release was 3.25.76 (2025-07-08); No official 3.x support horizon was foundzod on npm
typescript5.x (what the Next.js scaffold ships; the reference app uses it too)Next 16 needs 5.1 or later. TypeScript 7 with Next 16 is unverified, so this module does not use itNext.js 16 upgrade guide
openid-client6.8.x (reference app)No support horizon was read. It is the sign-in library of the core lessons: PKCE, state and nonce checksopenid-client on npm
vitest5.1.xNode 22.12, 24, or 26 and later; no Node 20vitest on npm
@playwright/test1.64.xNode 20 or later@playwright/test on npm
fast-check4.10.xproperty-based testing, lesson 25fast-check on npm
@stryker-mutator/core, @stryker-mutator/vitest-runner10.1.x (the two move together)the runner peers Vitest 2 or later; mutation testing, lesson 25Stryker Vitest runner
tailwindcss4.3.xnpm reports no Node floortailwindcss on npm
swr2.5.xPeer React includes 19swr on npm
mssql12.7.xNode 18.19 or latermssql on npm
@opentelemetry/api1.10.x (reference app)No support horizon was read@opentelemetry/api on npm
@opentelemetry/sdk-node, @opentelemetry/exporter-trace-otlp-http0.301.x (reference app; the two move together)No support horizon was read. These carry a 0.x version, which the project uses for its experimental packages@opentelemetry/sdk-node on npm
@opentelemetry/resources3.1.x (reference app)No support horizon was read@opentelemetry/resources on npm
@azure/identity4.14.x (lesson 34 only)Node 22 or later@azure/identity on npm
@azure/keyvault-secrets4.12.x (reference app; lesson 34 only)No support horizon was read@azure/keyvault-secrets on npm
@microsoft/opentelemetry1.5.x (lesson 34 only)Microsoft’s pick for new Node apps; the older @azure/monitor-opentelemetry (1.20.x) stays supported, and you initialize one, never bothMicrosoft Learn: enable Azure Monitor OpenTelemetry
@cyclonedx/cyclonedx-npm6.0.1 (exact pin, lesson 20)Node 20.18 or later; Apache-2.0; writes CycloneDX 1.6 by default@cyclonedx/cyclonedx-npm on npm

Three things in the table decide your first week:

  • Node 20 is out. Vitest and the Azure packages each exclude it, and Node 22 is already in Maintenance (end of life 2027-04-30). Start on 26, or on 24 when your base image or hosted build agent does not ship 26. Whether a node:26 container image exists on your platform’s container host is something to confirm in your own subscription or account; this lesson did not verify it.
  • One Node number, four places. engines.node in package.json, .nvmrc, the Dockerfile tag, and the pipeline’s Node task all carry the same major.
  • Majors are adopted, not inherited. MUI 9 declares compatibility with React 19.3 and Next 16 in its peer ranges, and Lesson 4 tests the two things peers cannot tell you: the Emotion nonce under a strict Content Security Policy, and Tailwind layer ordering.

Zod: what actually changed

An older version of this lesson told you Zod 4 breaks .transform() and .refine() and that you should decline the upgrade. That is wrong. The changelog shows a different break: error customization. One error parameter replaces message, invalid_type_error, required_error and errorMap; ZodError.format() and .flatten() are deprecated in favor of z.treeifyError and z.flattenError; .errors is gone (use .issues); z.string().email() is deprecated for the top-level z.email(); and .refine() no longer receives ctx.path. Default error wording also changed, so any test that matches message text needs to be updated in the same change.



Names that change with your platform

The hostnames, regions and credential kinds below are the part of the app that moves when the platform does. AI tools default to commercial endpoints, so these are the rows to put in your project memory. Availability inside each boundary is a dated fact and sits in the status box under the table.

What changesAzure GovernmentAWS GovCloud (US)Google Cloud with Assured Workloads
Regions or boundaryUS Gov Arizona, US Gov Texas, US Gov Virginiaus-gov-west-1, us-gov-east-1; ARN partition arn:aws-us-gov:; FIPS endpoints for FIPS 140-3No suffix change; the boundary is a folder plus organization policy (resource location, service restrictions), so the failure is a denied call, not a different hostname
Management consoleportal.azure.usconsole.amazonaws-us-gov.comnot read
Sign-inlogin.microsoftonline.usthe agency’s OIDC provider at the load balancer, which forwards signed claims in x-amzn-oidc-dataWorkforce Identity Federation, or the app’s own OIDC library
Database credential kindtoken (managed identity to Azure SQL)secret (RDS for SQL Server has no IAM database authentication)secret (Cloud SQL for SQL Server has no IAM database login; Entra authentication needs SQL Server 2022 or later)
SQL hostdatabase.usgovcloudapi.netfrom the RDS consolefrom the Cloud SQL console
Secret storevault.usgovcloudapi.netSecrets Managersecretmanager.googleapis.com
Container registryazurecr.usECRartifactregistry.googleapis.com
Container hostazurewebsites.usECS on FargateCloud Run (run.googleapis.com)
Telemetrypaste the portal connection string; token audience https://monitor.azure.ustraces to X-Ray through a collector or daemon (xray.us-gov-west-1.amazonaws.com)OTLP to Cloud Trace (cloudtrace.googleapis.com)
Blob storageblob.core.usgovcloudapi.netnot readnot read

Sources: Azure, Microsoft Learn, Compare Azure Government and global Azure and national cloud authentication endpoints; AWS, GovCloud endpoints and RDS for SQL Server IAM database authentication; Google, Assured Workloads overview and Cloud SQL IAM authentication. The Azure column is the one this lesson verified service by service; the other two hold only what the facts file read, and an empty cell means “not read”, not “none”. The Microsoft Graph hostname is not listed because this module does not call Graph.

ℹStatus checked 2026-11-05

Availability, authorization, agency approval, region support, and price are five separate facts. This box holds only what was read from a primary source on 2026-11-05. Recheck each source and your agency’s authorization boundary before you rely on any of it.

  • AWS GovCloud: Secrets Manager is available in both regions, except that Managed External Secrets are not (GovCloud Secrets Manager). ECR is available in both regions and public registries are not (GovCloud ECR). Fargate is available (GovCloud Fargate).
  • AWS GovCloud sign-in: the load balancer page says “Cognito authentication is not available”, and the load balancer user-authentication guide publishes GovCloud key endpoints for verifying x-amzn-oidc-data (GovCloud load balancing, authenticate users).
  • AWS GovCloud telemetry: OTLP traces to CloudWatch need Transaction Search, which the GovCloud CloudWatch page lists as not available; X-Ray is available in both regions (GovCloud CloudWatch, GovCloud X-Ray). UNVERIFIED: whether the CloudWatch OTLP logs and metrics endpoints exist in GovCloud.
  • Google: Secret Manager and Cloud Run are on the FedRAMP High and IL4 product lists (IL4 is the DoD impact level 4 tier for controlled unclassified data), with Cloud Run’s Cloud Trace integration unsupported at IL4. Cloud Trace is on the FedRAMP High list but not in the IL4 product table. Workforce Identity Federation is on the FedRAMP High list and not named in the IL4 table (supported products, IL4 control package). UNVERIFIED: Artifact Registry at IL4, the Telemetry API in either package, and the exact US region list (locations).
⚠Azure telemetry: paste the portal connection string

Microsoft’s own pages disagree on the Application Insights ingestion suffix for Azure Government: one lists {region}.in.applicationinsights.azure.us, another lists applicationinsights.us as a valid suffix. Do not build the endpoint by hand and do not let an AI tool do it. Open the Application Insights resource in the Government portal, copy the full connection string from the Overview pane (it includes the ingestion endpoint), and set it as APPLICATIONINSIGHTS_CONNECTION_STRING. Lesson 34 and Lesson 16 use it.

ℹAzure: the credential must name the Government authority

DefaultAzureCredential from @azure/identity targets Azure Commercial unless you pass authorityHost: AzureAuthorityHosts.AzureGovernment, which is https://login.microsoftonline.us. It is the same class with different configuration. An AADSTS90002 (tenant not found) error means a request reached the wrong authority. The package also reads the AZURE_AUTHORITY_HOST environment variable. Lesson 34 builds this.


A working layout

The lessons that follow assume this folder layout. It is a pattern, not a requirement; rename folders freely and tell your AI tool when you do. The companion gov-dev-reference-app repository is a runnable teaching harness shipping the completed platform seam (src/platform/, src/lib/auth/oidc.ts, src/lib/db/, src/lib/telemetry/) and modernization fixtures (src/modernization/, modernization/legacy/, fixtures/) so npm test runs out of the box, rather than a full Next.js app. When a lesson plans a file already in the harness, audit or extend it (or remove it on a scratch branch to rebuild from scratch), and when a lesson plans Next.js route or feature layers (src/app/, src/features/, src/config/), run it in your Next.js app or let the agent scaffold the folder stubs.

src/
app/
(auth)/ # routes that need a signed-in user
api/ # route handlers
layout.tsx # providers, theme, navigation
proxy.ts # coarse routing only: not the security boundary
platform/ # the seam: types.ts, getPlatform(), one folder per platform
lib/
auth/ # sign-in (oidc.ts), session store, requireSession()
db/ # connection provider, withPool(), query helpers
telemetry/ # registerTelemetry(serviceName) -> platform; startTelemetry = OTLP
components/
migrations/ # sequential SQL migration scripts

proxy.ts replaces the old middleware.ts in Next 16. It runs on the Node.js runtime only, and it does coarse routing such as redirecting an unsigned user to sign-in. Server Functions are POSTs to a page route, so a matcher that skips a path skips them too. Every route handler and Server Function therefore re-checks the session itself (Lesson 3 builds requireSession()).


Agent CLIs: versions and four-tool equivalents (checked 2026-11-05, rechecked 2026-11-07)

Every lesson that shows an AI CLI spelling uses Claude Code first. The table below is the one place that lists the same technique in all four tools, with the versions it was checked on. Lesson 1 holds the permission, sandbox and egress rows, so they are not repeated here.

ℹChecked 2026-11-05, rechecked 2026-11-07

Versions read on 2026-11-05: Claude Code 2.1.318, Codex CLI 0.166.0, Antigravity CLI (agy) 1.5.1, Copilot CLI 1.0.105 (stable, released 2026-10-28). Sources: each tool’s own --version on the review machine, Claude Code changelog, Codex changelog, Copilot CLI releases, Claude Code memory. Spellings that need a minimum version: Claude Code --permission-prompts needs 2.1.259 or later; Antigravity’s exit code 3 on a print timeout needs 1.5.0 or later. Antigravity documentation now lives at antigravity.google/docs, and Codex documentation at learn.chatgpt.com/docs. Rechecked 2026-11-07: Claude Code 2.1.319, Codex CLI 0.167.0, Antigravity CLI 1.5.3 (on the review machine; the Antigravity changelog still tops out at 1.5.1), Copilot CLI 1.0.107 (the latest stable release, 2026-11-06; the review machine still ran 1.0.105); that day’s recheck corrected the Codex cells (plan mode is the in-session /plan or Shift+Tab, /review in a session, --full-auto removed). Recheck the changelog before you copy a spelling into a script.

TechniqueClaude CodeCodexAntigravityCopilot
Plan before buildingclaude, then Shift+Tab or /plan (edits blocked while it plans, unless the session was started with approval prompts off)codex, then /plan or Shift+Tab (an instruction, not a lock); codex --sandbox read-only to enforce read-onlyagy, then Shift+Tab or /plan (waits for your approval of its outline; its documentation does not say edits are blocked)copilot, then Shift+Tab or /plan (edits blocked while it plans)
Unattended--permission-mode auto; CI: -p ... --permission-prompts none; locked-down CI: --permission-mode dontAsk --allowedTools "..."codex exec --sandbox workspace-write (the default sandbox for exec is read-only); --approve-for-meagy -p ... with the tools it needs pre-approved in permissions.allow; --dangerously-skip-permissions only in a hardened containercopilot -p ... --allow-tool='shell(git:*)' --allow-tool=write --no-ask-user; --allow-all or --yolo only in a container
Subagents and custom agents.claude/agents/<name>.md, frontmatter tools, model, isolation.codex/agents/<name>.toml.agents/agents/<name>.md.github/agents/<name>.agent.md, --agent
Background and parallel sessionsclaude --bg, claude agents, attach, logs, stopcodex agents, codex queue, codex fork/agents, /tasks, background subagents/fleet, --fleet, /tasks, /delegate
Git worktreesclaude --worktree <name> (-w); subagent isolation: worktree; .worktreeincludecodex --worktree (not on resume)subagent workspace mode branch/worktree, /fork worktree, /move
Skills.claude/skills/<name>/SKILL.md; plugin skills as /plugin:skill.agents/skills/<name>/SKILL.md; invoke $name or /skills.agents/skills/<name>/SKILL.md; each skill becomes /<name>.github/skills/<name>/SKILL.md (also .agents/skills, .claude/skills); /skills, copilot skill add
Hooks (event spelling)PreToolUse, PostToolUse, PermissionRequest, Stop, SessionStart, in settings.json hooksthe same names; hooks.json or [hooks] in config.toml; trust review requiredPreToolUse, PostToolUse, PreInvocation, PostInvocation, SessionStart, Stop; .agents/hooks.json (not settings.json)preToolUse, postToolUse, permissionRequest, agentStop, sessionStart (camelCase); .github/hooks/*.json
Plugins and marketplacesclaude plugin marketplace add <src>; /plugincodex plugin marketplace add; codex plugin add <name>agy plugin install <name>@antigravity-plugins-official; agy plugin import claudecopilot plugin marketplace add <spec>; copilot plugin install <name>@<marketplace>
Headless and CI outputclaude -p --output-format json|stream-json --json-schema '...'; --bare is recommended for scripted callscodex exec --json --output-schema <file> -o <file>agy -p --output-format json|stream-json --json-schema ... --print-timeout 10mcopilot -p "..." --output-format json -s
Official CI integrationGitHub: anthropics/claude-code-action@v1; GitLab (beta, maintained by GitLab)GitHub: openai/codex-action@v1none officialnone official (install the CLI on the runner)
Project memory fileCLAUDE.md; AGENTS.md only if no CLAUDE.md exists, or importedAGENTS.md (AGENTS.override.md wins per directory); 32 KiB capAGENTS.md and GEMINI.md, both loaded (neither replaces the other), plus .agents/rules/*.md (frontmatter required).github/copilot-instructions.md, AGENTS.md, CLAUDE.md, GEMINI.md, *.instructions.md
Code review/code-review (alias /review), /code-review ultra or claude ultrareview; Code Review on GitHub (Team and Enterprise; not with Zero Data Retention or the HIPAA configuration)/review in a session (base branch, uncommitted changes, a commit, or custom instructions); codex review --base <branch>; @codex review on a GitHub pull request/diff (per-turn and commit-tree views), then a review prompt/review, /security-review; Copilot code review on GitHub

Never use Codex’s --full-auto: it was removed in Codex 0.147.0 (2026-08-07) and the flag now fails with an error; use --sandbox workspace-write. Codex permission profiles are beta. A headless run is never judged by its exit status alone: Claude Code’s --bare skips hooks and CLAUDE.md, and agy -p soft-denies an unapproved action and still exits 0, so the referee checks the artifact the run produced. In Copilot, the help text for --allow-all-tools says it is required for non-interactive mode, while the official Actions example omits it: test yours before you script it.

Sources for the table are the vendors’ own documentation: Claude Code, Codex, Antigravity, Copilot CLI. Module 19 Context Engineering and Skills and Hooks teach the general method for project memory (AGENTS.md) and AI CLI hooks; this table only keeps the spellings dated.


Project memory for your AI tool

Each AI CLI reads a project-memory file at the repository root, and the four tools do not agree on its name. The shortest answer that works everywhere is one AGENTS.md that holds the content, plus a one-line CLAUDE.md that imports it:

ToolReads
Claude CodeCLAUDE.md. It reads AGENTS.md by itself only when no CLAUDE.md exists in or above the working directory; with both present it reads CLAUDE.md alone, unless CLAUDE.md imports AGENTS.md, in which case it reads both
CodexAGENTS.md only (no CLAUDE.md or GEMINI.md by default)
AntigravityAGENTS.md and GEMINI.md both: the documentation says rules do not replace each other and every rule found is loaded, so neither file wins over the other
CopilotAGENTS.md, CLAUDE.md, GEMINI.md and its own instruction files, all combined with duplicates removed

Source: Claude Code memory for the first row; the vendors’ instruction-file pages for the others, as listed under the table above. The import line is @AGENTS.md on its own line at the top of CLAUDE.md, with any Claude-specific notes below it. Module 19 Lesson 2, Context Engineering, covers how each tool loads the file and how to keep it short enough that it gets followed.

Plan the change with your agent

Open your workspace agent at the project root after Lesson 1 has cleared the tool for this repository, switch to Plan mode (Shift+Tab, /plan, or the desktop app’s mode picker), and ask:

Plan a project-memory setup for this repository: one AGENTS.md under 60 lines with our stack pins and platform seam rules, plus a CLAUDE.md that imports it. Ask anything unclear.

What to check in the plan before you approve

  • AGENTS.md stays under 60 lines and carries the dated stack pins from the baseline table (2026-11-05).
  • The platform seam rules state that core code imports only src/platform/types.ts and getPlatform(), uses PLATFORM=local on a laptop, and never hand-builds a telemetry ingestion URL.
  • Framework and security rules are written as short imperatives: App Router only, proxy.ts for routing only, await on cookies(), headers(), and params, requireSession() in every route handler and Server Function, app-owned sessions without next-auth, no database passwords in the repository, and no major upgrade without a version decision record.
  • CLAUDE.md contains only @AGENTS.md so every tool reads the same instructions.

If the first plan duplicates rules across both files, push back before approving:

Keep CLAUDE.md to a single @AGENTS.md import line, and state the prohibitions in AGENTS.md as short imperatives.

What you get

An AGENTS.md like this, which every later prompt in the project inherits:

REFERENCE CONFIG AGENTS.md: dated stack pins and platform seam rules open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
# Project memory (pins checked 2026-11-05; see the version decision record in docs/adr/)
## Stack
- One Node major (26, fallback 24) in engines.node, .nvmrc, Dockerfile, pipeline
- next 16.4.x App Router only; react 19.3.x; typescript 5.x strict
- @mui/material 9.5.x; tailwindcss 4.3.x; zod 4.6.x (use the `error` param)
- openid-client 6.8.x for sign-in; mssql 12.7.x; vitest 5.1.x; @playwright/test 1.64.x
## Platform seam
- Core code imports src/platform/types.ts and getPlatform() only; no cloud SDK in core
- PLATFORM=local on a laptop; PLATFORM=<your platform> in the deployment
- Database credential is a token or a secret from platform.secrets; never a password in a string
- Telemetry: the startup hook calls registerTelemetry(serviceName), which calls platform.telemetry.start; paste the platform's endpoint, never hand-build one
## My platform (fill in from lesson 34, 35 or 36)
- Sign-in issuer: ... SQL host: ... Registry: ... Telemetry endpoint: ...
## Rules
- proxy.ts not middleware.ts; it is routing only, never the auth boundary
- await cookies(), headers(), params
- Every route handler and Server Function calls requireSession()
- No next-auth. Local secrets are generated outside the repo. No major upgrade without a decision record

and a CLAUDE.md of one line:

@AGENTS.md
💡Dated, so it can be wrong out loud

The date in the first line is the point. A project-memory file with undated pins keeps instructing the AI long after the pins moved. Re-date it whenever the decision record changes.


See it in action

The same planning session in each of the four tools. Use the tool switcher; the opening lines are the planning start from the table’s “Plan before building” row: open the tool, then /plan on its second line. Note that the first request ends in a plan, not an edit:

SESSION Project memory: plan first, then write
  1. Typed in the terminal: claude
  2. Mode:Plan mode (Shift+Tab)
  3. You type in the session: Plan a project-memory setup: one AGENTS.md of under 60 lines holding our pins and the seam rules, and a CLAUDE.md that only imports it. Do not edit anything yet.
  4. The tool replies: Plan: 1. AGENTS.md: stack pins (checked 2026-11-05), the seam rule (core imports src/platform/types.ts and getPlatform() only), the platform names to fill in, and the rules list. About 35 lines. 2. CLAUDE.md: one line, @AGENTS.md. Claude Code reads CLAUDE.md, and the import brings AGENTS.md in with it, so there is one source of truth. 3. No changes to settings or policy/. Nothing has been edited. Approve to proceed.
  5. You type in the session: Approved. Create both files, then show me CLAUDE.md and the first 6 lines of AGENTS.md.
  6. The tool replies: Created AGENTS.md (35 lines) and CLAUDE.md (1 line). $ cat CLAUDE.md @AGENTS.md $ head -6 AGENTS.md # Project memory (pins checked 2026-11-05; see the version decision record in docs/adr/) ## Stack - One Node major (26, fallback 24) in engines.node, .nvmrc, Dockerfile, pipeline - next 16.4.x App Router only; react 19.3.x; typescript 5.x strict - @mui/material 9.5.x; tailwindcss 4.3.x; zod 4.6.x (use the error param)
  7. You type in the session: Upgrade everything to the newest major versions.
  8. The tool replies: I will not change majors without a version decision record. Here is what I propose instead: 1. Draft docs/adr/0004-upgrade-<package>.md using the template (status, date, context, options, decision, rollback). 2. Run the upgrade order on a branch: codemod, typecheck, test, axe, pipeline. 3. Ask your ISSO or authorizing official whether this major counts as a significant change to the system. Which package do you want to start with?

Illustrative session; exact output varies by tool and agency configuration.

The transcript is illustrative: it shows the shape of a good session (a read-only start, a plan you approve, evidence you can check, and a refusal that turns into a proposal), not output you should expect to match character for character.


The version decision record

An upgrade is a decision with a date, an owner and an undo. Write it down before you run it, in the repository, next to the code it governs.

REFERENCE CONFIG docs/adr/0004-upgrade.md: version decision record template open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
# ADR-0004: Upgrade <package> from <old major> to <new major>
- Date: 2026-11-05
- Status: proposed | accepted | superseded by ADR-____
- Owner: <name>, reviewer: <name>
## Context
What changed upstream, with a source link and the date you read it.
## Options
1. Stay on the current major until <date> (support horizon from the baseline).
2. Upgrade now.
3. Upgrade after <named blocker> is resolved.
## Decision
Which option, and the condition that would reopen it.
## Authorization check
Asked <ISSO / AO> on <date> whether this is a significant change. Answer: ____
## Verification
Codemod run, typecheck, tests, axe, pipeline result, with links.
## Rollback
The commit or image tag to return to, and who may trigger it.

The upgrade order

Run the steps in this order on a branch, and stop at the first red one:

  1. Codemod. Let the framework move the mechanical changes: npx @next/codemod@canary upgrade latest, then npx @next/codemod@canary next-async-request-api . (the upgrade codemod does not cover awaited request APIs) and npx @next/codemod@canary middleware-to-proxy ..
  2. Typecheck. npx tsc --noEmit. Type errors after a major are the cheapest findings you will get.
  3. Test. npx vitest run for server logic (Lesson 12).
  4. axe. Run the accessibility scan in your Playwright suite (Lesson 14). A UI library major changes markup.
  5. Pipeline. Push the branch and let the real pipeline build, scan, and package the container (Lessons 18 and 19). A green laptop is not a green pipeline.
  6. Rollback. Prove the undo before you merge: redeploy the previous image tag to a non-production slot and confirm it starts.

Is a major upgrade a significant change?

Raise the question; do not answer it from this lesson. OMB Circular A-130 is the federal policy on managing information resources. What is verified here is narrow: the footnotes of OMB memo M-25-21 (the April 2025 memo on federal AI use) say that an agency’s process for accepting AI risk is separate from, and does not replace, the system authorization process under A-130. This lesson does not claim more than that about what A-130 requires for a framework upgrade. Whether replacing a framework major counts as a significant change to your system is for your AO, the authorizing official, the executive who accepts the risk of running the system, and for your ISSO, the security officer who maintains the system’s control documentation. Agencies define “significant change” in their own policy. Ask them with the decision record in hand, and write the answer in it.


KNOWLEDGE CHECK

A teammate says, 'Everything in Azure Government ends in usgovcloudapi.net,' and wants the AI tool to enforce that in the project-memory file. Which hostname shows the rule is wrong?

KNOWLEDGE CHECK

A teammate proposes calling the cloud provider's SDK directly from each route handler, 'since we only have one platform.' What does the platform seam change about that?

KNOWLEDGE CHECK

Your repository has an AGENTS.md with the project rules and a CLAUDE.md with a few personal notes that does not import it. A teammate runs Claude Code in the repository. What does the tool read?


Key takeaway

The platform map is your first deliverable: the seam you will land on your platform, one dated table of pins, the names that change with your cloud, a project-memory file (an AGENTS.md that CLAUDE.md imports) that repeats them, and a decision record for every major you take. Upgrade in the order codemod, typecheck, test, axe, pipeline, rollback, and put the significant-change question to your AO before you merge.

LEADERSHIP DECISION
Who owns the platform map and which decision-record template every major upgrade must use.
PRACTITIONER ACTION
Fill in your platform's column of the names table, then commit the AGENTS.md and the CLAUDE.md that imports it.
SUCCESS MEASURE
Audit finding avoided: no upgrade or tool-setting change without a dated record an assessor can open.

Legend: LEADERSHIP DECISION = what a leader decides · PRACTITIONER ACTION = what the engineer does next · SUCCESS MEASURE = how you know, in calendar time, assessor-hours or cost, contract or revenue risk, or audit finding avoided

Search lessons