Holmes LabAgentic Software Engineering Architect

Adopt an existing codebase

Recover specifications from working code while separating observed behavior from intended 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.
  • Existing test commands and one small module to review

Establish reviewable requirement, specification and code links for one module.

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

Record baseline behavior

Choose one module and its public behavior to preserve.

Paste into your AI CLIShared

Ask your agent

Inspect this module read-only. Separate public inputs and outputs, existing tests and current failures, and label inferences.

Expected result — inspect your actual output

  • Current behavior and the test baseline are recorded without source edits.
A manual learning note, not automatic verification of your workspace.
If the result differs

Tests are absent or depend on an external service.

Narrow to reproducible local behavior and prepare separate authorization and environment for service execution.

What the agent does / terms

Use reverse_scan to inspect the selected scope; run the existing test command and record failures and unsupported areas.

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

Establish the adoption requirement

Define preserved behavior and the recovery scope.

Paste into your AI CLIShared

Ask your agent

I want to recover specification links without changing this module’s behavior. Persist requirement_triage and prepare the adoption REQ and success criteria in its lineage.

Expected result — inspect your actual output

  • The adoption goal, exclusions and actual parent REQ ID are available.
A manual learning note, not automatic verification of your workspace.
If the result differs

The response says parentReqId is required or the parent is missing.

Use spec_next to inspect lineage and prepare the actual REQ; never insert an invented ID.

What the agent does / terms

Persist requirement_triage and author the REQ in the appropriate lineage; retain its actual returned ID.

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

Recover a draft from code

Review whether each extracted behavior is a contract to preserve.

Paste into your AI CLIShared

Ask your agent

Inspect the current reverse_draft input schema and recover a draft for this module using the actual parentReqId of the adoption requirement. Separate observed code from inferred policy.

Expected result — inspect your actual output

  • Each drafted behavior can be traced to an actual file or test.
A manual learning note, not automatic verification of your workspace.
If the result differs

The draft omits exception handling or dynamic calls.

Inspect code manually and add omissions and uncertainty; do not mark unextracted behavior as supported.

What the agent does / terms

Inspect the current reverse_draft schema and run it for the selected scope with parentReqId. Review its default dry-run draft before deciding to apply it.

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

The Lab primary-navigation restoration already had specifications. This scenario is a conceptual application to your ungoverned module, not a claim of a recorded Lab adoption run.

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.