story-kit: create 174_story_matrix_chatbot_interface_for_story_kit
This commit is contained in:
Dave
@@ -10,7 +10,7 @@ As a developer, I want to interact with Story Kit through a Matrix chat room so
|
||||
|
||||
## 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:
|
||||
Story Kit currently requires the web UI or direct file manipulation to manage the pipeline. A Matrix bot built into the server bridges the gap between the existing internals and a conversational interface, enabling:
|
||||
|
||||
- Mobile access (manage agents from your phone)
|
||||
- Group collaboration (multiple people in a room managing work together)
|
||||
@@ -26,35 +26,44 @@ Matrix is the right platform because:
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Matrix (Conduit) <-> Story Kit Bot (matrix-sdk) <-> Story Kit Server (HTTP API)
|
||||
Matrix (Conduit) <-> Story Kit Server (matrix-sdk built in)
|
||||
|
|
||||
AppContext, AgentPool, watcher_tx (direct access)
|
||||
```
|
||||
|
||||
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 Matrix bot is built into the server process as a module (`server/src/matrix/`). It:
|
||||
1. Connects to the Matrix homeserver as a bot user on server startup
|
||||
2. Joins configured room(s)
|
||||
3. Listens for messages (commands)
|
||||
4. Calls internal functions directly (no HTTP round-trip to itself)
|
||||
5. Subscribes to `watcher_tx` broadcast channel for live pipeline updates
|
||||
6. Posts updates back to the room
|
||||
|
||||
The bot runs as a separate binary/process alongside the Story Kit server.
|
||||
Benefits of building it in:
|
||||
- Direct access to `AppContext`, `AgentPool`, pipeline state — no self-referential HTTP calls
|
||||
- Subscribes to existing broadcast channels (`watcher_tx`, `reconciliation_tx`) for live events
|
||||
- Single process to manage — no "where is the server?" configuration
|
||||
- Can restart cleanly with the 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)
|
||||
- [ ] 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(s))
|
||||
- [ ] Bot connection is optional — server starts normally if `bot.toml` is missing or Matrix is disabled
|
||||
- [ ] 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 story <title>` creates a new story in `1_upcoming/`
|
||||
- [ ] `!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
|
||||
- [ ] Bot subscribes to `watcher_tx` broadcast channel 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)
|
||||
@@ -69,14 +78,14 @@ The bot runs as a separate binary/process alongside the Story Kit server.
|
||||
|
||||
## 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
|
||||
- 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
|
||||
- Consider `reqwest` for HTTP calls to the Story Kit API (already in the workspace)
|
||||
- Bot spawns as a `tokio::spawn` task from `main.rs`, similar to the watcher and reaper tasks
|
||||
|
||||
## 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
|
||||
- Distributed mode: multiple servers in the same Matrix room, coordinating via git
|
||||
- Bridge to Signal/WhatsApp via Matrix bridges
|
||||
|
||||
Reference in New Issue
Block a user