Coding Framework

Portable Multi-Instance AI Coordination for Complex Projects

Transform any development project into a coordinated multi-instance workflow where specialized Claude Code instances collaborate via Git message queues.

What It Does

• Automatic Setup: Single command creates complete project infrastructure
• Dynamic Scaling: 2-4 instances allocated based on project complexity
• Agent Enforcement: Mandatory use of specialized agents (GitHub, Exa search, Playwright)
• Zero-Trust Security: All secrets via GCP Secret Manager (never hardcoded)
• Smart Coordination: Git-based message queue with LIFO retention (75% disk savings)

Quick Start

# 1. Clone framework
git clone https://github.com/langley232/coding-framework.git
cd coding-framework

# 2. Run initialization
./initialization/init-project.sh

# 3. Launch instances (commands generated for you)
wsl -d Ubuntu && cd ~/your-project && ./setup-instance.sh && claude

What Gets Created

For Every Project:

• ✅ GitHub repository
• ✅ 12 specialized agents installed
• ✅ 14 MCP servers configured
• ✅ CLAUDE.md (project instructions)
• ✅ CONSTITUTION.md (governance rules)
• ✅ GCP Secret Manager integration
• ✅ Message queue coordination
• ✅ Instance-specific task lists
• ✅ Setup scripts per instance

Instance Types (Auto-Allocated)

Complexity	Instances	Roles
Small (1-20 tasks)	2	Frontend + Backend
Medium (20-50 tasks)	3	Frontend + Backend + Testing
Large (50+ tasks)	4	Frontend + Backend + Testing + Supervisor

Mandatory Agent Rules

Three non-negotiable delegations:

1. Git Operations → @github-agent (ALL commits, pushes, PRs)
2. Browser Testing → @browser-testing-agent (ALL Playwright)
3. External Search → @exa-search-agent (ALL web research)

Violations = Task failure + re-execution

Security Features

• GCP Secret Manager required (no hardcoded secrets)
• Environment variable pattern: OPENAI_API_KEY=gcp-secret:openai-api-key
• Runtime loading: await loadAllSecrets() at startup
• 33 secrets supported (AI services, databases, payment, OAuth, etc.)

Message Queue Protocol

Every 2 Hours (Instances 1-3):

• Pull latest changes
• Check coordination/messages/instance-X/ for new messages
• Process by priority: USER-OVERRIDE > BLOCKER > STATUS

Every 30 Minutes (Supervisor):

• Monitor all instances
• Resolve blockers
• Auto-approve passing PRs
• Report to user

File Structure Created

your-project/
├── agents/                    ← 12 specialized agents
├── config/
│   └── mcp-servers.json      ← 14 MCP servers configured
├── coordination/messages/
│   ├── instance-1/           ← Frontend messages
│   ├── instance-2/           ← Backend messages
│   └── instance-3/           ← Testing messages
├── shared/utils/
│   └── gcp-secrets.js        ← Secret Manager integration
├── CLAUDE.md                 ← Project instructions (auto-generated)
├── CONSTITUTION.md           ← Governance rules (auto-generated)
├── setup-instance.sh         ← Per-instance setup
└── QUICK-START.md            ← Launch commands

Proven Results

AtlasWeb-Mini (Production Use):

• ✅ 31 tasks completed (3 weeks)
• ✅ 100+ commits across 4 instances
• ✅ 0 agent violations (100% compliance)
• ✅ 33 secrets migrated to GCP
• ✅ 75% disk savings with LIFO retention

Prerequisites

• WSL2 with Ubuntu (20.04, 22.04, 24.04)
• Claude Code CLI
• GCP Project with Secret Manager enabled
• GitHub account with PAT
• Node.js 18+

Example Usage

# Initialize new SaaS product
./init-project.sh
→ Project Name: acme-crm
→ Type: new-product
→ Tech Stack: React, FastAPI, PostgreSQL
→ Complexity: medium

# Result: 3 instances, 35 tasks, complete setup in 5 minutes

Documentation

• docs/AGENT-USAGE-PROTOCOL.md - Mandatory delegation rules
• docs/MESSAGE-QUEUE-RETENTION-POLICY.md - Disk optimization
• Templates in templates/ for reference

License

MIT - Use freely for any project type

---

Framework Version: 1.0.0 Built with Claude Code Repository: https://github.com/langley232/coding-framework