The Intent-Driven Registry: Start Simple, Then Make It Intelligent

Mark Kendall
3 hours ago
7 min read

The Intent-Driven Registry: Start Simple, Then Make It Intelligent

One of the most common objections to governance in Intent-Driven Engineering is also one of the most reasonable:

“You want every Intent registered, owned, versioned, dated, and governed. Who is going to maintain all of that?”

The answer should not be the developer.

If maintaining an Intent Registry becomes another manual administrative responsibility, teams will resist it, developers will work around it, and eventually the registry will become stale.

Intent-Driven Engineering should work differently.

Developers create Intent. The platform creates governance.

And you don’t need to build an enormous AI platform to get started.

Version 1 can be remarkably simple.

What Is an Intent-Driven Registry?

An Intent-Driven Registry is the enterprise record of the Intent artifacts driving software delivery.

At a minimum, it answers questions such as:

What Intent exists?
Who owns it?
What version is current?
When was it created or changed?
Which repository contains it?
What domain or service does it belong to?
What was the actual Intent?
What Inputs does it accept?
What Outputs does it produce?
What defines success?

Over time, the registry can become much more intelligent.

But don’t start there.

Start by making sure every Intent entering the delivery system is structurally sound.

The Four Pillars of an Intent File

For an Intent artifact to be useful, it needs at least four clearly defined elements:

1. Intent

What are we trying to accomplish, and why?

Not implementation instructions.

Not “create three classes and two endpoints.”

The Intent describes the desired outcome.

2. Inputs

What information, events, requests, dependencies, or conditions enter this capability?

Inputs establish the boundary of the work.

3. Outputs

What must the capability produce?

Outputs might be API responses, events, records, state changes, files, notifications, or other observable results.

4. Success Criteria

How do we objectively know the Intent has been satisfied?

This is critical.

Success Criteria turn Intent from prose into something that can eventually be verified by humans, agents, tests, CI/CD pipelines, or other automated systems.

These four elements form the minimum contract:

Intent → Inputs → Outputs → Success Criteria

If an Intent file doesn’t contain them, it shouldn’t enter an Intent-Driven delivery pipeline.

But We Need Governance Too

The four pillars describe the work.

The registry also needs enough metadata to govern the work.

A simple Intent file could therefore begin with YAML front matter:

---

id: INT-BILL-042

name: Billing Adjustment API

owner: billing-platform

version: 1.0.0

domain: billing

status: active

---

Followed by the actual Intent:

## Intent

Allow authorized customer-service representatives to issue

billing adjustments against an existing customer invoice.

## Inputs

- Customer ID

- Invoice ID

- Adjustment amount

- Adjustment reason

## Outputs

- Adjustment ID

- Adjustment status

- Updated billing balance

- Audit event

## Success Criteria

- Authorized users can submit an adjustment.

- Invalid invoices are rejected.

- The customer balance reflects an approved adjustment.

- Every adjustment produces an auditable event.

That’s enough to start.

And here’s the important part:

Don’t ask somebody to manually copy this information into a registry.

Automate it.

Version 1: Validate and Register

The first implementation of an Intent Registry only needs four major components:

Developer / AI Coding Agent

Intent File

Intent Hook

+-----+-----+

| |

VALID INVALID

| |

v X

Registry API FAIL

Intent Registry Database

That’s it.

You don’t need a vector database.

You don’t need a knowledge graph.

You don’t need a sophisticated agent architecture.

You don’t even need an LLM to perform the initial validation.

The first goal is much simpler:

No Intent enters the governed delivery process without meeting the enterprise Intent contract.

What Does the Hook Do?

The hook is the enforcement point.

Whenever an Intent is created or modified, the hook runs a validator.

Conceptually:

Intent changed

↓

Does an Intent file exist?

↓

Does it contain required registry metadata?

↓

Does it contain Intent?

↓

Does it contain Inputs?

↓

Does it contain Outputs?

↓

Does it contain Success Criteria?

↓

Is the version valid?

↓

PASS

↓

POST to Registry API

Anything missing?

Fail.

And tell the developer exactly why.

A Simple Intent Validation Hook

The actual implementation can vary depending on your engineering environment, but the hook itself should remain thin.

For example:

#!/bin/bash

echo "Validating Intent artifact..."

INTENT_FILE="intent.md"

if [ ! -f "$INTENT_FILE" ]; then

echo "ERROR: Required Intent file not found."

exit 1

required_sections=(

"## Intent"

"## Inputs"

"## Outputs"

"## Success Criteria"

)

for section in "${required_sections[@]}"; do

if ! grep -q "$section" "$INTENT_FILE"; then

echo "ERROR: Missing required section: $section"

exit 1

done

required_metadata=(

"id:"

"name:"

"owner:"

"version:"

)

for field in "${required_metadata[@]}"; do

if ! grep -q "$field" "$INTENT_FILE"; then

echo "ERROR: Missing registry metadata: $field"

exit 1

done

echo "Intent validation PASSED."

./register-intent.sh "$INTENT_FILE"

if [ $? -ne 0 ]; then

echo "ERROR: Intent Registry registration failed."

exit 1

echo "Intent successfully registered."

exit 0

This isn’t meant to be the final enterprise validator.

It demonstrates something more important:

The governance happens automatically because the developer is doing normal development work.

The developer doesn’t visit another system.

The developer doesn’t maintain a spreadsheet.

The developer doesn’t manually update a registry.

The pipeline does it.

Put the Intelligence Behind an API

The hook should not write directly into the database.

Instead:

Hook

| POST /registry/intents

Intent Registry API

Database

The hook has one responsibility:

Validate the artifact and submit it.

The Registry API owns persistence and registry rules.

A request might look conceptually like:

