The Canonical Intent-Driven Engineering Repository
- Mark Kendall
- 7 hours ago
- 4 min read
The Canonical Intent-Driven Engineering Repository
The Repository Every New AI Project Should Start From
The Canonical Intent-Driven Engineering Repository
One of the questions I receive most often is surprisingly simple.
“Where do I start?”
Not:
“How do I prompt Claude?”
Not:
“How do I use MCP?”
Not:
“How do I write better agents?”
Instead…
“What should my repository actually look like?”
After building numerous AI-enabled delivery projects and experimenting with different layouts, I’ve settled on a structure that consistently scales—from a single developer to enterprise teams.
This article describes that repository.
Think of it as the official starting point for Intent-Driven Engineering.
Philosophy First
Traditional projects begin with code.
Intent-Driven Engineering begins with understanding.
The repository is organized so that every AI system—Claude Code, Codex, Gemini CLI, Cursor, or future models—can answer four questions before writing a single line of code:
Why are we building this?
What already exists?
What constraints must never be violated?
What exactly should happen next?
Everything else is secondary.
Repository Layout
project-root/
.claude/
settings.json
intent/
backlog/
completed/
context/
skills/
agents/
hooks/
templates/
docs/
decisions/
diagrams/
src/
tests/
.github/
workflows/
Notice something important.
There is very little magic.
Most of the repository is simply organized knowledge.
The README isn’t for GitHub.
It’s for humans and AI.
It should answer:
What does this system do?
How do I run it?
How do I contribute?
Where is the intent?
Example
# Customer Portal
Purpose
Modern customer self-service portal.
Primary Intent
See intent/current-feature.md
Architecture
See context/architecture.md
Development
Use Claude Code or your preferred AI coding assistant.
.claude/
This is where Claude-specific configuration lives.
.claude/
settings.json
This directory contains instructions specific to Claude Code.
The rest of the repository remains model-agnostic.
That separation is important.
It means another AI assistant can be swapped in later without reorganizing the project.
Claude should immediately understand:
coding standards
testing philosophy
branching strategy
architecture rules
forbidden patterns
Example
Never bypass authentication.
Always write tests.
Never duplicate business rules.
Follow repository architecture.
Read current-feature.md before implementing.
Nothing here should describe a feature.
It describes how the AI behaves inside the repository.
intent/
This is the heart of the repository.
intent/
backlog/
completed/
Every implementation starts here.
This document rarely changes.
It answers:
Why does this system exist?
Example
Purpose
Enable customers to manage insurance policies online.
Business Goals
Reduce call center volume
Increase self-service
Improve customer satisfaction
This is what the AI works from.
It replaces enormous prompts.
Example
Feature
Customer Notification Preferences
Business Outcome
Reduce support calls.
Requirements
Allow email preferences
Allow SMS preferences
Persist selections
Constraints
Do not break existing notifications.
Must follow current architecture.
Success Criteria
Existing tests pass.
New integration tests added.
This single document becomes the implementation contract.
context/
Large language models need context.
Not prompts.
Context.
Store permanent project knowledge here.
These documents evolve slowly.
They’re referenced repeatedly.
Describe:
major services
APIs
databases
event flows
deployment
No implementation details.
Only architecture.
The rules developers constantly forget.
Examples
Premium customers receive priority processing.
Claims older than 90 days require supervisor approval.
Notifications must be logged.
Enterprise language matters.
Subscriber
Policy
Coverage
Agent
Beneficiary
AI should never invent terminology.
skills/
Skills encapsulate repeatable expertise.
Examples
Each skill performs one job exceptionally well.
Small.
Focused.
Reusable.
agents/
Agents coordinate work.
Example
Planner
↓
Developer
↓
Reviewer
↓
QA
Each has one responsibility.
No giant super-agent.
hooks/
Hooks enforce consistency automatically.
Examples
Before implementation:
Validate intent
Check architecture
Before PR:
Run tests
Verify documentation
Update changelog
Hooks eliminate forgotten steps.
templates/
Never start with a blank document.
Provide templates for:
Feature
Bug
Architecture Decision
API
Database Change
Consistency compounds over time.
docs/
Architecture Decision Records
Design discussions
Reference diagrams
Meeting outcomes
These are long-lived organizational memory—not prompts.
src/
Your application code.
Notice how little attention we’ve given it.
That’s intentional.
The code is an output of the repository, not its organizing principle.
tests/
Every feature should include:
Unit tests
Integration tests
End-to-end tests (when appropriate)
Intent without verification is just documentation.
GitHub Actions
Automate everything possible.
Examples:
Intent validation
Linting
Test execution
Security scanning
Documentation verification
AI should spend its time solving problems, not remembering checklists.
The Development Workflow
Every feature follows the same lifecycle:
Capture the business intent.
Refine it into intent/current-feature.md.
Review architecture and business context.
Plan the implementation.
Generate code.
Run automated validation.
Review and improve.
Open a pull request.
Merge only after governance checks pass.
Archive the completed intent into intent/completed/.
Notice that prompts are never the primary artifact.
Intent is.
Why This Structure Works
This repository separates stable knowledge from changing work:
Intent defines what is being built.
Context explains why and how the system works.
Skills encode reusable expertise.
Agents coordinate specialized work.
Hooks enforce quality automatically.
Source code becomes the product of this process, not the starting point.
Because these responsibilities are clearly separated, any capable AI coding assistant—not just Claude Code—can understand the project with minimal prompting and produce more consistent, maintainable results.
Clone This Repository and Build
If you’re starting a new AI-enabled software project today, don’t begin with src/.
Begin with intent.
Create the repository structure first. Capture the business outcome before the implementation details. Give your AI assistants durable context instead of rewriting the same prompts every day.
Software projects have always had source code.
The next generation of projects will have source intent.
And that may become the most valuable asset in the entire repository.
Comments