Applied AI-Accelerated Government Development

The Dev Workbench

Updated

Intermediate

What you'll learn

~15 min
  • Verify the pinned Node.js major (or its stated fallback), Git, your shell (WSL2 on Windows) and a container runtime are ready
  • Configure Git Credential Manager so Git signs in with your identity instead of a stored token
  • Install an AI CLI tool and prove it with a multi-turn smoke test (plan, approve, edit, run, check, and optionally undo) in a scratch folder, until Lesson 1 clears your repository
  • Start the reference app's local stack (a SQL Server container, an OIDC provider that signs users in with signed tokens, and an OTLP collector that receives OpenTelemetry traces) with generated secrets kept outside the repository

Environment check

You probably have most of this already. This page is a short preflight so a tooling problem does not interrupt a later lesson. If every check below passes, go straight to Lesson 1. If one fails, the fix is inline.

⚠Do not point an AI CLI at an agency repository yet

The smoke test below runs in a throwaway folder on purpose, and the local stack check runs only the training’s reference app. Do not start 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 → inside an agency repository until you have finished the determination step in Lesson 1 (Approved Tools, Approved Endpoints): a written answer on whether your code and prompts may leave the boundary, and through which endpoint.


Checklist

1. Terminal and shell

You need a bash or zsh shell. On Windows that means WSL2 (the Linux environment built into Windows), not PowerShell.

Terminal window
echo $SHELL

If you see /bin/bash or /bin/zsh, you are set. On a Windows machine without WSL, open PowerShell as Administrator, run wsl --install, restart, then open the Ubuntu app.

2. Node.js at the reference pin

Every lesson in this module targets the same Node.js Node.js A runtime that lets you run JavaScript outside a browser. Needed when a web project runs npm; the native AI CLI installers include their own runtime. Full lesson → major, listed once in Lesson 2’s dated baseline table. The reference pin is 26. Fall back to 24 when your agency’s base image or hosted build agent does not ship 26 yet. Whichever you choose, use that one number everywhere it appears in a project.

Terminal window
node --version

If the major does not match, install it with nvm:

Terminal window
nvm install 26
nvm alias default 26

If your base image only ships the fallback, run nvm install 24 and nvm alias default 24 instead, and write that decision down in Lesson 2’s version decision record.

3. Git and Git Credential Manager

Check that Git Git Version control — saves snapshots of your project so you can undo mistakes. Like Google Docs history for code. Full lesson → is installed:

Terminal window
git --version

If it is missing: sudo apt install git (Ubuntu or WSL) or xcode-select --install (macOS).

Git Credential Manager (GCM) signs you in through your organization’s identity provider in a browser and keeps a short-lived token for you. It supports the common hosts (GitHub, GitLab, Bitbucket and Azure DevOps among them), so you configure it once whichever your agency uses. On native Linux or macOS, install GCM from its releases page and run:

Terminal window
git-credential-manager configure

On WSL, point Git at the GCM installed on the Windows side (this path is for the standalone GCM installer; Git for Windows installs it under its own folder, so check GCM’s WSL documentation if the path differs):

Terminal window
git config --global credential.helper "/mnt/c/Program\ Files/Git\ Credential\ Manager/git-credential-manager.exe"

On Azure DevOps, also run git config --global credential.https://dev.azure.com.useHttpPath true, so each organization gets its own sign-in.

Test access with a repository you already have permission to read. Expect a browser sign-in on the first call:

Terminal window
git ls-remote https://YOUR_GIT_HOST/YOUR_GROUP/YOUR_REPO.git

If that returns refs, your sign-in works.

ℹWhich Git host?

Your agency decides the host, and it may be self-managed inside your boundary rather than a hosted service. The sign-in pattern above is the same for all of them; Lesson 37 covers each host’s pipeline and review rules. Whether any hosted service you might use for code is inside your agency’s authorization boundary is a question this module does not answer either way: ask your ISSO (the security officer who signs off on your system’s controls) before you choose.

⚠Personal access tokens are a constrained legacy path

A personal access token (PAT) is a long-lived password you paste into Git, and every host offers one. Prefer the browser sign-in above. If a legacy system forces a PAT, scope it to one repository or organization, give it the shortest expiry the system allows, and keep it out of shell history and .env files. Lesson 17 covers the pipeline side, where federation replaces stored tokens altogether. On Azure DevOps specifically, Microsoft’s guidance is to avoid PATs wherever an Entra sign-in, a managed identity or a service principal can do the job, and its own page gives two dates for the retirement of global PATs: December 1, 2026 in one section and January 27, 2027 in another (as of 2026-11-07). Plan for the earlier one; once it has passed, check that page for which date Microsoft enforced.

