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
Choose a CLI, OS and installation mode to see the matching commands. This page does not inspect or execute on your computer.
AGY CLI ordinary integration is supported. AGY run start is refused in 0.40.0; this orchestration lesson has no executable AGY start procedure. Keep your choice, select a different CLI explicitly, or return to Basics.
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 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.mdTerminal 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.mdTerminal 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.mdExpected result — inspect your actual output
- The new practice directory and tool versions are visible. Starter files contain the existing named greeting.
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.
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"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"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"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"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"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"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"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"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.
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.
Preview · no writes · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-runApply · after reviewing preview · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomyPreview · no writes · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-runApply · after reviewing preview · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomyPreview · no writes · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-runApply · after reviewing preview · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomyPreview · 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
}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
}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
}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
}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
}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
}Preview · no writes · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-runApply · after reviewing preview · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomyPreview · no writes · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-runApply · after reviewing preview · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomyPreview · no writes · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-runApply · after reviewing preview · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomyExpected result — inspect your actual output
- Configuration was reviewed and a fresh selected CLI session was opened.
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 your workspace
node "$HOLMES_CLI" doctor --target . --agent claudeTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent codexTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent antigravityTerminal in your workspace
node "$HolmesCli" doctor --target . --agent claudeTerminal in your workspace
node "$HolmesCli" doctor --target . --agent codexTerminal in your workspace
node "$HolmesCli" doctor --target . --agent antigravityTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent claudeTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent codexTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent antigravityAsk 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.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.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.
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.
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.
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.
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.
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.
Preview · no writes · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force --dry-runApply · after reviewing preview · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --forcePreview · no writes · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force --dry-runApply · after reviewing preview · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --forcePreview · no writes · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-runApply · after reviewing preview · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --forcePreview · 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
}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
}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
}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
}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
}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
}Preview · no writes · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --force --dry-runApply · after reviewing preview · Claude Code CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode governed --no-autonomy --forcePreview · no writes · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --force --dry-runApply · after reviewing preview · Codex CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode governed --no-autonomy --forcePreview · no writes · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --force --dry-runApply · after reviewing preview · AGY CLI
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode governed --no-autonomy --forceExpected result — inspect your actual output
- Governed configuration and reconnection are checked; unobserved enforcement remains unverified.
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.
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.
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.
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.
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 your workspace
git status --short
git diff --stat
git diff --check
git diff -- src/greet.js tests/greet.test.jsAsk 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.
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.