{

"id": "INT-BILL-042",

"name": "Billing Adjustment API",

"owner": "billing-platform",

"version": "1.0.0",

"domain": "billing",

"status": "active",

"repository": "billing-services",

"commit": "abc123",

"intent": "Allow authorized customer-service representatives to issue billing adjustments.",

"inputs": [

"customerId",

"invoiceId",

"adjustmentAmount",

"adjustmentReason"

"outputs": [

"adjustmentId",

"status",

"updatedBalance"

"successCriteria": [

"Authorized adjustments are accepted",

"Invalid invoices are rejected",

"Balances are updated",

"An audit event is generated"

]

}

The API can add things the developer shouldn’t have to manage manually:

Registration timestamp
Last-modified timestamp
Repository information
Commit SHA
Registry audit history
Validation status

Now there is one controlled entrance into the Intent Registry.

The Intent File Should Remain the Source Artifact

There is an important architectural distinction here.

Don’t create an Intent file and then require developers to maintain a separate registry file containing essentially the same information.

That creates two sources of truth.

Instead:

Intent File = Developer-owned source artifact

Registry Database = Platform-generated enterprise representation

The registry is derived from the Intent.

The developer changes the Intent.

The system updates the registry.

What Happens When Validation Fails?

This is where governance becomes practical.

Suppose someone submits:

## Intent

Create an API for customer billing adjustments.

## Inputs

Customer ID and amount.

The hook immediately returns:

INTENT VALIDATION FAILED

✓ Intent

✓ Inputs

✗ Outputs

✗ Success Criteria

✗ Owner

✗ Version

This Intent cannot enter the governed delivery workflow.

Add the missing required information and retry.

The AI coding agent can even correct the problem.

The important thing is that an incomplete Intent never silently becomes implementation work.

We’re checking Intent before we’re spending tokens building the wrong thing.

The Registry Can Grow in Four Versions

This is where the architecture becomes much more interesting.

Don’t attempt to build everything on day one.

Version 1 — Validate + Register

The system:

Detects Intent artifacts.
Validates the four pillars.
Validates required metadata.
Validates semantic-version syntax.
Rejects incomplete Intent.
Calls the Registry API.
Stores the Intent.
Records owner, version, repository and timestamps.
Maintains basic history.

This creates the enterprise foundation.

Question answered:

Do we have governed Intent?

Version 2 — Version + History Intelligence

Now the registry begins comparing Intent versions.

It can determine:

What changed?
Who changed it?
When did it change?
Were Inputs changed?
Were Outputs changed?
Did Success Criteria change?
Was ownership changed?
Is the proposed semantic version reasonable?

Now a pull request can say:

INT-BILL-042

Current: 1.3.2

Proposed: 1.4.0

Changes detected:

+ New optional input

+ Two new Success Criteria

+ Existing outputs unchanged

Recommendation:

MINOR VERSION

1.4.0 appears appropriate.

Question answered:

What changed in our Intent?

Version 3 — Semantic Intent Intelligence

Now add semantic retrieval.

The system can identify Intent that means something similar even when developers use different terminology.

A developer proposes:

Create a service allowing agents to correct erroneous customer invoice amounts.

The registry discovers:

INT-BILL-042

Billing Adjustment API

Semantic similarity: 93%

Now the system can recommend:

REUSE

EXTEND

CREATE

This is where technologies such as embeddings and pgvector can become valuable.

Question answered:

Have we already expressed this Intent somewhere else?

Version 4 — Intent Impact & Decision Intelligence

Now the registry becomes an Intent Control Plane.

Relationships between Intent artifacts allow the system to reason about:

Dependencies
Consumers
Shared services
API contracts
Owners
Standards
Breaking changes
Organizational impact
Architectural duplication

A developer proposes changing the Billing Adjustment output.

The system responds:

PROPOSED CHANGE

INT-BILL-042

Potential breaking change detected.

Affected Intent:

INT-COLL-019 Collections

INT-INV-031 Invoice Generation

INT-CARE-011 Customer Care

Current Version:

3.4.2

Recommended Version:

4.0.0

Recommended Action:

Notify affected Intent owners before implementation.

Now the registry isn’t simply telling us what exists.

It is helping determine what should happen next.

Question answered:

If we change this Intent, what does it mean to the enterprise?

From Registry to Intent Control Plane

The progression becomes:

VERSION 1

VALIDATE

↓

VERSION 2

UNDERSTAND CHANGE

↓

VERSION 3

UNDERSTAND SIMILARITY

↓

VERSION 4

UNDERSTAND IMPACT

Or more simply:

Govern → Remember → Understand → Decide

That’s the roadmap.

Why Version 1 Matters

It’s tempting to jump immediately to semantic search, embeddings, AI reasoning, knowledge graphs, and autonomous agents.

Don’t.

Version 1 solves an extremely important problem by itself.

It establishes an enterprise rule:

If an artifact is going to drive AI-assisted implementation, it must first meet the minimum Intent contract.

Every Intent has:

Intent.

Inputs.

Outputs.

Success Criteria.

And every registered Intent has basic governance:

Identity.

Ownership.

Version.

History.

The developer shouldn’t have to become a governance expert to make that happen.

They create the Intent.

The hook validates it.

The API registers it.

The platform governs it.

And tomorrow, the same registry can become intelligent.

That’s how an Intent Registry can evolve from a simple database into an enterprise Intent Control Plane without forcing developers to carry the operational burden.

Start with validation. Automate the governance. Add intelligence when the foundation is trustworthy.

I’d keep that four-version progression as the canonical roadmap. It makes the first implementation very defensible: V1 isn’t trying to be AI magic; it’s establishing trusted Intent data that makes V2–V4 possible.

The Intent-Driven Registry: Start Simple, Then Make It Intelligent

Recent Posts

Comments

Subscribe Form