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
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
- 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 your workspace
node "$HOLMES_CLI" run --helpTerminal in your workspace
node "$HOLMES_CLI" run --helpTerminal in your workspace
node "$HolmesCli" run --helpAsk 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.
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.
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.
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.
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.
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.
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.
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.