Holmes LabAgentic Software Engineering Architect

From installation to a verified first change

Compare three installation modes, then follow approved specifications and RED/GREEN in a common practice project.

Guide verification basis: Holmes-Kit 0.40.0 · 2026-11-05 · Installation target: latest at execution time

Prerequisites, evidence and installation tradeoffs

Before you start

  • Node.js 20+, npm, Git and one of Claude Code CLI / Codex CLI / AGY CLI. Use a new practice folder.

You can review the requirement, design, tests, code and execution results together.

Documented for 0.40.0 · release contracts reviewed 2026-11-04. Native evidence is the historical 0.39.0 run of 2026-11-01. Read-only binding matched for Codex and Claude in an independent macOS workspace. Claude hook events were observed but routing is unverified; Codex hooks were not observed. Native revalidation on 0.40.0 and RED/GREEN acceptance of a small governed change remain incomplete. Windows/Linux instructions have no native acceptance run.

1. Separate user folder
Keeps project dependencies and global npm installation unchanged; separate versioned folder. Manage its path and updates separately; retain the folder while workspaces use it.
2. Project local
Project/team versioning through a lockfile; recommended for the practice project. Changes package.json and lockfile; may introduce npm metadata to a non-Node project.
3. Global npm
Convenient shared installation across projects. Check write permissions and update impact on all projects sharing this installation.

Package location and client settings are separate. Even project-local Codex wiring may change user-level settings.

Download practice starter ZIP ↓ · Ask your AI to install first ↗

Step 1 / 10

Check tools and your practice folder

Extract the practice ZIP into a new folder and open its package.json directory. Do not overwrite an existing project. Node.js 20+, npm, Git and Claude Code CLI, Codex CLI or AGY CLI are required. Follow the official tool setup if missing. In this new practice folder run npm install and npm test; require the original single test to PASS. Then git init and stage only the four named starter files as the review baseline, without committing. Stop if dependency installation or the baseline test fails.

Terminal in the confirmed projectShared · macos

Terminal in your workspace

pwd
node --version
npm --version
git --version
npm install
npm test
# Continue only after the original named-greeting test passes.
git init
git add package.json src/greet.js tests/greet.test.js README.md
Terminal in the confirmed projectShared · windows

Terminal in your workspace

Get-Location
node --version
npm.cmd --version
git --version
npm.cmd install
npm.cmd test
# Continue only after the original named-greeting test passes.
git init
git add package.json src/greet.js tests/greet.test.js README.md
Terminal in the confirmed projectShared · linux

Terminal in your workspace

pwd
node --version
npm --version
git --version
npm install
npm test
# Continue only after the original named-greeting test passes.
git init
git add package.json src/greet.js tests/greet.test.js README.md

Expected result — inspect your actual output

  • The new practice directory and tool versions are visible. Starter files contain the existing named greeting.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

Stop on a wrong path or existing files and choose an empty folder. On ARM Linux consult the package-supported Node versions.

What the agent does / terms

Read the absolute path and existing files; identify missing prerequisites without editing an existing project.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 2 / 10

Choose your installation

Run only your selected installation below, one line at a time. Confirm the resolved latest and actual installed versions match before continuing.

Terminal in the confirmed projectShared · macos

Auxiliary option · separate user folder

HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
Terminal in the confirmed projectShared · macos

2. Project local

HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
Terminal in the confirmed projectShared · macos

3. Global npm

HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
Terminal in the confirmed projectShared · windows

Auxiliary option · separate user folder

$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --prefix "$env:USERPROFILE/holmes-tools/$HolmesVersion" "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path $env:USERPROFILE "holmes-tools/$HolmesVersion/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
Terminal in the confirmed projectShared · windows

2. Project local

$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --save-dev --save-exact "@holmes-lab/holmes-kit@$HolmesVersion"
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (Get-Location) "node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
Terminal in the confirmed projectShared · windows

3. Global npm

$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
npm.cmd config get prefix
# Continue only if the prefix is writable by your user.
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --global "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (npm.cmd root --global) "@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
Terminal in the confirmed projectShared · linux

Auxiliary option · separate user folder

HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
Terminal in the confirmed projectShared · linux

2. Project local

HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
Terminal in the confirmed projectShared · linux

3. Global npm

HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"

Expected result — inspect your actual output

  • Resolved latest and Verified installed match. 0.40.0 is the guide verification basis, not an installation pin.
A manual learning note, not automatic verification of your workspace.
If the result differs

EPERM, ETARGET or a native-module error occurs.

For EPERM use a user-owned local path. For ETARGET refresh metadata with --prefer-online. Diagnose native failures with doctor and repair only the affected dependency.

What the agent does / terms

Commands defer model download with command-scoped HOLMES_SKIP_MODEL_INSTALL=1 and restore the environment. Prepare the model in the advanced lesson. Installation location and user-level client configuration are separate impacts.

This guide was reviewed against 0.40.0. This self-service path uses latest. For a guide-basis versus latest decision and prerequisite-change review, use the AI installation guide first. Installation resolves npm latest at execution time, installs that exact release and records it. First inspect current official Node/platform/model-download requirements. Choose a mode for each workspace and review shared global impact. On Windows inspect write permission for Program Files or administrator-owned locations; use the selected user-owned path rather than elevating privileges.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 3 / 10

Connect your selected AI CLI

Inspect the installed CLI init --help and doctor --help plus its version-specific official README before using these 0.40.0-based examples. If flags, modes, model policy or settings scope differ or remain unclear, stop before applying configuration. Review files with the preview, then run the apply command. New projects start in guardrail mode with autonomy off. Inspect impacts such as Codex user-level configuration shared by other projects.

Terminal in the confirmed projectClaude Code CLI · macos

Preview · no writes · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-run
Terminal in the confirmed projectClaude Code CLI · macos

Apply · after reviewing preview · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy
Terminal in the confirmed projectCodex CLI · macos

Preview · no writes · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-run
Terminal in the confirmed projectCodex CLI · macos

Apply · after reviewing preview · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy
Terminal in the confirmed projectAGY CLI · macos

Preview · no writes · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run
Terminal in the confirmed projectAGY CLI · macos

Apply · after reviewing preview · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy
Terminal in the confirmed projectClaude Code CLI · windows

Preview · no writes · Claude Code CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent claude --mode guardrail --no-autonomy --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Terminal in the confirmed projectClaude Code CLI · windows

Apply · after reviewing preview · Claude Code CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent claude --mode guardrail --no-autonomy
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Terminal in the confirmed projectCodex CLI · windows

Preview · no writes · Codex CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent codex --mode guardrail --no-autonomy --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Terminal in the confirmed projectCodex CLI · windows

Apply · after reviewing preview · Codex CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent codex --mode guardrail --no-autonomy
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Terminal in the confirmed projectAGY CLI · windows

Preview · no writes · AGY CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Terminal in the confirmed projectAGY CLI · windows

Apply · after reviewing preview · AGY CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent antigravity --mode guardrail --no-autonomy
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Terminal in the confirmed projectClaude Code CLI · linux

Preview · no writes · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-run
Terminal in the confirmed projectClaude Code CLI · linux

Apply · after reviewing preview · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy
Terminal in the confirmed projectCodex CLI · linux

Preview · no writes · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-run
Terminal in the confirmed projectCodex CLI · linux

Apply · after reviewing preview · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy
Terminal in the confirmed projectAGY CLI · linux

Preview · no writes · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run
Terminal in the confirmed projectAGY CLI · linux

Apply · after reviewing preview · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy

Expected result — inspect your actual output

  • Configuration was reviewed and a fresh selected CLI session was opened.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

For existing wiring or required approval follow the official refusal. Do not add --force blindly or automatically trust hooks.

What the agent does / terms

Preserve settings. Open the chosen CLI in this folder after applying. In Codex personally review trust in /hooks. A preview alone is not a configured client.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 4 / 10

Verify installation and live binding separately

Read doctor for the selected CLI. It diagnoses preparation, not this conversation binding.

