story-kit: start 174_story_matrix_chatbot_interface_for_story_kit

.story_kit/work/2_current/174_story_matrix_chatbot_interface_for_story_kit.md

@@ -0,0 +1,71 @@
+---
+name: Matrix Bot with LLM Conversation
+---
+
+# Matrix Bot with LLM Conversation
+
+## User Story
+
+As a developer, I want to talk to Story Kit through a Matrix chat room so that I can create stories, assign agents, and manage the pipeline conversationally from any Matrix client (Element, Element X, mobile).
+
+## Background
+
+Story Kit currently requires the web UI or direct file manipulation to manage the pipeline. A Matrix bot built into the server provides a conversational interface powered by an LLM with access to Story Kit's MCP tools. Users talk naturally — "we need a dark mode feature", "what's stuck?", "put a coder on 42" — and the LLM interprets intent and calls the appropriate tools.
+
+Matrix is the right platform because:
+- Self-hosted (Conduit already running)
+- Proper bot API (appservice or client SDK)
+- E2EE support
+- Bridges to Signal/WhatsApp for free
+
+## Architecture
+
+```
+Matrix Room
+    |
+    v
+Story Kit Server
+    |-- matrix module (matrix-sdk) -- receives messages, posts responses
+    |-- LLM (Anthropic API) -------- interprets intent, decides actions
+    |-- MCP tools ------------------- create_story, start_agent, list_agents, etc.
+```
+
+The Matrix module is built into the server process (`server/src/matrix/`). It:
+1. Connects to the Matrix homeserver as a bot user on server startup
+2. Joins a configured room
+3. Passes incoming messages to an LLM with Story Kit MCP tools available
+4. Posts LLM responses back to the room
+
+Benefits of building it in:
+- Direct access to `AppContext`, `AgentPool`, pipeline state
+- Single process to manage
+- MCP tools already exist — the LLM uses the same tools that CLI agents use
+
+## Acceptance Criteria
+
+- [ ] New `server/src/matrix/` module that connects to a Matrix homeserver using `matrix-sdk`
+- [ ] Bot reads configuration from `.story_kit/bot.toml` (homeserver URL, bot user credentials, room ID)
+- [ ] Bot connection is optional — server starts normally if `bot.toml` is missing or Matrix is disabled
+- [ ] Bot joins configured room on startup
+- [ ] Bot ignores its own messages (no echo loops)
+- [ ] Incoming room messages are passed to an LLM (Anthropic API) with Story Kit MCP tools
+- [ ] The LLM can call MCP tools to answer questions and take actions (create stories, assign agents, check pipeline status, etc.)
+- [ ] LLM responses are posted back to the room as the bot user
+
+## Out of Scope
+- Conversation context / message history (see story 182)
+- Live pipeline update feed (see story 181)
+- Multi-room support (see story 182)
+- E2EE (can be added later)
+- Distributed multi-node coordination
+- Web UI changes
+- Permission/auth model for who can run commands
+
+## Technical Notes
+- Use `matrix-sdk` crate for Matrix client
+- Module lives at `server/src/matrix/` (mod.rs + submodules as needed)
+- Bot receives `Arc<AppContext>` (or relevant sub-fields) at startup to access internals directly
+- Configuration in `.story_kit/bot.toml` keeps bot config alongside project config
+- Bot spawns as a `tokio::spawn` task from `main.rs`, similar to the watcher and reaper tasks
+- LLM calls use the same Anthropic API path the server already uses for the web UI chat
+- MCP tool definitions are already registered at `POST /mcp` — the LLM can use the same tool schemas