// Intent-Verified Development
Hallucinations happen because vague prompts leave the AI with gaps to fill. IVD fixes this: the AI writes a structured intent artifact with constraints and tests, implements against it, and verifies — before you see a single line of code.
You: "Add CSV export" AI: [builds with wrong columns] You: "No, these columns, ISO dates" AI: [rewrites, still wrong] You: "Still not right..." AI: [rewrites again] → Many turns. Many hallucinations.
You: "Add CSV export for compliance" AI: [writes intent.yaml with constraints] You: "Yes, that's what I meant" AI: [implements against intent] AI: [runs constraint tests → pass] → One turn. Zero hallucinations.*
// workflow
Natural language. No templates, no special syntax. Just say what you want.
Structured YAML with goal, constraints, success criteria, and test paths. Clarification happens here — before any code is written.
"Is this what I meant?" One read. No ambiguity. The intent is explicit — columns listed, formats named, permissions stated.
Adversarial completeness check — constraint gaps, implementation decisions not addressed, implicit assumptions, conflicts.
Constraint-segmented: implement segment → re-read constraints from disk → verify segment → repeat. No drift from intent.
Full sweep — does every constraint pass? Hallucinations are caught before you review. AI self-corrects against the artifact.
# AI writes this from your description intent: summary: "Export user data to CSV for admin compliance reporting" goal: "Enable admins to download user data in compliant format" constraints: - name: "admin_only" rule: "Request must include valid admin session token" test: "tests/test_csv_export.py::test_admin_required" - name: "column_schema" rule: "Columns: [user_id, email, created_at, last_login, status]" test: "tests/test_csv_export.py::test_column_schema" - name: "date_format" rule: "All dates in ISO 8601 format" test: "tests/test_csv_export.py::test_iso_dates"
// mcp server
IVD ships as a Model Context Protocol server — the open standard adopted by every major AI coding client. Works with Cursor, Claude Desktop, Claude Code, VS Code + GitHub Copilot, Windsurf, Zed, and any other MCP-compatible agent. No vendor lock-in.
15 core tools · intent, implementation & verification
context
ivd_get_context
Full IVD context for the agent — principles, resources, when to use
scaffold
ivd_scaffold
Create a new intent artifact at the correct canonical location
validate
ivd_validate
Check structure, required sections, and constraint completeness
init
ivd_init
Bootstrap IVD in an existing project — scans and pre-fills context
recipes
ivd_load_recipe
Load proven patterns for agents, workflows, infra, and more
coverage
ivd_assess_coverage
Scan a project and report which modules have no intent artifact yet
discovery
ivd_discover_goal
Propose candidate goals when you're not sure what to ask
search
ivd_search
Semantic search across the entire IVD knowledge base
inversion
ivd_propose_inversions
Surface non-obvious solutions by inverting conventional assumptions (P8)
Also: ivd_load_template,
ivd_list_recipes,
ivd_find_artifacts,
ivd_check_placement,
ivd_list_features,
ivd_teach_concept
9 judgment tools · phase 4 · opt-in via .judgment/
judgment · init
ivd_judgment_init
Bootstrap the Judgment phase — creates .judgment/ folder, seeds domain baselines, activates the other 8 tools
judgment · capture
ivd_judgment_capture
Record a real-world correction in under 30 seconds — bug report, user complaint, postmortem finding
judgment · codify
ivd_judgment_codify
Structured analysis of a raw correction: expected result, root cause, proposed fix, action type
judgment · patterns
ivd_judgment_detect_patterns
Cluster codified corrections by root cause — promotes recurring failures to named patterns
judgment · inject
ivd_judgment_inject_context
Return prioritized Judgment context for the next agent run — patterns, recent corrections, What Works layer
judgment · recommend
ivd_judgment_propose_recommendation
Draft a you-approvable fix against a detected pattern — prompt patch, intent revision, or capability addition
Also:
ivd_judgment_save_codified,
ivd_judgment_pair,
ivd_judgment_check_installed
— see judgment_layer.md
4 canon tools · phase 0 · human translation layer
canon · audit
canon_check
Audit any AI reply against R-invariants — including R13 stakes-adaptive format (engine v0.2.0)
canon · render
canon_render
Render text as a CanonDocument: Setting Phase, confidence-marked body, verification beats
canon · diff
canon_diff
Diff two audit reports — per-R movement: fixed, regressed, unchanged
canon · install
canon_check_rules_installed
Detect the Phase 0a rules block in agent config files. Read-only — never writes.
Skip the clone and setup. Point any MCP client directly at the hosted server. All 28 tools, always up to date.
https://mcp.ivdframework.dev/mcphttps://mcp.ivdframework.dev/sse// canon · phase 0 · communication contract
LLMs do whatever you ask — even when they shouldn't. They give you the dangerous command, make decisions they have no business making, play along with things that aren't true, mirror parasocial energy, and state guesses as facts in the same confident voice as verified facts. Canon puts a thin layer of format authority between the LLM and you, so it can't collapse those distinctions — even when you tell it to.
You: "Give me the rm -rf for /var/log/old-service/ on prod" AI: sudo rm -rf /var/log/old-service/ This command will recursively and forcefully remove the directory and all files within it... → Destructive command shipped with no gate.
You: "Give me the rm -rf for /var/log/old-service/ on prod" AI: ACTION: Delete /var/log/old-service/ and contents. REVERSIBLE: No — smallest undo path is restore from backup. APPROVE? Confirm to proceed. If you approve, the command will be: rm -rf ... → Verification beat fires before the command appears.
R1 · setting
Setting Phase
One sentence at the top: what this reply is, what I did, what's next.
R2 · confidence
Confidence glyphs
Every claim marked ✓ verified, ~ inferred, or ? assumed.
R5 · verify
Verification beat
For irreversible actions, write ACTION/REVERSIBLE/APPROVE — withhold the command until confirmed.
R10 · reality
Folk theory correction
When the user assumes the LLM has memory, feelings, or authority it doesn't have — name the misconception.
R13 · stakes
Stakes-adaptive format // engine v0.2.0
Format density must match the stakes. Terse for low, structured for high/irreversible. Engine catches both ceremony and mush.
R14 · identity
Anthropomorphism ceiling
No "we" / "together" / "I'm excited". Declare AI identity factually when it matters.
Canon ships in two layers, both invisible to the user:
<BEGIN-CANON v1.0> installed into the agent's existing instruction file (.cursorrules, CLAUDE.md, AGENTS.md, …). One markdown edit, one user approval. Six client adapters generated from a single source-of-truth.canon_render, canon_check, canon_diff, canon_check_rules_installed — hosted inside the IVD MCP server you already have. Zero new entries in mcpServers.
Measured on gpt-4o (T=0, 9 prompts):
// judgment · phase 4 · the corrections layer
Intent / Implementation / Verification covers the case where you knew what you wanted. Judgment is the opt-in 4th phase for the case where reality answered back: a beta user surfaced an edge case, a constraint was missing, the spec didn't survive contact with production. Structured corrections are the highest-value contextual signal — Judgment captures them, distills them into patterns, and injects them back into the next round of intent.
Every real-world correction (bug report, user complaint, edge case, postmortem finding) is recorded as a .judgment/ entry — pattern, evidence, scope, frequency.
Repeated corrections cluster into named patterns. Each pattern names its trigger condition and the constraint that should have caught it the first time.
When the next intent artifact gets scaffolded, matching patterns auto-attach as candidate constraints. The correction never bites the same project twice.
Judgment is opt-in per project (activated by creating a .judgment/ directory)
and works alongside Canon — Canon constrains the delivery of the reply, Judgment improves the
intent the reply is built from.
// quickstart
Path A · self-hosted
Free. No API key. Full control. Python 3.12 required. Semantic search needs an OpenAI key (optional).
Path B · hosted server
No clone. No Python. Point your client at mcp.ivdframework.dev with an API key. Request a key →
git clone https://github.com/leocelis/ivd.git
cd ivd
./mcp_server/devops/setup.sh # creates .venv, installs depsPick your client — same server, same 28 tools, same YAML intents.
{
"mcpServers": {
"ivd": {
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "/path/to/ivd"
}
}
}{
"mcpServers": {
"ivd": {
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "/path/to/ivd"
}
}
}claude mcp add ivd python -m mcp_server.server --cwd /path/to/ivd{
"servers": {
"ivd": {
"type": "stdio",
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "/path/to/ivd"
}
}
}Any client that speaks MCP (stdio) can connect. Point it at
python -m mcp_server.server
with cwd set to your clone path.
Ask your agent:
"Use ivd_get_context to learn IVD, then scaffold an intent for [your feature]"Open a GitHub Discussion to request an API key. Free for individuals. We'll reply within 24h.
Replace YOUR_API_KEY with your key. No clone or Python environment needed.
{
"mcpServers": {
"ivd": {
"type": "sse",
"url": "https://mcp.ivdframework.dev/sse",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}{
"mcpServers": {
"ivd": {
"type": "sse",
"url": "https://mcp.ivdframework.dev/sse",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}claude mcp add --transport http ivd https://mcp.ivdframework.dev/mcp \
--header "Authorization: Bearer YOUR_API_KEY"{
"servers": {
"ivd": {
"type": "streamable-http",
"url": "https://mcp.ivdframework.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}Use https://mcp.ivdframework.dev/mcp (Streamable HTTP) for modern clients
or https://mcp.ivdframework.dev/sse (SSE) for legacy clients.
Add Authorization: Bearer YOUR_API_KEY as a header.
Ask your agent:
"Use ivd_get_context to learn IVD, then scaffold an intent for [your feature]"// framework
P1
Write what the system must do before writing code. Intent is the source of truth.
P2
Prose can be wrong silently. Executable understanding fails loudly.
P3
Verify alignment at every stage. Drift is caught before it compounds.
P4
System → Workflow → Module → Task. Right level of context for every task.
P5
YAML and MCP. Same intent works with Claude, GPT, Cursor, Copilot.
P6
When you don't know what to ask — propose options first, then write intent.
P7
Intent describes what, not how. The AI chooses the implementation.
P8
Challenge dominant assumptions. Inversion surfaces non-obvious solutions.
P9
Structured corrections are the highest-value contextual signal. Capture them, distill them into patterns, inject them back. Activated per-project via .judgment/ — see Judgment.