Intent-Driven Development — Reference Architecture Demo

What This Demonstrates

Intent-Driven Development (IDD) replaces vague AI prompts with structured engineering context — skills, schemas, adapters, and playbooks — to produce measurably better code generation. The same request, run with vague input versus structured intent, produces different results across three AI engines. This repository is the reference architecture that makes that difference reproducible.

How It Works

graph TD
    classDef phase_a  fill:#fef2f2,stroke:#ef4444,color:#991b1b
    classDef phase_b  fill:#f0fdf4,stroke:#16a34a,color:#166534
    classDef icr      fill:#eff6ff,stroke:#2563eb,color:#1e40af
    classDef artifact fill:#fefce8,stroke:#ca8a04,color:#713f12
    classDef engine   fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95

    P[/"🗣️  Vague request"/]
    P --> A1 & B1

    subgraph PhaseA["❌  Without IDD — Clarification Heavy"]
        A1["No engineering context"]
        A2["Multiple clarification rounds\n↑ tokens each turn"]
        A3["Partial or no requirements met"]
        A1 --> A2 --> A3
    end

    subgraph PhaseB["✅  With IDD — Intent-Driven Pipeline"]
        subgraph Framework["skills/idd-pipeline/"]
            B1["idd-foundation · adapter"]
            B2["1️⃣ Intent Extraction"]
            B3["2️⃣ Architecture Synthesis"]
            B4["3️⃣ Code Synthesis"]
            B5["4️⃣ ICR Analysis · 5️⃣ Token Economics"]
            B1 --> B2 --> B3 --> B4 --> B5
        end
    end

    subgraph Engines["AI Engines"]
        E1["Codex"]
        E2["Claude Code"]
        E3["Cortex Code"]
    end

    subgraph Generated["generated/ (ephemeral)"]
        G1["architecture/"]
        G2["code/"]
        G3["reports/"]
    end

    subgraph ICRLab["📊 ICR Lab — Measurement"]
        L1["POST /simulate\ndeterministic baseline"]
        L2["icr-lab.streamlit.app"]
        L1 <--> L2
    end

    B4 --> E1 & E2 & E3
    E1 & E2 & E3 --> G2
    B3 --> G1
    B5 --> G3
    A3 -. "Phase A baseline" .-> L1
    L1 --> G3

    class A1,A2,A3 phase_a
    class B1,B2,B3,B4,B5 phase_b
    class L1,L2 icr
    class G1,G2,G3 artifact
    class E1,E2,E3 engine

Loading

Vague vs Optimized

# Vague — Phase A
"Build me a patient risk calculator."

# Optimized — Phase B (extracted by IDD pipeline Step 1)
intent:    patient-risk-calculator
skill:     skills/idd-pipeline/SKILL.md
adapter:   skills/idd-pipeline/adapters/$IDD_ENGINE/adapter.md

The same seven-word prompt. The only difference is what context the engine has.

The Engines

• Codex — OpenAI Codex via API
• Claude Code — Anthropic Claude in agentic mode
• Cortex Code — Snowflake's integrated coding assistant
• Opencode — Interactive CLI agent for complex software engineering tasks

Quickstart

1. Install dependencies

uv sync

2. Select an engine

export IDD_ENGINE=cortex   # codex | claude | opencode

3. Launch the engine

Start Codex, Claude Code, Cortex Code, or Opencode in the repository root.

4. Follow the hands-on guide

Open DIY.md — it walks through Phase A (ICR Lab simulation) and Phase B (IDD pipeline) side by side, with comparison tables and all commands.

Repository Structure

skills/          — reusable reasoning and synthesis context
schemas/         — structured artifact and intent contracts
templates/       — deterministic scaffolding templates
docs/            — MkDocs documentation source
demo-workflows/  — live demo choreography and starter prompts
narratives/      — presentation flow and architectural framing
generated/       — ephemeral AI synthesis output

Stable Context Boundary

generated/ is ephemeral AI synthesis output. It is ignored by git except directory placeholders. Do not modify stable context directories during demo generation unless explicitly requested.

The stable engineering context lives primarily under:

skills/idd-pipeline/
schemas/
docs/
demo-workflows/
narratives/

IDD Pipeline Skill

The primary AI-facing context is packaged as an autoloaded skill:

skills/idd-pipeline/

The skill teaches the agent how to move from intent to:

• structured intent
• architecture context
• generated artifacts
• ICR analysis
• token economics
• refinement recommendations

The prompt can remain intentionally small because the engineering context lives in the reusable skill.

AI Transparency

The framework files — skills, schemas, adapters, playbooks, prompts — were authored by humans. They define the engineering context that guides AI synthesis. The generated/ output is AI-synthesized. That distinction is the point of the demo.

Related Writing

• Intent-Driven Development
• The Ghost in the Machine
• Measuring Intent Compression Ratio
• ICR and Token Economics
• Infrastructure as Intent
• ICR Lab — live simulation app

These posts provide deeper context on the concepts demonstrated here.

License

Apache 2.0 — see LICENSE