2l

2L - Two-Level Orchestration System

2L is an AI agent orchestration system that breaks down complex development tasks into manageable iterations executed by specialized agents.

---

Quick Start (5 Minutes)

Get up and running with 2L in 5 simple steps:

1. Clone Repository

git clone https://github.com/Ahiya1/2L.git && cd 2L

2. Install 2L

./2l.sh install

This installs all agents and commands to ~/.claude/.

3. Setup Database Access

/2l-setup-db

Configures Claude to access Supabase local database (requires sudo password).

4. (Optional) Setup MCPs

/2l-setup-mcps

Guided setup for Playwright and Chrome DevTools MCP servers.

5. Start Building

cd ~/your-project
/2l-mvp "build a todo app with React and Supabase"

In another terminal, monitor progress:

/2l-dashboard

Done! Your first orchestration is running.

---

Table of Contents

• Quick Start
• What is 2L?
• Core Workflow
• Event System Architecture
• Dashboard Access
• Advanced Topics
  • MCP Integration
  • GitHub Integration
  • Setup Verification
  • Architecture Decisions
• Troubleshooting
• Additional Resources

---

What is 2L?

2L (Two-Level) orchestrates AI agents to build software projects by:

• Breaking your vision into iterations
• Spawning specialized agents (explorers, planners, builders, integrators, validators)
• Coordinating their work through a structured workflow
• Tracking everything via events for real-time monitoring
• Committing results to git and optionally pushing to GitHub

Target audience: Developers who want to build MVPs, prototypes, or complete features using AI agents with full visibility into the orchestration process.

---

Core Workflow

# Option 1: Interactive requirements gathering
/2l-vision

# Option 2: Full autonomy mode (recommended for quick starts)
/2l-mvp "Build a todo app with React and Supabase"

The /2l-mvp command will:

1. Break your vision into iterations (based on complexity)
2. For each iteration:
   • Exploration phase: Explorers analyze requirements and codebase
   • Planning phase: Planner creates detailed implementation plan
   • Building phase: Builders implement features (with potential sub-builders if complex)
   • Integration phase: Integrator merges all builder work
   • Validation phase: Validator tests everything
   • Healing phase: If validation fails, healer fixes issues
3. Commit completed work to git
4. Push to GitHub (if gh CLI configured)
5. Emit events throughout for real-time monitoring

Example Usage

# Navigate to your project directory
cd ~/projects/my-app

# Start orchestration
/2l-mvp "Create a REST API with authentication and user management"

# Open dashboard in another terminal to watch progress
/2l-dashboard

The dashboard will show:

• Real-time event timeline
• Active agents and their progress
• Current phase and metrics
• All events color-coded by type

---

Event System Architecture

Why Events?

The 2L event system provides:

• Observability: See exactly what each agent is doing in real-time
• Debugging: Trace problems back to specific agents and phases
• Non-blocking: Events don't slow down orchestration
• Historical record: Full audit trail of orchestration decisions

Event Flow

┌─────────────────┐
│  Orchestrator   │ (28 emission points)
└────────┬────────┘
         │
         ├─> plan_start
         ├─> iteration_start
         ├─> phase_change (exploration → planning → building → ...)
         ├─> agent_start/agent_complete (spawns agents)
         ├─> validation_result
         └─> iteration_complete
         │
         ▼
   .2L/events.jsonl (JSONL format)
         │
         ▲
         │
┌────────┴────────┐
│     Agents      │ (All 10 agent types)
└─────────────────┘
         │
         ├─> agent_start (before work begins)
         └─> agent_complete (after work finishes)

         │
         ▼
   Dashboard polls events.jsonl every 2 seconds
         │
         ▼
   Real-time display in browser

8 Event Types

All events in 2L use one of these standardized types:

1. plan_start - Orchestration begins for a plan

   • Emitted when: /2l-mvp starts execution
   • Contains: Plan ID, mode (MASTER/AUTO), project name

2. iteration_start - New iteration begins

   • Emitted when: Starting iteration N
   • Contains: Iteration number, goals, estimated complexity

3. phase_change - Phase transition occurs

   • Emitted when: Moving between phases (exploration → planning → building → integration → validation → completion)
   • Contains: Previous phase, new phase, reason