Holmes LabAgentic Software Engineering Architect

Refine requirements without duplication

Follow intake from classification and lineage selection to success criteria and approval.

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.

Decide with evidence whether to create a requirement or extend an existing one.

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

Write observable success

Specify the user, starting state, action, observable result and behavior to preserve.

Paste into your AI CLIShared

Ask your agent

Preserve my request verbatim and propose success criteria observable through user behavior. Separate assumptions from questions requiring confirmation.

Expected result — inspect your actual output

  • Each criterion has a concrete way to check it.
A manual learning note, not automatic verification of your workspace.
If the result differs

A quality goal lacks a measurement or observable condition.

Define a measurement environment or user scenario; do not invent an unagreed metric.

What the agent does / terms

Preserve the original request and separate ambiguities from candidate acceptance criteria.

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

Triage with fresh evidence

Check that the classification matches your intent.

Paste into your AI CLIShared

Ask your agent

Run requirement_triage with my exact request and persist:true. Explain the fulfilled, existing-change, new or ambiguous classification, candidate lineage and digest.

Expected result — inspect your actual output

  • A fulfilled result reuses existing lineage; an existing-change names its predecessor.
A manual learning note, not automatic verification of your workspace.
If the result differs

A failed refresh leaves the result ambiguous.

Resolve the refresh failure and triage again; do not present cached evidence as fresh.

What the agent does / terms

Pass the exact original prompt and persist:true to requirement_triage and inspect evidence freshness.

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

Author the document body

Review exclusions and compatibility boundaries together.

Paste into your AI CLIShared

Ask your agent

Create specifications through official tools in the classified lineage. Replace every TODO and author REQ Success Criteria, linking inputs, outputs, failures, compatibility and files to touch.

Expected result — inspect your actual output

  • Failure cases and exclusions are documented.
A manual learning note, not automatic verification of your workspace.
If the result differs

There is a file list but no explanation of the desired behavior.

Complete user behavior and success criteria before detailing implementation.

What the agent does / terms

Scaffold with official tools and edit the Markdown body. Pass fresh triage_evidence when creating a new REQ.

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 connect current content

Read the current diff and decide the official approval request.

Paste into your AI CLIShared

Ask your agent

Use spec_next to inspect approval order and show current documents and digests. After approval, report lineage and the next test step. Do not reuse an earlier approval after content changes.

Expected result — inspect your actual output

  • Approval matches current content and the next step is clear.
A manual learning note, not automatic verification of your workspace.
If the result differs

A parent digest mismatch or pending approval remains.

Inspect the changed parent and affected children, then follow official reapproval ordering.

What the agent does / terms

Check ordering with spec_next and use spec_slice_approve or spec_approve. Re-review later edits.

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.

Recorded Holmes Lab change

A-SPEC-101.21 restored three hidden primary links on home—Technical journey, Work and Practice—removed graph fallback JSON links and expanded Practice content. RED, regression and build records in docs/evidence/engineering-perspective are historical evidence. Running these instructions in your project is a reproduction, not that historical execution.

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.