duo, Construct Protocol

When to Use duo

Good Fit

• Building a web app
• Refactoring a codebase
• Creating a product from scratch
• Prototyping and deploying

Not The Right Fit

• Planning a trip
• Tracking onboarding
• Maintaining documentation
• Simple delegation

→ Use uno for non-code work

The Atomic Cycle

Every interaction, whether you're planning architecture or fixing a bug, follows the same five phases.

Each cycle's RECORD makes the next cycle's LOAD richer.

The cycle runs automatically. What changes between planning and building is the role you are in. Architect designs and gets sign-off. Builder executes the approved plan.

Two Roles, One Cycle

One playbook, two roles. duo separates designing from building, then makes the design stick.

Architect

Design and get sign-off

Strategy, decisions, the plan

• 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

Builder

Build the approved plan

CLAUDE.md, TODO.md, code

• 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

Where do the roles live? Claude Code's native plan mode runs the Architect. You design, it presents a plan, you approve, then it builds. The protocol's job is to make the plan stick. Acceptance criteria land in TODO.md, decisions in DECISIONS.md, so the Builder works from a real contract.

Your first design session sets the tone. Bring your PRFAQ, your project's compass. The AI reads it and asks questions you haven't thought of yet. That's the ritual. Tell it where you're going. It helps you figure out how.

Core Files

my-project/
├── CLAUDE.md           # Technical reference (ground truth)
├── PRFAQ.md            # Product vision (Press Release / FAQ)
├── TODO.md             # Prioritised task list
├── PROGRESS.md         # Session-by-session log
├── DECISIONS.md        # Architecture Decision Records
├── CONSTRAINTS.md      # Principles, rejected approaches
├── TASKS/              # Human-only tasks (priority, todo, blocked, done)
└── README.md           # User-facing docs

The shape it grows into. You begin with three and accumulate the rest; the full set ships in the template.

These files aren't just documentation. They're the protocol's memory. Each one serves a specific phase:

TODO.md + TASKS/: What EXECUTE pulls from. Every task has acceptance criteria. Habit 1
DECISIONS.md + CONSTRAINTS.md: Protect what's expensive to get wrong. Architecture, not code. Habit 2
PRFAQ.md + CLAUDE.md: Ground truth for LOAD. AI reads goals and constraints before acting. Habit 3
PROGRESS.md: Written during RECORD. Makes next session's LOAD richer. Habit 4

How It Works in Practice

Designing a feature

# plan mode, design and get approval first
"Add user authentication" # AI runs the atomic cycle
                          #   LOAD → reads PRFAQ, DECISIONS, CONSTRAINTS
                          #   CLARIFY → "OAuth or email/password? Session or JWT?"
                          #   EXECUTE → writes the spec to TODO.md with AC
                          #   RECORD → updates DECISIONS.md
                          #   REFLECT → flags "Consider rate limiting"

Building the feature

# approve the plan, then build
"Build the auth system" # AI runs the atomic cycle
                        #   LOAD → reads CLAUDE.md, TODO.md
                        #   CLARIFY → "I see the auth spec. Starting with login flow."
                        #   EXECUTE → writes code, tests
                        #   RECORD → updates PROGRESS.md, commits
                        #   REFLECT → "Login done. Signup next session."

Maintenance

"..hygiene"              # AI runs the maintenance pass
                         #   LOAD → checks all file sizes
                         #   EXECUTE → archives old entries
                         #   RECORD → commits cleanup

Notice: you never run ..end or ..exit. The RECORD step commits after every interaction. Fossilisation is automatic. Commands as of v1.3.1, May 2026. The template is the spec.

Safety Features

CLARIFY before acting: AI confirms understanding before executing
AC verification: Tasks only marked done when acceptance criteria pass
Automatic RECORD: Context is committed every interaction. No forgotten decisions.
Drift detection: REFLECT surfaces when code diverges from documented decisions

Anti-Patterns

Don't: Start building a cascading change before the plan is persisted
Don't: Skip CLARIFY on ambiguous requests
Don't: Let PROGRESS.md grow huge. Run ..hygiene
Don't: Write TODO without acceptance criteria

Quick Start

# 1. Clone template
git clone https://github.com/marekgorski/protocol-duo.git my-app
cd my-app && rm -rf .git && git init

# 2. Open with Claude. It reads CLAUDE.md and starts the atomic cycle.

# 3. Design in plan mode
"Add a login page"   # LOAD → CLARIFY → EXECUTE → RECORD → REFLECT
                     # AC lands in TODO.md, decisions in DECISIONS.md

# 4. Approve, then build
"Build login"        # LOAD → CLARIFY → EXECUTE → RECORD → REFLECT

# That's it. No ..end, no ..exit. RECORD commits automatically.

Guided Curriculum: 5 Sessions

Build a real app from scratch. Each session adds a layer. By the end, you have a deployed product and the atomic cycle is second nature.

Session 1

The Protocol

Initialise a duo repo. Create your context files (CLAUDE.md, PRFAQ.md, TODO.md, DECISIONS.md). Run your first atomic cycle. LOAD reads the files, CLARIFY asks what you're building, EXECUTE scaffolds the project, RECORD commits it.

Session 2

Version Control

GitHub as source of truth. Learn Git fundamentals, commits, branches, pull requests. Your RECORD step now pushes to a remote repo. Every decision has history.

Session 3

Deployment

Deploy to Vercel. Push code, get a live URL. Your app is real, accessible to anyone, updated on every push. By now the atomic cycle is becoming habit.

Session 4

Persistence

Add Supabase for real data. Your app stores and retrieves information. No more mock data. DECISIONS.md tracks why you chose this database. CONSTRAINTS.md records what you won't do.

Session 5

The Compound Effect

Look back at what accumulated. Your DECISIONS.md has real architecture records. Your PROGRESS.md shows the journey. Each LOAD reads richer context than the last. This is the compound effect, and it's yours to keep building on.

The compound effect: By session 5, all 4 habits are active. Plans in markdown, decisions protected, goals aligned, sessions compounding. AI doesn't just know your codebase. It knows why your codebase is the way it is.

duo