Terminal in the confirmed projectClaude Code CLI · macos

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent claude
Terminal in the confirmed projectCodex CLI · macos

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent codex
Terminal in the confirmed projectAGY CLI · macos

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent antigravity
Terminal in the confirmed projectClaude Code CLI · windows

Terminal in your workspace

node "$HolmesCli" doctor --target . --agent claude
Terminal in the confirmed projectCodex CLI · windows

Terminal in your workspace

node "$HolmesCli" doctor --target . --agent codex
Terminal in the confirmed projectAGY CLI · windows

Terminal in your workspace

node "$HolmesCli" doctor --target . --agent antigravity
Terminal in the confirmed projectClaude Code CLI · linux

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent claude
Terminal in the confirmed projectCodex CLI · linux

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent codex
Terminal in the confirmed projectAGY CLI · linux

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent antigravity
Paste into your AI CLIClaude Code CLI

Ask your agent

Call workspace_preflight with my actual practice root and harness claude. Separate root/spec-store/build matching from live hook observation; keep unknowns unverified.
Paste into your AI CLICodex CLI

Ask your agent

Call workspace_preflight with my actual practice root and harness codex. Separate root/spec-store/build matching from live hook observation; keep unknowns unverified.
Paste into your AI CLIAGY CLI

Ask your agent

Call workspace_preflight with my actual practice root and harness antigravity. Separate root/spec-store/build matching from live hook observation; keep unknowns unverified.

Expected result — inspect your actual output

  • Current root, spec store and build match. Hook observation is reported separately.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

On mismatch or stale server reconnect from the right project without editing. Never equate a doctor probe with the current session.

What the agent does / terms

In the new session call workspace_preflight with the actual root and selected harness; AGY uses antigravity. If tools are unavailable here, report restart_required.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 5 / 10

Define the common sample change

greet already returns Hello, Ada! for Ada. Preserve that behavior, trim surrounding whitespace, and return Hello, World! for empty or whitespace names.

Paste into your AI CLIShared

Ask your agent

Make greet trim names and use World for empty or whitespace names in this practice project. Preserve Hello, Ada! for Ada. First run requirement_triage with persist:true; show classification, lineage and fresh evidence. Do not edit code yet.

Expected result — inspect your actual output

  • Observable success criteria and current requirement classification are available.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

Resolve ambiguity/staleness and refresh classification. Never invent IDs.

What the agent does / terms

Run requirement_triage with the exact request and persist:true; explain lineage and fresh evidence.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 6 / 10

Write and approve requirement and design

Read scope, inputs/outputs and success criteria, then decide the actual approval request.

Paste into your AI CLIShared

Ask your agent

Prepare the selected lineage with official tools. Specify preserved named greeting, trimming, World fallback and files to change; show it before approval. Use only actual returned IDs.

Expected result — inspect your actual output

  • An A-SPEC for current content is approved and its actual ID is known.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

Use spec_next or spec_remediate for ordering. If in-session approval is unavailable, show the actual request ID/target to the operator and follow the official approval path.

What the agent does / terms

Use official tools for the selected REQ→H-SPEC→A-SPEC lineage, fill TODOs and seal; do not implement yet.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 7 / 10

Enable governed checks after design approval

Guardrail is the default and differs from governed code checks. After verifying an approved A-SPEC, preview the transition, obtain required operator approval, apply and reconnect.

Operator terminal · review firstClaude Code CLI · macos

Preview · no writes · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force --dry-run
Operator terminal · review firstClaude Code CLI · macos

Apply · after reviewing preview · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force
Operator terminal · review firstCodex CLI · macos

Preview · no writes · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force --dry-run
Operator terminal · review firstCodex CLI · macos

Apply · after reviewing preview · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force
Operator terminal · review firstAGY CLI · macos

Preview · no writes · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-run
Operator terminal · review firstAGY CLI · macos

Apply · after reviewing preview · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force
Operator terminal · review firstClaude Code CLI · windows

Preview · no writes · Claude Code CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent claude --mode governed --no-autonomy --force --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Operator terminal · review firstClaude Code CLI · windows

Apply · after reviewing preview · Claude Code CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent claude --mode governed --no-autonomy --force
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Operator terminal · review firstCodex CLI · windows