4. A container runtime

The reference app’s local stack runs three containers, so docker version (or your agency’s approved equivalent) has to answer from the same shell you will use for the rest of the module. On WSL2, that means the container runtime is reachable from inside the Ubuntu shell, not only from Windows.

Terminal window
docker version

If your workstation policy forbids a container runtime, say so now. Several later lessons assume one, and Lesson 1’s approval conversation is the place to get an exception.

5. AI CLI tool

Install one tool your agency has approved. If you do not know yet which one that is, install nothing today, skip the smoke test below, and let Lesson 1 tell you.

Terminal window
# Claude Code: the native installer is the recommended route (macOS, Linux, WSL); npm is no longer the headline method
curl -fsSL https://claude.ai/install.sh | bash
# Codex CLI (on Linux and WSL, its sandbox needs bubblewrap first: sudo apt install bubblewrap)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Antigravity CLI
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Copilot CLI
curl -fsSL https://gh.io/copilot-install | bash

Each installer is a script from the vendor’s own host that runs as you. If your agency ships these tools through its own software channel, use that channel instead and skip the lines above. Where it does not, download the script, read it, then run it. Lesson 2 holds the dated four-tool table, including each tool’s current version, so a version never has to be copied from this page.

Run it once to sign in, from your home directory, not from a repository (claude, codex, agy or copilot, whichever you installed):

Terminal window
claude
ℹCorporate or agency network?

If you are behind a proxy or need a custom certificate store, the shared curriculum covers it: Overview & Prerequisites. That lesson includes proxy variables, certificate trust, and device-flow sign-in for restricted networks.


Smoke test: four turns, not one

A one-shot prompt that writes a file proves the install and nothing else. The real work in this module is a session: the tool reads, proposes, waits for you, edits, and runs something that shows whether it worked. This smoke test exercises that loop in a throwaway folder that holds no agency code, no secrets, and no real data.

Terminal window
dir=~/scratch-workbench-$(date +%Y%m%d-%H%M%S)
mkdir -p "$dir" && cd "$dir"
git init
printf 'console.log("Workbench not ready");\n' > hello.js
git add hello.js && git commit -m "scratch: start"

The folder name carries the date and time, so a second run never lands in an old folder. git init starts tracking this folder, and git commit saves a checkpoint you can return to; Turn 5 uses it. If git commit asks who you are, run git config --global user.name "Your Name" and git config --global user.email "you@example.com" once, then run the git add line again.

Once the commit has gone through, open the tool:

Terminal window
claude

Then switch to plan mode inside the session: press Shift+Tab until the status bar says plan, or type /plan. In plan mode the tool reads files and writes a plan before it builds; opened this way, Claude Code and Copilot hold edits until you approve, and the tool modes table says how firmly each tool waits. Using another tool? Replace that line with codex, agy or copilot, then switch the same way. When read-only must be enforced by the operating system rather than by a mode, start Codex as codex --sandbox read-only, and switch it with /permissions when you reach the edit. Codex also starts read-only in a folder that is not a Git repository, one more reason this check runs git init first. Lesson 2’s table, “Plan before building”, lists the four side by side with the other techniques the module uses.

Turn 1, read and propose. Prompt first:

Read hello.js. Propose the smallest change that makes it print "Workbench ready"
and exit with code 0. Say how you would check it worked. Do not edit anything yet.

Expect a plan and no edits. To be sure, open a second terminal window (on Windows, open Ubuntu again from the Start menu), go to the same folder with cd "$(ls -dt ~/scratch-workbench-* | head -1)" (it picks the newest scratch folder), and run git status. Keep the tool session open in the first terminal: Turn 5 uses this same session, and the clean-up step uses the $dir that terminal remembers. If git status shows a modified file, the tool changed something while it was planning: stop, check that the status bar says plan, and start again.

Turn 2, approve. Approve the plan in the tool’s own prompt (in Claude Code that leaves plan mode; in Codex, Shift+Tab or /plan toggles plan mode off; in Copilot, say go ahead and pick “Accept plan and continue”; if you started Codex with --sandbox read-only, leaving plan mode does not lift that sandbox, so switch to Auto with /permissions as well).

Turn 3, edit and run.

Make that change, run node hello.js, and show me the output and the git diff.

Turn 4, check it yourself. Do not accept the tool’s report as the evidence. In the second terminal:

Terminal window
node hello.js # expect: Workbench ready
git diff --stat # expect: one file changed, matching the plan

Turn 5 (optional), undo once. Do it now, so the first time you need an undo is not the first time you use one. In Claude Code, prompt first:

