synapbus/BOOTSTRAP_PROMPT.md

# SynapBus Bootstrap Prompt

Paste everything below the line into Claude in the `/Users/user/repos/synapbus` directory.

---

I'm bootstrapping **SynapBus** — an open-source, local-first, MCP-native agent-to-agent messaging service written in Go. Single binary, embedded storage, semantic search, Slack-like Web UI.

The project idea is fully described in `IDEA.md` — read it first.

The repo is at https://github.com/synapbus/synapbus (public, empty).
Domains: synapbus.com + synapbus.dev (to be registered).

## What I need you to do (in order):

### 1. Create CLAUDE.md

Write the project CLAUDE.md with:
- Project overview (from IDEA.md)
- Tech stack: Go 1.23+, modernc.org/sqlite (pure Go), TFMV/hnsw (pure Go vectors), mcp-go (mark3labs), chi router, embedded Svelte SPA, fosite (OAuth 2.1)
- Directory structure (Go standard layout):
  ```
  synapbus/
  ├── cmd/synapbus/         # main.go entry point
  ├── internal/
  │   ├── auth/             # OAuth 2.1, API keys, sessions
  │   ├── messaging/        # core message engine
  │   ├── channels/         # channel management
  │   ├── agents/           # agent registry
  │   ├── search/           # semantic search (embeddings + HNSW)
  │   ├── storage/          # SQLite + migrations
  │   ├── attachments/      # content-addressable FS
  │   ├── mcp/              # MCP server (tools, transport)
  │   ├── api/              # REST API handlers
  │   ├── web/              # embedded Web UI (Svelte SPA)
  │   └── trace/            # agent activity logging
  ├── web/                  # Svelte source (built → internal/web/dist/)
  ├── schema/               # SQLite migrations
  ├── docs/                 # documentation
  ├── .specify/             # speckit specs
  └── Makefile
  ```
- Build commands: `make build`, `make test`, `make dev`, `make web` (build Svelte SPA)
- Run: `./synapbus serve --port 8080 --data ./data`
- Conventions: Go standard, `internal/` for non-public packages, table-driven tests, context propagation, structured logging (slog)
- Environment variables: `SYNAPBUS_PORT`, `SYNAPBUS_DATA_DIR`, `SYNAPBUS_EMBEDDING_PROVIDER` (openai/gemini/ollama), `SYNAPBUS_EMBEDDING_API_KEY`, `SYNAPBUS_OLLAMA_URL`

### 2. Create speckit constitution

Run `/speckit.constitution` and provide these architecture decisions:

**Principles:**
1. **Local-first, single binary** — everything in one Go binary, no external dependencies at runtime
2. **MCP-native** — agents interact exclusively through MCP protocol tools, REST API is internal only
3. **Pure Go, zero CGO** — all dependencies must be pure Go (modernc.org/sqlite, not mattn/go-sqlite3)
4. **Multi-tenant with ownership** — every agent has a human owner; owners control access and see traces
5. **Embedded OAuth 2.1** — authentication server built into SynapBus, not delegated externally
6. **Semantic-ready storage** — SQLite for relational data, HNSW for vector search, both embedded
7. **Swarm intelligence patterns** — first-class support for stigmergy, task auction, agent discovery
8. **Observable by default** — all agent actions traced, searchable, auditable by owners
9. **Progressive complexity** — start with basic messaging, layer on vectors/attachments/swarm later
10. **Web UI as first-class citizen** — embedded Svelte SPA, not an afterthought

**Technology decisions:**
- Go 1.23+ (single binary, cross-compilation)
- modernc.org/sqlite (pure Go SQLite, no CGO)
- TFMV/hnsw (pure Go HNSW vector index)
- mark3labs/mcp-go (MCP server library)
- go-chi/chi (HTTP router)
- ory/fosite (OAuth 2.1 framework)
- Svelte 5 + Tailwind (Web UI, embedded via go:embed)
- slog (structured logging)
- Content-addressable filesystem for attachments (SHA-256)

**Non-goals:**
- No PostgreSQL, Redis, or external DB dependency
- No framework lock-in (LangChain, CrewAI, etc.)
- No A2A protocol support (yet) — MCP only for v1
- No cloud-specific features — local-first always

### 3. Create specs for these features (use /speckit.specify for each):

**Spec 001: Core Messaging**
- Messages: send (DM or channel), read inbox, claim for processing, mark done/failed
- Conversations: threaded, with subjects, auto-created on first message
- Priority levels (1-10), status tracking (pending/processing/done/failed)
- Rich metadata (JSON) on messages for filtering
- Read/unread tracking per agent per conversation
- SQLite storage with migrations
- MCP tools: `send_message`, `read_inbox`, `claim_messages`, `mark_done`, `search_messages` (full-text initially)

**Spec 002: Agent Registry & Auth**
- Agent self-registration via MCP tool `register_agent`
- Each agent has: name (unique), display_name, type (ai/human), capabilities (JSON), owner_id
- API key authentication for agents (generated on registration, returned once)
- Agent CRUD: register, update capabilities, deregister (owner only)
- Owner-scoped access: agents can only see own messages + joined channels
- MCP tools: `register_agent`, `discover_agents`, `update_agent`, `deregister_agent`
- Agent capability cards (JSON schema describing what the agent can do)

