From a2a5f5320923a95d3b5784955878f70d7d9fc5f5 Mon Sep 17 00:00:00 2001 From: Dave Date: Wed, 25 Feb 2026 11:36:54 +0000 Subject: [PATCH] story-kit: create 174_story_matrix_chatbot_interface_for_story_kit --- ..._matrix_chatbot_interface_for_story_kit.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 .story_kit/work/1_upcoming/174_story_matrix_chatbot_interface_for_story_kit.md diff --git a/.story_kit/work/1_upcoming/174_story_matrix_chatbot_interface_for_story_kit.md b/.story_kit/work/1_upcoming/174_story_matrix_chatbot_interface_for_story_kit.md new file mode 100644 index 0000000..86f1244 --- /dev/null +++ b/.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 ` 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