/rewind

Pick the checkpoint from before Turn 3 and restore the code. Claude Code saves a checkpoint before each prompt, and it covers the edits its own file tools made; changes made by shell commands it ran are not tracked, so they do not roll back. The other tools differ. Codex has no /rewind; OpenAI’s own guide says to create git checkpoints before and after a task. Antigravity’s /rewind rolls back the conversation; its documentation does not say whether file edits roll back too, so check /diff and git status afterwards. Copilot lists /rewind in its help; what it restores is not documented.

In every tool, git is the undo that covers every tracked file, whoever changed it. In the second terminal:

Terminal window
git restore --staged --worktree hello.js # return this one file to its committed version
node hello.js # expect: Workbench not ready
git status --short # expect: nothing listed

--staged --worktree takes that one file back to the commit you made before Turn 1, both the file on disk and git’s staging area (the changes queued for the next commit), so it works whether or not the tool staged its change, and it leaves every other file alone. If you already used /rewind, it changes nothing, and the two checks after it in the block confirm the rewind worked.

Clean up, as its own step. Exit the tool and close the second terminal, then from the first one:

Terminal window
cd ~ && rm -rf "${dir:?}" # :? stops with an error if $dir is empty

If you closed the first terminal, $dir is empty in a new one, so the command above stops and deletes nothing. Run ls -d ~/scratch-workbench-* to list the scratch folders, then delete the one you made by its full name, for example rm -rf ~/scratch-workbench-20261107-143000 with your folder’s date and time.

You have now seen a switch to plan mode, an approval, an edit, a run you verified yourself and, if you took Turn 5, an undo. That is the loop every later lesson uses.


Check the local stack

The worked example in this module runs on your laptop first and reaches a cloud only in the platform lessons at the end. This check starts the app’s local stack once, so a missing container shows up today.

Your own project will have its own local stack. Whatever form it takes, it needs three things:

  • A SQL Server container, so database code runs against the same engine your platform hosts.
  • An OIDC provider of record, or a mock of one. OIDC (OpenID Connect) is the standard by which an identity provider signs a user in and hands your app a signed token. A mock is a local stand-in that issues test tokens.
  • An OTLP collector. OTLP is the wire format of OpenTelemetry, the standard for reporting what an app did; the collector is the local receiver that proves your app’s telemetry leaves the process.

The reference app is public: github.com/Intellimetrics/gov-dev-reference-app. Every code block in this module that names one of its files is checked against it when the site builds, so what you clone is what the lessons quote. gov-dev-reference-app 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, run it in your Next.js app or let the agent scaffold the folder stubs. Clone it, then run its stack script:

Terminal window
git clone https://github.com/Intellimetrics/gov-dev-reference-app.git
cd gov-dev-reference-app
npm install
npm run local:up

local:up starts the three containers on loopback only (SQL Server on 127.0.0.1:14330, the mock OIDC provider on :8080 and the collector on :4318) and creates an intake database with a login for the app.

Prove it with the project’s own tests, which run against those containers:

Terminal window
npm test # unit tests, no containers needed
export M14_SECRET_DIR="$HOME/.config/m14-reference"
npm run test:env # sign-in, database rotation and a span reaching the collector

Expect every test to pass. If test:env fails on the first run, docker ps should list m14-sql, m14-oidc and m14-otel; a missing one is the fix.

Local secrets are generated, and they live outside the repository

local:up generates the database password and the OIDC client secret itself. Nobody types them, they are never printed, and they are written with owner-only permissions to ~/.config/m14-reference (or the folder in M14_SECRET_DIR), which is not inside any repository. Confirm that, because a secret in a working tree is one git add . from a commit:

Terminal window
ls ~/.config/m14-reference # expect: the generated secret files
git status --short # expect: nothing from the secrets folder

Use the same rule for your own project’s local stack: generate, store outside the tree, never commit a .env that holds a real value. When you are done for the day, npm run local:down removes the containers and the secrets folder.

Move on to Lesson 1, where you decide which tools and endpoints you may use with agency code at all.


Key takeaway

A workbench is ready when the smoke test and the local stack’s own tests pass, and no secret sits inside a working tree. Nothing touches agency code until Lesson 1 records what may leave the boundary.

LEADERSHIP DECISION
Who signs the written determination of approved tools and endpoints before anyone opens an agency repository.
PRACTITIONER ACTION
Run npm test and npm run test:env, then confirm git status shows nothing from the secrets folder.
SUCCESS MEASURE
Calendar time: a new engineer reaches a passing local stack in one session, without a secret in any commit.

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