Q-00 Architecture Synthesis - Executive Summary

Status: ANSWERED ✅
Lead: lead
Timestamp: 2026-05-11T02:55:00Z
Location: /workcell/llm-wiki/wiki/research/answers/q-00-architecture-synthesis.md

🎯 Decision: Minimal Viable Architecture

Recommendation: Use Pi Teams framework in a single Docker container with LLM-wiki file-based knowledge depot.

Core Components

┌─────────────────────────────────────────────────────────────┐
│                    Pi Workcell MVP Architecture            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  • Framework: Pi Teams (Bun-based)                         │
│  • Container: Single Docker container                      │
│  • Knowledge: LLM-wiki file-based Markdown                │
│  • Workflow: T0-T7 structured lifecycle                    │
│  • Coordination: Claim board + append-only logging         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

✅ What To Use

Framework

• Pi Teams (Bun-based)
• Already working in current setup
• Lightweight (~5MB install, ~50MB runtime)
• Simple YAML configuration
• Built-in coordination features
• Raspberry Pi compatible

Container

• Single Docker Container
• Current setup (Debian 13 base)
• ext4 bind mounts for workcell/repo
• Simple operational model
• Low overhead

Knowledge System

• LLM-wiki File-Based Markdown
• Proven effective in current use
• Direct file I/O for agents
• Git version control built-in
• grep/find sufficient for searching

Workflow

• T0-T7 Structured Lifecycle
• T0: Intake → T1: Research → T2: Plan → T3: Chunk
• T4: Implement → T5: Validate → T6: Review → T7: Close
• Mandatory artifacts at each stage
• Clear decision points

❌ What To Avoid

Frameworks

• ❌ LangGraph (too complex, high memory)
• ❌ CrewAI (Python dependency, overlap)
• ❌ AutoGen (enterprise-focused, overkill)
• ❌ Pydantic AI (limited value, Python)

Container Strategies

