Di-Atomic Dev Assistant: Human-AI Pair Programming Framework

A lightweight framework for building software projects with AI assistants like Claude Code, Cursor, and Gemini Code Assist.

Managing multiple projects simultaneously or need autonomous agents? Check out Di-Atomic AI Agency - Full production multi-agent system with GitHub orchestration.

🎯 Which Framework Should I Use?

Scenario	Framework	Why
Building 1 project with Claude Code/Cursor	✅ Dev Assistant (this repo)	Human-AI pair programming, no API costs
Managing 5-7 projects simultaneously	✅ AI Agency	Autonomous agents, GitHub Issues orchestration
Rapid prototyping (2-8 weeks)	✅ Dev Assistant	Direct iteration, modular tasks
Long-term maintenance (6+ months)	✅ AI Agency	Context preservation, version tracking
Want to code alongside AI	✅ Dev Assistant	Real-time collaboration in IDE
Need autonomous code generation	✅ AI Agency	API-driven agents work independently

See Choosing a Framework for detailed comparison.

🚀 What Makes This Different?

The Problem: Sequential Workflows

Traditional AI coding sessions force you to work sequentially:

Session: "Build authentication system"

Must do in order:
├─ Phase 1: Research           ← Can't skip!
├─ Phase 2: Architecture       ← Can't skip!
├─ Phase 3: Database design    ← Can't skip!
├─ Phase 4: API implementation ← Can't skip!
├─ Phase 5: Frontend           ← Can't skip!
├─ Phase 6: Testing            ← Can't skip!
├─ Phase 7: Documentation      ← Can't skip!
└─ Phase 8: Deployment         ← Can't skip!

Problems:
❌ 8+ hours, can't pause
❌ Context loss if interrupted
❌ Can't parallelize work
❌ Must complete all phases in one session

The Solution: Modular .atf Tasks

Di-Atomic Dev Assistant breaks projects into independent task files:

tasks/
├─ 01-design-user-database-schema.atf       ← Independent, 2 hours
├─ 02-implement-password-hashing.atf        ← Independent, 2 hours
├─ 03-create-registration-endpoint.atf      ← Depends on 01, 02 (3 hours)
├─ 04-create-login-endpoint.atf             ← Depends on 01, 02 (2 hours)
├─ 05-implement-jwt-tokens.atf              ← Independent, 3 hours
└─ 06-write-auth-tests.atf                  ← Depends on 03, 04, 05 (3 hours)

Benefits:
✅ Work on ANY task in ANY order
✅ Pause/resume anytime (each task is self-contained)
✅ Parallelize: Open 3 IDE windows, work on 3 tasks simultaneously
✅ Context preservation: All requirements in .atf file
✅ 3x faster with parallel execution

🌟 Key Features

1. Two-Phase Workflow

Planning Phase (with templates):

Create PRD (Product Requirements Document)
Design architecture
Break project into 15-20 modular .atf task files
Framework templates guide you through process

Implementation Phase (without templates):

Run python cleanup-planning-phase.py to remove framework templates
Execute tasks in ANY order using AI assistants
Work on multiple tasks in parallel
Clean project with only your code and task files

2. Modular Task System

Every task is a self-contained .atf file:

✅ Complete Context: All requirements, success criteria, and instructions
✅ 2-4 Hours: Sized for one focused session
✅ Independent: Minimal dependencies enable parallel work
✅ Verifiable: Clear success criteria for completion

3. No API Costs

Works with IDE-based AI assistants:

