From 0fa05fecee26ec35399b09274cd4a4cc5de32fe1 Mon Sep 17 00:00:00 2001 From: Ani Date: Thu, 19 Mar 2026 19:31:21 -0400 Subject: [PATCH] Add Community ADE architecture and START_HERE summary - Architecture v0.1: 7-phase research complete - 8-week implementation roadmap (Phases A-D) - Critical gaps identified (persistence, auth, locking) - START_HERE.md summary: SDK rules, build steps, architecture - Status: Step 3 (SDK session service) is next critical bridge --- projects/community_ade.md | 147 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 projects/community_ade.md diff --git a/projects/community_ade.md b/projects/community_ade.md new file mode 100644 index 0000000..46f4d5e --- /dev/null +++ b/projects/community_ade.md @@ -0,0 +1,147 @@ +--- +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. + +--- + +*Cathedral Status: Blueprints detailed, foundation assessed, construction plan established. Awaiting build signal.*