**Spec 003: Human Auth (OAuth 2.1)**
- OAuth 2.1 authorization server embedded in SynapBus (using fosite)
- Local accounts: username + password (bcrypt hashed)
- Token endpoints: /oauth/authorize, /oauth/token, /oauth/introspect
- Grant types: authorization_code (Web UI), client_credentials (programmatic)
- Session management for Web UI (httponly cookies)
- User CRUD: create account, change password, list owned agents
- PKCE required for all authorization code flows
- Refresh token rotation

**Spec 004: Channels**
- Public channels: any registered agent can join
- Private channels: invite-only, managed by creator
- Channel metadata: name, description, topic, created_by
- Membership management: join, leave, invite, kick (owner only)
- Channel message broadcast: message sent to channel delivered to all members
- MCP tools: `create_channel`, `join_channel`, `leave_channel`, `list_channels`, `invite_to_channel`

**Spec 005: Web UI**
- Svelte 5 + Tailwind CSS embedded SPA
- Pages: Login, Dashboard (recent messages), Conversations (thread view), Channels, Agents, Settings
- Real-time updates via SSE
- Compose: send DM or channel message, select recipient from dropdown
- Search: full-text search across messages
- Agent management: view owned agents, their traces, revoke API keys
- Responsive, dark mode support
- Built with `make web`, embedded in Go binary via `go:embed`

**Spec 006: MCP Server**
- MCP server using mark3labs/mcp-go
- SSE transport (primary) + Streamable HTTP transport
- All messaging operations exposed as MCP tools
- Tool authentication: API key in MCP request headers
- Tool listing with JSON schema descriptions
- Health check endpoint
- Connection management: track connected agents

**Spec 007: Trace Logging & Observability**
- All agent actions logged: tool calls, messages sent/received, channel joins, errors
- Traces stored in SQLite with agent_name, action, details, timestamp
- Owner can view traces for their agents via Web UI
- Filterable by agent, action type, time range
- Exportable as JSON/CSV
- Optional Prometheus metrics endpoint (/metrics)
- Structured logging (slog) to stdout

**Spec 008: Semantic Search**
- Message embedding on ingest (async, configurable provider)
- Providers: OpenAI text-embedding-3-small, Gemini embedding, Ollama (local)
- HNSW vector index (TFMV/hnsw) for ANN search
- Combined search: vector similarity + metadata filters + full-text
- MCP tool: `search_messages` with query, filters, limit
- Incremental indexing: new messages embedded in background
- Fallback: full-text search if no embedding provider configured

**Spec 009: Attachments**
- Upload files up to 50MB per message
- Content-addressable storage: SHA-256 hash as filename, dedup
- Store in `{data_dir}/attachments/{hash[0:2]}/{hash[2:4]}/{hash}`
- Metadata in SQLite: hash, original_filename, size, mime_type, message_id
- MCP tools: `upload_attachment` (returns hash), `download_attachment` (by hash)
- Web UI: inline preview for images, download link for others
- Garbage collection: remove orphaned attachments

**Spec 010: Swarm Patterns**
- **Stigmergy (Blackboard)**: tagged messages on a shared channel that agents read and react to. Tags: `#finding`, `#task`, `#decision`, `#trace`
- **Task Auction**: `post_task` with requirements + deadline → agents `bid_task` with capabilities + time estimate → poster selects winner → task assigned
- **Agent Discovery**: `discover_agents` searches capability cards by keyword/semantic match
- Channel types: `standard` (chat), `blackboard` (stigmergy), `auction` (tasks)
- MCP tools: `post_task`, `bid_task`, `accept_bid`, `complete_task`

### 4. Generate tasks from specs

After creating all specs, run `/speckit.tasks` for each spec to generate implementation tasks.

### 5. Create initial project files

- `go.mod` with module `github.com/synapbus/synapbus`
- `Makefile` with targets: build, test, dev, web, clean, lint
- `cmd/synapbus/main.go` — cobra CLI with `serve` command (placeholder)
- `schema/001_initial.sql` — SQLite migration for agents, messages, conversations, channels, channel_members, inbox_state, traces, attachments
- `README.md` — project overview, installation, quick start
- `.gitignore` — Go + Node + data directory
- `LICENSE` — Apache 2.0

### 6. Push initial commit

Stage all files, commit with message "feat: initial SynapBus project scaffolding", push to `main` on origin.

---

**Key design constraints to keep in mind:**
- ZERO CGO — the binary must cross-compile cleanly for linux/amd64, darwin/arm64
- All storage in a single `--data` directory (SQLite DB file + attachments dir + vector index)
- MCP is THE interface for agents — REST API is for internal Web UI use only
- Every agent action must be traceable by the human owner
- OAuth 2.1 is built INTO the binary, not a separate service
- Web UI is built from Svelte source, embedded at compile time