---
description: Community ADE (Agentic Development Environment). Architecture v0.1. 7-phase research complete.
limit: 40000
---

# Community ADE Architecture

## Executive Summary

7-phase research and design project for an open-source ADE on Letta/Lettabot infrastructure. **Architecture ready for implementation when prioritized.** Critical gaps identified. Clear 8-week roadmap established.

**Status:** Phases 1-6 Complete, Phase 7 In Progress (March 16-17, 2026)

---

## Design Principles

1. **Leverage Existing:** Build on Letta's approval queues, Zod schemas, audit infrastructure
2. **Pragmatic Orchestration:** Coordinator pattern without full Intent complexity
3. **Executable Specs:** Enhance existing Zod schemas vs formal spec languages
4. **Community-First:** Open source, self-hosted, extensible via MCP

---

## Core Components

### 1. Task Coordinator
- **Role:** Decomposes high-level goals into parallel subtasks
- **Location:** Extends existing approval queue system
- **Pattern:** Manual coordinator (human) + automated task spawning
- **Outputs:** Task specifications with dependencies

### 2. Execution Environments
- **Primary:** Git worktrees (lightweight, native isolation, ~1s creation)
- **Fallback:** Container sandboxes for untrusted agents
- **Simple:** Sequential execution in main workspace for trusted agents
- **Configuration:** Per-agent environment selection

### 3. Spec System
- **Format:** Enhanced Zod schemas with documentation fields
- **Lifecycle:** Draft → Validated → Active → Archived
- **Sync:** Schema changes trigger validation, not auto-application
- **Traceability:** Each spec version linked to generated artifacts

### 4. Verification Layer
- **Static:** Schema validation, lint checks
- **Dynamic:** Test execution, integration validation
- **Human:** Required review before merge to protected branches
- **Auto-Reject:** Failed runs automatically reject pending approvals

### 5. Compliance Features
- **Audit:** JSONL logs (already implemented) with enhanced metadata
- **ZDR:** Configurable data retention policies, not contractual
- **BYOA:** Agent registration whitelist, DLP scanning hooks
- **Access:** Role-based permissions (leverage existing Letta auth)

---

## Data Flow

```
Human Intent → Coordinator → Task Spec → Approval Queue → Agent Execution
                                                        ↓
                          Verification ← Artifacts ← Worktree
                               ↓
                        Human Review → Merge → Audit Log
```

---

## 8-Week Implementation Roadmap

### Phase A (Weeks 1-2): Foundation
- [ ] Git worktree integration
- [ ] Enhanced task specification schema
- [ ] Parallel task execution (basic)

### Phase B (Weeks 3-4): Verification
- [ ] Verification pipeline
- [ ] Auto-rejection on failure
- [ ] Enhanced audit logging

### Phase C (Weeks 5-6): Compliance
- [ ] BYOA agent registry
- [ ] Configurable ZDR policies
- [ ] Role-based access controls

### Phase D (Weeks 7-8): Polish
- [ ] MCP integration for extensibility
- [ ] Dashboard for task monitoring
- [ ] Documentation and examples

---

## Critical Gaps Identified

**🔴 CRITICAL:**
1. **In-Memory Storage** — Map objects, no persistence (data loss on restart)
2. **No Authentication** — Routes accept userId without validation
3. **Race Conditions** — No locking on apply operations

**🟡 HIGH:**
4. **Audit Log Unbounded Growth** — No rotation, memory exhaustion
5. **Missing Encryption** — Plaintext storage
6. **No Rate Limiting** — Bulk operations unbounded
7. **Weak Confirmation** — Token exists, no validation logic
8. **No Schema Migrations** — Breaking changes on updates

**Recommendation:** Extend current foundation with persistence layer, auth, locking, encryption. Document limitations clearly.

---

## Decisions Made

| Ambiguity | Decision | Rationale |
|-----------|----------|-----------|
| Commercial vs local patterns | Hybrid | Leverage existing, add selective commercial features |
| Git worktrees vs containers | Both | Worktrees default, containers for isolation |
| Formal specs vs Zod | Enhanced Zod | Existing infrastructure, sufficient for community |
| SOC 2 priority | Deferred | Focus on features, audit trails enable future certification |

---

## Research Summary

**Phase 1:** Discovery — Multi-agent orchestration, spec-driven development, enterprise compliance
**Phase 2:** Exploration — 3 parallel subagents (compliance, orchestration, specs)
**Phase 3:** Clarification — Hybrid approach, pragmatic community-first
**Phase 4:** Architecture — Core components, data flow, 8-week roadmap
**Phase 5:** Implementation Research — Git worktree patterns, industry adoption (~63% CI build time reduction)
**Phase 6:** Review — Critical gaps identified with severity ratings
**Phase 7:** Documentation — In progress

---

## Next Steps

**When Prioritized:**
1. **Week 0:** Address critical gaps (persistence, auth, locking)
2. **Weeks 1-2:** Phase A — Foundation
3. **Continue through Phases B-D**

**Alternative:** Use as reference for evaluating commercial ADEs (Intent, Warp) without building.

---

## Current Status (March 21, 2026)

**Infrastructure Update:**
- **Lettabot:** TTS wired for Discord, functional
- **Letta Code:** Upstream fixes applied
- **Letta AI:** Upstream fixes applied
- **Synthetic API:** Crash issues resolved - "good for the long haul"

**Development:**
- Coming along well
- Subagent inquiry available for progress checks

---

*Cathedral Status: Blueprints detailed, foundation assessed, construction plan established. Infrastructure maturing. Awaiting build signal.*