• ❌ Multiple containers (docker-in-docker not available)
• ❌ pi-container-sandbox (doesn't exist)
• ❌ Complex isolation mechanisms (not needed)

Knowledge Systems

• ❌ LlamaIndex/RAG (too heavy for Raspberry Pi)
• ❌ Complex databases (SQLite optional only)
• ❌ Over-engineered retrieval systems

📋 Research Status

Answered Questions

• ✅ Q-00: Architecture Synthesis (this answer)
• ✅ Q-05: Knowledge Depot/RAG (LLM-wiki + optional SQLite)

Claimed Questions

• ⏳ Q-06: Runtime Container Shape (builder-reviewer)

Critical Path Questions (HIGH Priority)

• 🔴 Q-04: Work Shape / Lifecycle (blocks Q-08, Q-12)
• 🔴 Q-01: Pi Teams Fit (blocks Q-03)

Implementation Questions (MEDIUM Priority)

• 🟡 Q-03: Framework Comparison (confirms Pi Teams)
• 🟡 Q-07: Toolchain / KOS Contract (D3-TUI specific)
• 🟡 Q-08: Forgejo Workflow (process integration)
• 🟡 Q-09: Bun / Pi Install (runtime setup)
• 🟡 Q-10: Validation / Smoke Testing (quality)

Enhancement Questions (LOW Priority)

• 🔵 Q-02: LangGraph Fit (alternative analysis)
• 🔵 Q-11: Remote UI / Observability (nice-to-have)
• 🔵 Q-12: External Agent Coordination (collaboration)

🎯 Next Steps

Immediate (Researcher)

Claim Q-04 Work Shape / Lifecycle: - Define exact T0-T7 stage requirements - Specify mandatory artifacts - Document decision points - Create workflow templates

Immediate (Builder-Reviewer)

Complete Q-06 Runtime Container Shape: - Document current single container setup - Specify bind mount requirements - Define operational controls - Test resource limits

Short-term (Team)

1. Answer critical path questions (Q-04, Q-01)
2. Confirm framework choice (Q-03)
3. Stage configuration files
4. Test coordination workflow

Medium-term (Implementation)

1. Implement LLM-wiki structure
2. Configure Pi Teams
3. Set up tmux panes
4. Document operational procedures

📁 Deliverables

Published

• ✅ /workcell/llm-wiki/wiki/research/answers/q-00-architecture-synthesis.md (main answer)
• ✅ /workcell/llm-wiki/wiki/research/answers/q-00-architecture-synthesis/t0-findings.md
• ✅ /workcell/llm-wiki/wiki/research/answers/q-00-architecture-synthesis/t1-research.md
• ✅ Updated research-queue.md (Q-00 marked ANSWERED)
• ✅ Updated claim-board.md (Q-00 released)
• ✅ Updated log.md (complete traceability)

Next Deliverables Needed

• Q-04 answer: Work Shape / Lifecycle definition
• Q-01 answer: Pi Teams Fit details
• Q-06 answer: Runtime Container Shape documentation
• teams.yaml configuration file
• Agent prompt files

🎯 Success Criteria

MVP Success: - ✅ Three agents coordinating effectively via Pi Teams - ✅ File-based knowledge system operational - ✅ T0-T7 lifecycle followed consistently - ✅ Single container running smoothly - ✅ D3-TUI work progressing - ✅ Traceable work products in LLM-wiki

Architecture Success: - ✅ Minimal viable components only - ✅ Raspberry Pi compatible (< 2GB memory, ARM compatible) - ✅ Simple to operate and debug - ✅ Scalable to 5+ agents if needed - ✅ No unnecessary complexity or dependencies

🔍 Key Insights

Why This Works

1. Uses What's Already Working: Pi Teams and LLM-wiki are proven
2. Respects Constraints: Raspberry Pi memory/CPU limitations
3. Avoids Complexity: No Python, no heavy frameworks, no RAG
4. Clear Path: Simple to implement, easy to debug
5. Traceable: Append-only logging, Git version control
6. Maintainable: File-based systems are easy to manage

What Makes It Different

• No Over-Engineering: Many agent systems use complex orchestration
• File-Based: Most systems use databases or APIs
• Minimal Dependencies: Avoids Python and heavy runtimes
• Raspberry Pi First: Designed for constrained hardware
• Traceability Focus: Built-in logging and version control

Risks Mitigated

• Framework Complexity: ❌ LangGraph → ✅ Pi Teams
• Memory Constraints: ❌ Python → ✅ Bun/JS
• Knowledge Scaling: ⚠️ File search → ✅ Optional SQLite
• Coordination: ⚠️ Manual → ✅ Claim board protocol

📋 Checklist for Implementation

Configuration

• [ ] Create /workcell/config/teams.yaml
• [ ] Create agent prompt files
• [ ] Document T0-T7 lifecycle
• [ ] Stage bind mount configuration

Knowledge System

• [ ] Implement LLM-wiki structure
• [ ] Create research queue template
• [ ] Add optional SQLite (if needed)
• [ ] Document access patterns

Coordination

• [ ] Test claim board workflow
• [ ] Validate messaging between agents
• [ ] Test plan approval process
• [ ] Verify append-only logging

Validation

• [ ] Define smoke test procedures
• [ ] Create validation contract
• [ ] Test error handling
• [ ] Verify recovery procedures

🎯 Final Recommendation

Build the minimal viable architecture as documented: 1. Framework: Pi Teams (Bun-based) 2. Container: Single Docker container 3. Knowledge: LLM-wiki file-based 4. Workflow: T0-T7 lifecycle 5. Coordination: Claim board protocol

Avoid adding complexity until demonstrated need arises. The current design is sufficient for MVP and likely for the foreseeable future. Enhancements like SQLite, remote UI, and advanced validation can be added incrementally.

This architecture enables immediate progress on D3-TUI work while respecting Raspberry Pi constraints and providing effective coordination among three Pi agents and external contributors.

📞 Call to Action

Researcher: Please claim Q-04 Work Shape / Lifecycle next to unblock the critical path.

Builder-Reviewer: Please complete Q-06 Runtime Container Shape documentation.

Team: Review the architecture recommendation and provide feedback. Let's confirm this direction and move forward with implementation.

Next Session: Coordinate question assignments, answer critical path questions, and begin configuration staging.