Claude Code (VS Code extension)
Cursor (AI-first editor)
Gemini Code Assist (Google's IDE AI)

Cost: Flat subscription fee (no per-token charges)

4. Parallel Execution

Open 3 IDE windows, work on 3 tasks simultaneously:

Window 1 (Claude Code): Complex business logic
Window 2 (Cursor): API endpoints
Window 3 (Gemini): Frontend components

Result: 3x faster than sequential execution

📦 Quick Start

Installation

# Clone the framework
git clone https://github.com/martinshein/di-atomic-dev-assistant.git
cd di-atomic-dev-assistant

Create New Project

# Open the installation task file
code templates/atf/install-dev-assistant-fresh.atf

# Ask your AI assistant (Claude Code/Cursor/Gemini):
"Help me set up a new project using this .atf installation file.

Project details:
- Name: my-awesome-project
- Description: [your project description]
- Path: /path/to/projects"

Planning Phase

cd my-awesome-project

# 1. Read planning guide
code templates/PLANNING_PHASE.md

# 2. Create PRD with AI
"Help me create a comprehensive PRD for [your project]"

# 3. Design architecture
"Based on this PRD, design the system architecture"

# 4. Break into tasks
"Break this project into 15-20 modular .atf task files"

Transition to Implementation

# When planning is complete, run cleanup script
python cleanup-planning-phase.py

# This removes templates and creates IMPLEMENTATION.md

Implementation Phase

# Open a task file
code tasks/03-create-registration-endpoint.atf

# Ask AI:
"Help me implement this .atf task step-by-step"

# Repeat for each task (in ANY order!)

📚 Documentation

Guides

Quick Start Guide - Get started in 5 minutes
Two-Phase Workflow - Understanding Planning → Implementation
Modular Tasks - How to break projects into tasks
IDE Integration - Claude Code, Cursor, Gemini setup

Framework Comparison

Choosing a Framework - Dev Assistant vs AI Agency

🎓 Example: Authentication System

Traditional Approach (BAD)

Session: "Build auth system"
Duration: 8+ hours
Must complete all phases sequentially
Can't pause without losing context

Di-Atomic Approach (GOOD)

Planning Phase (1-2 days):

✅ Create PRD
✅ Design architecture
✅ Break into tasks:
   ├─ 01-design-database-schema.atf (2h)
   ├─ 02-implement-password-hashing.atf (2h)
   ├─ 03-create-registration-endpoint.atf (3h)
   ├─ 04-create-login-endpoint.atf (2h)
   ├─ 05-implement-jwt-tokens.atf (3h)
   └─ 06-write-auth-tests.atf (3h)
✅ Run cleanup script

Implementation Phase (parallel execution):

Day 1:
├─ Window 1 (Claude): Task 02 (2h)
├─ Window 2 (Cursor): Task 01 (2h)
└─ Window 3 (Gemini): Task 05 (3h)

Day 2:
├─ Window 1 (Claude): Task 03 (3h)
├─ Window 2 (Cursor): Task 04 (2h)
└─ Window 3 (Gemini): Task 06 (3h)

Result: Auth system complete in 2 days (6 hours work)
vs 15 hours sequential work

🏗️ Directory Structure

di-atomic-dev-assistant/
├── templates/                    # Framework templates (temporary in projects)
│   ├── atf/
│   │   └── install-dev-assistant-fresh.atf
│   ├── PLANNING_PHASE.md         # Planning guide
│   ├── CLAUDE_CODE_INSTRUCTIONS.md
│   ├── CURSOR_INSTRUCTIONS.md
│   └── GEMINI_CODE_ASSIST_INSTRUCTIONS.md
│
├── docs/                         # Documentation
│   └── guides/
│       ├── QUICK_START.md
│       ├── TWO_PHASE_WORKFLOW.md
│       ├── MODULAR_TASKS.md
│       └── IDE_INTEGRATION.md
│
├── cleanup-planning-phase.py     # Phase transition script
└── README.md                     # This file

After installing in a project:

my-project/
├── .planning-phase               # Phase marker
├── docs/
│   ├── prd/                     # Your PRD
│   └── architecture/            # Your architecture
├── tasks/                       # Your .atf task files
├── app/                         # Your application code
├── tests/                       # Your tests
├── templates/                   # Framework templates (deleted after planning)
└── cleanup-planning-phase.py    # Phase transition script

🔥 Real-World Benefits

1. Context Preservation

Without .atf files:

Day 1: Start auth system
Day 7: Resume auth system
       "What was I doing? Where did I leave off?"
       ❌ 30 minutes lost remembering context

With .atf files:

Day 1: Complete task 03
Day 7: Open task 04
       "All context in .atf file, continue immediately"
       ✅ 0 minutes lost

2. Parallelization

Sequential (1 AI assistant):

Task A: 3 hours
Task B: 2 hours
Task C: 3 hours
Total: 8 hours over 3 days

Parallel (3 AI assistants):

Task A (Claude)  ┐
Task B (Cursor)  ├─ 3 hours (simultaneously)
Task C (Gemini)  ┘
Total: 3 hours in 1 day

3. Flexible Workflow

Traditional:

❌ Must complete Phase 1 before Phase 2
❌ Can't work on tests until implementation done
❌ Can't pause mid-phase

Di-Atomic:

✅ Work on ANY task when motivated
✅ Can write tests before implementation (TDD!)
✅ Pause anytime (just pick a different task)

🆚 Dev Assistant vs AI Agency

Feature	Dev Assistant	AI Agency
Use Case	Single project	Multiple projects
AI Type	IDE assistants	API agents
Cost	Subscription only	API per-token
Workflow	Human-AI pair programming	Autonomous agents
Parallelization	3 IDE windows	Unlimited agents
GitHub Integration	Manual	Automated (Issues, PRs)
Context Preservation	.atf files	CLAUDE.md, GEMINI.md
Best For	Rapid development	Long-term maintenance

Choose Dev Assistant if:

✅ Building 1-2 projects
✅ Want hands-on coding
✅ Using Claude Code/Cursor/Gemini
✅ Need rapid iteration
✅ Budget-conscious (no API costs)

Choose AI Agency if:

✅ Managing 5-7+ projects
✅ Want autonomous agents
✅ Need GitHub automation
✅ Long-term projects (6+ months)
✅ Team collaboration

🤝 Contributing

Contributions welcome! This framework is designed to help developers build projects faster with AI assistance.

Ideas for contributions:

New .atf template examples
IDE integration guides
Task breakdown strategies
Real-world project case studies

📄 License

MIT License - See LICENSE file for details.

🔗 Related Projects

Di-Atomic AI Agency - Multi-agent autonomous development system
Choosing a Framework - Detailed comparison guide

📞 Support

Documentation: See docs/guides/ directory
Issues: GitHub Issues
Discussions: GitHub Discussions

🙏 Acknowledgments

Built on principles of modular development, human-AI collaboration, and context preservation.

Inspired by the need for flexible, parallelizable workflows when working with AI coding assistants.

Ready to build faster with AI? → Quick Start Guide

Di-Atomic Dev Assistant v1.0.0

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backups		backups
config/standards/global		config/standards/global
docs		docs
frontend		frontend
reports		reports
tasks		tasks
templates		templates
tests		tests
workflows		workflows
.DS_Store		.DS_Store
.credentials.template		.credentials.template
.gitignore		.gitignore
README.md		README.md
_preview.html		_preview.html
cleanup-planning-phase.py		cleanup-planning-phase.py
requirements.txt		requirements.txt

martinshein/di-atomic-dev-assistant

Folders and files

Latest commit

History

Repository files navigation