LLM Agent Orchestrator

System Architecture

Core Components

1. AgentSimulation (agent_logic.py)

Central orchestration engine managing conversation state, chat history, retry logic, JSON validation, and file system operations.

2. LLM Provider Layer (llm_providers.py)

Data Flow

1. User Input → Prompt
2. Select Agent (Round-Robin / QUESTION TO)
3. Load Context (Architect plan + current/ files)
4. LLM API Call (with bounded retry/backoff)
5. Parse Response (validate JSON if Programmer)
6. Save Files (current/ + versions/)
7. Update UI → Next Turn

File System Structure

output/project_name_20240115_143022/
├── logs/
│   ├── conversation.log      # JSON-lines
│   └── agents.json            # Config snapshot
├── current/                   # EXECUTABLE
│   ├── main.py
│   └── src/
│       ├── __init__.py        # Auto-generated
│       └── main.py
└── versions/                  # HISTORY
    ├── main.py.v001
    └── main.py.v002

Communication Protocols

JSON Self-Healing

1. Parser detects syntax error in Programmer response
2. Error message constructed with original attempt
3. Correction prompt sent back to Programmer (no turn increment)
4. Loop until valid JSON or retry limit is reached
5. Valid JSON → Files saved → Flow continues

Agent System

1. Strategist (Konrad) - Optional

2. Project Manager (Klaus)

3. Software Architect (Eva)

4. Programmer (Ben)

JSON Format:

{"files": [
  {"file_path": "main.py", "content": "..."},
  {"file_path": "engine.py", "content": "..."}
]}

5. Bug-Hunter (Findus)

6. Consensus Finder (Judge)

Communication Patterns

Round-Robin:
  PM → Architect → Programmer → Bug-Hunter → Consensus

Question-Based:
  Bug-Hunter finds error → QUESTION TO Programmer
  Programmer fixes → Back to Bug-Hunter
  Bug-Hunter approves → Continue to Consensus

Configuration System

Agent Parameters

Recommended Configs by Role

Environment Variables

Best Practices

• System Prompts: Use ALL-CAPS for critical rules (NEVER, MUST, ALWAYS)
• Temperature: Code generation: 0.1-0.3, Design: 0.5-0.7, Brainstorming: 0.8-1.0
• Token Meter: Gemini, OpenAI, and Anthropic report actual completed-request usage when available; local or compatible endpoints fall back to a conservative estimate. The preflight guard remains conservative.
• Ordering: Architect MUST come before Programmer (plan cached for context injection)

Simulation Workflow

1. Initialization

1. Launch the web application
2. Load default agent config
3. Check API key environment variables
4. Detect available LLM providers

2. Configuration

Workflow Profiles

Phased Engineering persists implementation_plan.json, a human-readable implementation_plan.md, zero or more material ADR-*.md records, a safe-boundary graph_checkpoint.json, and a phase result for every delivery gate. The PM selects a small, standard, or high-risk delivery budget; it constrains rather than pads ADRs and phases. The user remains the final authority: edited ADRs are impact-reviewed and any revised plan returns for fresh approval. These artifacts make resume behavior inspectable.

3. Orchestration Loop

Round N:
  Turn 1-5: Agents respond in sequence

  If APPROVAL → Advance Round / End
  If QUESTION TO → Jump to target agent
  Else → Next agent

4. Multi-Pass Refinement

Pass 1: Programmer delivers → Bug-Hunter finds issue
 Pass 2: Programmer fixes → Bug-Hunter approves
 Pass 3: Consensus checks → Missing file found
 Pass 4: Programmer adds → Consensus → APPROVAL

5. Completion

Browser Session Recovery

1. Each browser session receives a server-owned session key.
2. RQ jobs persist their status, update stream, artifact manifest, generated project files, and a worker liveness lease.
3. After a reload, the browser offers a reconnect action for the same session only. Paused RQ runs expose a resume action from their durable checkpoint.
4. Persisted events are replayed while SSE reconnects; polling remains the recovery path if a proxy buffers streams.
5. Completed projects can start a controlled continuation with a new instruction; the existing generated files remain the source of truth.
6. Completed projects remain available for ZIP download until the configured retention cleanup runs.
7. A stale lease is diagnostic only: the app waits for the durable RQ state or a user-controlled checkpoint resume instead of risking concurrent writers.

Troubleshooting Guide

API Issues

Immediate Red Error

Gemini 400 Error

Local LLM Refused

JSON Errors

Infinite Healing Loop

Import Errors

ModuleNotFoundError

Circular Import

Known Limitations

• Binary Assets: Binary assets and native GUI dependencies may require explicit requirements, approval, and manual review
• Large Projects: 50+ files may exceed context. Workaround: Split into modules
• GUI/game frameworks: Dependencies such as pygame can be installed into .sandbox_deps after approval. Long-running startup probes are accepted for games and event loops; native desktop GUI limits such as missing Tkinter libraries or an X display are reported as host limitations rather than code defects.