Technical Deep Dive
The duo/ab Protocol Infrastructure
Most teams hit a ceiling with AI tools. Chat-based workflows work for small tasks, but context resets kill compound progress. The protocol solves this: structured markdown files in Git that grow with your project, so every AI interaction builds on the last.
The protocol family (uno/duo/tre) is designed for different working modes. This page documents duo/ab specifically, the Construct protocol for software development.
Watch the Overview. See how the protocol works in practice
The Atomic Interaction Model
Every interaction follows the same five phases, whether you're planning architecture or fixing a bug.
Each cycle's RECORD makes the next cycle's LOAD richer. That's the compound effect.
LOAD
Read context files, check git status
CLARIFY
Confirm understanding before acting
EXECUTE
Do the work
RECORD
Update docs, commit immediately
REFLECT
Surface improvements, flag drift
The cycle runs automatically. What changes is scope. ..architect expands to full context (strategy + execution files), ..builder stays lean (CLAUDE.md + TODO.md). No ..end or ..exit. RECORD commits every interaction.
The 4 Habits
The atomic cycle is the engine. These four habits are what make it compound.
Plan in Markdown, Not Jira
TODO.md and TASKS/ are your tactical playbook. AI reads them every session. No board, no grooming.
Protect Decisions, Not Code
DECISIONS.md and CONSTRAINTS.md guard your strategic playbook. Code is cheap. Direction isn't.
Align with Files, Not Meetings
PRFAQ is the compass. AI reads goals, principles, and constraints before writing a line of code.
Measure Compound, Not Output
PROGRESS.md carries what happened. Each RECORD makes the next LOAD richer. That's the J-curve.
Each habit reinforces the others. The system works because it's one loop, not four separate habits.
Understanding the Four Layers
Every developer progresses through these layers. Most get stuck at Layer 2. Here's why, and how to escape.
Layer 1: Chat Interface
You use Claude, ChatGPT, or Cursor in its default state. Fast to start, but context resets constantly.
Example: Copy-pasting code snippets, losing history when you refresh.
Layer 2: Custom Instructions
You add system prompts, create .cursorrules files, try to inject "memory" into every session.
Ceiling: You hit the 41KB wall. Chat history bloats. The AI forgets your architectural decisions. 85% of your token budget is wasted on "thinking" that could be summarised.
Layer 3: Transparent Infrastructure
You build structured markdown files (role.md, context.md, etc.) that agents read/write automatically via MCP.
This is where you escape the ceiling. Context is Git-managed. Agents reference files instead of relying on fragile chat memory.
Layer 4: Context Servers at Scale
You run dedicated context servers, custom MCP implementations, and multi-agent orchestration.
This is enterprise-grade infrastructure. You don't need this unless you're running AI at organizational scale.
Most developers never reach Layer 3. They bounce between Layer 1 and Layer 2, hitting the same context walls over and over. Layer 3 is the breakthrough. It's where you stop fighting the tool and start building systems that scale.
How the Protocol Works
A transparent system built on three principles: structured files, agent roles, and Git-based context management.
The protocol gives you context files in Git. Layer 4 scales to team-wide context servers.
The Seven Files
Two files run the engine. The rest serve the four habits.
Step 1
We work like this
These two files run the atomic cycle. Every session starts here.
CLAUDE.mdTechnical context: stack, patterns, standards.
▶See what this looks like
Example:
Tech Stack
• React 18 + TypeScript (strict mode)
• Tailwind CSS v4.0 (CSS variables, no config file)
• Vite for build tooling
File Structure
• /features/public/ User-facing features
• /data/ Business data
• /types/ TypeScript types
AI learns the codebase structure instantly. No "how do we handle styling?" questions.
ROLE_PROTOCOL.mdScope modifiers and the atomic cycle.
..architect for full scope, ..builder for lean.
▶See what this looks like
Scope modifiers:
..architect → Expand to full scope
..builder → Confirm lean scope
Scope changes, cycle stays the same. Every interaction runs LOAD → CLARIFY → EXECUTE → RECORD → REFLECT.
Step 2
We work on this
PRFAQ.mdThe destination. AI reads this first.
Product vision and strategy. Where we're going and why.
▶See what this looks like
Example:
Instead of buried vision docs, we write:
"We're teaching product teams to compound their effort with AI. Success = PMs create GitHub context in 90 minutes. Why it matters. Their work finally gets seen by engineers."
AI reads this first to understand the destination, not the next task.
Step 3
We split our work
TODO.mdAI's work queue (with acceptance criteria).
▶See what this looks like
Example:
- [ ] Add webinar CTA to ForProductTeams
- AC: Button text "Watch the 30-Min Webinar"
- AC: Links to YouTube URL
- AC: Uses secondary button styling
Acceptance criteria make "done" verifiable. No ambiguity.
TASKS/Your work queue. Human tasks tracked in markdown.
Step 4
I learn, we go faster
DECISIONS.mdWhy we chose this (ADRs).
▶See what this looks like
Example ADR:
DEC-009: React Router (not Next.js)
Context. Landing page needed routing
Decision. Use React Router, not Next.js
Rationale. SPA works, no SEO/SSR needed, simpler deployment
AI understands context behind decisions. Can apply same reasoning to new features.
PROGRESS.mdWhat shipped, when, and why. Each entry makes the next session richer.
PRINCIPLES.md and CONSTRAINTS.md are distilled from DECISIONS.md as patterns emerge.
The Harness
You write the rules in markdown. The AI follows them. Until it saves context somewhere you can't search, or a session ends with work uncommitted, or the next session starts from scratch.
The protocol is the playbook. Any LLM can read it. The harness is the coach in the room. Always present, catches you drifting, never punishes.
Protocol
The playbook
Markdown files that show any AI what good looks like. Portable across every LLM that reads files.
Works everywhere
Harness
The coach in the room
Hooks in .claude/settings.json that remind you of the playbook and catch drift. Claude Code specific.
Travels in git. Clone the repo, get both.
What the coach does
Keeps your memory in the repo
AI tools scatter context across their own systems by default. You can't search it, version it, or share it. The coach keeps decisions, constraints, and progress in your markdown files, in git, where they compound.
Reminds you to save your work
Thirty minutes of decisions and code, session closes, nothing saved. The coach notices uncommitted changes and reminds you before the session ends. Not a wall. A tap on the shoulder.
Loads your context so you start informed
Every session starts by loading what's already there. The protocol knows what changed since last time. No more "where did we leave off?" The AI reads your files, checks git, and picks up where you stopped.
Guardrails, not taskmasters.
The hooks prevent data loss. They don't police every action. No forced commits after each edit. No mandatory progress updates. The protocol guides and structures. The harness catches the things that actually cost you. Forgotten saves, scattered context, sessions that start from zero.
The protocol is the playbook. The harness is the coach. Clone the repo, get both.
duo/ab Protocol: Architect + Builder Workflow
The Discovery. We tried loading all 7 markdown files for every session. It cost 15% of the token budget before any work began. Then we realised Architect needs strategy files (PRFAQ.md, DECISIONS.md, CONSTRAINTS.md), Builder only needs execution files (TODO.md, CLAUDE.md).
Token cost dropped from 15% to 5%. That's when role-based context clicked.
Every interaction follows the same five-phase cycle. What changes is scope, how much context you load.
..architectFull Scope
Design, strategy, planning
- • LOAD PRFAQ, DECISIONS, CONSTRAINTS, PROGRESS
- • CLARIFY Validate approach before building
- • EXECUTE Write specs, design architecture
- • RECORD Update DECISIONS.md, TODO.md
- • REFLECT Flag risks, surface trade-offs
..builderLean Scope
Write code, execute tasks
- • LOAD CLAUDE.md, TODO.md, TASKS/
- • CLARIFY Confirm task, check AC
- • EXECUTE Write code, implement feature
- • RECORD Update PROGRESS.md, commit
- • REFLECT Flag what didn't work
Key Features
- ✓Acceptance Criteria. Every task has testable conditions. "Done" is verifiable, not ambiguous.
- ✓Automatic RECORD. Every interaction commits decisions and context. No ceremony required. Fossilisation is built into the cycle.
- ✓Token Budget Awareness. Full scope loads ~15%, lean scope loads ~5%. Know your costs.
- ✓Drift Detection. REFLECT surfaces when code diverges from documented decisions.
- ✓Recovery Protocol. 3-level emergency recovery (git reset, dependency reset, full environment reset).
Transparent
Every decision is visible in markdown. No hidden context.
Git-Managed
Version control for AI context. Rollback bad decisions.
Scalable
No token limits. Context grows with your project.
Ready to Implement?
Clone the template, follow the learn guide, and run your first atomic cycle. The protocol is open source. Start building today.