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 scope, how much context you load.
Two Scopes, One Cycle
One playbook, two ways to read it. duo separates planning from implementation through scope, not modes.
..architectRead the full playbook
Strategy, decisions, constraints
- • 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
..builderRead the tactical chapter
CLAUDE.md, TODO.md, execute
- • 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
Why separate scope? Architect reads the whole playbook for planning. Builder reads the tactical chapter for implementation. Same playbook, different depth.
Your first ..architect session sets the tone. Bring your PRFAQ, your project's compass. The AI will read it and ask questions you haven't thought of yet. That's the ritual: tell it where you're going. It'll help 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
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
Planning a feature
..architect # Expand to full scope
"Add user authentication" # AI runs the atomic cycle:
# LOAD → reads PRFAQ, DECISIONS, CONSTRAINTS
# CLARIFY → "OAuth or email/password? Session or JWT?"
# EXECUTE → writes spec in TODO.md with AC
# RECORD → updates DECISIONS.md
# REFLECT → flags: "Consider rate limiting"Building the feature
..builder # Confirm lean scope
"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
..architect # Full scope for hygiene
"..hygiene" # LOAD → checks all file sizes
# EXECUTE → archives old entries
# RECORD → commits cleanupNotice: you never run ..end or ..exit. The RECORD step commits after every interaction. Fossilisation is automatic.
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: Use full scope for simple tasks (wastes tokens)
- 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. Plan with full scope ..architect "Add login page" # LOAD → CLARIFY → EXECUTE → RECORD → REFLECT # 4. Build with lean scope ..builder "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.
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.
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.
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.
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.
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.