sipeed · Leeaandrob · Feb 18, 2026 · Feb 18, 2026 · Feb 18, 2026 · Feb 18, 2026
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -0,0 +1,52 @@
+# PicoClaw Multi-Agent Architecture
+
+This directory contains C4 model diagrams (rendered with Mermaid) documenting the multi-agent collaboration framework for PicoClaw.
+
+## Reference Implementation
+
+**OpenClaw (moltbot)** — the state-of-the-art personal AI gateway whose founder was hired by OpenAI. picoclaw ports and improves upon OpenClaw's validated patterns in a lightweight Go single-binary.
+
+- Reference code: `/home/leeaandrob/Projects/Personal/llm/auto-agents/moltbot`
+- See [PRP](../prp/multi-agent-hardening.md) for detailed implementation plan
+
+## Documents
+
+| Document | Scope | Description |
+|----------|-------|-------------|
+| [C1 - System Context](./c1-system-context.md) | Highest level | PicoClaw in its ecosystem: users, channels, LLM providers |
+| [C2 - Container](./c2-container.md) | Runtime containers | Gateway, Agent Loop, Provider Layer, Channels |
+| [C3 - Component](./c3-component-multi-agent.md) | Multi-agent internals | Current + planned components across 4 hardening phases |
+| [C4 - Code](./c4-code-detail.md) | Key structs/interfaces | Go interfaces, data flow, tool execution |
+| [Sequence Diagrams](./sequences.md) | Runtime flows | Handoff, Blackboard sync, Fallback chain |
+| [Roadmap](./roadmap.md) | Phased plan | 4-phase hardening based on OpenClaw gap analysis |
+
+## Related
+
+- **PRP**: [Multi-Agent Hardening](../prp/multi-agent-hardening.md) — Full implementation plan with acceptance criteria
+- **Issue**: [#294 - Base Multi-agent Collaboration Framework](https://github.com/sipeed/picoclaw/issues/294)
+- **Issue**: [#283 - Refactor Provider Architecture](https://github.com/sipeed/picoclaw/issues/283)
+- **Discussion**: [#122 - Provider Architecture Proposal](https://github.com/sipeed/picoclaw/discussions/122)
+
+## Status
+
+| Phase | Status | PR |
+|-------|--------|----|
+| Provider Protocol Refactor | Merged | [#213](https://github.com/sipeed/picoclaw/pull/213) |
+| Model Fallback + Routing | Merged | [#131](https://github.com/sipeed/picoclaw/pull/131) |
+| Blackboard + Handoff + Discovery | WIP | [#423](https://github.com/sipeed/picoclaw/pull/423) |
+| Phase 1: Foundation Fix | Planned | PR #423 |
+| Phase 2: Tool Policy | Planned | PR #423 |
+| Phase 3: Resilience | Planned | TBD |
+| Phase 4: Async Multi-Agent | Planned | TBD |
+| SOUL.md Bootstrap | In Progress (other dev) | TBD |
+
+## picoclaw Advantages Over OpenClaw
+
+| Area | picoclaw | OpenClaw |
+|------|----------|----------|
+| Shared agent state | Blackboard (real-time) | None (announce-only) |
+| Runtime | Go single binary | Node.js |
+| Memory footprint | ~10x smaller | Node.js overhead |
+| Deployment | Copy binary and run | npm install + config |
+| Concurrency | goroutines (native) | async/await |
+| Type safety | Compile-time | Runtime |
diff --git a/docs/architecture/c1-system-context.md b/docs/architecture/c1-system-context.md
@@ -0,0 +1,59 @@
+# C1 - System Context Diagram
+
+PicoClaw as a multi-agent platform within its ecosystem.
+
+```mermaid
+C4Context
+    title System Context - PicoClaw Multi-Agent Platform
+
+    Person(user, "User", "Interacts via messaging channels or CLI")
+    Person(dev, "Developer", "Configures agents, skills, and providers")
+
+    System(picoclaw, "PicoClaw", "Multi-agent AI platform that routes user messages to specialized agents backed by multiple LLM providers")
+
+    System_Ext(discord, "Discord", "Chat platform")
+    System_Ext(telegram, "Telegram", "Chat platform")
+    System_Ext(slack, "Slack", "Workspace messaging")
+    System_Ext(whatsapp, "WhatsApp", "Messaging")
+    System_Ext(cli, "CLI", "Direct terminal access")
+
+    System_Ext(openai, "OpenAI API", "GPT models, Codex")
+    System_Ext(anthropic, "Anthropic API", "Claude models")
+    System_Ext(gemini, "Google Gemini", "Gemini models")
+    System_Ext(openrouter, "OpenRouter", "Multi-model gateway")
+    System_Ext(groq, "Groq", "Fast inference")
+    System_Ext(ollama, "Ollama", "Local LLM")
+    System_Ext(claude_cli, "Claude Code CLI", "Subprocess provider")
+    System_Ext(codex_cli, "Codex CLI", "Subprocess provider")
+
+    Rel(user, discord, "Sends messages")
+    Rel(user, telegram, "Sends messages")
+    Rel(user, slack, "Sends messages")
+    Rel(user, whatsapp, "Sends messages")
+    Rel(user, cli, "Direct input")
+    Rel(dev, picoclaw, "Configures via config.json")
+
+    Rel(discord, picoclaw, "Webhook/Bot events")
+    Rel(telegram, picoclaw, "Bot API")
+    Rel(slack, picoclaw, "Events API")
+    Rel(whatsapp, picoclaw, "Webhook")
+    Rel(cli, picoclaw, "Stdin/Stdout")
+
+    Rel(picoclaw, openai, "HTTPS/REST")
+    Rel(picoclaw, anthropic, "HTTPS/REST")
+    Rel(picoclaw, gemini, "HTTPS/REST")
+    Rel(picoclaw, openrouter, "HTTPS/REST")
+    Rel(picoclaw, groq, "HTTPS/REST")
+    Rel(picoclaw, ollama, "HTTP localhost")
+    Rel(picoclaw, claude_cli, "Subprocess stdio")
+    Rel(picoclaw, codex_cli, "Subprocess stdio")
+```
+
+## Key interactions
+
+| Boundary | Protocol | Direction |
+|----------|----------|-----------|
+| User -> Channels | Platform-native (Discord bot, Telegram bot, etc.) | Inbound |
+| Channels -> PicoClaw | Go channel bus (`pkg/bus`) | Internal |
+| PicoClaw -> LLM Providers | HTTPS REST / Subprocess stdio | Outbound |
+| Developer -> PicoClaw | `~/.picoclaw/config.json` + workspace files | Config |
diff --git a/docs/architecture/c2-container.md b/docs/architecture/c2-container.md
@@ -0,0 +1,58 @@
+# C2 - Container Diagram
+
+Runtime containers inside PicoClaw.
+
+```mermaid
+C4Container
+    title Container Diagram - PicoClaw Runtime
+
+    Person(user, "User")
+
+    System_Boundary(picoclaw, "PicoClaw Process") {
+        Container(gateway, "Gateway", "Go HTTP server", "Exposes health/ready endpoints, manages lifecycle")
+        Container(channel_mgr, "Channel Manager", "pkg/channels", "Manages Discord, Telegram, Slack, WhatsApp, CLI connections")
+        Container(msg_bus, "Message Bus", "pkg/bus", "Pub/sub event bus routing messages between channels and agents")
+        Container(agent_loop, "Agent Loop", "pkg/agent", "Core orchestrator: routes messages to agents, manages tool loops, sessions")
+        Container(registry, "Agent Registry", "pkg/agent", "Stores AgentInstance configs, resolves agent by ID or route")
+        Container(router, "Route Resolver", "pkg/routing", "Matches incoming messages to agents based on channel/chat/peer bindings")
+        Container(multiagent, "Multi-Agent Framework", "pkg/multiagent", "Blackboard shared context, Handoff mechanism, Agent discovery tools")
+        Container(tools, "Tool Registry", "pkg/tools", "Shell, file, web, session, message, spawn, exec tools")
+        Container(providers, "Provider Layer", "pkg/providers", "LLM provider abstraction: HTTP, CLI, OAuth, Fallback chain")
+        Container(session, "Session Store", "pkg/session", "Per-agent session persistence with conversation history")
+        Container(skills, "Skills Engine", "pkg/skills", "Loads SKILL.md files, provides skill tools to agents")
+        Container(config, "Config", "pkg/config", "Loads config.json, agent definitions, model_list")
+    }
+
+    System_Ext(llm, "LLM Providers", "OpenAI, Anthropic, Gemini, Groq, Ollama, Claude CLI, Codex CLI")
+    System_Ext(channels_ext, "Messaging Platforms", "Discord, Telegram, Slack, WhatsApp")
+
+    Rel(user, channels_ext, "Sends message")
+    Rel(channels_ext, channel_mgr, "Delivers event")
+    Rel(channel_mgr, msg_bus, "Publishes message")
+    Rel(msg_bus, agent_loop, "Delivers to agent")
+    Rel(agent_loop, router, "Resolves target agent")
+    Rel(agent_loop, registry, "Gets AgentInstance")
+    Rel(agent_loop, multiagent, "Blackboard sync, Handoff")
+    Rel(agent_loop, tools, "Executes tool calls")
+    Rel(agent_loop, session, "Load/save history")
+    Rel(agent_loop, skills, "Resolves skill tools")
+    Rel(agent_loop, providers, "LLM Chat()")
+    Rel(providers, llm, "API calls")
+    Rel(gateway, agent_loop, "Lifecycle management")
+    Rel(config, agent_loop, "Agent definitions")
+    Rel(config, providers, "Provider config")
+    Rel(config, registry, "AgentConfig list")
+```
+
+## Container responsibilities
+
+| Container | Package | Key types |
+|-----------|---------|-----------|
+| Agent Loop | `pkg/agent` | `AgentLoop`, `RunToolLoop()` |
+| Agent Registry | `pkg/agent` | `AgentRegistry`, `AgentInstance` |
+| Route Resolver | `pkg/routing` | `RouteResolver`, `SessionKeyBuilder` |
+| Multi-Agent | `pkg/multiagent` | `Blackboard`, `HandoffTool`, `ListAgentsTool` |
+| Provider Layer | `pkg/providers` | `LLMProvider`, `FallbackChain`, `HTTPProvider` |
+| Tool Registry | `pkg/tools` | `Tool`, `ContextualTool`, `AsyncTool` |
+| Session Store | `pkg/session` | `SessionStore`, conversation history |
+| Config | `pkg/config` | `Config`, `AgentConfig`, `ModelConfig` |