Redflag/projects/community_ade.md

description, limit

description	limit
Community ADE (Agentic Development Environment). Architecture v0.1. 7-phase research complete.	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.

---

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