docs(adr): add ADR-001 API-first agent-agnostic design

Key decision: Mosaic Stack exposes APIs first, agent skills are thin wrappers. Platform works standalone, agent layer is swappable.
2026-01-29 16:05:09 -06:00
parent 91399f597f
commit 9b7e1f926f
1 changed files with 87 additions and 0 deletions
--- a/docs/design/architecture-decisions.md
+++ b/docs/design/architecture-decisions.md
@@ -0,0 +1,87 @@
+# Architecture Decision Records (ADRs)
+
+## ADR-001: API-First with Agent-Agnostic Design
+
+**Date:** 2025-01-29  
+**Status:** Accepted  
+**Deciders:** Jason, Jarvis
+
+### Context
+
+Mosaic Stack needs to integrate with AI agents (currently ClawdBot, formerly MoltBot). The question is how tightly to couple the platform with the agent layer.
+
+### Decision
+
+**Mosaic Stack will be API-first and agent-agnostic.**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Users                                │
+│         (Web UI, Mobile, CLI, API clients)                 │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Mosaic Stack                             │
+│                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
+│  │ Knowledge   │  │ Tasks/Gantt │  │ Agent Orchestration │ │
+│  │ Module      │  │ Module      │  │ Module              │ │
+│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
+│         │                │                     │            │
+│         └────────────────┼─────────────────────┘            │
+│                          ▼                                  │
+│                    REST/GraphQL APIs                        │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │ ClawdBot │    │ Other    │    │ Direct   │
+    │ Skills   │    │ Agents   │    │ API Use  │
+    └──────────┘    └──────────┘    └──────────┘
+```
+
+### Implications
+
+1. **All functionality exposed via APIs first**
+   - REST endpoints for CRUD operations
+   - GraphQL for complex queries (optional)
+   - WebSocket for real-time updates
+
+2. **Agent skills are thin wrappers**
+   - ClawdBot skills (`mosaic-skill-*`) wrap Mosaic APIs
+   - Skills handle: auth, tool definitions, response formatting
+   - Business logic lives in Mosaic, not skills
+
+3. **Mosaic works standalone**
+   - Web UI is fully functional without any agent
+   - Users can choose to use agents or not
+   - Different agents can integrate (ClawdBot, custom, future)
+
+4. **Agent layer is swappable**
+   - Not locked to ClawdBot
+   - Could use Claude directly, OpenAI agents, or custom
+   - Mosaic is the source of truth
+
+### Consequences
+
+**Positive:**
+- Platform independence
+- Multiple integration paths
+- Clear separation of concerns
+- Easier testing (API-level tests)
+
+**Negative:**
+- Extra network hop for agent access
+- Need to maintain both API and skill code
+- Slightly more initial work
+
+### Related Issues
+
+- #22: Brain query API endpoint (API-first ✓)
+- #23-26: mosaic-plugin-* → rename to mosaic-skill-* (thin wrappers)
+
+---
+
+*Future ADRs will be added to this document.*