Intent-Oriented Programming (IOP)

A research project exploring post-code software engineering.

The Question

In a future where all code is written by AI, what does software engineering look like?

Code authorship is ending. AI will write the implementations. But software still needs to be built, maintained, evolved, and understood. What replaces the practices, tools, and mental models we currently use?

IOP is one attempt to answer that question.

The Core Idea

• Intent becomes the source of truth — code becomes a build artifact
• The Orchestrator — an AI system specialized for intent reasoning, not just code generation
• You debug intent, not code — when things break, you fix the spec
• Teams share an intent graph — not a codebase
• Domain-specific intents — product, design, infrastructure, security each have specialized schemas
• Intent frameworks — community-built packages, like npm but for intent patterns

---

Documentation

1. Foundation

Document	Description
Whitepaper	Formal definition of the IOP paradigm
Introduction	Why IOP exists, the problem it solves
Glossary	Core vocabulary: Prompt, Kind, Orchestrator, etc.
Architecture	Visual guide to Planning and Implementation cycles

2. The Language

Document	Description
Language Specification	Full syntax and semantics of .iop files
Context Gating	Prompt kinds and allowed blocks matrix

3. System Architecture

Document	Description
The Orchestrator	Compilation, graph building, semantic diffing
Implementation Details	Code Anchors, Ownership Zones, Manifests
Developer Workflow	Planning and Implementation cycles
Context Management	Graph-Walking Retrieval for agents

4. Usage & Tools

Document	Description
CLI Reference	iop validate, compile, format commands
Adoption Guide	Bringing IOP to existing projects
Collaboration Guide	Git workflows and team strategies
Implementation Roadmap	Building the toolset

5. Ecosystem & Vision

Document	Description
Intent Domains & Frameworks	Specialized domains, community frameworks
Future Vision	Visual editors, IDE integration, prompt-only views
Example Walkthrough	Step-by-step feature addition

---

Project Structure

iop-docs/
├── README.md                 # This file
├── whitepaper.pdf            # Formal paradigm definition
├── whitepaper.tex            # LaTeX source
├── CONSOLIDATION_PLAN.md     # SPL integration plan
│
├── spec/                     # Specification documents
│   ├── 00-introduction.md
│   ├── 01-glossary.md
│   ├── 02-architecture.md
│   ├── 03-language-spec.md   # ★ Language specification
│   ├── 15-intent-domains.md  # ★ Domain frameworks ecosystem
│   ├── 04-context-gating.md  # ★ Prompt kinds & blocks matrix
│   ├── 05-orchestrator.md
│   ├── 06-implementation.md
│   ├── 07-developer-workflow.md
│   ├── 08-context-management.md
│   ├── 09-cli-reference.md
│   ├── 10-adoption-guide.md
│   ├── 11-collaboration.md
│   ├── 12-roadmap.md
│   ├── 13-future-vision.md
│   └── 14-example-walkthrough.md
│
├── language/                 # Language implementation (Langium)
│   └── packages/
│       ├── language/         # Grammar, validator, LSP
│       ├── cli/              # Compiler CLI
│       └── extension/        # VSCode extension
│
├── examples/                 # Example projects
│   └── ifvisible/            # Visibility detection library
│
├── documents/                # Legacy location (see spec/)
│
└── archive/                  # Historical documents
    ├── ideation-docs/        # Original design notes
    └── legacy-language/      # Original HCL-like grammar

---

Key Concepts

Prompt Kinds

Every prompt has a kind that determines its role and allowed configuration:

Kind	Purpose	Allowed Context
product	Product requirements	design
design	UI/UX specifications	design
technical	Implementation architecture	technical, data, api, testing, security, delivery, ops
data	Data models	data, technical
api	API contracts	api, technical, security, testing
testing	Test strategies	testing, technical
security	Security requirements	security, technical, api
delivery	CI/CD processes	delivery, technical, ops
ops	Operations	ops, technical, delivery
task	Simple tasks	(none)

The Dual-Cycle Workflow

Planning Cycle (Human ↔ Orchestrator)

1. Author/modify prompts
2. Orchestrator validates and produces patch plan
3. Human reviews and approves

Implementation Cycle (Orchestrator ↔ Agent)

1. Orchestrator dispatches approved tasks
2. Agent executes within constraints
3. Verification gates check results
4. Manifest updated on success

---

Language Evolution

IOP v2 introduces significant improvements:

Feature	v1	v2
Syntax	HCL-like with {}	Indentation-based
Root element	intent "name" {}	Document:
Terminology	Intent	Prompt
Schema enforcement	Basic	Strict with context gating
File extension	.intent	.iop (.intent supported)

See Appendix B of Language Spec for migration guide.

---

Getting Started

1. Read the Introduction - spec/00-introduction.md
2. Learn the Language - spec/03-language-spec.md
3. Understand Context Gating - spec/04-context-gating.md
4. Try an Example - spec/14-example-walkthrough.md

---

Related Resources

• Structured Prompt Language (SPL) - The indentation-based syntax implementation that powers IOP v2
• Langium - The language framework used for grammar and LSP implementation

---

Intent-Oriented Programming: Where humans architect meaning, and machines execute with precision.