The Framework for the AI Agents Era
We are in the AI Agents era. The AI builds. The AI writes. And the AI fills in the gaps—often wrong.
You: "Add export to CSV"
AI: [builds a CSV export with wrong columns, wrong format, wrong permissions]
You: "No, I meant only these columns, ISO dates, admins only"
AI: [rewrites, still wrong]
You: "Still not right..." (frustration, exhaustion)
[Repeat. Many turns. Many hallucinations.]
This is the core pain point:
Why traditional artifacts fail:
| Artifact | Who Writes | Can AI Verify? | Result |
|---|---|---|---|
| PRD | Human | No | AI reads prose, guesses |
| User Story | Human | No | AI reads prose, guesses |
| Prompt | Human | No | AI reads prompt, guesses |
The problem: These artifacts were designed for humans to read and interpret. AI reads them and guesses. Guessing is hallucination. Hallucination causes many turns.
LLMs have two distinct knowledge systems:
| Parametric Knowledge | Contextual Knowledge | |
|---|---|---|
| What | Training weights — everything the model learned from the internet, books, code | The prompt — what you tell it right now |
| When created | During training (frozen) | Each conversation (live) |
| Specificity | Generalized — averaged patterns across millions of sources | Specific — your constraints, your codebase, your intent |
| Control | None — you cannot change it | Full — you decide exactly what goes in |
| Reliance | ~30% | ~70% |
Research across nine LLMs found a consistent split: models allocate ~70% reliance on contextual knowledge and ~30% on parametric knowledge. The model prefers what you tell it over what it “knows.”
So why do hallucinations happen?
When you give the AI vague prose — a PRD, a user story, a natural-language prompt — the contextual channel is underloaded. There isn’t enough specific information to answer the questions the model needs to answer during generation. The model compensates by filling gaps from parametric memory — generalized, averaged patterns from training data. Your columns, your date format, your permission model? Not in training. The model guesses from patterns it’s seen in other codebases. That guess is the hallucination.
Hallucinations aren’t AI being wrong. They’re AI using the wrong knowledge system — because you didn’t feed the right one.
The fix is not “better prompts.” The fix is saturating the contextual channel with specific, structured, verifiable information — so the model has no reason to fall back on parametric gap-filling.
That is what IVD does.
Now extend this beyond a single developer.
Every company has knowledge that does not exist in any LLM’s parametric channel: your business rules, your architecture decisions, your compliance requirements, your domain expertise. This knowledge is inherently contextual — it can only enter through the context window. There is no other path.
Generic AI tools — Copilot without project context, Zapier, Notion AI — feed generic information into the contextual channel. When company-specific gaps appear, the parametric channel fills them with averaged training-data patterns. The AI “knows” what a typical API looks like, not what your API requires.
AI capability is commoditized. Every team has access to the same models. The competitive advantage is whether you’ve structured your company’s unique knowledge so the contextual channel is loaded with your ground truth. IVD provides the structure: project_context captures architecture and conventions, organizational recipe libraries encode institutional best practices, and intent artifacts encode the specific constraints that define your system.
Companies that structure their knowledge get AI that works with their reality. Companies that don’t get AI that guesses.
The most valuable form of this knowledge is process knowledge: your decision points, escalation criteria, approval chains, compliance gates. Generic tools offer generic workflows. IVD’s recipe libraries encode your company’s actual processes — so AI executes YOUR workflows, not averaged approximations.
This kills the enterprise software tradeoff. For decades, software was either too rigid (doesn’t fit your process) or too configurable (needs a specialist army). Both problems share the same root: generic software forcing you to inject YOUR knowledge after the fact. When your business rules and processes are structured in intent artifacts, the configuration layer collapses into the contextual knowledge layer — software is born custom, and the consultant model dies.
IVD makes a fundamental shift:
The AI writes the intent artifact, not the human.
You: "Add export to CSV for admin compliance reporting"
AI: [writes structured intent artifact with constraints and tests]
You: [review] "Yes, that's what I meant" (clarification at intent stage)
AI: [implements against intent, runs tests, verifies]
You: [review code] "Done. First try."
The workflow:
0a. (Optional) Teaching: If you lack technical knowledge to understand concepts, AI creates educational artifact explaining what you need to know; you confirm understanding. Then continue. 0b. (Optional) Discovery (Experimental): If you don’t know what to ask (but understand concepts), AI proposes candidate goals or patterns (e.g. from recipes); you pick or refine. Then continue with 1–6.
Why this works:
Without IVD: Intent artifacts are just another prose document (like PRDs, user stories, prompts). AI reads prose, interprets, guesses. Many turns. Hallucinations.
With IVD: The AI writes structured intent, implements against it, verifies. Turns drop. Hallucinations are caught.
| Traditional | IVD | |
|---|---|---|
| Who writes intent | Human (PRD, user story, prompt) | AI (following IVD framework) |
| Format | Prose (unverifiable) | Structured YAML (verifiable) |
| Can AI verify? | No (AI guesses) | Yes (AI runs constraint tests) |
| Hallucinations | Discovered in review (many turns) | Caught at source (test fails) |
| Turns | Many | One (or zero) |
This is the key insight: IVD is not just another documentation format. It’s a framework where the AI writes, implements, and verifies.
Human writes requirements (PRD, user story) → Human developer implements
Worked when humans asked clarifying questions. AI doesn’t ask—it guesses.
Documentation is primary → Code extracted (tooling killed adoption)
Beautiful for human readers. AI cannot verify prose.
AI writes intent → AI implements → AI verifies → AI compounds judgment
Designed for AI agents. Structured, verifiable, executable. And — as of v3.0 — the corrections that come back from real-world use are themselves captured, codified, clustered, and fed back as context. The fourth phase (Judgment) is what turns single-run quality into compounding organizational judgment, the only kind of advantage that does not commoditize when the model layer commoditizes.
Intent artifacts create a verifiable contract that the AI writes and verifies:
# AI writes this based on human description
intent:
summary: "Export user data to CSV for admin compliance reporting"
goal: "Enable admins to download user data in compliant format"
success_criteria:
- "Only users with admin role can access the export"
- "Export includes exactly: user_id, email, created_at, last_login, status"
- "All dates in ISO 8601 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: "Output columns are exactly [user_id, email, created_at, last_login, status]"
test: "tests/test_csv_export.py::test_column_schema"
The AI verifies its own work:
test_admin_required → Pass or fixtest_column_schema → Pass or fix“Prose can be wrong silently. Executable understanding fails loudly.”
Traditional documentation:
"The system should be fast and reliable"
IVD intent:
success_criteria:
- metric: "p95 latency < 200ms"
test: "tests/perf/test_latency.py"
- metric: "99.9% uptime"
test: "tests/reliability/test_availability.py"
The AI doesn’t just claim it understood—it can prove it by running tests.
YAML/JSON Schema isn’t just a format choice. It enables:
Every intent artifact includes:
verification:
success_criteria: [...] # What success looks like
test_path: "tests/..." # Where to verify it
evidence: "metrics/..." # Proof of alignment
Drift is caught before it compounds.
Level 1: SYSTEM - Strategic vision (product/platform scope)
Level 2: WORKFLOW - Multi-step processes (sequence, 3+ modules)
Level 3: MODULE - Component architecture (single system boundary)
Level 4: TASK - Function contracts (inputs/outputs, behavior)
AI agents get the right level of context for their task—not everything, not too little.
IVD artifacts use:
Same knowledge works with:
| Step | Cost |
|---|---|
| Human explains task (ambiguous prompt) | Time + mental effort |
| AI guesses interpretation | Risk of misalignment |
| AI produces output | Wasted effort if wrong |
| Human reviews, finds misalignment | Frustration + delay |
| Human re-explains (another prompt) | More time + more effort |
| Repeat until lucky or exhausted | Compounding inefficiency |
Total cost: Multiple iterations (many turns), frustration, hallucinations
| Step | Cost |
|---|---|
| Human describes what they want (natural language) | Normal conversation |
| AI writes intent artifact (structured, verifiable) | AI’s upfront work |
| Human reviews intent: “Is this what I meant?” | Clarification before code |
| AI implements against intent + runs verification | Self-checking |
| AI verifies: “Does output satisfy intent?” | Catches hallucinations |
| If not aligned: AI fixes against known criteria | AI self-corrects |
Total cost: One turn, higher confidence, no hallucinations
We discovered the AI industry is converging on similar patterns:
| Platform | Evolution |
|---|---|
| Cursor | Evolved from .cursorrules to structured .cursor/rules/ |
| Cline | AI-editable configuration (agents improve their own instructions) |
| GitHub Copilot | Multi-level instruction hierarchy |
| Anthropic + OpenAI | Converging on Model Context Protocol (MCP) |
| Industry Standards | JSON Agents, Agent Spec, APS (agent portability) |
IVD isn’t an isolated idea—it’s aligned with where the AI collaboration space is heading.
The research conclusion:
“The industry trend is clear: structured, versioned, programmatically accessible knowledge artifacts are becoming the standard for human-AI collaboration.”
.ivd/ loadingIVD isn’t revolutionary in its parts—it’s revolutionary in its synthesis.
It combines:
Into a single coherent methodology for human-AI collaboration.
Here’s what’s remarkable: We used IVD principles to develop IVD improvements.
The process:
ivd_system_intent.yaml)That’s not just theory. That’s the system working.
The intent artifact acted as our source of truth. Both human and AI could verify:
Clarity:
Efficiency:
Control:
Context:
Verification:
Learning:
A Shared Contract:
┌─────────────────────────────────────────┐
│ INTENT ARTIFACT │
│ │
│ Human: "This is what I want and why" │
│ AI: "This is what I understood" │
│ Tests: "This proves alignment" │
│ │
│ Both can verify against same artifact │
└─────────────────────────────────────────┘
The AI Agents era has a core pain point:
AI writes structured intent, implements, verifies:
From many turns to one:
Before IVD (Many Turns):
┌────────┐ ┌────────┐ ┌────────┐
│ Prompt │ ──> │ Wrong │ ──> │ Correct│ ──> (repeat 10x)
└────────┘ └────────┘ └────────┘
With IVD (One Turn):
┌────────────┐ ┌────────────┐ ┌────────────┐
│ AI writes │ ──> │ AI verifies│ ──> │ Done │
│ intent │ │ + fixes │ │ first try │
└────────────┘ └────────────┘ └────────────┘
The framework for the AI Agents era:
It solves a real problem:
“How do humans and AI verify they understand each other?”
The answer:
It’s not just theory:
Discipline:
The question:
“Will enough people adopt the discipline of writing intent artifacts?”
The answer:
Those who do will get better outputs. Those who don’t will keep guessing.
cookbook.md (practical guide)templates/intent.yaml for your next featureTrack:
You’ve identified a legitimate pattern:
Structured intent + executable verification + universal protocol = better human-AI collaboration
It’s not the individual pieces—it’s recognizing they fit together into a verifiable communication contract.
AI capabilities will keep improving.
But alignment will always be the bottleneck.
IVD makes alignment verifiable.
That’s why it exists.
README.md - Quick start and structure overviewcookbook.md - Practical implementation guide (start here!)framework.md - Complete IVD specificationivd_system_intent.yaml - Master intent (rules for extending IVD)The first three phases — Intent, Implementation, Verification — solve “how do we get the first draft right?” The fourth phase, Judgment, solves the question that comes after the system ships:
Reality answered back. Now what?
When a domain expert says “this isn’t what we wanted,” when an audience signal flags a regression, when two real runs of the same workflow diverge — that answer-back is the most expensive signal a system has, and historically it has been thrown away. The Judgment phase makes it a first-class IVD artifact:
build | buy | hire | partner sub-types when the fix needs new capability)Why “compounds”: without structure, corrections decay (lost when someone leaves). With structure, they accumulate — and accumulated organizational judgment is precisely the moat that survives model commoditization.
Activation: opt-in per project via the .judgment/ folder at the project
root. Most projects don’t need a Judgment phase on day one; forcing it
everywhere would dilute IVD’s first three phases.
Canonical doc: judgment_layer.md. Principle: 9 (Judgment Compounds, immutable).
Governed by: ivd_system_intent.yaml
Version: 3.1
Created: January 24, 2026
Updated: April 23, 2026 (v3.0: Judgment phase + Principle 9; v3.1: Canon phase — see canon_layer.md)
Author: IVD Project
“The breakthrough isn’t making AI smarter. It’s having AI write, implement, and verify intent—so hallucinations are caught and turns drop to one.”