Purpose: AI writes intent, implements against it, verifies, and compounds judgment from real-world corrections—for code, docs, architecture, research, and any AI-produced artifact
Status: Production Ready
Version: 3.1
Created: January 23, 2026
Updated: April 23, 2026 (Canon — Human Translation Layer added as Phase 0; 4 canon_* MCP tools; canon-rules recipe)
Updated: March 21, 2026 (Judgment phase added as IVD’s 4th phase; Principle 9 — Judgment Compounds; validation Level 5; canonization step 4.5)
📋 Framework Evolution Rules: See
ivd_system_intent.yamlfor the canonical reference on how to extend IVD. All additions to the framework must follow the 9 principles, 5 validation levels, and 6-step canonization process defined in the system intent.
Traditional Development:
Human writes requirements (PRD, user story) → Human developer implements
Worked when humans asked clarifying questions. AI doesn’t ask—it guesses.
Literate Programming (Knuth, 1984):
Write explanation → Write code matching it → Tools verify format
Beautiful for human readers. AI cannot verify prose.
AI-Assisted Development (Current Default):
Human writes prompt → AI guesses intent → Builds wrong → Many turns of correction
The many-turns and hallucinations problem.
Intent-Verified Development (AI Agents Era):
Human describes → AI writes intent → Human reviews → AI stress-tests → AI implements → AI verifies → Done first try
The AI writes the intent, implements against it, catches its own hallucinations.
IVD works not just because structured artifacts are “better” — it works because of how LLMs process information at a fundamental level.
LLMs have two distinct knowledge systems. Parametric knowledge is encoded in the model’s weights during training — generalized, frozen, and shared across all users and tasks. Contextual knowledge is what’s in the current prompt and context window — specific, current, and fully controllable. Research across nine LLMs found that models allocate approximately 70% reliance on contextual knowledge and 30% on parametric knowledge when generating responses, regardless of context size.
When you give an AI agent vague prose (a PRD, a user story, a natural-language prompt), the contextual channel is underloaded. The model compensates by filling gaps from parametric memory — which encodes averaged patterns from training data, not your specific constraints. That gap-filling produces two distinct failure modes: hallucination (factually wrong output) and homogenization (factually acceptable but generically averaged output). For code, homogenization is largely invisible — correct code is correct code. For creative work, documentation, marketing copy, and narrative artifacts, homogenization is the primary failure mode: the output isn’t wrong, it’s indistinguishable from every other LLM output on the same prompt. The problem is not the AI. The problem is that prose doesn’t load the contextual channel with enough specificity to prevent parametric gap-filling.
A structured intent artifact — with explicit constraints, test paths, scope boundaries, and rationale — saturates the contextual channel. A constraint like p95 latency < 200ms linked to tests/perf/test_latency.py has near-zero interpretive entropy. The model cannot guess; it can only match or fail. That is why executable understanding fails loudly.
The lost-in-the-middle effect explains why the verification protocol’s Step 1 (“re-read the intent from disk”) is not a best practice — it is a cognitive necessity. Research shows that LLMs degrade in accuracy for information positioned in the middle of long contexts, even in strong models. The effective context window can differ from the advertised limit by up to 99%. Re-reading the intent artifact before verification repositions the ground truth at the top of the context stack, where the attention mechanism weights it highest.
“Hallucinations aren’t AI being wrong. They’re AI using the wrong knowledge system — because you didn’t feed the right one.”
The cognitive mechanism above explains how IVD works at the individual developer level. But the strategic implication is larger.
Every company has knowledge that does not exist in any LLM’s parametric channel — and never will. Your business rules, your architecture decisions, your compliance requirements, your domain expertise, your internal APIs. 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, ChatGPT with a pasted prompt, Zapier automations, Notion AI — feed generic context. When company-specific gaps appear, the parametric channel fills them with averaged patterns from training data. The AI “knows” what a typical permission model looks like, not what your permission model requires. That delta between typical and yours is the hallucination.
AI capability is commoditized. Every team has access to the same models. The competitive advantage is not the model — it’s whether you’ve structured your company’s unique knowledge so the contextual channel is loaded with your ground truth instead of generic approximations. IVD is the framework for doing exactly that: project_context sections capture architecture and code rules, organizational recipe libraries encode institutional best practices, and intent artifacts encode the specific constraints and verification criteria that define your system.
Companies that structure their knowledge with IVD get AI that works with their reality. Companies that don’t get AI that guesses — faster, but still wrong.
Of all company-specific knowledge, process knowledge is the most operationally valuable: your decision points, escalation criteria, approval chains, and compliance gates — the workflows that define how your company actually operates. Generic tools offer generic workflows. IVD’s organizational recipe libraries encode your company’s actual processes so AI agents execute your workflows correctly, not an averaged approximation of how things “typically” work.
This has a deeper implication for how software is built and bought. Enterprise software has been stuck in a false dichotomy for decades: too rigid (the tool doesn’t fit your process) or too configurable (you need a specialist army to make it fit). Both options share the same root problem — software built with generic knowledge, with you paying the cost to inject YOUR knowledge after the fact. When business rules and processes are structured in intent artifacts, the configuration layer collapses into the contextual knowledge layer. AI builds software that’s custom from day one. The Salesforce admin, the SAP consultant, the ServiceNow specialist — these roles exist because injecting company-specific knowledge into generic platforms is hard. When the knowledge is already structured, the injection cost approaches zero.
Not code. Not documentation. Not prompts. Structured intent.
HUMAN DESCRIBES (natural language)
↓
AI WRITES INTENT (structured YAML)
↓
┌───────────────────────────────────┐
│ AI Produces: │
│ • Implementation (code, docs, etc.)│
│ • Tests (verification) │
│ • Documentation (explanation) │
└───────────────────────────────────┘
↓
AI VERIFIES: Does output match intent constraints?
Scope: Code, architecture, documentation, research, books, processes—any AI-produced artifact.
Why:
Prose documentation can be wrong. Executable understanding fails loudly.
Traditional:
def qualify_lead(score: float) -> bool:
"""Returns True if score >= 0.70"""
return score >= 0.70
Intent-Verified:
@intent("Qualify leads with score >= 0.70")
@constraint("precision >= 0.80")
@constraint("recall >= 0.60")
@validates_with("tests/test_lead_qualification.py")
def qualify_lead(score: float) -> bool:
return score >= 0.70
The decorators are executable:
@intent declares what this should do@constraint declares what must hold true@validates_with links to tests that verifySystem can check: Do tests verify the constraints? Does implementation match intent?
The code example above shows the canonical form for a technical constraint. But Principle 2 applies to every artifact type IVD covers — code, architecture, documentation, research, books, marketing copy. For non-technical artifacts, the form of an executable constraint differs. The next two subsections define how.
Not all constraints are equal in their verifiability. Constraints exist on a spectrum of interpretive entropy — how much interpretive space remains between the constraint and its verification.
The spectrum (research grounding: CMU 2025 underspecification study; UltraBench 2025; DETAIL 2024):
Near-zero entropy ────────────────────────────────────────────────── High entropy
│ p95 latency < 200ms │ tone: melancholic │ write well │
│ precision >= 0.80 │ length: 1,200–1,400 words │ be creative │
│ test: tests/perf/latency.py │ structure: three-act │ sound natural │
└──────────────────────────── └────────────────────────────── └──────────────┘
Binary pass/fail Qualitative + measurable Pure prose
Model cannot guess Model can evaluate Model averages
Why entropy matters: A constraint like p95 latency < 200ms has near-zero interpretive entropy — the model cannot guess; it can only match or fail. A constraint like “write well” has near-total entropy — the model fills it from parametric averaged patterns, producing output that is statistically indistinguishable from other LLM outputs (what research calls creative homogenization). The 2025 study “We’re Different, We’re the Same” found LLM outputs are significantly more similar to each other than human outputs are to each other, even across models from different organizations — direct evidence that high-entropy prompts trigger parametric averaging.
Constraint design rules by artifact type:
For code and technical artifacts — target near-zero entropy. Every constraint must be binary and testable:
- name: "latency"
requirement: "p95 < 200ms"
test: "tests/perf/test_latency.py::test_p95"
entropy: "near-zero"
For creative, narrative, and documentary artifacts — decompose into the lowest-entropy constraints you can construct. Qualitative constraints are acceptable when they include measurable proxies:
- name: "tone"
requirement: "melancholic but not sentimental — no emotional resolution in final paragraph; protagonist does not cry"
test: "human review against checklist: does final paragraph resolve? does protagonist cry?"
entropy: "low-qualitative"
proxy_measurable: true
- name: "length"
requirement: "1,200–1,400 words"
test: "wc -w output | awk '$1 >= 1200 && $1 <= 1400'"
entropy: "near-zero"
- name: "structure"
requirement: "exactly three scenes, each set in a different room; no flashbacks"
test: "human review: count scene breaks, verify settings, check for temporal reversals"
entropy: "low-qualitative"
The key insight for non-code artifacts: Constraints that feel “creative” are often decomposable into near-zero-entropy sub-constraints. “Write a compelling story” is pure entropy. “1,400 words, three scenes, first person, present tense, melancholic protagonist, no dialogue in final scene” is six near-zero or low-qualitative constraints. The CS4 benchmark (2024) demonstrated this directly: increasing prompt constraint specificity measurably improves creative output quality and reduces reliance on parametric averaging.
conflict_prone ConstraintsSome constraints encode idiosyncratic business logic that contradicts the model’s typical training prior. Research on knowledge conflict (arXiv 2409.08435) shows models often ignore loaded context and fall back on the parametric prior exactly when the rule is unusual — IVD’s value proposition and its weak spot.
Manual flag only: set conflict_prone: true on a constraint during the Rule 4 stress test when the rule is unusual for the domain. ivd_validate never auto-detects conflict-prone constraints — detecting “conflicts with the model’s prior” is high interpretive entropy (Rule 6).
Requirements when conflict_prone: true:
test_provenance: execution_derived with an execution_oracle block (golden fixture, property test, or differential test)anti_pattern naming the common pattern and why this system requires NOT-itanti_pattern text into the active implementation context — YAML storage alone is insufficientivd_validate emits verification_gating.conflict_prone when execution-derived evidence or anchors are missing (report-only; never an error).
ivd_validate and ivd_review_intent emit an optional top-level client_enforcement block when implementation must not be marked complete:
implementation_complete_blocked: true — external monitors or IDE hooks should treat this as a hard stopactive_gates — machine-readable gate ids (e.g. UNVERIFIED, joint_satisfaction:MISSING_JOINT_TEST, PENDING_SIGNOFF)monitoring_event — verification_gating_active or review_gate_pending_signoffThis is report-only on the server — same as verification_gating. Clients (Cursor hooks, CI scripts, custom agent loops) consume the signal. Re-run ivd_validate after clearing conditions; when gating is absent, client_enforcement is omitted.
Opt-in test runner: ivd_run_constraint_tests runs allowlisted pytest nodes from the intent when IVD_TEST_RUNNER_ENABLED=true (default false on public MCP servers). It never runs inside ivd_validate.
A critical failure mode that IVD’s original constraint model did not address: constraints can conflict, and LLMs fail disproportionately when all constraints must be satisfied simultaneously.
Research grounding (UltraBench 2025, multi-dimensional constraint framework 2025): Models exceed 70% accuracy on individual constraints but fail when satisfying all constraints at once. The UltraBench study found position bias — models prioritize constraints appearing later in the prompt list — causing earlier constraints to be silently violated. The CMU underspecification study found constraint sets where even explicit specification produced 20%+ accuracy drops from this interaction effect.
This changes how intents must be written. Before finalizing constraints, the stress test (Principle 6, Step 4) must now include a fourth probe:
Probe 4 — Constraint conflict check: “Do any two constraints in this intent conflict? Is it possible to satisfy all constraints simultaneously? Are any constraints likely to be violated due to position bias (appearing early in a long list while later constraints dominate)?”
Practical rules:
constraints:
# Order: less critical first, most critical last (position-bias mitigation)
- name: "word_count"
requirement: "1,200–1,400 words"
test: "wc -w"
priority: 3
- name: "structure"
requirement: "three scenes, different rooms, no flashbacks"
test: "human checklist"
priority: 2
- name: "tone"
requirement: "melancholic, no resolution, no tears"
test: "human checklist"
priority: 1 # highest priority; declared last for position-bias
constraint_satisfiability:
conflicts_checked: true
known_tensions:
- between: ["word_count", "structure"]
resolution: "If three full scenes require > 1,400 words, reduce non-scene material (transitions, descriptions), not scenes"
simultaneous_satisfaction: "All constraints satisfiable with known tensions resolved above"
One-way flow (Knuth): Literate source → tangled code + woven docs
Bidirectional (IVD): Any change propagates to others, with verification
INTENT
↗ ↑ ↖
/ | \
↓ | ↓
CODE ←→ | ←→ DOCS
↓ | ↓
\ | /
↘ ↓ ↙
VERIFICATION
When threshold changes from 0.70 to 0.75:
Bidirectional sync handles code drift — you changed the code, now update the intent. But there is a second, equally important direction: reality contradicts the intent’s assumptions.
This happens constantly during LLM workflow development. Your research says the model should return confidence scores between 0 and 1 — but the actual API returns logits. Your intent assumes p95 latency under 200ms — but the real service has a 500ms cold start. Your constraint says classification accuracy >= 85% — but empirical testing shows 72% on your actual data. The intent was written from research; reality is different.
This is not a code bug. This is new contextual knowledge that the intent didn’t have at write time. The intent’s assumptions were based on parametric-level information (general knowledge, documentation, research). Implementation revealed empirical evidence that changes what the intent should say.
The Empirical Refinement Protocol:
ENRICH — If the discovery reveals a knowledge gap, pull more contextual knowledge into the session. Not all sources are equal. Use the highest-signal source available for the problem type:
Source hierarchy for code failures (ranked by signal):
Iterating without enrichment — making repeated implementation attempts using only the model’s parametric knowledge — is drawing from the same well that already produced the wrong answer. Each attempt is a parametric variation of the same incorrect pattern.
The 2-attempt trigger rule: If the same error or failure pattern persists after two implementation attempts without new external data, STOP and ENRICH before attempting again. Two attempts establish that the parametric channel doesn’t have the answer. Further attempts without new contextual knowledge are wasted turns.
If the discovery changes the scope significantly (what was a simple API call now requires retry logic, circuit breakers, and fallback handling), flag for human review before continuing.
Why this matters through the cognitive lens: The intent artifact is the spine of contextual knowledge. When it contains assumptions instead of empirical facts, the model fills gaps between those assumptions and reality using parametric knowledge — exactly the gap-filling mechanism that causes hallucinations. Empirical refinement replaces assumptions with observed behavior, strengthening the contextual channel at the exact point where it was weakest. The source hierarchy exists because not all contextual knowledge is equal — a GitHub issue with a confirmed fix is higher signal than documentation that may not cover the edge case, which is higher signal than parametric recall that already failed.
The stress test (Step 4) anticipates. Empirical refinement discovers. Together, they close the loop: the stress test catches what you can reason about before building; empirical refinement catches what only running the code reveals.
Static docs become stale on day 2. Verify continuously.
$ ivd verify lead_qualifier
Checking: agent/lead_qualifier/
✅ Intent artifact found: lead_qualifier_intent.yaml
✅ Implementation matches intent: threshold = 0.70
✅ Constraints satisfied:
- precision = 0.85 (>= 0.80) ✓
- recall = 0.70 (>= 0.60) ✓
✅ Evidence is current: playground/lead_analysis_2025-12.ipynb (recently run)
✅ Tests passing: 12/12 ✓
⚠️ Risk alert: precision at 0.82, approaching minimum threshold
UNDERSTANDING VERIFIED ✓
Every PR, every deploy, every change: Verify understanding still matches reality.
Principle 4 says verify continuously, but what does that concretely mean for an AI agent that just implemented code from an intent artifact? The Post-Implementation Verification Protocol is the prescribed 4-step audit that every AI agent must execute after any implementation derived from an intent artifact:
Re-read the literal intent — Open and re-read the intent artifact from disk. Do not rely on memory or context from earlier in the conversation. The intent may have been updated, or the agent’s memory may have drifted during a long session.
Diff each change against constraints — For every change made during implementation, check: does this change satisfy, violate, or not affect each constraint in the intent artifact? List each constraint and its status.
Check verification criteria — For each constraint that has a test field, verify: does the test path exist? Can the test be run? Does the implementation pass the test? If the test can’t be run (e.g., manual review), note what a reviewer should check.
Report results — Produce a structured report: for each constraint, PASS / FAIL / NEEDS_REVIEW. Do not declare implementation complete until all constraints are PASS or explicitly acknowledged as NEEDS_REVIEW with justification.
When constraint-segmented implementation (Step 5) was used: The protocol functions as a cross-cutting final sweep. Per-constraint compliance was already established at the segment level during implementation. The sweep’s value is catching inter-constraint gaps — situations where satisfying one segment’s constraints introduced a violation in another.
When single-pass implementation was used (1–2 constraints): The protocol is the primary verification mechanism. Re-reading from disk (Step 1) is especially critical here — it counteracts the lost-in-the-middle effect by repositioning intent at the top of the attention window.
Without this protocol, the IVD loop is broken: Intent exists → Implementation exists → But no verification connects them. The intent becomes decoration, not a contract.
See: recipes/agent-rules-ivd.yaml for the concrete agent instruction rules that enforce this protocol in .cursorrules, .clinerules, Copilot instructions, or any AI agent configuration file.
Not just “WHY” - multiple layers, each verifiable:
Layer 1: INTENT
"Qualify high-probability leads for sales team"
→ Executable as: acceptance criteria, business metrics
Layer 2: CONSTRAINTS
"Must maintain precision >= 0.80 and recall >= 0.60"
→ Executable as: property-based tests, invariants
Layer 3: RATIONALE
"0.70 threshold chosen based on Dec 2025 experiment"
→ Executable as: link to notebook that can be re-run
Layer 4: ALTERNATIVES
"Considered 0.60 (rejected: too many false positives) and 0.80 (rejected: insufficient volume)"
→ Executable as: comparison experiments still runnable
Layer 5: RISKS
"If precision drops below 0.75, sales quality suffers"
→ Executable as: monitoring alerts, rollback triggers
Each layer is verifiable, not just readable.
The AI writes the intent, implements against it, and verifies—not just syncs.
This is the key principle for the AI Agents era:
You: "Add export to CSV for admin compliance reporting"
AI: "I'll write the intent artifact first."
[Writes structured YAML with constraints and tests]
AI: "Here's the intent I wrote:
- Summary: Export user data to CSV for admin compliance
- Constraints: admin_only, column_schema, date_format, performance
- Tests: test_admin_required, test_column_schema, etc.
Does this capture what you meant?"
You: "Yes, exactly."
AI: [Implements against intent, runs tests, all pass]
"Done. All constraints verified."
The workflow:
Why this matters: Clarification at intent stage, not after code. Turns drop to one.
After the human approves the intent and before implementation begins, the AI adversarially probes its own intent artifact for completeness. This catches gaps that are cheaper to fix in intent than in code.
The stress test checks four dimensions:
If the stress test reveals gaps, the AI updates the intent (adds constraints, test paths, or clarifying notes) before implementing. The human may re-review if the changes are significant.
Why this step exists: Intent captures what you know at the time of writing. Implementation forces decisions the intent didn’t anticipate. The stress test is a structured way to anticipate those decisions before they become implementation rework. It’s Principle 2 (Understanding Must Be Executable) applied reflexively — the AI checks whether its own understanding is complete before acting on it. The fourth probe (constraint satisfiability) prevents the especially costly failure mode where all individual constraints are well-formed but the set as a whole is impossible to satisfy simultaneously.
When to skip: Trivial changes where the intent is a single constraint with an obvious implementation. The stress test adds value proportional to the complexity of the intent.
After the stress test and before the final verification sweep, implementation itself must account for a documented architectural limitation of transformer-based LLMs: constraint compliance degrades during long generation spans.
The research basis:
The problem is structural, not a model quality issue:
The protocol:
For intents with 3+ constraints, do not implement in a single pass. Use constraint segments:
CONSTRAINT-SEGMENTED IMPLEMENTATION:
1. GROUP — After the stress test, group constraints into implementation
segments by functional area. Example groups:
- Input validation constraints
- Core logic / output constraints
- Performance / latency constraints
- Error handling constraints
2. IMPLEMENT one segment
3. RE-READ the constraints for that segment from the intent artifact
(not from memory — counter lost-in-the-middle)
4. VERIFY the segment satisfies its constraints before proceeding
5. NEXT SEGMENT — repeat steps 2–4
6. CROSS-CUT — after all segments, run the full Post-Implementation
Verification Protocol as a final sweep for inter-constraint gaps
Why re-reading after each segment works: Each re-read repositions the constraint text at the top of the context stack, where the transformer’s attention mechanism weights it highest. This converts one long generation (where early constraints fade into low-attention middle positions) into multiple short generations, each starting with fresh constraint attention. The cognitive necessity of re-reading intent from disk (established for Verification Protocol Step 1) applies equally here — not as a best practice, but as a structural requirement.
When to skip: Intents with 1–2 constraints where a single implementation pass is trivially verifiable. The segmented approach adds value proportional to constraint count. Below 3 constraints, the overhead exceeds the benefit.
What this changes about post-implementation verification: When constraint-segmented implementation was used, the Post-Implementation Verification Protocol (Principle 4) functions as a cross-cutting final sweep — most per-constraint compliance is already established at the segment level. The sweep’s primary value shifts to catching inter-constraint gaps and verifying that segment-level fixes didn’t introduce cross-segment violations.
Sometimes the user lacks the technical knowledge to understand domain concepts, patterns, or technologies needed for the task. They can’t review intent if they don’t understand what “ETL,” “Saga pattern,” or “CDC” means. They can’t evaluate discovery options if the terminology is unfamiliar.
This is the critical bottleneck: Lack of technical knowledge blocks the entire IVD flow before it can even start.
When to use: User says “I don’t know what X is,” user can’t evaluate discovery options because they don’t understand the terms, reverse engineering (AI writes intent from existing code but user can’t review patterns they haven’t seen), or user is new to domain/codebase.
Pattern (Step 0a):
Example: User needs ETL but doesn’t know what ETL is → AI creates educational artifact explaining Extract/Transform/Load, batch vs streaming, incremental vs full refresh, with verification questions → user understands → then discovery (which ETL pattern?) → describe → intent.
Tools: Use ivd_teach_concept to create educational artifact. Recipe: recipes/teaching-before-intent.yaml.
For reverse engineering: When AI writes intent from existing code, add an optional education section to the intent itself so the user learns domain patterns while reviewing.
This is Principle 6 (AI as understanding partner): the AI helps the user gain the knowledge they need before they can participate in the IVD flow.
Sometimes the user doesn’t have enough knowledge to give clear instructions or know what to ask—new to the domain, unfamiliar with the codebase, or unsure of the goal. IVD still applies: use an optional discovery step before “Human describes.”
Status: Experimental — This pattern is being validated. Use it and report results to help promote it to canonical.
When to use: User says “I’m not sure what we need,” or the problem is in a new domain, or the user is exploring.
Pattern:
Tools: Use ivd_discover_goal (or list recipes + list features) to gather options; then proceed to intent writing. Recipe: recipes/discovery-before-intent.yaml.
This is still Principle 6 (AI as understanding partner)—the AI helps the user form intent when they can’t yet articulate it.
Before formal constraint tests, you can detect misalignment through linguistic mirroring.
The pattern: When the AI echoes your key terms in its response, it signals alignment. When it substitutes different terminology, it signals potential misalignment.
✅ ALIGNED (AI echoes key terms):
Human: "Add admin compliance CSV export with ISO dates"
AI: "I'll write the intent for the admin compliance CSV export.
Constraints: admin_only, ISO 8601 date format..."
❌ MISALIGNED (AI substitutes terms):
Human: "Add admin compliance CSV export with ISO dates"
AI: "I'll create a data dump feature for users..."
Why this works: The AI’s choice of vocabulary reveals its internal understanding. If it understood “admin compliance”, it will use those words. If it generalized to “users” or “data dump”, it filled a gap incorrectly.
When to use:
This is not a replacement for verification. It’s an early signal. Formal constraint tests (Principle 2) are still required.
When multiple agents collaborate, Principle 6 applies at every level:
Human describes
↓
Coordinator AI writes COORDINATOR INTENT
├─→ What agents to route to
├─→ What each should accomplish
└─→ How to synthesize results
↓
For each agent, Coordinator writes AGENT INTENT
├─→ Specific task
├─→ Constraints
└─→ Verification criteria
↓
Each Agent stress-tests its intent (edge cases, missing constraints)
↓
Each Agent implements against its intent
↓
Each Agent verifies its output
↓
Coordinator synthesizes verified results
The key insight: Intent doesn’t stop at the coordinator. The coordinator produces intent artifacts for each specialist agent. This prevents “coordination errors” where the coordinator routes correctly but passes wrong parameters.
Core principle: Tools are truth, history is context. The coordinator uses tools to verify current state—never assumes from chat history.
Routing Surface: In LLM-based multi-agent systems, the coordinator decides which agent to call based on description strings it reads at runtime — AGENT_DESCRIPTION, COORDINATOR_INSTRUCTIONS, tool descriptions, or equivalent. This description is the routing surface: the actual integration contract between coordinator and agent. IVD captures this surface in the agent’s intent via the optional interface.routing sub-field (description, keywords, consumed_by), making it verifiable. When agent capabilities change (new tools, modified behavior), the routing surface must update — or the coordinator can’t route to the new capability. See the agent-capability-propagation recipe for the bottom-up propagation pattern (agent changes → coordinator routing update), which complements the top-down coordinator-intent-propagation recipe.
Recipes:
recipes/coordinator-intent-propagation.yaml (top-down: coordinator → agents at runtime)recipes/agent-capability-propagation.yaml (bottom-up: agent changes → coordinator routing)Implementation changes. Languages change. Intent persists.
# lead_qualifier_intent.yaml v3
intent:
goal: "Qualify high-probability leads for sales team"
success_metric: "Sales conversion rate >= 15%"
constraints:
- precision >= 0.80
- recall >= 0.60
implementation_history:
- version: 1
language: Python
approach: "Rule-based thresholds"
deprecated: "2025-11-01"
reason: "Too brittle for changing data"
- version: 2
language: Python
approach: "ML classifier"
deprecated: "2025-12-15"
reason: "Overfitting, poor generalization"
- version: 3 (current)
language: Python
approach: "Statistical threshold with data quality gate"
file: "agent/lead_qualifier/scoring.py"
rationale:
decision: "threshold = 0.70"
evidence: "playground/lead_analysis_2025-12.ipynb"
stakeholder: "VP Sales, approved 2025-12-15"
When you rewrite in Go, or replace with vendor service, intent transfers.
Innovation comes from inverting dominant beliefs—state the default, invert it, evaluate, implement.
The conventional way to solve a problem is often a “dominant belief.” By explicitly stating the default and considering the opposite approach, we surface non-obvious solutions. IVD supports this with:
inversion_opportunities) and verify.| Intent artifacts can include an optional inversion_opportunities block: problem, dominant belief(s), and proposed inversions with rationale and status (chosen | rejected | deferred). Use the ivd_propose_inversions MCP tool to brainstorm inversions; then document chosen/rejected ones in the intent. |
When to use Principle 8:
Corrections from real-world use, when captured, codified, and structured into patterns, are the most valuable form of contextual knowledge a system has — and the only knowledge that does not commoditize when the model layer commoditizes.
Principles 1-8 cover the cost of getting intent right the first time (hallucinations, drift, missed constraints). Principle 9 covers what happens after the system ships and reality answers back: “this is not what we wanted.” That answer-back is the most expensive signal a system has; historically it has been thrown away or stored as scattered prompt edits and retro notes.
The Judgment phase (IVD’s 4th phase, see Judgment Phase below) makes the answer-back a first-class IVD activity:
diagnosed_cause, weighted by your domain_depth)build | buy | hire | partner sub-types when the fix is a capability_addition)Why “compounds”: each captured correction increases the value of the next run. 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 via the .judgment/ folder at the project root. All
9 ivd_judgment_* MCP tools are dormant unless the folder exists. (The single
exception is ivd_judgment_check_installed, added in v3.1, which is read-only
and reports activation state without writing to disk so agents can offer the
init payload to the user.) A server-level kill switch
(IVD_JUDGMENT_TOOLS_ENABLED=false) lets operators disable the entire phase
without de-registering the tools — mirrors IVD_CANON_TOOLS_ENABLED.
When to use Principle 9:
See it work. A runnable showcase under examples/judgment_demo/ walks the full loop in ~5 seconds (capture × 3 → codify × 3 → detect → inject) and demonstrates the agent generating a completely different test file on the same request after Judgment compounds — adopting the project’s local testing conventions (renderWithProviders, MSW handlers, userEvent.setup()) that cannot have come from the LLM’s training data. This is the canonical Judgment use case for AI coding agent users: project-specific conventions that no static system-prompt nudge can teach, only repo-derived Patterns can. Offline mode uses outputs literally captured from gpt-4o-mini at temperature=0; with an OPENAI_API_KEY it makes a real LLM call (~$0.001) and shows the live behavioral diff:
python examples/judgment_demo/run_demo.py
Canonical doc: judgment_layer.md. Decision records:
DECISIONS.md FDR-015 (bundling rationale), FDR-016 (v3.0 bump rationale).
A structured, version-controlled file that declares:
Format: YAML (structured, readable, diffable, version-controllable)
# {module}_intent.yaml
# Reference parent intent (for workflow/module/task that's part of larger system)
# Recommended for all non-system intents to establish hierarchy
parent_intent: "../../system_intent.yaml" # Relative path to parent
# Examples:
# Task → Module: "../{module}_intent.yaml"
# Module → Workflow: "../../workflows/{workflow}_intent.yaml"
# Module → System: "../../system_intent.yaml"
# Workflow → System: "../system_intent.yaml"
# WHAT should this do?
intent:
summary: "One-line description"
goal: "Detailed explanation of purpose"
success_metric: "How to measure success"
stakeholders: ["Who cares about this"]
# OPTIONAL: Project context (SYSTEM-LEVEL ONLY - for existing projects)
# project_context:
# code_rules: [{path, description}] # .cursorrules, lint configs
# architecture: [{path, description}] # ARCHITECTURE.md, ADRs, principles
# tools_scripts: [{path, description}] # Key scripts, CLIs, utilities
# libraries_reuse: [{library, when_to_use}] # Shared internal libraries
# key_paths: # "Map to the stars"
# entrypoints: [{path, description}] # API main, worker entry
# modules: [{path, description}] # agent/, entity/, integrations/
# workflows: [{path, description}] # workflows/
# docs: [{path, description}] # docs/, runbooks/
# tests: [{path, description}] # tests/
# existing_docs: [{path, description}] # README, API.md, CONTRIBUTING
# OPTIONAL: Feature inventory (large projects - avoid duplication)
# metadata:
# feature_id: "csv_export" # Stable, unique slug (lowercase, snake_case)
# category: "data_export" # Group for filtering (auth, reporting, api)
# tags: ["admin", "compliance"] # Searchable keywords
# status: "implemented" # implemented | planned | deprecated
# introduced_version: "1.2.0" # Optional
# deprecated_version: null # Optional (if status: deprecated)
# OPTIONAL: Innovation through Inversion (Principle 8)
# inversion_opportunities:
# problem: "e.g., CSV processing for large files"
# dominant_belief: "Load entire file into memory, then parse"
# proposed_inversions:
# - name: "Stream rows, never load file"
# description: "Process row-by-row"
# rationale: "Better for large files; no random access"
# status: "chosen" # chosen | rejected | deferred
# OPTIONAL: Field Mapping (for data-heavy intents)
# field_mapping:
# summary: "Brief description of what data is being mapped"
# sources:
# - system: "source_system_name"
# type: "database | api | file"
# location: "table or endpoint"
# targets:
# - system: "target_system_name"
# type: "database | api | file"
# location: "table or endpoint"
# mappings:
# - source_field: "source.field"
# target_field: "target.field"
# transformation: "description"
# required: true
# verification:
# schema_validation:
# - check: "fields exist in schemas"
# test: "path/to/test"
#
# Use this section for:
# - API integrations (CRM, payment, external services)
# - ETL pipelines and data synchronization
# - Data import/export features
# See: recipes/data-field-mapping.yaml for complete pattern
# WHAT must hold true?
constraints:
- name: "constraint_id"
requirement: "precision >= 0.80"
test: "path/to/test.py::test_name"
consequence_if_violated: "What breaks if this fails"
# OPTIONAL: set when constraints above were drafted from an external spec
# artifact (e.g. a GitHub Spec Kit or OpenSpec spec.md) via ivd_import_spec,
# rather than from a human description.
# imported_from:
# tool: "spec-kit" # "spec-kit" | "openspec"
# source_path: "specs/001-feature-name/spec.md"
# WHY this approach?
rationale:
decision: "Key decision made"
evidence: "Link to validation (notebook, doc, etc.)"
date: "2026-01-23"
stakeholder: "Who approved this"
# WHY NOT alternatives?
alternatives:
- name: "alternative_approach"
rejected_because: "Reason"
experiment: "path/to/comparison"
date_tested: "2026-01-15"
# WHAT could go wrong?
risks:
- condition: "When does this become a problem?"
action: "What should happen?"
monitor: "Where to watch for this"
severity: "high|medium|low"
# WHERE is this implemented?
implementation:
current: "path/to/file.py"
version: 3
tests: "path/to/tests/"
documentation: "path/to/docs.md"
# WHEN was this changed?
changelog:
- version: 3
date: "2026-01-23"
change: "Updated threshold from 0.65 to 0.70"
reason: "Precision was too low"
evidence: "playground/threshold_tuning_2026-01.ipynb"
project/
├── agent/
│ ├── lead_qualifier/
│ │ ├── scoring.py # Implementation
│ │ ├── scoring_intent.yaml # ← Intent artifact
│ │ └── tests/ # Verification
├── playground/
│ └── lead_analysis_2025-12.ipynb # Evidence
└── docs/
└── agents/
└── lead_qualifier_DESIGN.md # Generated from intent
Intent artifact lives alongside implementation, not in separate docs folder.
IVD is not just for code. Any artifact produced by AI should have its paired intent—its point of origin, its original intention.
The framework supports intent artifacts for:
Core principle: If AI produced it, it should have verifiable intent.
Documentation plays two roles in IVD:
implementation.documentation field. No separate intent needed.{name}_intent.yaml alongside it—same pattern as code intents.Rule of thumb: If you removed the code and the document still has value on its own, it’s a primary artifact and deserves its own intent.
The “intent alongside implementation” principle applies universally:
Books:
my-book/
├── book_system_intent.yaml # Intent for entire book
└── manuscript/
└── part-1/
└── chapter-01/
├── intent.yaml # Intent for this chapter
└── chapter.md # Implementation (manuscript)
Research:
research/
├── topic_analysis_intent.yaml # Intent
└── topic_analysis.md # Implementation (findings)
Architecture:
architecture/
├── decisions/
│ ├── adr_001_intent.yaml # Intent for decision
│ └── adr_001_database_choice.md # Implementation (ADR)
Documentation (guides, runbooks, specifications):
docs/
├── operations/
│ ├── runbook_incident_response_intent.yaml # Intent
│ └── runbook_incident_response.md # Implementation (runbook)
├── onboarding/
│ ├── onboarding_guide_intent.yaml # Intent
│ └── onboarding_guide.md # Implementation (guide)
Processes:
processes/
├── chapter_writing_process_intent.yaml # Intent (defines process)
└── examples/ # Implementation (process outputs)
Why this matters:
Example constraint for book chapter:
# chapter-01/intent.yaml
constraints:
- name: "paragraph_length"
requirement: "Most paragraphs 3-5 sentences, max 7"
test: "visual inspection and readability review"
- name: "author_sourced_examples"
requirement: "All examples must be labeled as author-sourced or industry-typical"
test: "grep for unlabeled 'example' instances"
Example constraint for research:
# research/analysis_intent.yaml
constraints:
- name: "source_validation"
requirement: "All claims backed by URL or citation"
test: "Every finding has 'source:' field with URL"
- name: "recency"
requirement: "Sources from 2024-2026 unless historical context"
test: "Check all URLs and citations for date"
Example constraint for documentation (runbook):
# docs/operations/runbook_incident_response_intent.yaml
constraints:
- name: "actionable_steps"
requirement: "Every section has numbered steps a new engineer can follow"
test: "Each H2 section contains an ordered list of concrete actions"
- name: "up_to_date_references"
requirement: "All tool names, URLs, and commands verified against current infra"
test: "Run every command in dry-run mode; check all URLs return 200"
In large projects, knowing what features exist prevents duplication and helps AI agents (and humans) load context quickly. IVD supports this without a separate inventory file—inventory is derived from intent artifacts.
metadata block to intent artifacts (see schema above) with:
csv_export, lead_qualifier). Use lowercase snake_case.data_export, auth, reporting, api). Define a short list per project.admin, compliance, reporting).status: implemented |
planned |
deprecated. |
Derived inventory: Use the IVD feature-list tool (e.g. ivd_list_features) to scan all *_intent.yaml files and return an aggregated list. No separate feature_inventory.yaml—inventory is always generated from source, so it cannot drift. IVD placement and tools are per-project (co-locate with code in that repo); MCP tools accept an optional project_root for use in any repository.
metadata and IVD works as before.implemented, planned, deprecated.For non-system intents (workflow, module, task), IVD supports an optional parent_intent field that links a child intent to its parent — establishing hierarchy and enabling context inheritance.
Use parent_intent when:
Skip this field when:
parent_intent, load the parent’s project_context section, and follow project conventions automaticallyWithout parent_intent, every child intent is an island. AI agents creating a new module intent don’t know the project uses event-driven architecture, has a shared auth library, or follows specific logging conventions. With parent_intent, the agent loads the parent, reads the project context, and follows conventions — automatically, not by accident (Principle 7: Understanding Survives Implementation; Principle 5: Layered Understanding).
# agent/lead_scorer/lead_scorer_intent.yaml
parent_intent: "../../system_intent.yaml"
scope:
level: "module"
type: "agent"
# ...
The relative path points to the system intent. AI agents resolve this path, load the parent, and inherit its context. Task intents point to their module; modules point to workflows or directly to the system intent.
For system-level intents in existing projects, IVD supports an optional project_context section that captures project-wide conventions, architecture, tools, and key paths—enabling all child intents to reuse and reference them.
Use the project_context section when:
ivd init in a codebase that already has structureSkip this section when:
parent_intent instead)The project_context section documents:
.cursorrules, lint configs, formatting standardsWithout project context:
With project context:
# system_intent.yaml (project root)
project_context:
code_rules:
- path: ".cursorrules"
description: "Cursor IDE rules and conventions"
- path: "pyproject.toml"
description: "Python formatting (black), linting (ruff), type checking (mypy)"
architecture:
- path: "docs/ARCHITECTURE.md"
description: "High-level system architecture and design principles"
- path: "docs/architecture/"
description: "Architecture Decision Records (ADRs)"
- principle: "Event-driven microservices with async messaging (RabbitMQ)"
- principle: "No direct database access from frontend; all via API"
- principle: "Idempotent operations for all background jobs"
tools_scripts:
- path: "scripts/deploy.sh"
description: "Deployment automation (staging, production)"
- path: "scripts/db_migrate.py"
description: "Database migration runner (Alembic wrapper)"
- path: "tools/data_pipeline/extract.py"
description: "Data extraction utilities for ETL"
libraries_reuse:
- library: "internal/auth_utils"
description: "Authentication and authorization utilities (JWT, RBAC)"
when_to_use: "All auth-related features; never reimplement auth logic"
- library: "internal/logging"
description: "Structured logging with correlation IDs and tracing"
when_to_use: "All modules and workflows; use log_context decorator"
key_paths:
entrypoints:
- path: "api/main.py"
description: "FastAPI application entrypoint (REST API)"
- path: "worker/celery_app.py"
description: "Background job worker (Celery)"
modules:
- path: "agent/"
description: "AI agents (classifiers, extractors, coordinators)"
- path: "entity/"
description: "Core business entities (User, Lead, Organization)"
- path: "integrations/"
description: "External service integrations (Salesforce, Stripe, Twilio)"
workflows:
- path: "workflows/"
description: "Multi-step business processes (lead_qualification, onboarding)"
docs:
- path: "docs/"
description: "Project documentation (architecture, API, runbooks)"
- path: "docs/runbooks/"
description: "Operational runbooks for common incidents"
tests:
- path: "tests/"
description: "Test suites (unit, integration, e2e)"
existing_docs:
- path: "README.md"
description: "Project overview and quick start"
- path: "docs/API.md"
description: "API reference (autogenerated from OpenAPI spec)"
- path: "docs/CONTRIBUTING.md"
description: "Contribution guidelines and development setup"
Once system intent has project context, child intents reference it:
# agent/lead_scorer/lead_scorer_intent.yaml
parent_intent: "../../system_intent.yaml"
scope:
level: "module"
type: "agent"
intent:
summary: "Lead scoring agent for CRM pipeline"
goal: |
Classify leads as qualified/unqualified using ML model.
Project context:
- Follows event-driven architecture (principle from parent)
- Uses internal/logging for structured logging (library from parent)
- Reuses internal/auth_utils for API authentication (library from parent)
success_metric: "Precision >= 85%"
stakeholders: ["VP Sales"]
# Implementation references parent context
implementation:
current: "agent/lead_scorer/scorer.py"
reuses:
- library: "internal/logging"
usage: "@log_context decorator for all public methods"
- library: "internal/auth_utils"
usage: "API key validation before scoring"
follows_architecture:
- "Event-driven: Publishes 'lead.scored' events to RabbitMQ"
- "Idempotent: Same lead ID + data = same score (no side effects)"
The benefit: AI agents creating or modifying this intent:
parent_intent: "../../system_intent.yaml"For intents that document data movement, integration, or transformation between systems, IVD supports an optional field_mapping section that makes field mappings, data sources, and transformations explicit and verifiable.
Use the field_mapping section when:
Skip this section when:
The field_mapping section documents:
Field mappings are often undocumented or only in prose, leading to:
This section makes mappings:
# In workflow-level or module-level intent
field_mapping:
summary: "Sync qualified leads from internal DB to Salesforce CRM"
sources:
- system: "internal_db"
type: "database"
location: "leads table"
targets:
- system: "salesforce"
type: "api"
location: "Lead object"
mappings:
- source_field: "internal_db.leads.email"
target_field: "salesforce.Lead.Email"
transformation: "none"
required: true
- source_field: "internal_db.leads.score"
target_field: "salesforce.Lead.Lead_Score__c"
transformation: "round(score * 100)"
data_type: "float → integer"
example:
source: 0.87
target: 87
verification:
schema_validation:
- check: "All fields exist in schemas"
test: "tests/test_schema_conformance.py"
sample_validation:
- description: "Compare 10 random synced leads"
test: "tests/test_sync_accuracy.py"
See: recipes/data-field-mapping.yaml for complete pattern, examples, and verification strategies.
For modules that expose tools, commands, or endpoints to external consumers — agents, MCP servers, APIs, CLIs, or services — IVD supports an optional interface section that documents the callable tool surface as a verifiable contract.
Use the interface section when:
Skip this section when:
The interface section documents:
Tool surfaces are often undocumented or only discoverable by reading implementation code, leading to:
This section makes tool surfaces:
For agents that are consumed by a coordinator (the coordinator routes requests to this agent based on descriptions), the interface section supports an optional routing sub-field that captures the routing surface — the description the coordinator LLM reads to make routing decisions.
When to Use:
Why It Matters: In LLM-based multi-agent systems, the routing surface (the description string) is the actual runtime interface between coordinator and agent — as critical as an API contract. Without capturing it in intent, capability changes silently break routing: the coordinator can’t discover new capabilities, or still routes to removed ones.
The routing sub-field makes this surface:
routing.description keywords against actual tools — detect drift (Principle 2)tools change, routing.description must update (Principle 3)Recipe: recipes/agent-capability-propagation.yaml (bottom-up propagation pattern)
# In module-level intent for agents, MCP servers, APIs, CLIs, services
interface:
type: "mcp" # "mcp" | "agent" | "api" | "cli" | "service"
# Optional — for agents consumed by a coordinator
routing:
description: "One-line: what the coordinator tells the LLM about this agent"
keywords: ["psychology", "therapy", "memory"]
consumed_by: "agent/coordinator"
tools:
- name: "ivd_validate"
description: "Validate structure of an IVD intent artifact"
parameters:
- name: "artifact_yaml"
type: "string"
required: true
description: "Raw YAML content of the artifact to validate"
- name: "artifact_type"
type: "string"
required: false
description: "Type: intent, recipe, workflow (default: intent)"
returns: "JSON with valid (bool), errors, warnings, suggestions"
test: "tests/unit/test_validate.py::test_valid_intent"
- name: "ivd_search"
description: "Semantic search across IVD knowledge base"
parameters:
- name: "query"
type: "string"
required: true
description: "Natural language query"
- name: "top_k"
type: "number"
required: false
description: "Number of results (default: 5)"
returns: "JSON array of matching chunks with content, source, similarity"
test: "tests/unit/test_search.py::test_search_returns_results"
The interface section provides an aggregate view of the module’s tool surface. For complex or critical tools, you may also create individual task-level intents that go deeper into the tool’s internal logic:
MODULE INTENT (interface section) → "These are the 15 tools, their types, their tests"
↓
TASK INTENT (per critical tool) → "This tool's internal logic, edge cases, rationale"
They complement each other — the interface is the summary; task intents are the deep-dive.
For AI agents that switch behavioral modes depending on context — implementer, reviewer, architect, teacher, debugger — IVD supports an optional roles section that documents each behavioral profile as a verifiable contract.
Status: Experimental — This section is being validated. Apply it to real agents and report results to help promote it to canonical.
Use the roles section when:
interfaceSkip this section when:
interface)The roles section documents:
Role behaviors are often undocumented or only exist in system prompts and code, leading to:
This section makes role behaviors:
The roles and interface sections complement each other:
INTERFACE = WHAT the agent can do (tools, parameters, returns)
ROLES = HOW the agent behaves in different contexts (constraints, tool subsets)
A role may restrict which interface tools are available. For example, a “reviewer” role might only allow read, search, and validate tools from the full interface, while an “implementer” role allows all tools.
roles:
default: "implementer"
switching:
mechanism: "user_directed"
description: "User selects mode explicitly or agent infers from request context"
definitions:
- name: "implementer"
description: "Writes code, creates files, executes commands"
when: "User requests building, fixing, creating, or implementing"
constraints:
- "Must write/update intent before implementing"
- "Must verify constraints after implementation"
tools: ["all"]
verification: "tests/test_role_implementer.py"
- name: "reviewer"
description: "Reviews code for quality, alignment, issues"
when: "User requests review, audit, check, or code review"
constraints:
- "Read-only: no file modifications"
- "Must cite specific file and line references"
- "Must check alignment against intent artifact"
tools: ["read", "search", "validate"]
verification: "tests/test_role_reviewer.py"
- name: "architect"
description: "Designs systems, proposes structure, evaluates tradeoffs"
when: "User requests design, planning, architecture decisions"
constraints:
- "Must present alternatives with tradeoffs (Principle 8)"
- "Must reference existing architecture from parent_intent"
- "Read-only: no implementation changes"
tools: ["read", "search", "scaffold"]
verification: "tests/test_role_architect.py"
The roles section is for one agent with multiple modes. The coordinator-intent-propagation recipe is for multiple agents, each with its own intent. They are distinct but compatible:
ONE AGENT, MULTIPLE ROLES → roles section in that agent's intent
MULTIPLE AGENTS → coordinator recipe, each agent has its own intent
MULTIPLE AGENTS WITH ROLES → coordinator routes to agents; each agent's intent has roles
A coordinator can read an agent’s roles section to understand not just what the agent can do (interface), but how it behaves in different contexts — enabling smarter routing.
In standard IVD, the human describes what they want and the AI writes the intent artifact. But as AI agents become more autonomous — designing workflows, proposing process changes, creating new intents for sub-tasks — the question arises: who originated this intent, and what can the AI change without asking?
The optional authorship section formalizes the trust boundary for intent creation and modification.
Status: Experimental — This section is being validated. Apply it to real autonomous workflows and report results to help promote it to canonical.
Use the authorship section when:
Skip this section when:
The authorship section declares:
Without explicit authorship boundaries:
This section makes authorship:
authorship:
origin: "ai_proposed" # human_directed | ai_proposed | ai_autonomous
human_oversight: "review_required" # review_required | audit_trail | escalation_only
ai_authority:
can_create: true # can AI create new sub-intents?
can_modify: # which sections AI can modify without approval
- "implementation"
- "verification"
- "workflow.steps"
requires_approval: # fields that need human sign-off before changes take effect
- "intent.goal"
- "intent.success_metric"
- "constraints"
escalation: "When AI confidence < 80%, when change impacts other intents, or when modification touches protected fields"
The three origin levels represent a spectrum of human involvement:
HUMAN_DIRECTED → Human describes, AI writes, human reviews (current IVD default)
AI_PROPOSED → AI proposes new intent or modifications, human reviews before activation
AI_AUTONOMOUS → AI creates/modifies intent within declared boundaries, human audits after
Each level requires increasing guardrails:
can_modify boundaries. requires_approval fields are locked. Escalation rules are critical.Authorship complements roles: roles define how an agent behaves in different contexts; authorship defines what authority that agent has over intent itself. An agent in “architect” role might have authority to create new intents (can_create: true), while in “implementer” role it can only modify implementation sections.
Authorship is the governance layer for the evaluation loop. When evaluation identifies an improvement, the adjustment.authority in the evaluation section must respect the ai_authority declared in authorship. If authorship says the AI cannot modify constraints, the evaluation loop cannot relax constraints even if quality would improve.
IVD verification answers: does the output pass the constraints? That’s binary — pass or fail. But production systems need more: how good is the output, and how can it improve?
The optional evaluation section formalizes the continuous improvement loop: evaluate output quality → identify weakness → propose adjustment → verify the adjustment doesn’t violate constraints → apply.
Status: Experimental — This section is being validated. Apply it to real workflows with measurable quality and report results to help promote it to canonical.
Use the evaluation section when:
Skip this section when:
The evaluation section documents:
Without a formalized evaluation loop:
This section makes improvement:
evaluation:
criteria:
- metric: "classification_precision"
target: ">= 0.90"
source: "automated" # automated | human_review | hybrid
- metric: "end_to_end_latency"
target: "p95 < 2s"
source: "automated"
- metric: "constraint_pass_rate"
target: "100%"
source: "ivd_validate"
adjustment:
authority: "ai_proposed" # human_only | ai_proposed | ai_autonomous
scope: # what CAN be adjusted
- "implementation"
- "workflow_steps"
- "model_parameters"
protected: # what CANNOT be adjusted
- "intent.goal"
- "intent.success_metric"
- "constraints"
cycle:
trigger: "on_completion" # on_completion | on_failure | scheduled | continuous
max_iterations: 3
stop_when: "All criteria met or max_iterations reached"
escalate_when: "Cannot meet criteria after max_iterations"
VERIFICATION → "Does the output pass the constraints?" (binary: yes/no)
EVALUATION → "How good is the output? How can it improve?" (continuous: 0.78 → 0.85 → 0.92)
Verification is a gate. Evaluation is a loop. Verification asks pass/fail. Evaluation asks how much better. Both are anchored to intent — but evaluation extends verification with quality measurement, adjustment authority, and bounded iteration.
Critical rule: Evaluation NEVER relaxes constraints. Constraints are the floor. Evaluation improves quality above the floor.
The evaluation loop’s adjustment.authority must respect the authorship section’s ai_authority. If authorship declares that the AI cannot modify constraints, evaluation cannot relax constraints. If authorship says changes need human review, evaluation proposes adjustments but doesn’t apply them until approved.
AUTHORSHIP → Who can change intent, and what fields are protected
EVALUATION → How to improve quality within those boundaries
They work together: authorship sets the rules; evaluation operates within them.
Constraints and evaluation criteria serve different purposes:
CONSTRAINTS → Binary guardrails: "precision >= 85% or fail"
EVALUATION → Quality targets: "precision is 87%, can we reach 92%?"
Constraints define the minimum. Evaluation drives toward the optimum. The evaluation loop cannot change constraints — only improve quality within them.
IVD supports four levels of intent granularity to match different documentation needs:
SYSTEM LEVEL → Entire product or platform
↓
WORKFLOW LEVEL → Multi-step process (NEW in v1.2)
↓
MODULE LEVEL → Feature, agent, component
↓
TASK LEVEL → Function, method, API endpoint
For: Entire products, platforms, or strategic initiatives
Characteristics:
Example: Product development roadmap, multi-quarter platform migration
File location: system_intent.yaml or {project}_system_intent.yaml at repository root
For: Multi-step processes that span multiple modules or functions
Characteristics:
Example: Lead qualification workflow (validate → enrich → score → qualify → sync to CRM)
File location:
workflows/{workflow_name}_intent.yaml
find workflows/ -name "*_intent.yaml" discoveryworkflows/ by default; use “alongside coordinator” only when the workflow has a single orchestrator and is not referenced elsewhere.Why workflow-level matters:
Traditional documentation forces choice between:
Workflow-level fills the gap:
Workflow schema (key sections):
scope:
level: "workflow"
type: "process"
workflow:
summary: "What this workflow accomplishes"
trigger: "What initiates the workflow"
steps:
- step: 1
name: "Descriptive step name"
file: "path/to/module.py"
function: "function_name()"
description: "What this step does"
input: "What data comes in"
output: "What data goes out"
business_logic: "Key rules and decisions"
- step: 2
name: "Next step"
file: "path/to/another_module.py"
# ... and so on
data_flow:
- "High-level data transformations"
- "Input → Step 1 → Step 2 → ... → Output"
error_handling:
- step: 1
failure_mode: "What can go wrong"
action: "What happens when it fails"
fallback: "Alternative behavior"
orchestration:
type: "sequential | parallel | mixed"
coordinator: "path/to/coordinator.py"
When to create workflow intent:
Real-world examples:
See: templates/examples/workflow-lead-qualification-example.yaml for complete example
Recipe: recipes/workflow-orchestration.yaml for workflow pattern template
For: Features, agents, components with clear boundaries
Characteristics:
Example: Lead qualifier agent, fact checker agent, background job processor
File location: {module}/{module}_intent.yaml alongside implementation
Note: For tooling compatibility (MCP tools use glob **/*_intent.yaml), module intents must use the {module}_intent.yaml pattern. A bare intent.yaml without the module name prefix will not be discovered by ivd_find_artifacts or ivd_list_features.
For: Individual functions, methods, or API endpoints
Characteristics:
Example: qualify_lead() function, extract_claims() function, POST /api/leads endpoint
File location: {module}/intents/{function}_intent.yaml
find */intents/ -name "*_intent.yaml" finds all task-level intentsintents/ in path; flat placement not supported by discovery toolsA module may require multiple intent artifacts for variants, personas, or configurations:
| Pattern | Use Case | Example | Discovery Pattern |
|---|---|---|---|
{module}_intent.yaml |
Primary module intent | reviewer_intent.yaml |
{module}_intent.yaml |
{variant}_{module}_intent.yaml |
Variant (persona, config) | erik_reviewer_intent.yaml |
*_{module}_intent.yaml |
intents/{function}_intent.yaml |
Task-level intents | intents/review_article_intent.yaml |
intents/*_intent.yaml |
Naming Rules:
{module}_intent.yaml{variant}_{module}_intent.yamlintents/ subdirectory: intents/{function}_intent.yamlAI Agent Discovery:
# Find all module-level intents (primary + variants):
find agent/ -maxdepth 2 -name "*_intent.yaml" ! -path "*/intents/*"
# Find all task-level intents:
find agent/ -path "*/intents/*_intent.yaml"
# Find all variants of a specific module:
find agent/reviewer/ -name "*_reviewer_intent.yaml"
Why variants exist:
Default to MODULE-level unless:
The rule: Use the highest level that captures necessary detail.
Example hierarchy:
SYSTEM: My Writing Project (my_project_system_intent.yaml)
└─ WORKFLOW: Meeting extraction workflow (workflows/meeting_extraction_intent.yaml)
├─ MODULE: Meeting extractor agent (agent/meeting_extractor/meeting_extractor_intent.yaml)
│ └─ TASK: extract_insights() function (agent/meeting_extractor/intents/extract_insights_intent.yaml)
└─ MODULE: Fact checker agent (agent/fact_checker/fact_checker_intent.yaml)
See: templates/intent_levels_guide.md for complete guide on level selection
For existing projects (brownfield), understanding which modules already have intent artifacts—and which don’t—is essential before deciding where to invest effort. IVD provides a dedicated tool for this.
ivd_assess_coverage scans a project’s directory structure, discovers all *_intent.yaml and *_system_intent.yaml artifacts, maps them to code directories, and produces a structured report:
| Depth | What it checks |
|---|---|
module (default) |
System intent + module-level coverage |
full |
System + workflow + module + task-level coverage |
ivd init and enriching the system intent, run ivd_assess_coverage to see where intent exists and where it doesn’t. Use the report to prioritize which modules get intents first.# Default: module-level coverage with suggestions
ivd_assess_coverage(project_root="/path/to/project")
# Full depth: includes workflow and task-level analysis
ivd_assess_coverage(project_root="/path/to/project", depth="full")
# Without suggestions (just the data)
ivd_assess_coverage(project_root="/path/to/project", include_suggestions=False)
{
"summary": {
"has_system_intent": true,
"total_coverable_modules": 8,
"covered_modules": 3,
"uncovered_modules": 5,
"coverage_percent": 37.5,
"total_intent_artifacts": 5
},
"covered": [...],
"uncovered": [
{"path": "agent/auth", "code_files": 6, "priority": "high"},
{"path": "agent/reporting", "code_files": 3, "priority": "medium"}
],
"suggestions": [
{"action": "Create module-level intents for 2 high-priority module(s)", "priority": "high"}
]
}
When an AI agent is asked to help adopt IVD in an existing project:
ivd_init → creates system intent with project contextivd_assess_coverage → structured coverage reportivd_scaffold for those modules, referencing parent_intentivd_assess_coverage periodically to track progressNot every directory needs an intent artifact. Intent belongs where it adds value:
Simple utility directories, configuration, or stable code that rarely changes may not need explicit intent.
NEW in IVD v1.1: Recipes are reusable pattern templates that capture how to solve common development problems.
The key distinction:
| Intent Artifact | Recipe |
|---|---|
| Specific to one implementation | Reusable across many implementations |
| Documents “what we built” | Documents “how to build similar things” |
| Lives next to code | Lives in recipes directory |
| Changes with that module | Changes when pattern improves |
Example: lead_scorer_intent.yaml |
Example: agent-classifier.yaml |
The problem recipes solve:
Without recipes:
With recipes:
# recipe_[pattern_name].yaml
recipe:
name: "Pattern Name"
description: "What problem this solves"
when_to_use: [...]
when_NOT_to_use: [...]
# Template sections (filled in for specific implementation)
intent_template: {...}
constraints_template: {...}
rationale_template: {...}
alternatives_template: {...}
risks_template: {...}
# Pattern guidance
implementation_pattern: {...}
verification_pattern: {...}
best_practices: [...]
common_pitfalls: [...]
# Real examples
examples: [...]
Full specification: See recipe-spec.md
1. Workflow Patterns (NEW in v1.2) - Multi-step processes
workflow-orchestration.yaml - Process orchestration (lead qualification, ETL, etc.)workflow-pipeline.yaml - Data pipelinesworkflow-event-driven.yaml - Event-driven workflows2. Agent Patterns - Building AI agents
agent-classifier.yaml - Classification agentsagent-extractor.yaml - Data extractionagent-coordinator.yaml - Orchestrationagent-fact-checker.yaml - Fact verification3. Integration Patterns - External system integration
recipe_api_integration.yaml - REST API integrationsrecipe_webhook_handler.yaml - Webhook processingrecipe_database_sync.yaml - Database synchronization4. Data Patterns - Data processing
recipe_data_validation_pipeline.yaml - Data qualityrecipe_etl_workflow.yaml - Extract, transform, loadrecipe_batch_processor.yaml - Batch processing5. Infrastructure Patterns - Operations
infra-monitoring.yaml - Observabilityinfra-background-job.yaml - Async job processinginfra-retry.yaml - Resilience patternsRECIPE (reusable pattern)
↓
Provides template structure
↓
INTENT ARTIFACT (specific implementation)
↓
References recipe, fills in specifics
↓
IMPLEMENTATION (code)
↓
Follows pattern from recipe
↓
VERIFICATION (tests)
↓
Validates constraints from intent
Example:
# recipes/agent-classifier.yaml
# This is the REUSABLE PATTERN
recipe:
name: "AI Classifier Agent Pattern"
applies_to:
- "Classification requiring context understanding"
- "Quality thresholds are critical"
intent_template:
summary: "[Domain] classifier for [use case]"
goal: "Classify [items] into [categories] for [stakeholder]"
success_metric: "[Metric] >= [target]%"
constraints_template:
- name: "classification_accuracy"
requirement: "accuracy >= [0.80-0.95 typical]"
test: "tests/test_[module]_accuracy.py"
# agent/lead_scorer/scorer_intent.yaml
# This is the SPECIFIC IMPLEMENTATION
recipe: "agent-classifier" # ← Links to pattern
recipe_version: "1.0"
# Now fill in the template with specifics:
intent:
summary: "Lead scoring classifier for CRM" # Specific
goal: "Classify leads as qualified/unqualified for sales team" # Specific
success_metric: "Precision >= 85%" # Specific
stakeholders: ["VP Sales (Jane Smith)"] # Specific
constraints:
- name: "classification_accuracy"
requirement: "precision >= 0.85" # Specific (recipe said 0.80-0.95 typical)
test: "tests/test_scorer_accuracy.py" # Specific
consequence_if_violated: "Sales team wastes time on unqualified leads" # Specific
Step 1: Find the right recipe
ivd recipe list
ivd recipe search "classifier"
Step 2: Apply recipe to your implementation
# Copy intent template
cp templates/intent.yaml agent/my_classifier/my_classifier_intent.yaml
# Reference recipe in my_classifier_intent.yaml:
# recipe: "agent-classifier"
# recipe_version: "1.0"
Step 3: Fill in specifics
Generated intent artifact has:
Step 4: Implement following the pattern
Recipe provides:
When to create a recipe:
Recipe creation:
ivd recipe create \
--from-intent agent/successful_module/module_intent.yaml \
--name recipe_my_pattern
Recipes improve over time:
changelog:
- version: "1.2"
date: "2026-02-15"
change: "Added error handling best practices"
reason: "Production incidents revealed missing error cases"
- version: "1.1"
date: "2026-01-30"
change: "Added performance optimization patterns"
reason: "Performance issues in 3 implementations"
Recipe versioning ensures:
For Developers:
For Teams:
For Organization:
# Verify single module
$ ivd verify agent/lead_qualifier
# Verify entire codebase
$ ivd verify --all
# Verify before commit
$ ivd verify --staged
# Deep verification (re-run experiments)
$ ivd verify --deep agent/lead_qualifier
| Check | Verifies |
|---|---|
| Intent exists | Module has declared intent |
| Implementation matches | Code implements what intent declares |
| Constraints hold | Tests validate all stated constraints |
| Evidence is current | Linked experiments/notebooks still run |
| Alternatives documented | Rejected approaches are recorded |
| Risks monitored | Monitoring exists for stated risks |
| Documentation synced | Docs reflect current intent |
| Tests comprehensive | Coverage matches intent scope |
INTENT VERIFICATION REPORT
Module: agent/lead_qualifier/scoring.py
Intent Artifact: scoring_intent.yaml v3
✅ ALIGNMENT CHECKS
Code threshold (0.70) matches intent ✓
Function signature matches intent ✓
Edge cases handled per intent ✓
✅ CONSTRAINT VALIDATION
precision >= 0.80: PASS (actual: 0.85)
recall >= 0.60: PASS (actual: 0.70)
✅ EVIDENCE VERIFICATION
playground/lead_analysis_2025-12.ipynb:
- Last run: recently
- Results match rationale ✓
- All cells executed successfully ✓
⚠️ RISK MONITORING
Risk: "precision drops below 0.75"
Current: 0.82 (within safe range)
Status: MONITORING (approaching threshold)
Action: Continue monitoring, no intervention needed
✅ DOCUMENTATION SYNC
Design doc reflects current intent ✓
FDR-089 matches decision ✓
Comments in code cite intent artifact ✓
OVERALL: VERIFIED ✓
Confidence: 95%
Last verified: 2026-01-23 14:30:00 UTC
Status: Canonical (added in v3.0) Activation: Dormant unless
<project_root>/.judgment/exists Canonical operational doc:judgment_layer.mdPrinciple: Principle 9 — Judgment Compounds (immutable)
The first three IVD phases — Intent, Implementation, Verification — answer the question “How do we get the first draft right?” The Judgment phase answers the question that comes after the system ships:
Reality answered back. Now what?
That answer-back — the correction from a domain expert, an audience signal, a runtime exception, or two real runs that diverged — 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.
Principles 1–8 cover the cost of getting intent right the first time (hallucinations, drift, missed constraints, premature defaults). They do not cover what happens when the intent itself was wrong, the verification passed, and the world produced an outcome we didn’t want. Without a structured way to capture, codify, cluster, and feed back those corrections, every project starts judgment from zero — and any moat the first three phases built erodes when the model layer commoditizes.
The Judgment phase is the structural answer: model parity is converging, but structured organizational judgment cannot be downloaded. It can only be accumulated. Principle 9 makes the accumulation mechanical.
0. Baseline & Goal Calibration ──┐
│
1. Capture (raw correction) │ agent + you
2. Codify (5 structured fields) │
3. Pair (optional comparison) │
│
4. Detect Patterns ───────────────┤ detector
│
5. Propose Recommendation ────────┤ drafter
│
6. Approve (you) ────────────────┤ GATE ← only mandatory human gate
│
7. Apply Fix │ agent
│
8. Inject Context (next runs) │ injector
│
9. Resolve / Archive │ bookkeeper
─┘
.judgment/ folder gateThe Judgment phase is opt-in per project. Eight of the nine
ivd_judgment_* MCP tools return a “judgment phase not initialized” error
unless the project root contains .judgment/. The lone exception,
ivd_judgment_check_installed (added in v3.1), is read-only and intentionally
runnable in any project — its job is to detect the absence of .judgment/ and
return the ready-to-call init payload the agent must offer to the user with
explicit permission, mirroring canon_check_rules_installed. The project root
contains:
<project_root>/.judgment/
├── baselines/ # one per domain
├── ledger/ # raw → codified → (paired | pattern-member) → resolved → archived
├── patterns/ # detected patterns (≥ 3 entries with shared diagnosed_cause)
├── recommendations/ # drafted + approved recommendations
└── config.yaml # injection budget, freshness defaults, weights
Bootstrap with ivd_judgment_init(project_root, domains=[...]). Most
projects do not need a Judgment phase on day one; forcing it everywhere
would dilute the rest of IVD.
| Tool | Purpose |
|---|---|
ivd_judgment_init |
Bootstrap .judgment/ skeleton + per-domain baselines |
ivd_judgment_capture |
Write a raw ledger entry (target: < 30 seconds) |
ivd_judgment_codify |
Return a structured codify prompt for the agent |
ivd_judgment_save_codified |
Persist the agent’s filled codify fields |
ivd_judgment_pair |
Capture a comparison_pair entry |
ivd_judgment_detect_patterns |
Scan ledger; create/update patterns |
ivd_judgment_inject_context |
Return prioritized context block for downstream agents |
ivd_judgment_propose_recommendation |
Draft a recommendation against a pattern |
ivd_judgment_check_installed |
Workspace/project activation visibility (read-only; v3.1) |
Total IVD tool surface in v3.1: 33 (19 core + 10 Judgment + 4 Canon).
Server-level opt-out for the Judgment tools: IVD_JUDGMENT_TOOLS_ENABLED=false
(mirrors Canon’s IVD_CANON_TOOLS_ENABLED; tools remain registered when
disabled and return an enabled=false payload).
Most production AI systems cannot run strict A/B tests — creative outputs are not repeatable, multi-agent runtimes share state, low-volume domains never reach significance. The Judgment phase canonizes comparison pairs as the Rung-1 (Pearl, Book of Why) alternative: capture two real runs as a single ledger entry, enumerate observed differences in conditions and outcomes, generate diagnostic hypotheses with at least one competing hypothesis, and mark the working hypothesis as plausible until 2+ independent pairs corroborate it.
Only corroborated hypotheses graduate to the What Works layer of context injection — generative guidance (“when X, prefer Y”) rather than failure-avoidance (“don’t do X”). This is intentional: compounding requires the system to learn what works, not just what doesn’t.
build | buy | hire | partner)When fix_action_type == capability_addition, recommendations must pick a
sub-type:
This is the most strategic output of the loop: it tells you which tool to build next, with explicit rationale rooted in repeated real-world corrections.
Pattern confidence is weighted by domain_depth (the practitioner’s
self-rated depth in the domain): expert 1.0 / practitioner 0.7 / adjacent
0.4 / novice 0.2. AI reviewer agents are structural
conformance checkers, not quality judges — their corrections enter as
source: runtime and are not weighted by domain_depth. This separation
is what lets the loop amplify weak expert signals into reliable patterns
without diluting them with structural noise.
Patterns age. A pattern about claude-3 prompting is stale when the project
moved to claude-4. Each pattern carries a half_life_days (defaults from the
domain baseline):
| freshness | rule | injectable? |
|---|---|---|
fresh |
age ≤ half_life | yes |
aging |
half_life < age ≤ 2 × half_life | yes |
stale |
2 × half_life < age ≤ 3 × half_life | flagged, requires re-validation |
expired |
age > 3 × half_life | no |
If a pattern’s members are dominated by entries with the same
originated_from_tool, the tool is flagged in
pattern.originated_from_tools and net_pattern_delta increments. A tool
with positive net_pattern_delta is producing more patterns (failures) than
it eliminates — a candidate for deprecation. This is how the Judgment phase
keeps the recipe library honest.
| Artifact | Template | Recipe |
|---|---|---|
| Baseline | templates/baseline.yaml |
— |
| Ledger entry | templates/ledger-entry.yaml |
recipes/capture-correction.yaml |
| Comparison pair | templates/comparison-pair.yaml |
recipes/comparison-pair.yaml |
| Pattern | templates/pattern.yaml |
recipes/distill-pattern.yaml |
Validator (ivd_validate) accepts these artifact_type values: ledger_entry, comparison_pair, pattern, baseline.
For deeper coverage — confidence math, freshness thresholds, the What Works
layer, the full state machine, and worked examples — see
judgment_layer.md.
When: You lack the technical knowledge to understand concepts, patterns, or technologies needed for the task.
Signals:
Process:
Example:
education:
concept: "ETL (Extract, Transform, Load)"
what_it_is: |
ETL is a data pipeline pattern: Extract data from sources, Transform it to
match target schema/business rules, Load it into a destination system.
why_it_matters_here: |
Your project needs to sync lead data from Salesforce to PostgreSQL daily.
key_concepts:
- name: "Extract"
definition: "Read data from source system (API, database, file)"
example: "Pull leads from Salesforce REST API"
- name: "Transform"
definition: "Apply business rules, normalize schema"
example: "Convert Salesforce Status to lead_stage enum"
- name: "Load"
definition: "Write data to destination"
example: "UPSERT into PostgreSQL analytics.leads table"
tradeoffs:
- decision: "Batch vs Streaming"
options:
- name: "Batch"
when: "Daily/hourly sync acceptable"
pros: ["Simpler", "Lower cost"]
cons: ["Data lag (hours)"]
verification:
- question: "What are the 3 steps of ETL?"
answer: "Extract, Transform, Load"
Tools: ivd_teach_concept(concept="ETL", user_context="sync Salesforce leads daily")
Recipe: recipes/teaching-before-intent.yaml
Why this matters: Lack of technical knowledge is the main bottleneck in project critical paths. You can’t review intent if you don’t understand the concepts it references.
When: You don’t know what to build (goal uncertainty), but you have the technical knowledge to evaluate options once presented.
Note: If you lack the technical knowledge to understand the options themselves, use Step 0a (Teaching) first.
Signals:
Process:
Tools: ivd_discover_goal(domain_or_context="data_export", user_hint="compliance")
Recipe: recipes/discovery-before-intent.yaml
When adopting IVD in an existing project with code and docs already in place:
# 1. Initialize IVD - creates system intent with project context
$ ivd init --project-root /path/to/your/project
Scanning project...
- Found: .cursorrules
- Found: docs/ARCHITECTURE.md
- Found: scripts/ (5 scripts)
- Found: agent/ (3 agents)
- Found: docs/ (10 docs)
Generated: system_intent.yaml
Project context captured:
✓ Code rules: .cursorrules, pyproject.toml
✓ Architecture: docs/ARCHITECTURE.md, 3 ADRs
✓ Tools/scripts: 5 scripts in scripts/
✓ Key paths: entrypoints, modules, workflows, docs, tests
✓ Existing docs: README.md, API.md, CONTRIBUTING.md
Next steps:
1. Review and enrich system_intent.yaml
2. Assess coverage: ivd_assess_coverage → see which modules need intents
3. Create intents for high-priority modules (ivd scaffold)
4. Reference parent_intent: "../../system_intent.yaml" in child intents
The workflow for existing projects:
ivd init to scan project and create system_intent.yamlivd_assess_coverage to see which modules have intents and which don’t (prioritized)ivd scaffold for high-priority uncovered modules, referencing parent_intentivd_assess_coverage periodically to track progressKey differences from greenfield:
parent_intent.cursorrules or equivalent agent instruction file exists, add the IVD verification rules (see below)AI agent instruction files (.cursorrules, .clinerules, Copilot system prompts, Aider configuration) are the runtime enforcement point for IVD. Without IVD rules in the agent’s instructions, nothing enforces the post-implementation verification protocol — the agent implements and moves on.
When ivd init scans a project and finds .cursorrules or equivalent, it suggests adding the IVD rules block. The block enforces three rules:
test field. A constraint without a test is an unverifiable claim.See recipes/agent-rules-ivd.yaml for the complete rules block in .cursorrules, .clinerules, and Copilot formats.
For a module that already exists:
$ ivd intent create agent/lead_qualifier/scoring.py
Analyzing: agent/lead_qualifier/scoring.py
Found threshold: 0.70
Found data_quality check: 0.80
Searching for rationale...
- Checking git history... found commit
- Checking playground/... found lead_analysis_2025-12.ipynb
- Checking docs/... found partial explanation
Loading project context from system_intent.yaml...
- Code rules: .cursorrules (loaded)
- Architecture principles: Event-driven, no direct DB access
- Reusable libraries: internal/auth_utils, internal/logging
Generated: scoring_intent.yaml
Please review and complete:
- [✓] Intent goal extracted
- [✓] Constraints identified from code
- [✓] Evidence linked from git/playground
- [✓] Parent intent: ../../system_intent.yaml (auto-linked)
- [✓] Project context: code rules, architecture loaded
- [?] Stakeholder approval (needs human input)
- [?] Alternatives (needs human input)
- [?] Risk monitoring (needs human input)
Human reviews generated intent artifact:
# scoring_intent.yaml (generated, needs review)
intent:
summary: "Qualify leads based on score and data quality"
goal: "Filter leads to sales team to maximize conversion rate"
success_metric: "???" # ← NEEDS INPUT
stakeholders: ["???"] # ← NEEDS INPUT
constraints:
- name: "score_threshold"
requirement: "score >= 0.70"
test: "tests/test_scoring.py::test_threshold" # ← Verify this exists
rationale:
decision: "threshold = 0.70"
evidence: "playground/lead_analysis_2025-12.ipynb" # ← Found automatically
date: "2025-12-15" # ← From git
stakeholder: "???" # ← NEEDS INPUT
alternatives: [] # ← NEEDS INPUT
risks: [] # ← NEEDS INPUT
Human completes missing pieces:
intent:
success_metric: "Sales conversion rate >= 15%"
stakeholders: ["VP Sales", "Sales Operations"]
rationale:
stakeholder: "VP Sales (Jane Smith)"
alternatives:
- name: "threshold_0.60"
rejected_because: "Sales feedback: too many low-quality leads"
date_tested: "2025-12-01"
- name: "threshold_0.80"
rejected_because: "Insufficient pipeline volume"
date_tested: "2025-12-01"
risks:
- condition: "precision drops below 0.75"
action: "Alert sales leadership"
monitor: "dashboards/lead_quality.json"
severity: "high"
Add to CI/CD:
# .github/workflows/verify.yml
name: Intent Verification
on: [push, pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Verify Intent Alignment
run: |
ivd verify --all
ivd verify --deep --changed-only
Add pre-commit hook:
# .git/hooks/pre-commit
#!/bin/bash
ivd verify --staged || exit 1
Workflow:
Developer changes threshold: 0.70 → 0.75
$ git add agent/lead_qualifier/scoring.py
$ git commit -m "Increase threshold to 0.75"
[Pre-commit hook runs]
❌ Intent verification FAILED:
- Code says threshold = 0.75
- Intent says threshold = 0.70
- DRIFT DETECTED
Choose action:
1. Update intent to match code (threshold → 0.75)
2. Revert code to match intent (threshold → 0.70)
3. Skip verification (not recommended)
> 1
Updating scoring_intent.yaml...
Re-running validation experiments...
Updating documentation...
✅ Intent updated and verified
✅ Commit proceeding
# agent/lead_qualifier/scoring.py
def qualify_lead(score: float, data_quality: float) -> bool:
"""Qualify lead based on score and data quality."""
if score >= 0.70 and data_quality >= 0.80:
return True
return False
Problems:
Intent Artifact:
# agent/lead_qualifier/lead_qualifier_intent.yaml
intent:
summary: "Qualify high-probability leads for sales team"
goal: |
Filter pipeline to send only leads with high conversion probability
to sales team. Balance quality (minimize wasted sales time) vs
quantity (maintain sufficient pipeline for revenue goals).
success_metric: "Sales conversion rate >= 15%"
stakeholders: ["VP Sales (Jane Smith)", "Sales Operations"]
constraints:
- name: "minimum_precision"
requirement: "precision >= 0.80"
test: "tests/test_lead_qualification.py::test_precision_threshold"
consequence_if_violated: "Sales team wastes time on low-quality leads"
- name: "minimum_recall"
requirement: "recall >= 0.60"
test: "tests/test_lead_qualification.py::test_recall_threshold"
consequence_if_violated: "Insufficient pipeline volume for revenue goals"
rationale:
decision: |
Score threshold: 0.70
Data quality threshold: 0.80
Both must pass for qualification
evidence: "playground/lead_analysis_2025-12.ipynb"
date: "2025-12-15"
stakeholder: "VP Sales (Jane Smith)"
methodology: |
Tested thresholds 0.60, 0.65, 0.70, 0.75, 0.80 on 500 historical leads.
Measured precision, recall, and gathered sales team feedback.
0.70 provided best balance: 85% precision, 70% recall.
alternatives:
- name: "rule_based_classification"
rejected_because: "Too brittle, couldn't adapt to changing lead characteristics"
experiment: "playground/rule_based_comparison_2025-11.ipynb"
date_tested: "2025-11-15"
- name: "ml_classifier_v1"
rejected_because: "Overfitting on training data, poor generalization"
experiment: "playground/ml_classifier_eval_2025-12.ipynb"
date_tested: "2025-12-01"
- name: "threshold_0.60"
rejected_because: "Only 75% precision - sales feedback negative"
experiment: "playground/threshold_comparison_2025-12.ipynb"
date_tested: "2025-12-10"
- name: "threshold_0.80"
rejected_because: "Only 50% recall - insufficient pipeline volume"
experiment: "playground/threshold_comparison_2025-12.ipynb"
date_tested: "2025-12-10"
risks:
- condition: "precision drops below 0.75"
action: "Alert VP Sales, review threshold increase"
monitor: "dashboards/lead_quality.json"
severity: "high"
- condition: "recall drops below 0.50"
action: "Alert Sales Ops, review threshold decrease"
monitor: "dashboards/pipeline_volume.json"
severity: "medium"
- condition: "market conditions change significantly"
action: "Re-run validation experiment, consider re-tuning"
monitor: "quarterly review"
severity: "medium"
implementation:
current: "agent/lead_qualifier/scoring.py"
version: 3
tests: "tests/test_lead_qualification.py"
documentation: "docs/agents/lead_qualifier_DESIGN.md"
deployment: "production since 2025-12-20"
changelog:
- version: 3
date: "2025-12-15"
change: "Implemented statistical threshold with data quality gate"
reason: "ML classifier overfitted, rule-based too brittle"
evidence: "playground/approach_comparison_2025-12.ipynb"
approved_by: "VP Sales (Jane Smith)"
- version: 2
date: "2025-12-01"
change: "Attempted ML classifier"
reason: "Wanted adaptive classification"
deprecated: "2025-12-15"
deprecated_reason: "Overfitting issues"
- version: 1
date: "2025-11-01"
change: "Initial rule-based implementation"
deprecated: "2025-12-01"
deprecated_reason: "Too brittle for changing data"
Implementation (Clean):
# agent/lead_qualifier/scoring.py
# Intent: scoring_intent.yaml v3
from typing import Tuple
# Constants from intent artifact
SCORE_THRESHOLD = 0.70 # See scoring_intent.yaml for rationale
DATA_QUALITY_THRESHOLD = 0.80
def qualify_lead(score: float, data_quality: float) -> bool:
"""
Qualify lead for sales team.
Full intent and rationale in: scoring_intent.yaml
Constraints (verified in tests):
- Precision >= 0.80
- Recall >= 0.60
Args:
score: Predictive score (0.0-1.0) from lead scoring model
data_quality: Data completeness score (0.0-1.0)
Returns:
True if lead qualifies, False otherwise
"""
return (
score >= SCORE_THRESHOLD and
data_quality >= DATA_QUALITY_THRESHOLD
)
Verification:
$ ivd verify agent/lead_qualifier/
✅ Intent artifact: scoring_intent.yaml v3
✅ Implementation matches: thresholds correct
✅ Constraints satisfied:
- precision = 0.85 (>= 0.80) ✓
- recall = 0.70 (>= 0.60) ✓
✅ Evidence current: playground/lead_analysis_2025-12.ipynb (recently run)
✅ Tests: 12/12 passing ✓
✅ Risks monitored: dashboards configured ✓
⚠️ Note: precision at 0.82, within acceptable range but monitor trend
UNDERSTANDING VERIFIED ✓
Next review: 2026-04-01 (quarterly)
| Aspect | Traditional | Literate (Knuth) | Pragmatic LP | Intent-Verified |
|---|---|---|---|---|
| Primary artifact | Code | Documentation | Code + docs | Intent |
| Understanding format | Comments | Prose | Rich comments | Structured YAML |
| Can diverge? | Always | No (single source) | Yes (AI helps) | No (verified) |
| Verification | None | Manual reading | Manual review | Continuous automated |
| AI role | None | None | Synchronizer | Understanding partner |
| Survives rewrites | No | Tied to impl | No | Yes |
| Tooling | Standard | Specialized | Standard | Standard + verifier |
| Adoption | Universal | Failed | Growing | Experimental |
| Knowledge capture | 10-15% | 60-80% | 60-80% | 85-95% |
ivd verify system doesn’t exist yet (needs building)Don’t convert everything at once:
recipes/discovery-before-intent.yaml)ivd intent create - Generate intent from existing codeivd verify - Check alignmentivd verify systemWant to add a new intent level, section, or recipe pattern?
All extensions to IVD must follow the rules defined in ivd_system_intent.yaml:
The master intent documents:
Read ivd_system_intent.yaml to understand:
<project_root>/.judgment/)IVD evolves slowly and deliberately:
Why? IVD is about durable understanding. Better to evolve slowly with confidence than quickly with chaos.
Intent-Verified Development is the framework for the AI Agents era:
It acknowledges that in the AI Agents era, the AI builds, writes, and verifies. Traditional artifacts (PRDs, user stories, prompts) are prose the AI reads and guesses at. IVD provides structured intent the AI can write, verify, and self-correct against.
The paradigm shift: From “prompt the AI and hope” to “AI writes intent, implements, verifies.”
README.md - Quick start guidecookbook.md - Practical implementation guideivd_system_intent.yaml - System intent (rules for extending IVD)cheatsheet.md - Quick referencetemplates/intent_levels_guide.md - When to use which intent levelVersion: 3.1
Status: Production Ready
Maintained by: IVD maintainers
Key Insight: The AI writes the intent, implements against it (constraint-segmented for 3+ constraints), verifies, and compounds judgment from real-world corrections — eliminating many-turns and hallucinations.