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
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.
- 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.
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.
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.
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.
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.
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.
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.
Step 4 / 4
Approve and link a small scope
Resolve gaps between draft and behavior before approving.
Ask your agent
Show unresolved issues in the recovered specifications first. After approval, persist maintenance_analyze and connect anchors and traceability within scope. Treat needed behavior changes as a separate change request.Expected result — inspect your actual output
- Code links and regression results exist; behavior changes remain in separate lineage.
If the result differs
An existing defect is discovered while linking.
Record the defect and triage a separate change instead of silently expanding adoption scope.
What the agent does / terms
After official approval, persist maintenance_analyze. Review the default reverse_anchor dry-run plan, apply within approved scope and rerun existing tests.
- 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.