The next-gen approach
You define the what. LLMs generate the how. hlv validates the proof.
Specs define the rules. LLMs generate the code. A Rust binary called hlv validates every step — because prompts are not guarantees.
HLV separates every project into three layers with strict ownership. Each layer has clear inputs, clear outputs, and one owner.
Artifacts, constraints, milestones — everything the LLM needs, expressed in declarative files that are version-controlled and diffable.
human/Generated code is disposable. The LLM reads human artifacts, produces implementation, and regenerates on demand. No manual edits, no merge conflicts, no drift.
llm/Automated validators compare LLM output against human specs. Every field, type, constraint, and invariant is verified. Violations surface before code leaves the loop.
human/milestones/{id}/Code is never the source of truth. Contracts are.
hlv is a compiled Rust binary. It runs locally, validates your entire project structure against a living specification, and enforces the workflow gates that keep LLM-generated code on track.
It doesn't call the LLM. It doesn't generate code. It makes sure LLM output matches the spec — checking every file, every milestone, every gate in seconds.
$ hlv check
── Project structure ──
✓ project.yaml exists and is valid
✓ map.yaml references all source dirs
✓ milestones graph is acyclic
── Contracts ──
✓ 14 contracts found in milestones, all valid
✓ acceptance criteria present on every contract
✖ contract/api-auth.md missing dependency link
── Test specs ──
✓ 42 test specs mapped to contracts
✓ no orphan test files detected
✓ coverage above threshold (87%)
── Traceability ──
✓ all code files traced to a contract
✓ no unlinked deliverables detected
── Status ──
✓ current phase: implementing (M2)
✓ no out-of-order deliverables
── Constraints ──
✓ no duplicate rule IDs in constraints
✓ severity levels valid across 3 files
── Map ──
✓ map.yaml forward check passed
✓ map.yaml reverse check passed (no orphans)
Phase: implementing · FAILED · 29/30 passed, 1 failurehlv init
Generate the full HLV directory structure, blueprint template, and initial project map in seconds.
hlv milestone
View progress across milestones. See which deliverables are done, pending, or blocked at a glance.
hlv check
Run the full validation suite — specs, gates, dependencies, coverage thresholds, and structural integrity.
hlv workflow
See where you are in the development lifecycle and what the next required step is for your current milestone.
hlv gates
Enforce quality gates before milestone transitions. No milestone advances until every gate condition is met.
hlv constraints
Define cross-cutting rules — security, performance, observability — as YAML configs enforced by hlv check.
hlv dashboard
Full TUI with 5 tabs — Status, Contracts, Plan, Gates, Questions. File watcher with live revalidation.
hlv trace --visual
Visualize the full chain REQ → CTR → TST → GATE. See exactly which test covers which contract.
hlv plan --visual
ASCII dependency graph of tasks in the current stage. See the critical path and what can run in parallel.
Specs tell the LLM what to do. hlv catches when it doesn't.
HLV implements Spec-Driven Development for LLM-assisted delivery.
Every piece of code traces to a formal spec. Every spec traces to
human intent. The chain is unbroken — and hlv proves it.
Independent verifiability — hlv check validates the entire project structure without running a single line of code. It reads specs, not execution results. Anyone can verify, anytime.
Complete traceability — every contract links to code, every code file links back to a contract, and hlv proves the chain is complete. No trust required, only proof.
Mechanical enforcement — hlv catches missing markers, orphaned specs, and broken links without understanding your code. The spec is the source of truth, and hlv enforces it mechanically.
In HLV, you don't review LLM code line by line. You verify that the spec is right, and that the code passes the gates derived from that spec. The proof is independent of the code.
HLV is designed for Rust, Go, TypeScript strict, Kotlin, Java — languages where the compiler is another enforcement layer. An LLM generating Python can silently return the wrong type. An LLM generating Rust gets stopped by the compiler before the code ever ships.
Each layer catches a different class of drift. Contracts catch
requirement drift. The type system catches structural drift.
@hlv markers catch traceability drift. hlv check
catches coverage drift. Validation gates catch integration drift.
The compiler doesn't care that the LLM was pretty sure. Neither does hlv.
Developers build intuitions about clean code — dependency injection, factories, middleware, deep directory trees, convention-over-configuration. For humans, these patterns reduce cognitive load. For LLMs, every single one is a trap. Each pattern hides information the LLM needs to generate correct code.
llm/ layer is designed for LLM generationFlat structure. Explicit everything. Direct code. Errors as values. Types as documentation. No magic, no conventions, no hidden paths. Every file is self-contained. Every dependency is visible. Every type tells the LLM exactly what to generate.
Code in llm/ is optimized for one reader: the next LLM invocation. And for one validator: hlv.
The LLM implements one stage at a time (~30K tokens per stage), not the entire milestone. Each stage is a bounded, verifiable unit of work.
When /validate finds gate failures, FIX tasks are generated automatically. /implement executes the fixes, /validate re-runs — the loop repeats until all gates pass.
hlv check runs at every transition point — structure is validated continuously, ensuring the harness holds throughout the entire operational cycle.
Every step produces concrete, verifiable artifacts. No hand-waving, just commands and results.
Define a bounded unit of work. One command sets the scope, gates, and traceability requirements.
$ hlv milestone new add-payments✓ Milestone created: add-payments
scope: payment-processing integration
gates: specs · tests · traceability · validation
stages: 4 estimatedAn interactive interview captures what you want — first global context (domain, stack, constraints), then milestone-specific features and decisions.
$ /artifacts◐ Interview started for add-payments
── Global artifacts (shared) ──
✓ context.md exists, skipping
✓ stack.md exists, skipping
── Milestone artifacts ──
Q: Which payment provider?
A: Stripe, with fallback to manual
Q: Should failed charges retry?
A: Yes, 3 attempts with backoff
✓ Intent captured: 8 decisions recordedStructured artifacts generated from captured intent — contracts, test specs, and a full implementation file tree.
$ /generate✓ Generated artifacts:
├── contracts/payment-api.contract.yaml
├── contracts/payment-flow.contract.yaml
├── plan.md (4 stages)
├── stage_1.md .. stage_4.md
└── gates-policy.yaml
6 files · all requirements traced to artifactsSurface open questions that block progress, then cross-check generated specs for consistency and run structural validation.
$ /questions
$ /verify
$ hlv check◐ Open questions for add-payments
Q: Max retry delay for failed charges?
→ Recommended: 30s exponential backoff
A: Accepted recommendation
✓ 3/3 questions resolved
✓ Contract consistency PASSED
✓ Gates coverage check PASSED
✓ No open questions PASSED
hlv check .............. PASSED
All gates passed — ready to implementThe LLM implements against the spec, one bounded stage at a time. Drift is caught at every boundary.
$ /implement
$ hlv workflow◐ Milestone: add-payments
Phase: implementing
stage 1/4 ████████████████████ ✓ validated
stage 2/4 ████████████░░░░░░░░ implementing
stage 3/4 ○ pending
stage 4/4 ○ pending
Next: finish stage 2, then /validateThe harness holds — every stage validated before the next begins.
Final validation confirms every requirement is met, every gate passes. Ship with confidence.
$ /validate✓ Contract compliance PASSED
✓ Test specs executed PASSED (47/47)
✓ Traceability verified PASSED
✓ No regressions PASSED
All gates passed across all 4 stages$ hlv milestone done add-payments✓ Milestone complete: add-payments
4 stages · 47 tests · all gates passed
Ready to ship.Side-by-side against current approaches to AI-assisted development.
You spend more time fixing drift than writing code. Every AI-generated file needs manual review, and the inconsistencies compound faster than you can catch them.
You've reverted more agent PRs than you've merged. Without machine-checkable invariants, code review becomes a guessing game about what the LLM actually changed.
Every team reinvents the wheel with their own AI workflow. You need a repeatable, auditable process that works across squads — not another hero-developer workaround.
Compliance, audit trails, and proof chains aren't optional — they're the product. You need every requirement traceable from intent to deployed code, with machine-verified evidence at every step.
"We paste context into chat, hope the agent understood everything, then spend days chasing inconsistencies across files we barely reviewed."
"We capture intent in artifacts, formalize it in contracts, implement one stage at a time, and get machine-verified proof at every step. When the LLM drifts, hlv check catches it before we do."
HLV includes a built-in MCP server. Claude Code, web dashboards, Kanban boards, and custom tools get full programmatic access to your project data and operations — over stdio or SSE.
stdio
SSE / HTTP
stdio / SSE
Milestones, stages, and tasks rendered as cards with real-time status updates.
Monitor project health, gate results, and progress — live in the browser via SSE.
Give Claude full context: contracts, tasks, constraints, workflow phase — all via MCP resources.
Build your own tooling on top of 27 MCP tools and 12 read-only resources.
{
"mcpServers": {
"hlv": {
"command": "hlv",
"args": ["mcp"]
}
}
}# Start SSE server
$ hlv mcp --transport sse --port 3000
HLV MCP server (SSE) listening
on http://0.0.0.0:3000/mcpInstall a release binary for your platform, then run hlv check.
macOS (Apple Silicon)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-aarch64-apple-darwin.tar.gz | tar xz -C /usr/local/binhlv check
macOS (Intel)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-apple-darwin.tar.gz | tar xz -C /usr/local/binhlv check
Linux (x86_64)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-x86_64-unknown-linux-gnu.tar.gz | tar xz -C /usr/local/binhlv check
Linux (aarch64)
curl -fsSL https://github.com/lee-to/hlv/releases/latest/download/hlv-aarch64-unknown-linux-gnu.tar.gz | tar xz -C /usr/local/binhlv check
Windows (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 check
The bottleneck isn't generation speed. It's knowing that what was built matches what was intended. hlv closes that gap.