ai-duo-framework

AI Duo Framework 🤝

Overview

AI Duo Framework is a structured methodology and toolset for orchestrating collaboration between multiple AI agents in software development projects. It provides clear separation of concerns between Solution Architecture and Implementation roles, enabling efficient, high-quality software development with AI assistance.

Features

• 🎭 Dual AI Agent System - Separate Solution Architect and Developer roles
• 📝 Structured Communication - File-based messaging with clear protocols
• 🔄 Iterative Development - Phase-based progression with feedback loops
• 🧪 Built-in Testing Framework - Architect-controlled quality assurance
• 📦 Project Templates - Quick project initialization
• 🛠️ CLI Tools - Easy project management and status tracking
• 📚 Version Control Ready - Git-friendly with commit templates
• 🔐 Clear Boundaries - Prevents AI conflicts and maintains separation

Installation

Global Installation (Recommended)

npm install -g ai-duo-framework

Local Installation

npm install ai-duo-framework

Quick Start

1. Create a New Project

ai-duo init my-awesome-project

This will prompt you for:

• Project type (Web, API, CLI, Library, General)
• Git initialization preference

2. Start Your AI Agents

Open two terminal windows in your project directory:

Terminal 1 - Solution Architect:

cd my-awesome-project
# Provide your AI with: context/SOLUTION_ARCHITECT_PROMPT.md
# Start giving your project requirements

Terminal 2 - Software Developer:

cd my-awesome-project
# Provide your AI with: context/SOFTWARE_DEVELOPER_PROMPT.md
# The AI will monitor for instructions

3. Begin Development

• Give requirements to the Solution Architect
• Architect writes specifications in context/INSTRUCTIONS.md
• Developer implements and documents in implementation/IMPLEMENTATION_RESULTS.md
• Architect reviews, tests, and provides feedback
• Iterate until phase complete

CLI Commands

# Create a new project
ai-duo init [project-name]

# Check project status
ai-duo status

# Validate project structure
ai-duo validate

# Archive a completed phase
ai-duo archive <phase-number>

# Show help
ai-duo --help

Project Structure

my-project/
├── context/                    # Architecture & communication
│   ├── SOLUTION_ARCHITECT_PROMPT.md   # Architect AI instructions
│   ├── SOFTWARE_DEVELOPER_PROMPT.md   # Developer AI instructions
│   ├── INSTRUCTIONS.md                # Architect → Developer specs
│   ├── MEMORY.md                       # Shared learnings
│   └── COLLABORATION_PROTOCOL.md      # Communication rules
│
├── implementation/            # Development results
│   └── IMPLEMENTATION_RESULTS.md      # Developer → Architect
│
├── tests/                     # Testing (Architect-controlled)
│   ├── scripts/              # Test implementations
│   ├── outputs/              # Test results
│   ├── logs/                # Test logs
│   └── TEST_FRAMEWORK.md    # Testing guidelines
│
├── versions/                  # Version control
│   ├── COMMIT_TEMPLATE.md   # Commit message format
│   └── ROLLBACK_GUIDE.md    # Rollback procedures
│
├── src/                      # Your actual project code
└── dist/                     # Build outputs

Workflow Diagram

graph TD
    A[User Requirements] --> B[Solution Architect AI]
    B --> C{Writes Instructions}
    C --> D[INSTRUCTIONS.md]
    D --> E[Software Developer AI]
    E --> F{Implements Code}
    F --> G[src/ folder]
    F --> H[IMPLEMENTATION_RESULTS.md]
    H --> I[Solution Architect AI]
    I --> J{Reviews & Tests}
    J -->|Approved| K[Next Phase]
    J -->|Needs Changes| C

Status Flags

The framework uses status flags for clear communication:

• [READY_FOR_IMPLEMENTATION] - Specs ready for developer
• [IMPLEMENTATION_COMPLETE] - Code ready for review
• [REVISION_REQUIRED] - Changes needed
• [PHASE_COMPLETE] - Phase approved
• [BLOCKED] - Need intervention
• [CLARIFICATION_NEEDED] - Ambiguous requirements

Best Practices

For Users:

• Start with clear, comprehensive requirements
• Review and approve phase completions
• Make architectural decisions when prompted
• Monitor for blockers or escalations

For Solution Architect AI:

• Write detailed, unambiguous specifications
• Create comprehensive test cases
• Document all architectural decisions
• Review code thoroughly before approval

For Software Developer AI:

• Follow specifications exactly
• Document all implementations
• Suggest improvements without overstepping
• Escalate blockers immediately

Advanced Usage

Custom Templates

Create custom project templates in templates/:

ai-duo init my-project --template custom-template

Phase Archiving

Archive completed phases for version control:

ai-duo archive 1  # Archives phase 1 with timestamp

Status Monitoring

Check project status programmatically:

const { checkStatus } = require('ai-duo-framework');
const status = await checkStatus('./my-project');
console.log(status);

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/cwmaia/ai-duo-framework.git
cd ai-duo-framework
npm install
npm link  # Test CLI locally

Running Tests

npm test

Use Cases

• 🌐 Web Applications - Full-stack development with clear frontend/backend separation
• 🔧 APIs & Services - RESTful APIs, GraphQL services, microservices
• 📦 Libraries & Packages - NPM packages, Python libraries, etc.
• 🖥️ CLI Tools - Command-line applications with complex logic
• 🤖 AI/ML Projects - Data pipelines, model training, deployment
• 📱 Mobile Apps - React Native, Flutter applications

Troubleshooting

Common Issues:

AIs conflicting with each other:

• Ensure each AI is using the correct prompt file
• Check that file permissions in prompts are clear
• Validate project structure with ai-duo validate

Requirements unclear:

• Architect should request clarification in feedback
• User should provide additional details
• Update INSTRUCTIONS.md with clarified specs

Tests failing repeatedly:

• Review test requirements in TEST_FRAMEWORK.md
• Check for environment issues
• Consider adjusting specifications

Roadmap

• VSCode extension for visual status monitoring
• Web dashboard for project management
• Support for 3+ AI agents
• Integration with popular CI/CD pipelines
• AI model agnostic prompts
• Real-time collaboration features
• Project metrics and analytics

License

MIT - See LICENSE file for details

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Contact: Create an issue for questions

Acknowledgments

Built with inspiration from modern software development practices and the potential of AI collaboration.

Made with ❤️ by developers, for developers using AI

Transform your development workflow with intelligent AI collaboration