story-kit: create 174_story_matrix_chatbot_interface_for_story_kit

.story_kit/work/1_upcoming/174_story_matrix_chatbot_interface_for_story_kit.md

@@ -0,0 +1,82 @@
+---
+name: Matrix Chatbot Interface for Story Kit
+---
+
+# Matrix Chatbot Interface for Story Kit
+
+## User Story
+
+As a developer, I want to interact with Story Kit through a Matrix chat room so that I can create stories, assign agents, and monitor pipeline progress from any Matrix client (Element, Element X, mobile) without needing the web UI open.
+
+## Background
+
+Story Kit currently requires the web UI or direct file manipulation to manage the pipeline. A Matrix bot bridges the gap between the existing HTTP/WebSocket API and a conversational interface, enabling:
+
+- Mobile access (manage agents from your phone)
+- Group collaboration (multiple people in a room managing work together)
+- Social coding (see agent activity as chat messages, discuss stories in-thread)
+- Future distributed computing (multiple Story Kit nodes coordinated via Matrix)
+
+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 (Conduit) <-> Story Kit Bot (matrix-sdk) <-> Story Kit Server (HTTP API)
+```
+
+The bot is a Matrix client that:
+1. Joins rooms (group or 1:1 DM)
+2. Listens for messages (commands or natural language)
+3. Calls the existing Story Kit HTTP API
+4. Posts pipeline updates back to the room (sourced from WebSocket events)
+
+The bot runs as a separate binary/process alongside the Story Kit server.
+
+## Acceptance Criteria
+
+### Phase 1: Core Bot Infrastructure
+- [ ] A new Rust binary `story-kit-bot` that connects to a Matrix homeserver as a bot user
+- [ ] Bot reads configuration from `.story_kit/bot.toml` (homeserver URL, bot user credentials, room ID(s), Story Kit server URL)
+- [ ] Bot joins configured room(s) on startup
+- [ ] Bot responds to a `!status` command with current pipeline state (counts per stage)
+- [ ] Bot responds to `!pipeline` with a formatted list of all stories across all stages
+
+### Phase 2: Story Management
+- [ ] `!create story <title>` creates a new story in `1_upcoming/` via the Story Kit API
+- [ ] `!create bug <title>` creates a new bug in `1_upcoming/`
+- [ ] `!assign <story_id>` starts a coder agent on the given story
+- [ ] `!stop <story_id>` stops the agent working on the given story
+- [ ] `!agents` lists all agents and their current status
+
+### Phase 3: Live Updates
+- [ ] Bot subscribes to Story Kit WebSocket and posts pipeline changes to the room
+- [ ] Agent state changes (started, completed, failed) appear as room messages
+- [ ] Stories moving between pipeline stages generate notifications
+- [ ] Messages are concise and formatted for readability (not noisy)
+
+## Out of Scope
+- Natural language understanding (LLM-powered intent parsing) — commands are explicit for now
+- E2EE (can be added later, start with unencrypted room)
+- Multi-project support (single project per bot instance)
+- Distributed multi-node coordination (future story)
+- Web UI changes
+- Permission/auth model for who can run commands
+
+## Technical Notes
+- Use `matrix-sdk` crate for Matrix client
+- Bot is a separate binary in the workspace (`bot/` directory sibling to `server/` and `frontend/`)
+- Reuse existing HTTP API endpoints — no new server endpoints needed
+- Configuration in `.story_kit/bot.toml` keeps bot config alongside project config
+- Consider `reqwest` for HTTP calls to the Story Kit API (already in the workspace)
+
+## Future Considerations
+- LLM-powered natural language commands ("put a coder on the auth story")
+- Thread-based story discussions (Matrix threads per story)
+- Code review in-chat (show diffs, approve/reject)
+- Distributed mode: multiple bots on different machines sharing a repo
+- Bridge to Signal/WhatsApp via Matrix bridges