Preview · no writes · Codex CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent codex --mode governed --no-autonomy --force --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Operator terminal · review firstCodex CLI · windows

Apply · after reviewing preview · Codex CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent codex --mode governed --no-autonomy --force
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Operator terminal · review firstAGY CLI · windows

Preview · no writes · AGY CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Operator terminal · review firstAGY CLI · windows

Apply · after reviewing preview · AGY CLI

$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent antigravity --mode governed --no-autonomy --force
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
Operator terminal · review firstClaude Code CLI · linux

Preview · no writes · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force --dry-run
Operator terminal · review firstClaude Code CLI · linux

Apply · after reviewing preview · Claude Code CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force
Operator terminal · review firstCodex CLI · linux

Preview · no writes · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force --dry-run
Operator terminal · review firstCodex CLI · linux

Apply · after reviewing preview · Codex CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force
Operator terminal · review firstAGY CLI · linux

Preview · no writes · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-run
Operator terminal · review firstAGY CLI · linux

Apply · after reviewing preview · AGY CLI

HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force

Expected result — inspect your actual output

  • Governed configuration and reconnection are checked; unobserved enforcement remains unverified.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

Do not switch without an approved A-SPEC. Do not bypass a refusal or switch harness silently.

What the agent does / terms

Rewiring uses --force and official approval; do not grant it yourself. Restart the selected CLI and separate configured mode from observed enforcement.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 8 / 10

Observe assertion RED first

Review tests for existing Ada behavior, trimming and blank names.

Paste into your AI CLIShared

Ask your agent

Persist maintenance_analyze for the approved greet change. Anchor the test first line with @implements and the actual A-SPEC ID. Test Ada, padded Ada, empty and whitespace strings. Record assertion RED with test_run; distinguish collection errors. Do not change source yet.

Expected result — inspect your actual output

  • Tests collect, new behavior assertions fail and official RED evidence exists.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

Import/syntax errors are not RED. Repair setup and run the same behavior assertions.

What the agent does / terms

Persist maintenance_analyze, put // @implements with the actual A-SPEC ID on the first test line and record assertion RED with official test_run. Do not change greet source yet.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 9 / 10

Approve test specification and implement

Review failing evidence and matching T-SPEC, then decide official approval.

Paste into your AI CLIShared

Ask your agent

After official approval of the matching T-SPEC, anchor greet source line one with @implements and the actual A-SPEC ID; minimally implement trimming and World fallback. Record GREEN and preserved Ada regression with the same test_run. Never fabricate approval or passing logs.

Expected result — inspect your actual output

  • The same tests pass and existing named behavior remains.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

Do not weaken assertions. Recheck the requirement and actual failure cause.

What the agent does / terms

After T-SPEC approval, anchor source line one with the actual A-SPEC ID, minimally update greet and record GREEN/regression using the same test_run.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 10 / 10

Review evidence, then apply to your project

Review new files from git status alongside the diff and actual test logs. Untracked files are absent from diff: ask the agent to inspect them individually; do not stage node_modules or secrets.

Terminal in the confirmed projectShared

Terminal in your workspace

git status --short
git diff --stat
git diff --check
git diff -- src/greet.js tests/greet.test.js
Paste into your AI CLIShared

Ask your agent

Summarize actual greet RED/GREEN, regression, diff and unverified scope. Do not label syntax errors RED or preparation as enforcement. Propose existing-project adoption separately; do not deploy.

Expected result — inspect your actual output

  • You can explain requirement/spec/test/code evidence and choose the next application path.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result differs or an official refusal occurs.

Preserve important unresolved items instead of presenting them as complete.

What the agent does / terms

Assemble evidence and distinguish independent from self review. Use Adoption for existing code without specs or Requirements for a governed project. Deployment/push is a separate decision.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Common practice: greet

This reproduction starter contains existing named greeting behavior, without specifications or approval IDs. Verify the blank-name change through RED/GREEN locally; displayed expected results are not observed execution logs.

Get the practice starter ↗

Continue with your project

Use Adoption for existing code without specs, or Requirements when specifications already exist. Other workflows require their stated prerequisites.