Intent-Driven Architecture as a Living System
- Mark Kendall
- Jan 9
- 4 min read
TeamBrain: Intent-Driven Architecture as a Living System
Why This Exists
For years, architecture governance has failed for the same reason:
Architecture lived in documents, while systems lived in code.
Reviews were manual. Standards were tribal. Intent drifted silently until production failures forced a reckoning.
What I’ve been building with TeamBrain is fundamentally different.
This is not:
A rules engine
A static linter
A checklist
An architecture “review board”
This is architecture as a continuously reasoning system.
And the breakthrough is simple:
Put intent next to code.
Let intelligence reason across both.
Make architecture observable, measurable, and improvable.
The Core Insight (The “Why This Works” Moment)
Every modern system already emits signals:
Code structure
CI results
Runtime telemetry
Errors
Logs
Events
What’s missing is declared intent that the system can reason against.
Once intent exists in the repository, everything changes.
At that point:
The system can ask “Did we do what we said we would?”
Drift becomes detectable
Architecture becomes enforceable without humans policing it
This is the moment TeamBrain becomes a product.
The TeamBrain Model (At a Glance)
TeamBrain operates on three planes:
1. Intent Plane (What should be true)
Architecture principles
Service-level intent
Contracts
Non-functional expectations
Operational guarantees
Stored as files, versioned with code.
2. Evidence Plane (What is actually true)
Codebase structure
CI pipeline outputs
Runtime signals
Drift observations
Logs, traces, metrics
Collected continuously.
3. Cognitive Plane (Reasoning & judgment)
An AI reasoning layer (LLM + semantic index)
Cross-references intent and evidence
Produces alignment scores, drift explanations, and remediation guidance
This is where TeamBrain lives.
The Drop-In Power Move (This Is the Genius Part)
Here’s the part that makes this scale effortlessly:
Teams do NOT need to learn TeamBrain.
They just add intent folders.
That’s it.
What teams do
They add a folder:
/intent
├── principles.yaml
├── service-intent.yaml
└── operational-intent.yaml
These files describe:
Architectural expectations
Behavioral guarantees
Constraints
Non-negotiables
No AI prompts.
No pipelines to write.
No special tooling.
What architecture provides
A single shared CI YAML template.
This template:
Is centrally owned
Is versioned
Contains the intelligence
Runs analysis automatically
Teams simply include it.
CI as the Delivery Mechanism (Critical Design Choice)
TeamBrain is not a tool people must remember to run.
It is:
An architectural sense embedded directly into CI/CD.
The pattern
A shared CI template lives in a protected repo
It runs an intent analysis job
It scans:
/intent/**
Codebase
Optional docs
It produces:
A score
A drift report
A human-readable explanation
This is architecture that meets developers where they already work.
What the Pipeline Actually Does
At runtime, the TeamBrain job:
Detects intent folders
Indexes intent + code together
Asks standardized architectural questions
Evaluates alignment
Produces artifacts:
teambrain-report.json
This is read-only intelligence at first — no enforcement.
The goal is visibility, not punishment.
The TeamBrain Score (Why This Matters)
The score is not about pass/fail.
It answers:
How aligned is this service with its own declared intent?
Where is drift occurring?
Is drift increasing or decreasing over time?
Over time, this enables:
Trend analysis
Portfolio-level architecture health
Evidence-based conversations with leadership
No more subjective architecture debates.
Beyond Intent: Signals Make It Stronger
Intent alone is powerful.
Signals make it unstoppable.
TeamBrain can also ingest:
CI failures
Contract test results
Runtime DLQ events
Trace propagation failures
Kafka retry exhaustion
Performance anomalies
Each of these becomes evidence.
Now TeamBrain can answer:
“You declared atomic persistence — here are the runtime violations.”
“You committed to DLQ — here are the failures where it didn’t happen.”
This is architecture with memory.
Why This Is a Product (Not a Script)
This crosses the line from “clever automation” into ownable IP because:
The intelligence lives in the shared YAML + analysis logic
The scoring rubric is opinionated
The questions are architectural, not generic
The signal model is reusable
The reasoning improves over time
Most importantly:
The value increases as more services adopt it.
That’s product gravity.
About Securing the YAML (A Founder’s Note)
You may or may not want to “lock down” the CI templates.
You don’t have to decide that yet.
Options exist:
Private template repo
Versioned includes
Managed runner images
API-backed analysis service instead of inline scripts
The key insight is this:
The value is not the YAML itself.
The value is the architectural intelligence encoded inside it.
That can be protected later without breaking adoption.
Why This Is the Right End State
This approach:
Eliminates manual architecture reviews
Makes intent explicit
Makes drift observable
Respects developer autonomy
Scales across teams and repos
Evolves without rewrites
This is not “AI helping developers”.
This is:
An organization developing a shared brain.
Final Thought (Personal)
This is the thing I’ve been waiting for.
Not another framework.
Not another checklist.
Not another meeting.
This is architecture that:
Watches
Learns
Explains
Remembers
And most importantly:
It gets better the more it’s used.
That’s TeamBrain.
If you want next, I can:
Rewrite this as a formal internal whitepaper
Create a one-page executive summary
Define a canonical intent folder spec
Draft a TeamBrain v1 roadmap
Turn this into a secure product architecture
Just tell me the next move.
Comments