Holmes LabAgentic Software Engineering Architect

Runs with roles and review gates

Open a run in an isolated worktree with explicit stages and review policy.

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

  • Your own workspace and connected MCP session after the basics. Define HOLMES_CLI or PowerShell HolmesCli from the installation step in this terminal and verify its file and version.
  • An operator-prepared worktree and approved implementation scope

Inspect run build, stage and review state, then end it through the official stop procedure.

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.

Step 1 / 4

Check harness support and worktree

Prepare an isolated worktree, scope and reviewer. For Codex confirm the main checkout or worktree is trusted.

Terminal in the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" run --help
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" run --help
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" run --help
Paste into your AI CLIShared

Ask your agent

Inspect 0.40.0 run start --provision for Claude/Codex. Separately check a trusted Codex checkout, ignored .codex/config.toml and user-level hooks. Label AGY run start unavailable; do not copy secrets or global hooks.

Expected result — inspect your actual output

  • Harness support, trust, configuration paths and actual entrypoints are checked separately.
A manual learning note, not automatic verification of your workspace.
If the result differs

AGY, tracked configuration, missing trust or executable wiring is refused.

Have the operator prepare official wiring and native trust, then inspect a fresh session; do not bypass the refusal.

What the agent does / terms

Codex provisioning writes only the MCP table in git-ignored .codex/config.toml. The gate remains in user-level hooks. Check that MCP and PreToolUse/Stop execute actual Holmes-Kit package entrypoints.

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 / 4

Start with scope and review policy

Choose the real worktree, A-SPEC ID and review-round limit.

Paste into your AI CLIShared

Ask your agent

Use installed run start help to prepare a plan with the real worktree, chosen engine claude or codex, approved scope, --provision, --review-base set to the task base commit, --review-rounds 3 and --strict-review. After starting, retain the actual run ID and stop key.

Expected result — inspect your actual output

  • The output contains an actual run ID, pinned build and review policy. --review-base must be an ancestor of HEAD; failed review rounds accumulate across runs on that base.
A manual learning note, not automatic verification of your workspace.
If the result differs

Configuration or build conflicts occur.

Resolve reported conflicts and inspect status; do not label partial preparation a successful run.

What the agent does / terms

Construct exact start arguments from installed help for review and safely return the actual run ID and stop key to the operator.

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 / 4

Work within declared stages

Check role deliverables and the independent reviewer.

Paste into your AI CLIShared

Ask your agent

Inspect status for the actual run ID and do only work allowed in its current stage. Before the next transition, check required deliverables, approval and independent review; retain refusal codes.

Expected result — inspect your actual output

  • Stage transitions, deliverables and review are connected.
A manual learning note, not automatic verification of your workspace.
If the result differs

The run stops for review.unresolved or a stage violation.

Fix unresolved findings or report them to the operator; do not hide defects by increasing the round cap.

What the agent does / terms

Inspect current run status and use official transition. Do not treat self-review or arbitrary child launches as authorized.

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 / 4

Package review results and close the run

Inspect important open findings and the change scope.

Paste into your AI CLIShared

Ask your agent

Check that independent review matches the current run and commit range. Report open items from the review gate and merge-ready package, then follow official termination with the actual stop key. Do not expose the key in public logs.

Expected result — inspect your actual output

  • Run termination state and remaining review limitations are confirmed.
A manual learning note, not automatic verification of your workspace.
If the result differs

The stop key is unavailable or the reviewed commits differ.

Check operator-held start records and actual commit range; never invent a key or review result.

What the agent does / terms

Inspect evidence using installed review status/gate/mrp and perform run stop with the actual stop key.

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.

Apply to your project

This is a conceptual example of run policy. It does not claim that an orchestrator performed the Lab primary-navigation restoration or that Codex provisioning was verified.

Related case ↗

Continue with your project

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