Intent-Verified Development (IVD)

Intent-Verified Development (IVD)

A framework where AI writes the intent, implements against it, and verifies — so hallucinations are caught and turns drop to one.

→ ivdframework.dev — full docs, hosted server, and access request

New here? Start with judgment_explained.md — a 5-minute, plain-English on-ramp that explains what problem the Judgment phase solves and how, before you read the spec.

---

The Problem

AI agents hallucinate not because they're bad — but because you're feeding the wrong knowledge system.

Research shows LLMs rely primarily on contextual knowledge (the prompt) over parametric knowledge (training data) — but only when the context is structured and precise (Huang et al., ICLR 2024; 9-LLM contextual vs. parametric study, 2024). When you give vague prose — a PRD, a user story, a chat message — the context channel is underloaded. The model fills the gaps from training. Those gaps are the hallucinations.

Without IVD                              With IVD

You: "Add CSV export" You: "Add CSV export for compliance" AI: [builds with wrong columns] AI: [writes intent.yaml with constraints] You: "No, these columns, ISO dates" You: "Yes, that's what I meant" AI: [rewrites, still wrong] AI: [implements, verifies against constraints] You: "Still not right..." You: "Done. First try." Many turns. Many hallucinations. One turn. Mismatches caught by the constraint check, not by you.

IVD saturates the contextual channel with structured, verifiable intent — so the model has nothing to guess.

---

Quick Start

Works locally. No API key required. Under 5 minutes.

0. See it work first (30 seconds, no setup)

git clone https://github.com/leocelis/ivd.git && cd ivd

python3 examples/intent_demo/run_demo.py

Runs offline. Shows a vague prompt producing a hallucinated implementation, then the same request run against a structured intent artifact — with the constraint check catching the mismatch before you'd ever see it. This is the core loop this README is about; everything below is how to wire it into your own agent.

1. Clone and setup

git clone https://github.com/leocelis/ivd.git

cd ivd ./mcp_server/devops/setup.sh # creates .venv, installs all deps

2. Add to your IDE

Important: command must point at the venv's Python — setup.sh installs IVD's dependencies into .venv/, not your system Python. Using "command": "python" here will fail with ModuleNotFoundError. Replace /path/to/ivd with your actual clone path.

Cursor (Settings → Features → MCP):

{

"servers": { "ivd": { "type": "stdio", "command": "/path/to/ivd/.venv/bin/python", "args": ["-m", "mcp_server.server"], "cwd": "/path/to/ivd" } } }

VS Code / GitHub Copilot (.vscode/mcp.json):

{

"mcpServers": { "ivd": { "command": "/path/to/ivd/.venv/bin/python", "args": ["-m", "mcp_server.server"], "cwd": "/path/to/ivd" } } }

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{

"mcpServers": { "ivd": { "command": "/path/to/ivd/.venv/bin/python", "args": ["-m", "mcp_server.server"], "cwd": "/path/to/ivd" } } }

A pyproject.toml now ships in the repo (pip install . or pip install -e .

gives you an ivd-mcp console command). A PyPI release (uvx ivd-mcp, no clone

required) is planned — see ROADMAP.md.

3. Use it

Ask your AI agent to use IVD tools. For example:

• *"Use ivd_get_context to learn about the IVD framework"*
• *"Use ivd_scaffold to create an intent for my user authentication module"*
• *"Use ivd_validate to check my intent artifact"*

That's it. 32 of 33 tools work immediately with zero configuration — only ivd_search needs an OPENAI_API_KEY.

4. Enable semantic search (optional)

ivd_search requires embeddings. Generate them once (~$0.01, under a minute):

export OPENAI_API_KEY=your-key

./mcp_server/devops/embed.sh

---

How It Works

1. You describe      →  what you want (natural language)

1. AI writes → structured intent artifact (YAML with constraints and tests)
2. You review → "Is this what I meant?" (clarification before code)
3. AI stress-tests → edge cases, gaps, assumptions, constraint conflicts
4. AI implements → constraint-segmented (group → implement → re-read → verify → next)
5. AI verifies → full sweep: does every constraint pass?

The key insight: clarification happens at the intent stage, not after code. The AI writes a verifiable contract, you approve it, then implementation is mechanical — and self-verifying.

If you already use spec-driven development (GitHub Spec Kit, OpenSpec), IVD adds what neither format provides by default: a test bound to each constraint. See docs/positioning.md.

---

MCP Tools

33 tools available to any MCP-compatible AI agent (19 core + 10 Judgment tools (8 added in v3.0; ivd_judgment_check_installed and ivd_judgment_resolve added in v3.1) + 4 Canon tools added in v3.1):

Core (19)

Judgment Phase (10) *— dormant unless /.judgment/ exists*

New to Judgment? Read judgment_explained.md first

— plain-English "what problem it solves and how" in 5 minutes — then the tool

table below and the runnable showcase further down will make immediate sense.

Architecture (v3.1): substance lives in the ivd/judgment/ engine package (typed @dataclass schemas; engine_version + reproducible SHA-256 hash on Pattern and InjectionResult for diffability and audit). mcp_server/tools/judgment.py is a thin facade that dispatches to the engine. Mirrors the Canon (Phase 0) architecture for symmetry. Server-level kill switch: IVD_JUDGMENT_TOOLS_ENABLED=false.

See it work. A runnable showcase walks through the full Judgment loop end-to-end — capture three real-world AI corrections, codify them, promote a Pattern, and watch the same LLM (gpt-4o-mini, temperature=0) generate different code on the same request after the Pattern enters its system message. No trust required — run it, read the terminal.

# From the ivd/ directory — runs offline, no API key required

python examples/judgment_demo/run_demo.py

Add OPENAI_API_KEY (in .env after setup) to see the live behavioral diff

OPENAI_API_KEY=sk-... python examples/judgment_demo/run_demo.py

The showcase simulates 3 weeks of an AI coding agent ignoring this project's React testing conventions across 3 different test files (PaymentForm.test.tsx, MetricsCard.test.tsx, ProfileSettings.test.tsx), feeds the 3 corrections through the 9 ivd_judgment_* tools, and writes 4 human-readable artifacts to examples/judgment_demo/output/: before.md (the agent's system message without Judgment), after.md (with the Pattern injected), diff.md (what Judgment added), and llm_responses.md (side-by-side Vitest test files with verdict).

Why this scenario: the project's testing conventions (renderWithProviders helper in src/test/test-utils.tsx, MSW server in src/test/mocks/server.ts, userEvent.setup() discipline) live ONLY in the repo. They do not exist in the LLM's training data, so a static system-prompt nudge cannot solve it — the model has to inherit the lesson from YOUR repo. That is precisely the use case Judgment is built for.

Representative result on the live LLM (gpt-4o-mini, temperature=0, n=3 trials, ~$0.001):

| injection_hash change (a