Intent-Verified Development (IVD)
A framework where AI writes the intent, implements against it, and verifies — so hallucinations are caught and turns drop to one.

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

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

Without IVD                              With IVD

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

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

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

git clone https://github.com/leocelis/ivd.git
cd ivd
./mcp_server/devops/setup.sh    # creates .venv, installs all deps

Cursor (Settings → Features → MCP):

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

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

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

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

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

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

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

That's it. 14 of 15 tools work immediately with zero configuration.

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

export OPENAI_API_KEY=your-key
./mcp_server/devops/embed.sh

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

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

15 tools available to any MCP-compatible AI agent:

Deep dive: purpose.md · framework.md · cheatsheet.md

13 reusable patterns that encode proven solutions:

IVD works out of the box with zero configuration. Optional settings for advanced use:

cp .env.example .env

Embeddings are not shipped in the repo — they are generated locally. To enable ivd_search:

export OPENAI_API_KEY=your-key
./mcp_server/devops/embed.sh          # generate (~$0.01)
./mcp_server/devops/embed.sh --force  # regenerate all
./mcp_server/devops/embed.sh --dry-run # preview what gets embedded

A hosted IVD MCP server is available for users who prefer not to run it locally.

Request access: [email protected]

Once you have an API key, use the URL that matches your client:

POST to /sse is also accepted (alias for Streamable HTTP) for clients that misconfigure the base URL; /mcp is still recommended for Copilot.

VS Code / GitHub Copilot (.vscode/mcp.json — remote URL must end with /mcp):

{
  "mcpServers": {
    "ivd-remote": {
      "type": "sse",
      "url": "https://mcp.ivdframework.dev/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

Cursor (Settings → Features → MCP):

{
  "servers": {
    "ivd-remote": {
      "type": "sse",
      "url": "https://mcp.ivdframework.dev/sse",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ivd-remote": {
      "url": "https://mcp.ivdframework.dev/sse",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

All 15 tools are available on the hosted server, including ivd_search (embeddings are pre-generated).

# Setup
./mcp_server/devops/setup.sh             # Create venv, install deps

# Run tests
./mcp_server/devops/test.sh              # All tests (unit + e2e)
./mcp_server/devops/test.sh --unit       # Unit only
./mcp_server/devops/test.sh --e2e        # E2E only

# Embeddings (requires OPENAI_API_KEY)
./mcp_server/devops/embed.sh             # Generate embeddings
./mcp_server/devops/embed.sh --dry-run   # Preview what gets embedded
./mcp_server/devops/embed.sh --force     # Regenerate everything

# Search embeddings locally (requires generated brain + OPENAI_API_KEY)
./mcp_server/devops/search.sh "query"

A comprehensive book on Intent-Verified Development — the cognitive foundations, case studies, and the full methodology — is coming soon.

Issues, bug reports, and recipe suggestions are welcome. See CONTRIBUTING.md for guidelines.

MIT · Created by Leo Celis