@holmes-lab/holmes-kit

v0.1.18

Published

a day ago

Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)

0High
0Medium
0Low

sungnam.park

ase agentic spec-driven rtm cpg traceability mcp guardrail

🔍 Holmes-Kit

"No Spec, No Code" — Deterministic Agentic Software Engineering (ASE) harness with causal traceability.

🕵️ Philosophy & Vision: Beyond Code Generation

Holmes-Kit is not merely an AI code generator. Inspired by Sherlock Holmes, Holmes-Kit is built to deduce, track down, and analyze code defects, structural drift, and security vulnerabilities across the full Software Development Life Cycle (SDLC).

🛡️ Currently Supported Features (v0.1.x Production Features)

📋 Requirements & Specification Governance: Strict "No Spec, No Code" enforcement with 4-tier spec chain traceability (REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC) and // @implements A-SPEC-XXX line 1 code anchors.
🐞 Causal Defect Localization & CPG: AST Code Property Graph (CPG) & Dataflow Taint reachability analysis across 7 languages (TS/JS, Python, Go, Rust, Java, C/C++, C#).
🧪 Self-Healing & Diagnostic Doctor: Automated integrity checks and self-healing auto-fix remediation (holmes-kit doctor --fix & spec_remediate).
🚦 CI/CD Governance Gate Runner: Non-interactive headless CI/CD build gate (holmes-kit ci) for GitHub Actions and GitLab CI pipelines.
📊 Automated RTM & Taint Heatmap: Interactive standalone HTML/SVG report generation (generateRtmHeatmap) for spec coverage and security dataflow reachability.
🤖 CLI-First AI Harness Matrix: Native process hook gating for Claude Code, Antigravity CLI (AGY), Codex CLI, and Google Antigravity SDK.

🚀 Full SDLC Vision & Roadmap (Future Goals)

Holmes-Kit strives to expand into a unified enterprise SDLC harness bridging external development tools:

🔌 Enterprise Issue Tracker Connectors: Flexible synchronization with Jira, GitHub Issues, Linear, and Notion.
🌐 Multi-Repository Polyrepo Governance: Multi-repo spec chain synchronization and cross-repository dependency impact analysis (REQ-211).
🛡️ External SAST & Linter Bridge: Deep integration with SonarQube, Semgrep, and ESLint findings.

🤖 Supported AI Coding Tools & Environments (CLI-First Focus)

Holmes-Kit prioritizes CLI-based AI Coding Agents where OS-level process hooks, subshell isolation, and deterministic control plane enforcement are natively guaranteed:

Note: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (deny enforcement) before file modifications occur.

⚡ Quickstart (3-Minute Setup)

1. Install — find your row first

The same wrong command was run three times by a real adopter before the right one; a table beats prose read top-to-bottom.

Windows (recommended) — a bootstrap installer that runs before npm and fixes what npm cannot: it relocates out of protected folders (an elevated PowerShell opens in C:\WINDOWS\System32, where npm install fails with EPERM), checks the Node.js version, and, if a native module fails to build, prints the one winget command that installs the missing C++ toolchain instead of raw compiler output. Pure Windows PowerShell 5.1; no prompts; nothing persistent is changed.

# From a downloaded copy of the package (e.g. after `npm pack`, or from a checkout):
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1

# One-liner (once hosted):
# irm https://<host>/install.ps1 | iex

Add -DryRun to see what it would do without installing. Exit codes: 0 ok / already installed · 2 bad argument · 3 Node.js too old · 4 npm failed (remediation printed) · 5 installed but not on PATH (prefix printed).

| Which situation are you in? | Privileges | Command | |---|---|---| | Using it in one project (most people) | none | npm install --save-dev @holmes-lab/holmes-kit | | Company-managed PC / restricted account | none | same — no system directory is touched | | CI / container | none | same, plus --prefer-online right after a release | | CLI across many projects (-g) | depends | run npm config get prefix first — see below |

Before npm install -g: if npm config get prefix names a protected directory (C:\Program Files\nodejs, /usr/local), -g dies with EPERM before any package file arrives — no package version can fix that, and elevation is the wrong fix (it runs native install scripts with system privileges, and it did not even work in the reported case). Move the prefix to user space instead — one-time setup, exact commands in the Install Guide, along with troubleshooting keyed to the exact error text (EPERM mkdir, notarget, better-sqlite3 build failures).

Prerequisites — Node.js >= 20.0.0. The 8 tree-sitter grammars ship prebuilt binaries for macOS/Linux/Windows and compile nothing; better-sqlite3 downloads a prebuild at install time, falling back to compiling — only that fallback needs a C++ toolchain (VS Build Tools / Xcode CLT / apk add python3 make g++).

2. Initialize in Your Project

cd /path/to/your/project
npx holmes-kit init      # drop the npx prefix if you installed with -g

An interactive prompt will ask which AI agent harnesses to wire into your project:

? Select the AI Agent harnesses to wire into this project:
  [X] 🤖 Claude Code          (.claude/settings.local.json, .mcp.json)
  [X] 🚀 Antigravity CLI (AGY) (.agents/mcp_config.json, hooks.json, skills)
  [ ] 💻 Codex CLI            (.codex/mcp_config.json)

3. Verify Health

npx holmes-kit doctor

If everything is green, your project is governed and ready for AI pair-programming!

🔄 Daily Workflow (How It Works)

Once initialized, your AI agent automatically follows the No Spec, No Code lifecycle:

flowchart LR
    A["1. Spec First<br/>(REQ → A-SPEC)"] --> B["2. Test First<br/>(TDD & T-SPEC)"]
    B --> C["3. Implementation<br/>(// @implements A-SPEC)"]
    C --> D["4. Verified Code<br/>(Provenance Sealed)"]

Spec First: The agent authors requirements and architecture specs via spec_create.
Test First: The agent writes tests and approves T-SPEC before writing implementation code.
Implement: Code files anchor to their architecture spec with // @implements A-SPEC-NNN.
Deterministic Guard: If the agent attempts to write code without approved specs, Holmes-Kit hooks block the action and provide exact next steps.

🧰 Essential CLI Cheatsheet

🧩 Optional: Manual MCP Integration (Cursor, Windsurf, Claude Desktop)

Note: If you ran holmes-kit init, this configuration is 100% automated for you.
Use the manual configuration below only if you wish to integrate Holmes-Kit into standalone third-party MCP clients like Cursor, Windsurf, Claude Desktop, or VS Code:

{
  "mcpServers": {
    "holmes-kit": {
      "command": "npx",
      "args": ["-y", "--package=@holmes-lab/holmes-kit", "holmes-mcp"],
      "env": {
        "HOLMES_SPECS": ".ax/specs"
      }
    }
  }
}

🌐 Supported Languages & Environments

Holmes-Kit embeds native AST & Code Property Graph (D-CPG) analyzers to track causal relationships and anchor implementations across diverse technology stacks.

💻 Supported Programming Languages

🖥️ Supported Operating Systems & Runtimes

Runtime Requirement: Node.js >= 20.0.0 (LTS recommended)
How a tier is decided: by the verification that actually executes, not by declaration. A platform is Tier 1 only while its gate verdicts are exercised by the suite; if that stops being true it is demoted and the demotion is recorded. See ADR-015.

🔒 Source Code Availability & Distribution Policy

Distribution Mode: Holmes-Kit is currently distributed and executable as an official public npm package (@holmes-lab/holmes-kit).
Source Code Status: The underlying source code repository is currently private / closed-source.
Open Source Consideration: Decisions regarding whether, when, and how to transition to a full open-source codebase will be reviewed and determined in future milestones based on enterprise feedback, security audits, and community governance requirements.

📜 License

Distributed under the MIT License.