Specs first. Code second. Proof always.
Warning
This project is under active development. Breaking changes may happen between releases.
You define the what. LLMs generate the how. hlv validates the proof.
A compiled Rust binary that keeps LLM-generated code on a leash — validating every file, every milestone, every gate in seconds. Because prompts are not guarantees.
intent → artifacts → contracts → code → hlv check → proof
You paste context into chat, hope the agent understood everything, then spend days chasing inconsistencies across files you barely reviewed.
LLMs generate code fast. But without machine-checkable invariants, you're left with:
- No traceability — which requirement produced which code?
- No verification — did the LLM actually follow the spec?
- No gates — what stops broken code from advancing?
HLV separates every project into three layers with strict ownership:
| Layer | Owner | Responsibility |
|---|---|---|
| WHAT | Human | Artifacts, constraints, milestones — everything the LLM needs, expressed in declarative files |
| HOW | LLM | All code. Every line. Generated from specs, disposable, regenerated on demand |
| PROOF | hlv | Machine-checkable validation. Every field, type, constraint, and invariant verified |
Code is never the source of truth. Contracts are.
hlv is a compiled Rust binary. It doesn't call the LLM. It doesn't generate code. It makes sure LLM output matches the spec.
$ hlv check
── Contracts ──
✓ 14 contracts found, all valid
✓ acceptance criteria present on every contract
✖ contract/api-auth.md missing dependency link
── Traceability ──
✓ all code files traced to a contract
✓ no unlinked deliverables detected
── Status ──
FAILED · 29/30 passed, 1 failure
| Domain | What it checks |
|---|---|
| Project map | project.yaml structure and paths |
| Contracts | MD sections, YAML blocks, glossary refs, version alignment |
| Test specs | derived_from refs, unique IDs, gate coverage |
| Traceability | REQ → CTR → TST → GATE chains, no dangling refs |
| Plan | DAG without cycles, contract coverage |
| Code traceability | @hlv markers in code match contract rules (skipped when features.hlv_markers: false) |
| Security markers | @hlv:sec attention markers by category (skipped when features.security_markers: false) |
| LLM map | every map.yaml entry exists on disk; generated source/tests stay inside paths.llm |
| Constraints | rule IDs, severity validation |
Phase-aware: checks expected at the current phase are automatically downgraded to info. Use hlv check --strict in CI to promote warnings to errors.
| Command | What it does |
|---|---|
hlv init |
Scaffold HLV and ask for project layout, profile, and feature flags |
hlv init --adopt |
Attach HLV to an existing Laravel, Go, Node/TypeScript, Python, or Rust codebase under .hlv/ |
hlv doctor |
Preflight paths, schema compatibility, command portability, cwd values, and rendering |
hlv check |
Run the full validation suite — specs, gates, deps, coverage |
hlv index build/show/list |
Build and query the compact signature index for adopted code |
hlv explain <CODE> |
Explain a diagnostic and common fixes |
hlv waivers |
List and audit explicit expiring diagnostic waivers |
hlv milestone |
Track progress across milestones |
hlv workflow |
See where you are and what the next step is |
hlv gates |
Enforce quality gates before milestone transitions |
hlv constraints |
Define cross-cutting rules as YAML configs |
hlv dashboard |
Full TUI with 5 tabs — Status, Contracts, Plan, Gates, Questions |
hlv trace --visual |
Visualize REQ → CTR → TST → GATE chains |
hlv plan --visual |
ASCII dependency graph with critical path |
hlv task |
Task lifecycle (start/done/block/unblock) |
hlv mcp |
Start MCP server (stdio or HTTP) |
hlv workspace |
Manage MCP workspace (init/add/remove/list) |
hlv update |
Update the binary and synchronize managed project files |
All commands support --json for programmatic access.
# 1. Create milestone
$ hlv milestone new add-payments
✓ Milestone created: add-payments
# 2. Capture intent (AI-driven interview)
$ /hlv-artifacts
✓ Intent captured: 8 decisions recorded
# 3. Generate specs
$ /hlv-generate
✓ Generated: contracts, plan (4 stages), gates-policy
# 4. Resolve questions, verify, check
$ /hlv-questions && /hlv-verify && hlv check
✓ All gates passed — ready to implement
# 5. Implement stage by stage
$ /hlv-implement
◐ stage 1/4 ████████████████████ ✓ validated
stage 2/4 ████████████░░░░░░░░ implementing
# 6. Validate and ship
$ /hlv-validate
✓ All gates passed across all 4 stages
$ hlv milestone done add-payments
✓ Ready to ship.HLV is designed for Rust, Go, TypeScript strict, Kotlin, Java — languages where the compiler is another enforcement layer.
Each layer catches a different class of drift:
- Contracts catch requirement drift
- Type system catches structural drift
@hlvmarkers catch traceability drifthlv checkcatches coverage drift- Validation gates catch integration drift
The compiler doesn't care that the LLM was pretty sure. Neither does hlv.
HLV ships with opinionated defaults, but you can opt out via project.yaml:
features:
linear_architecture: true # flat module structure, no layered arch
hlv_markers: true # @hlv code traceability markers + CTR-010/CTR-001
security_markers: true # @hlv:sec security attention markers + SEC-010
legacy_mode: false # true for adopted projects with paths.code
index_tracking: ignored # ignored or tracked for .hlv/index/Greenfield marker/style booleans default to true. Adopted projects default marker enforcement to false for untouched legacy code and store observed roots in paths.code; new or changed milestone work still goes through contracts, implementation, and validation. Plain hlv init defaults the project name from the current directory, defaults owner to the project name, accepts comma-separated agent names, and asks whether to use adopt mode.
| Developer pattern | LLM problem | HLV alternative |
|---|---|---|
| Dependency Injection | Magic wiring — LLM can't see what gets injected | Direct imports, explicit construction |
| Deep directory trees | Context burn — LLM wastes tokens navigating | Flat structure, everything discoverable |
| Convention over config | Magic paths — LLM guesses file locations | Explicit config, no guessing |
| Abstract factories | Hidden code paths — LLM can't trace what runs | Direct construction, visible types |
| ORM magic | Hidden SQL — LLM generates without seeing queries | Explicit queries, typed results |
| Lots of small files | Context hops — LLM loses coherence | Fewer, larger files with clear boundaries |
The llm/ layer is designed for LLM generation: flat structure, explicit everything, direct code, errors as values, types as documentation.
Code in llm/ is optimized for one reader: the next LLM invocation. And for one validator: hlv.
| Criteria | Chat + Copilot | Autonomous agents | HLV |
|---|---|---|---|
| Spec approach | Ad-hoc prompts | Agent infers | Formal contracts with invariants |
| Who writes code | Human+AI mixed | Agent alone | LLM writes all — within verified specs |
| Verification | Manual review | Agent self-checks | Independent Rust binary |
| Context control | Entire codebase | Agent picks files | One stage at a time |
| Traceability | None | None | REQ → contract → test → gate → code |
| When LLM drifts | Hope you catch it | Hope agent catches itself | hlv check shows what diverged |
| Release criteria | "Looks good" | "Agent says done" | All mandatory gates passed |
HLV includes a built-in MCP server. Claude Code, web dashboards, and custom tools get full programmatic access to your project.
{
"mcpServers": {
"hlv": {
"command": "hlv",
"args": ["mcp", "--root", "/path/to/your/hlv-project"]
}
}
}Alternatively, set the MCP server cwd to the HLV project root and use args: ["mcp"].
# Or start SSE server for web clients
hlv mcp --transport sse --port 300012 static resources + parameterized resources + 29 tools + change notifications. See docs/MCP.md for details.
Web Dashboard example: hlv-dashboard-example — a reference implementation of the Dashboard spec built with HLV MCP.
Build your own: the docs/specs/ directory contains detailed specifications you can use to build custom integrations on top of HLV MCP.
Built-in skills drive the full development lifecycle:
| Skill | What it does |
|---|---|
/hlv-artifacts |
Interview to capture domain context, stack, and constraints |
/hlv-generate |
Generate contracts, test specs, stages, and gates |
/hlv-implement |
Implement one stage at a time with validation cycles |
/hlv-validate |
Verify code against contracts, auto-create fix tasks on failure |
/hlv-verify |
Cross-check contracts for completeness and consistency |
/hlv-questions |
Surface open questions that block progress |
Skills are installed automatically by hlv init.
If HLV feels like overkill for your current workflow, start with AI Factory — a lighter approach to working with AI agents.
macOS (Apple Silicon)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-aarch64-apple-darwin.tar.gz | sudo tar xz -C /usr/local/binmacOS (Intel)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-apple-darwin.tar.gz | sudo tar xz -C /usr/local/binLinux (x86_64)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-unknown-linux-gnu.tar.gz | sudo tar xz -C /usr/local/binLinux (aarch64)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-aarch64-unknown-linux-gnu.tar.gz | sudo tar xz -C /usr/local/binWindows (x86_64, PowerShell)
Invoke-WebRequest -Uri "https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-pc-windows-msvc.zip" -OutFile hlv.zip
Expand-Archive hlv.zip -DestinationPath "$env:USERPROFILE\bin" -ForceAdd %USERPROFILE%\bin to PATH if needed.
Build from source
git clone https://github.com/lee-to/hlv.git
cd hlv
cargo install --path .hlv update # update the binary and sync the current project
hlv update --check # check for a new version without changing files
hlv update --binary-only # update only the executable
hlv update --project-only # sync project files without network accessWhen run inside an HLV project, hlv update synchronizes the installed
version's managed files after updating the executable: agent skills under
.{agent}/skills/, HLV.md, JSON Schemas, and known YAML schema references.
This synchronization also runs when the executable is already current.
Managed skills and HLV.md are generated files and local changes to them are
overwritten. Project data such as project.yaml, milestones.yaml, contracts,
and artifacts is preserved. AGENTS.md is created only when missing and is
never overwritten. Outside an HLV project, the default command updates only the
executable; use --root <path> to target a specific project.
Then bootstrap a project:
hlv init --project my-service --owner backend-team
hlv checkmy-project/
├── project.yaml # Project configuration
├── gates-policy.yaml # Quality gates
├── map.yaml # File → contract traceability
├── human/
│ ├── glossary.yaml # Domain glossary
│ ├── artifacts/ # Global artifacts (shared)
│ │ ├── context.md
│ │ ├── stack.md
│ │ └── constraints.md
│ └── milestones/
│ └── 001/
│ ├── plan.md # Implementation plan
│ ├── stage_1.md # Stage details
│ ├── contracts/ # Formal specifications
│ └── artifacts/ # Milestone-specific context
└── milestones.yaml # Milestone & task tracking
See docs/ARCH.md for the full architecture description.
cargo build
cargo test
cargo clippy
cargo fmt --check