storkit: accept 338_story_web_ui_button_to_move_stories_between_pipeline_stages

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/settings.json

@@ -1,10 +1,10 @@
 {
-  "enabledMcpjsonServers": ["story-kit"],
+  "enabledMcpjsonServers": ["storkit"],
   "permissions": {
     "allow": [
-      "Bash(./server/target/debug/story-kit:*)",
+      "Bash(./server/target/debug/storkit:*)",
-      "Bash(./target/debug/story-kit:*)",
+      "Bash(./target/debug/storkit:*)",
-      "Bash(STORYKIT_PORT=*)",
+      "Bash(STORKIT_PORT=*)",
       "Bash(cargo build:*)",
       "Bash(cargo check:*)",
       "Bash(cargo clippy:*)",
@@ -54,9 +54,20 @@
       "WebFetch(domain:portkey.ai)",
       "WebFetch(domain:www.shuttle.dev)",
       "WebSearch",
-      "mcp__story-kit__*",
+      "mcp__storkit__*",
       "Edit",
-      "Write"
+      "Write",
+      "Bash(find *)",
+      "Bash(sqlite3 *)",
+      "Bash(cat <<:*)",
+      "Bash(cat <<'ENDJSON:*)",
+      "Bash(make release:*)",
+      "Bash(npm test:*)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(npx vite:*)",
+      "Bash(npm run dev:*)"
     ]
   }
 }

.gitignore

@@ -1,25 +1,13 @@
 # Claude Code
 .claude/settings.local.json
+.mcp.json
 
 # Local environment (secrets)
 .env
 
-# App specific
+# App specific (root-level; storkit subdirectory patterns live in .storkit/.gitignore)
 store.json
-.story_kit_port
+.storkit_port
-
-# Bot config (contains credentials)
-.story_kit/bot.toml
-
-# Matrix SDK state store
-.story_kit/matrix_store/
-
-# Agent worktrees and merge workspace (managed by the server, not tracked in git)
-.story_kit/worktrees/
-.story_kit/merge_workspace/
-
-# Coverage reports (generated by cargo-llvm-cov, not tracked in git)
-.story_kit/coverage/
 
 # Rust stuff
 target
@@ -38,6 +26,7 @@ frontend/node_modules
 frontend/dist
 frontend/dist-ssr
 frontend/test-results
+frontend/serve
 frontend/*.local
 server/target
 

.storkit/.gitignore

@@ -0,0 +1,22 @@
+# Bot config (contains credentials)
+bot.toml
+
+# Matrix SDK state store
+matrix_store/
+matrix_device_id
+matrix_history.json
+
+# Agent worktrees and merge workspace (managed by the server, not tracked in git)
+worktrees/
+merge_workspace/
+
+# Intermediate pipeline stages (transient, not committed per spike 92)
+work/2_current/
+work/3_qa/
+work/4_merge/
+
+# Coverage reports (generated by cargo-llvm-cov, not tracked in git)
+coverage/
+
+# Token usage log (generated at runtime, contains cost data)
+token_usage.jsonl

.storkit/README.md

@@ -11,14 +11,14 @@ When you start a new session with this project:
 
 1. **Check for MCP Tools:** Read `.mcp.json` to discover the MCP server endpoint. Then list available tools by calling:
    ```bash
-   curl -s "$(jq -r '.mcpServers["story-kit"].url' .mcp.json)" \
+   curl -s "$(jq -r '.mcpServers["storkit"].url' .mcp.json)" \
      -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
    ```
    This returns the full tool catalog (create stories, spawn agents, record tests, manage worktrees, etc.). Familiarize yourself with the available tools before proceeding. These tools allow you to directly manipulate the workflow and spawn subsidiary agents without manual file manipulation.
 2. **Read Context:** Check `.story_kit/specs/00_CONTEXT.md` for high-level project goals.
 3. **Read Stack:** Check `.story_kit/specs/tech/STACK.md` for technical constraints and patterns.
-4. **Check Work Items:** Look at `.story_kit/work/1_upcoming/` and `.story_kit/work/2_current/` to see what work is pending.
+4. **Check Work Items:** Look at `.story_kit/work/1_backlog/` and `.story_kit/work/2_current/` to see what work is pending.
 
 
 ---
@@ -52,7 +52,7 @@ project_root/
   ├── README.md          # This document
   ├── project.toml       # Agent configuration (roles, models, prompts)
   ├── work/              # Unified work item pipeline (stories, bugs, spikes)
-  │   ├── 1_upcoming/    # New work items awaiting implementation
+  │   ├── 1_backlog/    # New work items awaiting implementation
   │   ├── 2_current/     # Work in progress
   │   ├── 3_qa/          # QA review
   │   ├── 4_merge/       # Ready to merge to master
@@ -78,7 +78,7 @@ All work items (stories, bugs, spikes) live in the same `work/` pipeline. Items
 
 Items move through stages by moving the file between directories:
 
-`1_upcoming` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
+`1_backlog` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
 
 Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 
@@ -87,7 +87,7 @@ Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 The server watches `.story_kit/work/` for changes. When a file is created, moved, or modified, the watcher auto-commits with a deterministic message and broadcasts a WebSocket notification to the frontend. This means:
 
 *   MCP tools only need to write/move files — the watcher handles git commits
-*   IDE drag-and-drop works (drag a story from `1_upcoming/` to `2_current/`)
+*   IDE drag-and-drop works (drag a story from `1_backlog/` to `2_current/`)
 *   The frontend updates automatically without manual refresh
 
 ---
@@ -156,7 +156,7 @@ Not everything needs to be a full story. Simple bugs can skip the story process:
 *   Performance issues with known fixes
 
 ### Bug Process
-1.  **Document Bug:** Create a bug file in `work/1_upcoming/` named `{id}_bug_{slug}.md` with:
+1.  **Document Bug:** Create a bug file in `work/1_backlog/` named `{id}_bug_{slug}.md` with:
     *   **Symptom:** What the user observes
     *   **Root Cause:** Technical explanation (if known)
     *   **Reproduction Steps:** How to trigger the bug
@@ -186,7 +186,7 @@ Not everything needs a story or bug fix. Spikes are time-boxed investigations to
 *   Need to validate performance constraints
 
 ### Spike Process
-1.  **Document Spike:** Create a spike file in `work/1_upcoming/` named `{id}_spike_{slug}.md` with:
+1.  **Document Spike:** Create a spike file in `work/1_backlog/` named `{id}_spike_{slug}.md` with:
     *   **Question:** What you need to answer
     *   **Hypothesis:** What you expect to be true
     *   **Timebox:** Strict limit for the research
@@ -209,7 +209,7 @@ When the LLM context window fills up (or the chat gets slow/confused):
 1.  **Stop Coding.**
 2.  **Instruction:** Tell the user to open a new chat.
 3.  **Handoff:** The only context the new LLM needs is in the `specs/` folder and `.mcp.json`.
-    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_upcoming/` and `work/2_current/` to see what is pending."
+    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_backlog/` and `work/2_current/` to see what is pending."
 
 
 ---
@@ -221,7 +221,7 @@ If a user hands you this document and says "Apply this process to my project":
 1.  **Check for MCP Tools:** Look for `.mcp.json` in the project root. If it exists, you have programmatic access to workflow tools and agent spawning capabilities.
 2.  **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
 3.  **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`.
-4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_upcoming/` through `work/6_archived/`).
+4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_backlog/` through `work/6_archived/`).
 5.  **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
 6.  **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
 7.  **Wait:** Ask the user for "Story #1".

.storkit/bot.toml.example

@@ -0,0 +1,61 @@
+homeserver = "https://matrix.example.com"
+username = "@botname:example.com"
+password = "your-bot-password"
+
+# List one or more rooms to listen in.  Use a single-element list for one room.
+room_ids = ["!roomid:example.com"]
+
+# Optional: the deprecated single-room key is still accepted for backwards compat.
+# room_id = "!roomid:example.com"
+
+allowed_users = ["@youruser:example.com"]
+enabled = false
+
+# Maximum conversation turns to remember per room (default: 20).
+# history_size = 20
+
+# Rooms where the bot responds to all messages (not just addressed ones).
+# This list is updated automatically when users toggle ambient mode at runtime.
+# ambient_rooms = ["!roomid:example.com"]
+
+# ── WhatsApp Business API ──────────────────────────────────────────────
+# Set transport = "whatsapp" to use WhatsApp instead of Matrix.
+# The webhook endpoint will be available at /webhook/whatsapp.
+# You must configure this URL in the Meta Developer Dashboard.
+#
+# transport = "whatsapp"
+# whatsapp_phone_number_id = "123456789012345"
+# whatsapp_access_token = "EAAx..."
+# whatsapp_verify_token = "my-secret-verify-token"
+#
+# ── 24-hour messaging window & notification templates ─────────────────
+# WhatsApp only allows free-form text messages within 24 hours of the last
+# inbound message from a user.  For proactive pipeline notifications sent
+# after the window expires, an approved Meta message template is used.
+#
+# Register the template in the Meta Business Manager:
+#   1. Go to Business Settings → WhatsApp → Message Templates → Create.
+#   2. Category: UTILITY
+#   3. Template name: pipeline_notification   (or your chosen name below)
+#   4. Language: English (en_US)
+#   5. Body text (example):
+#        Story *{{1}}* has moved to *{{2}}*.
+#      Where {{1}} = story name, {{2}} = pipeline stage.
+#   6. Submit for review.  Meta typically approves utility templates within
+#      minutes; transactional categories may take longer.
+#
+# Once approved, set the name below (default: "pipeline_notification"):
+# whatsapp_notification_template = "pipeline_notification"
+
+# ── Slack Bot API ─────────────────────────────────────────────────────
+# Set transport = "slack" to use Slack instead of Matrix.
+# The webhook endpoint will be available at /webhook/slack.
+# Configure this URL in the Slack App → Event Subscriptions → Request URL.
+#
+# Required Slack App scopes: chat:write, chat:update
+# Subscribe to bot events: message.channels, message.groups, message.im
+#
+# transport = "slack"
+# slack_bot_token = "xoxb-..."
+# slack_signing_secret = "your-signing-secret"
+# slack_channel_ids = ["C01ABCDEF"]

.storkit/problems.md

@@ -0,0 +1,28 @@
+# Problems
+
+Recurring issues observed during pipeline operation. Review periodically and create stories for systemic problems.
+
+## 2026-03-18: Stories graduating to "done" with empty merges (7 of 10)
+
+Pipeline allows stories to move through coding → QA → merge → done without any actual code changes landing on master. The squash-merge produces an empty diff but the pipeline still marks the story as done. Affected stories: 247, 273, 274, 278, 279, 280, 92. Only 266, 271, 277, and 281 actually shipped code. Root cause: no check that the merge commit contains a non-empty diff. Filed bug 283 for the manual_qa gate issue specifically, but the empty-merge-to-done problem is broader and needs its own fix.
+
+## 2026-03-18: Agent committed directly to master instead of worktree
+
+Multiple agents have committed directly to master instead of their worktree/feature branch:
+
+- Commit `5f4591f` ("fix: update should_commit_stage test to match 5_done") — likely mergemaster
+- Commit `a32cfbd` ("Add bot-level command registry with help command") — story 285 coder committed code + Cargo.lock directly to master
+
+Agents should only commit to their feature branch or merge-queue branch, never to master directly. Suspect agents are running `git commit` in the project root instead of the worktree directory. This can also revert uncommitted fixes on master (e.g. project.toml pkill fix was overwritten). Frequency: at least 2 confirmed cases. This is a recurring and serious problem — needs a guard in the server or agent prompts.
+
+## 2026-03-19: Auto-assign re-assigns mergemaster to failed merge stories in a loop
+
+After bug 295 fix (`auto_assign_available_work` after every pipeline advance), mergemaster gets re-assigned to stories that already have a merge failure flag. Story 310 had an empty diff merge failure — mergemaster correctly reported the failure, but auto-assign immediately re-assigned mergemaster to the same story, creating an infinite retry loop. The auto-assign logic needs to check for the `merge_failure` front matter flag before re-assigning agents to stories in `4_merge/`.
+
+## 2026-03-19: Coder produces no code (complete ghost — story 310)
+
+Story 310 (Bot delete command) went through the full pipeline — coder session ran, passed QA/gates, moved to merge — but the coder produced zero code. No commits on the feature branch, no commits on master. The entire agent session was a no-op. This is different from the "committed to master instead of worktree" problem — in this case, the coder simply did nothing. Need to investigate the coder logs to understand what happened. The empty-diff merge check would catch this at merge time, but ideally the server should detect "coder finished with no commits on feature branch" at the gate-check stage and fail early.
+
+## 2026-03-19: Auto-assign assigns mergemaster to coding-stage stories
+
+Auto-assign picked mergemaster for story 310 which was in `2_current/`. Mergemaster should only work on stories in `4_merge/`. The `auto_assign_available_work` function doesn't enforce that the agent's configured stage matches the pipeline stage of the story it's being assigned to. Story 279 (auto-assign respects agent stage from front matter) was supposed to fix this, but the check may only apply to front-matter preferences, not the fallback assignment path.

.storkit/project.toml

@@ -1,7 +1,22 @@
+# Project-wide default QA mode: "server", "agent", or "human".
+# Per-story `qa` front matter overrides this setting.
+default_qa = "server"
+
+# Default model for coder agents. Only agents with this model are auto-assigned.
+# Opus coders are reserved for explicit per-story `agent:` front matter requests.
+default_coder_model = "sonnet"
+
+# Maximum concurrent coder agents. Stories wait in 2_current/ when all slots are full.
+max_coders = 3
+
+# Maximum retries per story per pipeline stage before marking as blocked.
+# Set to 0 to disable retry limits.
+max_retries = 2
+
 [[component]]
 name = "frontend"
 path = "frontend"
-setup = ["pnpm install", "pnpm run build"]
+setup = ["npm install", "npm run build"]
 teardown = []
 
 [[component]]
@@ -10,45 +25,6 @@ path = "."
 setup = ["mkdir -p frontend/dist", "cargo check"]
 teardown = []
 
-[[agent]]
-name = "supervisor"
-stage = "other"
-role = "Coordinates work, reviews PRs, decomposes stories."
-model = "opus"
-max_turns = 200
-max_budget_usd = 15.00
-prompt = """You are the supervisor for story {{story_id}}. Your job is to coordinate coder agents to implement this story.
-
-Read CLAUDE.md first, then .story_kit/README.md to understand the dev process (SDTW). You are responsible for ensuring coders follow this process.
-
-## Your MCP Tools
-You have these tools via the story-kit MCP server:
-- start_agent(story_id, agent_name) - Start a coder agent on a story
-- wait_for_agent(story_id, agent_name, timeout_ms) - Block until the agent reaches a terminal state (completed/failed). Returns final status including completion report with gates_passed.
-- get_agent_output(story_id, agent_name, timeout_ms) - Poll agent output (returns recent events, call repeatedly)
-- list_agents() - See all running agents and their status
-- stop_agent(story_id, agent_name) - Stop a running agent
-- get_story_todos(story_id) - Get unchecked acceptance criteria for a story in work/2_current/
-- ensure_acceptance(story_id) - Check if a story passes acceptance gates
-
-## Your Workflow
-1. Read CLAUDE.md and .story_kit/README.md to understand the project and dev process
-2. Read the story file from .story_kit/work/ to understand requirements
-3. Move it to work/2_current/ if it is in work/1_upcoming/
-4. Start coder-1 on the story: call start_agent with story_id="{{story_id}}" and agent_name="coder-1"
-5. Wait for completion: call wait_for_agent with story_id="{{story_id}}" and agent_name="coder-1". The server automatically runs acceptance gates (cargo clippy + tests) when the coder process exits. wait_for_agent returns when the coder reaches a terminal state.
-6. Check the result: inspect the "completion" field in the wait_for_agent response — if gates_passed is true, the work is done; if false, review the gate_output and decide whether to start a fresh coder.
-7. If the agent gets stuck, stop it and start a fresh agent.
-8. STOP here. Do NOT accept the story or merge to master. Report the status to the human for final review and acceptance.
-
-## Rules
-- Do NOT implement code yourself - delegate to coder agents
-- Only run one coder at a time per story
-- Focus on coordination, monitoring, and quality review
-- Never accept stories or merge to master - that is the human's job
-- Your job ends when the coder's completion report shows gates_passed=true and you have reported the result"""
-system_prompt = "You are a supervisor agent. Read CLAUDE.md and .story_kit/README.md first to understand the project dev process. Use MCP tools to coordinate sub-agents. Never implement code directly - always delegate to coder agents and monitor their progress. Use wait_for_agent to block until the coder finishes — the server automatically runs acceptance gates when the agent process exits. Never accept stories or merge to master - get all gates green and report to the human."
-
 [[agent]]
 name = "coder-1"
 stage = "coder"
@@ -56,8 +32,8 @@ role = "Full-stack engineer. Implements features across all components."
 model = "sonnet"
 max_turns = 50
 max_budget_usd = 5.00
-prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results."
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
-system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
 
 [[agent]]
 name = "coder-2"
@@ -66,8 +42,18 @@ role = "Full-stack engineer. Implements features across all components."
 model = "sonnet"
 max_turns = 50
 max_budget_usd = 5.00
-prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results."
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
-system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+
+[[agent]]
+name = "coder-3"
+stage = "coder"
+role = "Full-stack engineer. Implements features across all components."
+model = "sonnet"
+max_turns = 50
+max_budget_usd = 5.00
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
 
 [[agent]]
 name = "qa-2"
@@ -87,12 +73,12 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 - Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
 - Run `cargo clippy --all-targets --all-features` and note any warnings
 - If a `frontend/` directory exists:
-  - Run `pnpm run build` and note any TypeScript errors
+  - Run `npm run build` and note any TypeScript errors
   - Run `npx @biomejs/biome check src/` and note any linting issues
 
 ### 2. Test Verification
 - Run `cargo test` and verify all tests pass
-- If `frontend/` exists: run `pnpm test --run` and verify all frontend tests pass
+- If `frontend/` exists: run `npm test` and verify all frontend tests pass
 - Review test quality: look for tests that are trivial or don't assert meaningful behavior
 
 ### 3. Manual Testing Support
@@ -102,7 +88,7 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - URL to visit in the browser
   - Things to check in the UI
   - curl commands to exercise relevant API endpoints
-- Kill the test server when done: `pkill -f story-kit || true`
+- Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — it kills the vite dev server)
 
 ### 4. Produce Structured Report
 Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
@@ -118,7 +104,7 @@ Print your QA report to stdout before your process exits. The server will automa
 
 ### Test Verification
 - cargo test: PASS/FAIL (N tests)
-- pnpm test: PASS/FAIL/SKIP (N tests)
+- npm test: PASS/FAIL/SKIP (N tests)
 - Test quality issues: (list any trivial/weak tests, or "None")
 
 ### Manual Testing Plan
@@ -143,8 +129,8 @@ role = "Senior full-stack engineer for complex tasks. Implements features across
 model = "opus"
 max_turns = 80
 max_budget_usd = 20.00
-prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results."
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
-system_prompt = "You are a senior full-stack engineer working autonomously in a git worktree. You handle complex tasks requiring deep architectural understanding. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits."
+system_prompt = "You are a senior full-stack engineer working autonomously in a git worktree. You handle complex tasks requiring deep architectural understanding. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
 
 [[agent]]
 name = "qa"
@@ -164,12 +150,12 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 - Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
 - Run `cargo clippy --all-targets --all-features` and note any warnings
 - If a `frontend/` directory exists:
-  - Run `pnpm run build` and note any TypeScript errors
+  - Run `npm run build` and note any TypeScript errors
   - Run `npx @biomejs/biome check src/` and note any linting issues
 
 ### 2. Test Verification
 - Run `cargo test` and verify all tests pass
-- If `frontend/` exists: run `pnpm test --run` and verify all frontend tests pass
+- If `frontend/` exists: run `npm test` and verify all frontend tests pass
 - Review test quality: look for tests that are trivial or don't assert meaningful behavior
 
 ### 3. Manual Testing Support
@@ -179,7 +165,7 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - URL to visit in the browser
   - Things to check in the UI
   - curl commands to exercise relevant API endpoints
-- Kill the test server when done: `pkill -f story-kit || true`
+- Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — it kills the vite dev server)
 
 ### 4. Produce Structured Report
 Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
@@ -195,7 +181,7 @@ Print your QA report to stdout before your process exits. The server will automa
 
 ### Test Verification
 - cargo test: PASS/FAIL (N tests)
-- pnpm test: PASS/FAIL/SKIP (N tests)
+- npm test: PASS/FAIL/SKIP (N tests)
 - Test quality issues: (list any trivial/weak tests, or "None")
 
 ### Manual Testing Plan
@@ -220,7 +206,7 @@ role = "Merges completed coder work into master, runs quality gates, archives st
 model = "opus"
 max_turns = 30
 max_budget_usd = 5.00
-prompt = """You are the mergemaster agent for story {{story_id}}. Your job is to merge the completed coder work into master using the merge_agent_work MCP tool.
+prompt = """You are the mergemaster agent for story {{story_id}}. Your job is to merge the completed coder work into master.
 
 Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 
@@ -229,20 +215,43 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 2. Review the result: check success, had_conflicts, conflicts_resolved, gates_passed, and gate_output
 3. If merge succeeded and gates passed: report success to the human
 4. If conflicts were auto-resolved (conflicts_resolved=true) and gates passed: report success, noting which conflicts were resolved
-5. If conflicts could not be auto-resolved: call report_merge_failure(story_id='{{story_id}}', reason='<conflict details>') and report to the human. Master is untouched.
+5. If conflicts could not be auto-resolved: **resolve them yourself** in the merge worktree (see below)
-6. If merge failed for any other reason: call report_merge_failure(story_id='{{story_id}}', reason='<details>') and report to the human.
+6. If merge failed for any other reason: call report_merge_failure(story_id='{{story_id}}', reason='<details>') and report to the human
-7. If gates failed after merge: attempt to fix minor issues (see below), then re-trigger merge_agent_work. After 2 fix attempts, call report_merge_failure and stop.
+7. If gates failed after merge: attempt to fix the issues yourself in the merge worktree, then re-trigger merge_agent_work. After 3 fix attempts, call report_merge_failure and stop.
 
-## How Conflict Resolution Works
+## Resolving Complex Conflicts Yourself
-The merge pipeline uses a temporary merge-queue branch and worktree to isolate merges from master. Simple additive conflicts (both branches adding code at the same location) are resolved automatically by keeping both additions. Complex conflicts (modifying the same lines differently) are reported without touching master.
 
-## Fixing Minor Gate Failures
+When the auto-resolver fails, you have access to the merge worktree at `.story_kit/merge_workspace/`. Go in there and resolve the conflicts manually:
-If quality gates fail (cargo clippy, cargo test, pnpm build, pnpm test), attempt to fix minor issues yourself before reporting to the human.
 
-**Fix yourself (up to 2 attempts total):**
+1. Run `git diff --name-only --diff-filter=U` in the merge worktree to list conflicted files
+2. **Build context before touching code.** Run `git log --oneline master...HEAD` on the feature branch to see its commits. Then run `git log --oneline --since="$(git log -1 --format=%ci <feature-branch-base-commit>)" master` to see what landed on master since the branch was created. Read the story files in `.story_kit/work/` for any recently merged stories that touch the same files — this tells you WHY master changed and what must be preserved.
+3. Read each conflicted file and understand both sides of the conflict
+4. **Understand intent, not just syntax.** The feature branch may be behind master — master's version of shared infrastructure is almost always correct. The feature branch's contribution is the NEW functionality it adds. Your job is to integrate the new into master's structure, not pick one side.
+5. Resolve by integrating the feature's new functionality into master's code structure
+5. Stage resolved files with `git add`
+6. Run `cargo check` (and `npm run build` if frontend changed) to verify compilation
+7. If it compiles, commit and re-trigger merge_agent_work
+
+### Common conflict patterns in this project:
+
+**Story file rename/rename conflicts:** Both branches moved the story .md file to different pipeline directories. Resolution: `git rm` both sides — story files in `work/2_current/`, `work/3_qa/`, `work/4_merge/` are gitignored and don't need to be committed.
+
+**bot.rs tokio::select! conflicts:** Master has a `tokio::select!` loop in `handle_message()` that handles permission forwarding (story 275). Feature branches created before story 275 have a simpler direct `provider.chat_stream().await` call. Resolution: KEEP master's tokio::select! loop. Integrate only the feature's new logic (e.g. typing indicators, new callbacks) into the existing loop structure. Do NOT replace the loop with the old direct call.
+
+**Duplicate functions/imports:** The auto-resolver keeps both sides, producing duplicates. Resolution: keep one copy (prefer master's version), delete the duplicate.
+
+**Formatting-only conflicts:** Both sides reformatted the same code differently. Resolution: pick either side (prefer master).
+
+## Fixing Gate Failures
+
+If quality gates fail (cargo clippy, cargo test, npm run build, npm test), attempt to fix issues yourself in the merge worktree.
+
+**Fix yourself (up to 3 attempts total):**
 - Syntax errors (missing semicolons, brackets, commas)
+- Duplicate definitions from merge artifacts
 - Simple type annotation errors
 - Unused import warnings flagged by clippy
+- Mismatched braces from bad conflict resolution
 - Trivial formatting issues that block compilation or linting
 
 **Report to human without attempting a fix:**
@@ -250,17 +259,14 @@ If quality gates fail (cargo clippy, cargo test, pnpm build, pnpm test), attempt
 - Missing function implementations
 - Architectural changes required
 - Non-trivial refactoring needed
-- Anything requiring understanding of broader system context
 
-**Max retry limit:** If gates still fail after 2 fix attempts, call report_merge_failure to record the failure, then stop immediately and report the full gate output to the human. Do not retry further.
+**Max retry limit:** If gates still fail after 3 fix attempts, call report_merge_failure to record the failure, then stop immediately and report the full gate output to the human.
 
 ## CRITICAL Rules
 - NEVER manually move story files between pipeline stages (e.g. from 4_merge/ to 5_done/)
 - NEVER call accept_story — only merge_agent_work can move stories to done after a successful merge
-- When merge fails, ALWAYS call report_merge_failure to record the failure — do NOT improvise with file moves
+- When merge fails after exhausting your fix attempts, ALWAYS call report_merge_failure
-- Only use MCP tools (merge_agent_work, report_merge_failure) to drive the merge process
-- Only attempt fixes that are clearly minor and low-risk
 - Report conflict resolution outcomes clearly
 - Report gate failures with full output so the human can act if needed
 - The server automatically runs acceptance gates when your process exits"""
-system_prompt = "You are the mergemaster agent. Your primary responsibility is to trigger the merge_agent_work MCP tool and report the results. CRITICAL: Never manually move story files or call accept_story. When merge fails, call report_merge_failure to record the failure. For minor gate failures (syntax errors, unused imports, missing semicolons), attempt to fix them yourself — but stop after 2 attempts, call report_merge_failure, and report to the human. For complex failures or unresolvable conflicts, call report_merge_failure and report clearly so the human can act. The merge pipeline automatically resolves simple additive conflicts."
+system_prompt = "You are the mergemaster agent. Your primary job is to merge feature branches to master. First try the merge_agent_work MCP tool. If the auto-resolver fails on complex conflicts, resolve them yourself in the merge worktree — you are an opus-class agent capable of understanding both sides of a conflict and producing correct merged code. Common patterns: keep master's tokio::select! permission loop in bot.rs, discard story file rename conflicts (gitignored), remove duplicate definitions. After resolving, verify compilation before re-triggering merge. CRITICAL: Never manually move story files or call accept_story. After 3 failed fix attempts, call report_merge_failure and stop."

.storkit/specs/functional/SLACK_SETUP.md

@@ -0,0 +1,44 @@
+# Slack Integration Setup
+
+## Bot Configuration
+
+Slack integration is configured via `bot.toml` in the project's `.story_kit/` directory:
+
+```toml
+transport = "slack"
+display_name = "Storkit"
+slack_bot_token = "xoxb-..."
+slack_signing_secret = "..."
+slack_channel_ids = ["C01ABCDEF"]
+```
+
+## Slack App Configuration
+
+### Event Subscriptions
+
+1. In your Slack app settings, enable **Event Subscriptions**.
+2. Set the **Request URL** to: `https://<your-host>/webhook/slack`
+3. Subscribe to the `message.channels` and `message.im` bot events.
+
+### Slash Commands
+
+Slash commands provide quick access to pipeline commands without mentioning the bot.
+
+1. In your Slack app settings, go to **Slash Commands**.
+2. Create the following commands, all pointing to the same **Request URL**: `https://<your-host>/webhook/slack/command`
+
+| Command | Description |
+|---------|-------------|
+| `/storkit-status` | Show pipeline status and agent availability |
+| `/storkit-cost` | Show token spend: 24h total, top stories, and breakdown |
+| `/storkit-show` | Display the full text of a work item (e.g. `/storkit-show 42`) |
+| `/storkit-git` | Show git status: branch, changes, ahead/behind |
+| `/storkit-htop` | Show system and agent process dashboard |
+
+All slash command responses are **ephemeral** — only the user who invoked the command sees the response.
+
+### OAuth & Permissions
+
+Required bot token scopes:
+- `chat:write` — send messages
+- `commands` — handle slash commands

.storkit/specs/tech/STACK.md

@@ -9,7 +9,7 @@ This project is a standalone Rust **web server binary** that serves a Vite/React
     *   **Framework:** Poem HTTP server with WebSocket support for streaming; HTTP APIs should use Poem OpenAPI (Swagger) for non-streaming endpoints.
 *   **Frontend:** TypeScript + React
     *   **Build Tool:** Vite
-    *   **Package Manager:** pnpm (required)
+    *   **Package Manager:** npm
     *   **Styling:** CSS Modules or Tailwind (TBD - Defaulting to CSS Modules)
     *   **State Management:** React Context / Hooks
     *   **Chat UI:** Rendered Markdown with syntax highlighting.
@@ -91,8 +91,8 @@ To support both Remote and Local models, the system implements a `ModelProvider`
 *   **Quality Gates:**
     *   `npx @biomejs/biome check src/` must show 0 errors, 0 warnings
     *   `npm run build` must succeed
-    *   `npx vitest run` must pass
+    *   `npm test` must pass
-    *   `npx playwright test` must pass
+    *   `npm run test:e2e` must pass
     *   No `any` types allowed (use proper types or `unknown`)
     *   React keys must use stable IDs, not array indices
     *   All buttons must have explicit `type` attribute
@@ -118,8 +118,8 @@ To support both Remote and Local models, the system implements a `ModelProvider`
 
 Multiple instances can run simultaneously in different worktrees. To avoid port conflicts:
 
-- **Backend:** Set `STORYKIT_PORT` to a unique port (default is 3001). Example: `STORYKIT_PORT=3002 cargo run`
+- **Backend:** Set `STORKIT_PORT` to a unique port (default is 3001). Example: `STORKIT_PORT=3002 cargo run`
-- **Frontend:** Run `pnpm dev` from `frontend/`. It auto-selects the next unused port. It reads `STORYKIT_PORT` to know which backend to talk to, so export it before running: `export STORYKIT_PORT=3002 && cd frontend && pnpm dev`
+- **Frontend:** Run `npm run dev` from `frontend/`. It auto-selects the next unused port. It reads `STORKIT_PORT` to know which backend to talk to, so export it before running: `export STORKIT_PORT=3002 && cd frontend && npm run dev`
 
 When running in a worktree, use a port that won't conflict with the main instance (3001). Ports 3002+ are good choices.
 
@@ -127,4 +127,4 @@ When running in a worktree, use a port that won't conflict with the main instanc
 1.  **Project Scope:** The application must strictly enforce that it does not read/write outside the `project_root` selected by the user.
 2.  **Human in the Loop:**
     *   Shell commands that modify state (non-readonly) should ideally require a UI confirmation (configurable).
-    *   File writes must be confirmed or revertible.
+    *   File writes must be confirmed or revertible.

.storkit/work/1_backlog/260_refactor_upgrade_libsqlite3_sys.md

@@ -0,0 +1,24 @@
+---
+name: "Upgrade libsqlite3-sys"
+---
+
+# Refactor 260: Upgrade libsqlite3-sys
+
+## Description
+
+Upgrade the `libsqlite3-sys` dependency from `0.35.0` to `0.37.0`. The crate is used with `features = ["bundled"]` for static builds.
+
+## Version Notes
+
+- Current: `libsqlite3-sys 0.35.0` (pinned transitively by `matrix-sdk 0.16.0` → `matrix-sdk-sqlite` → `rusqlite 0.37.x`)
+- Target: `libsqlite3-sys 0.37.0`
+- Latest upstream rusqlite: `0.39.0`
+- **Blocker**: `matrix-sdk 0.16.0` pins `rusqlite 0.37.x` which pins `libsqlite3-sys 0.35.0`. A clean upgrade requires either waiting for matrix-sdk to bump their rusqlite dep, or upgrading matrix-sdk itself.
+- **Reverted 2026-03-17**: A previous coder vendored the entire rusqlite crate with a fake `0.37.99` version and patched its libsqlite3-sys dep. This was too hacky — reverted to clean `0.35.0`.
+
+## Acceptance Criteria
+
+- [ ] `libsqlite3-sys` is upgraded to `0.37.0` via a clean dependency path (no vendored forks)
+- [ ] `cargo build` succeeds
+- [ ] All tests pass
+- [ ] No `[patch.crates-io]` hacks or vendored crates

.storkit/work/1_backlog/329_spike_evaluate_docker_orbstack_for_agent_isolation_and_resource_limiting.md

@@ -0,0 +1,69 @@
+---
+name: "Evaluate Docker/OrbStack for agent isolation and resource limiting"
+agent: coder-opus
+---
+
+# Spike 329: Evaluate Docker/OrbStack for agent isolation and resource limiting
+
+## Question
+
+Investigate running the entire storkit system (server, Matrix bot, agents, web UI) inside a single Docker container, using OrbStack as the macOS runtime for better performance. The goal is to isolate storkit from the host machine — not to isolate agents from each other.
+
+Currently storkit runs as bare processes on the host with full filesystem and network access. A single container would provide:
+
+1. **Host isolation** — storkit can't touch anything outside the container
+2. **Clean install/uninstall** — `docker run` to start, `docker rm` to remove
+3. **Reproducible environment** — same container works on any machine
+4. **Distributable product** — `docker pull storkit` for new users
+5. **Resource limits** — cap total CPU/memory for the whole system
+
+## Architecture
+
+```
+Docker Container (single)
+├── storkit server
+│   ├── Matrix bot
+│   ├── WhatsApp webhook
+│   ├── Slack webhook
+│   ├── Web UI
+│   └── MCP server
+├── Agent processes (coder-1, coder-2, coder-opus, qa, mergemaster)
+├── Rust toolchain + Node.js + Claude Code CLI
+└── /workspace (bind-mounted project repo from host)
+```
+
+## Key questions to answer:
+
+- **Performance**: How much slower are cargo builds inside the container on macOS? Compare Docker Desktop vs OrbStack for bind-mounted volumes.
+- **Dockerfile**: What's the minimal image for the full stack? Rust toolchain + Node.js + Claude Code CLI + cargo-nextest + git.
+- **Bind mounts**: The project repo is bind-mounted from the host. Any filesystem performance concerns with OrbStack?
+- **Networking**: Container exposes web UI port (3000). Matrix/WhatsApp/Slack connect outbound. Any issues?
+- **API key**: Pass ANTHROPIC_API_KEY as env var to the container.
+- **Git**: Git operations happen inside the container on the bind-mounted repo. Commits are visible on the host immediately.
+- **Cargo cache**: Use a named Docker volume for ~/.cargo/registry so dependencies persist across container restarts.
+- **Claude Code state**: Where does Claude Code store its session data? Needs to persist or be in a volume.
+- **OrbStack vs Docker Desktop**: Is OrbStack required for acceptable performance, or does Docker Desktop work too?
+- **Server restart**: Does `rebuild_and_restart` work inside a container (re-exec with new binary)?
+
+## Deliverable:
+A proof-of-concept Dockerfile, docker-compose.yml, and a short write-up with findings and performance benchmarks.
+
+## Hypothesis
+
+- TBD
+
+## Timebox
+
+- TBD
+
+## Investigation Plan
+
+- TBD
+
+## Findings
+
+- TBD
+
+## Recommendation
+
+- TBD

.storkit/work/1_backlog/343_refactor_abstract_agent_runtime_to_support_non_claude_code_backends.md

@@ -0,0 +1,40 @@
+---
+name: "Abstract agent runtime to support non-Claude-Code backends"
+---
+
+# Refactor 343: Abstract agent runtime to support non-Claude-Code backends
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Currently agent spawning is tightly coupled to Claude Code CLI — agents are spawned as PTY processes running the `claude` binary. To support ChatGPT and Gemini as agent backends, we need to abstract the agent runtime.
+
+The agent pool currently does:
+1. Spawn `claude` CLI process via portable-pty
+2. Stream JSON events from stdout
+3. Parse tool calls, text output, thinking traces
+4. Wait for process exit, run gates
+
+This needs to become a trait so different backends can be plugged in:
+- Claude Code (existing) — spawns `claude` CLI, parses JSON stream
+- OpenAI API — calls ChatGPT via API with tool definitions, manages conversation loop
+- Gemini API — calls Gemini via API with tool definitions, manages conversation loop
+
+The key abstraction is: an agent runtime takes a prompt + tools and produces a stream of events (text output, tool calls, completion). The existing PTY/Claude Code logic becomes one implementation of this trait.
+
+## Acceptance Criteria
+
+- [ ] Define an AgentRuntime trait with methods for: start, stream_events, stop, get_status
+- [ ] ClaudeCodeRuntime implements the trait using existing PTY spawning logic
+- [ ] Agent pool uses the trait instead of directly spawning Claude Code
+- [ ] Runtime selection is configurable per agent in project.toml (e.g. runtime = 'claude-code')
+- [ ] All existing Claude Code agent functionality preserved
+- [ ] Event stream format is runtime-agnostic (text, tool_call, thinking, done)
+- [ ] Token usage tracking works across runtimes
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/344_story_chatgpt_agent_backend_via_openai_api.md

@@ -0,0 +1,25 @@
+---
+name: "ChatGPT agent backend via OpenAI API"
+---
+
+# Story 344: ChatGPT agent backend via OpenAI API
+
+## User Story
+
+As a project owner, I want to run agents using ChatGPT (GPT-4o, o3, etc.) via the OpenAI API, so that I can use OpenAI models for coding tasks alongside Claude.
+
+## Acceptance Criteria
+
+- [ ] Implement OpenAiRuntime using the AgentRuntime trait from refactor 343
+- [ ] Supports GPT-4o and o3 models via the OpenAI chat completions API
+- [ ] Manages a conversation loop: send prompt + tool definitions, execute tool calls, continue until done
+- [ ] Agents connect to storkit's MCP server for all tool operations — no custom file/bash tools needed
+- [ ] MCP tool definitions are converted to OpenAI function calling format
+- [ ] Configurable in project.toml: runtime = 'openai', model = 'gpt-4o'
+- [ ] OPENAI_API_KEY passed via environment variable
+- [ ] Token usage tracked and logged to token_usage.jsonl
+- [ ] Agent output streams to the same event system (web UI, bot notifications)
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/345_story_gemini_agent_backend_via_google_ai_api.md

@@ -0,0 +1,25 @@
+---
+name: "Gemini agent backend via Google AI API"
+---
+
+# Story 345: Gemini agent backend via Google AI API
+
+## User Story
+
+As a project owner, I want to run agents using Gemini (2.5 Pro, etc.) via the Google AI API, so that I can use Google models for coding tasks alongside Claude and ChatGPT.
+
+## Acceptance Criteria
+
+- [ ] Implement GeminiRuntime using the AgentRuntime trait from refactor 343
+- [ ] Supports Gemini 2.5 Pro and other Gemini models via the Google AI generativeai API
+- [ ] Manages a conversation loop: send prompt + tool definitions, execute tool calls, continue until done
+- [ ] Agents connect to storkit's MCP server for all tool operations — no custom file/bash tools needed
+- [ ] MCP tool definitions are converted to Gemini function calling format
+- [ ] Configurable in project.toml: runtime = 'gemini', model = 'gemini-2.5-pro'
+- [ ] GOOGLE_AI_API_KEY passed via environment variable
+- [ ] Token usage tracked and logged to token_usage.jsonl
+- [ ] Agent output streams to the same event system (web UI, bot notifications)
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/348_story_mcp_tools_for_code_search_grep_and_glob.md

@@ -0,0 +1,22 @@
+---
+name: "MCP tools for code search (grep and glob)"
+---
+
+# Story 348: MCP tools for code search (grep and glob)
+
+## User Story
+
+As a non-Claude agent connected via MCP, I want search tools so that I can find files and search code contents in my worktree.
+
+## Acceptance Criteria
+
+- [ ] grep tool — searches file contents with regex support, returns matching lines with context
+- [ ] glob tool — finds files by pattern (e.g. '**/*.rs')
+- [ ] Both scoped to the agent's worktree
+- [ ] grep supports output modes: content (matching lines), files_with_matches (just paths), count
+- [ ] grep supports context lines (-A, -B, -C)
+- [ ] Results limited to prevent overwhelming the LLM context
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/349_story_mcp_tools_for_git_operations.md

@@ -0,0 +1,23 @@
+---
+name: "MCP tools for git operations"
+---
+
+# Story 349: MCP tools for git operations
+
+## User Story
+
+As a non-Claude agent connected via MCP, I want git tools so that I can check status, stage files, commit changes, and view history in my worktree.
+
+## Acceptance Criteria
+
+- [ ] git_status tool — returns working tree status (staged, unstaged, untracked files)
+- [ ] git_diff tool — returns diff output, supports staged/unstaged/commit range
+- [ ] git_add tool — stages files by path
+- [ ] git_commit tool — commits staged changes with a message
+- [ ] git_log tool — returns commit history with configurable count and format
+- [ ] All operations run in the agent's worktree
+- [ ] Cannot push, force-push, or modify remote — server handles that
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/350_story_mcp_tool_for_code_definitions_lookup.md

@@ -0,0 +1,21 @@
+---
+name: "MCP tool for code definitions lookup"
+---
+
+# Story 350: MCP tool for code definitions lookup
+
+## User Story
+
+As a non-Claude agent connected via MCP, I want a code intelligence tool so that I can find function, struct, and type definitions without grepping through all files.
+
+## Acceptance Criteria
+
+- [ ] get_definitions tool — finds function/struct/enum/type/class definitions by name or pattern
+- [ ] Supports Rust (fn, struct, enum, impl, trait) and TypeScript (function, class, interface, type) at minimum
+- [ ] Returns file path, line number, and the definition signature
+- [ ] Scoped to the agent's worktree
+- [ ] Faster than grepping — uses tree-sitter or regex-based parsing
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/354_story_make_help_command_output_alphabetical.md

@@ -0,0 +1,18 @@
+---
+name: "Make help command output alphabetical"
+---
+
+# Story 354: Make help command output alphabetical
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] Help command lists bot commands in alphabetical order
+- [ ] Existing help tests still pass
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/355_story_bot_rebuild_command_to_trigger_server_rebuild_and_restart.md

@@ -0,0 +1,20 @@
+---
+name: "Bot rebuild command to trigger server rebuild and restart"
+---
+
+# Story 355: Bot rebuild command to trigger server rebuild and restart
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] Matrix bot recognizes `rebuild` as a command
+- [ ] Command triggers rebuild_and_restart and reports result back to the room
+- [ ] Command appears in help output
+- [ ] Build failures are reported to the user without crashing the server
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/339_story_web_ui_agent_assignment_dropdown_on_work_items.md

@@ -0,0 +1,21 @@
+---
+name: "Web UI agent assignment dropdown on work items"
+---
+
+# Story 339: Web UI agent assignment dropdown on work items
+
+## User Story
+
+As a project owner using the web UI, I want to select which agent to assign to a work item from a dropdown, so that I can control agent assignments visually.
+
+## Acceptance Criteria
+
+- [ ] Agent dropdown visible in expanded work item detail panel
+- [ ] Shows available agents filtered by appropriate stage (coders for current, QA for qa, mergemaster for merge)
+- [ ] Selecting an agent stops any current agent and starts the new one
+- [ ] Updates the story front matter with the agent assignment
+- [ ] Shows agent status (running, idle) in the dropdown
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/340_story_web_ui_rebuild_and_restart_button.md

@@ -0,0 +1,21 @@
+---
+name: "Web UI rebuild and restart button"
+---
+
+# Story 340: Web UI rebuild and restart button
+
+## User Story
+
+As a project owner using the web UI, I want a rebuild and restart button, so that I can deploy changes without terminal access.
+
+## Acceptance Criteria
+
+- [ ] Rebuild button in the web UI header or settings area
+- [ ] Shows confirmation dialog before triggering rebuild
+- [ ] Triggers the rebuild_and_restart MCP tool
+- [ ] Shows build progress or status indicator
+- [ ] Handles reconnection after server restarts
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/346_story_mcp_tools_for_file_operations_read_write_edit_list.md

@@ -0,0 +1,22 @@
+---
+name: "MCP tools for file operations (read, write, edit, list)"
+---
+
+# Story 346: MCP tools for file operations (read, write, edit, list)
+
+## User Story
+
+As a non-Claude agent connected via MCP, I want file operation tools so that I can read, write, and edit code in my worktree.
+
+## Acceptance Criteria
+
+- [ ] read_file tool — reads file contents, supports offset/limit for large files
+- [ ] write_file tool — writes/creates a file at a given path
+- [ ] edit_file tool — replaces a string in a file (old_string/new_string like Claude Code's Edit)
+- [ ] list_files tool — glob pattern matching to find files in the worktree
+- [ ] All operations scoped to the agent's worktree path for safety
+- [ ] Returns clear errors for missing files, permission issues, etc.
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/347_story_mcp_tool_for_shell_command_execution.md

@@ -0,0 +1,22 @@
+---
+name: "MCP tool for shell command execution"
+---
+
+# Story 347: MCP tool for shell command execution
+
+## User Story
+
+As a non-Claude agent connected via MCP, I want a shell command tool so that I can run cargo build, npm test, and other commands in my worktree.
+
+## Acceptance Criteria
+
+- [ ] run_command tool — executes a bash command and returns stdout/stderr/exit_code
+- [ ] Command runs in the agent's worktree directory
+- [ ] Supports timeout parameter (default 120s, max 600s)
+- [ ] Sandboxed to worktree — cannot cd outside or access host paths
+- [ ] Returns streaming output for long-running commands
+- [ ] Dangerous commands blocked (rm -rf /, etc.)
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/351_story_bot_reset_command_to_clear_conversation_context.md

@@ -0,0 +1,22 @@
+---
+name: "Bot reset command to clear conversation context"
+---
+
+# Story 351: Bot reset command to clear conversation context
+
+## User Story
+
+As a project owner in a chat room, I want to type "{bot_name} reset" to drop the current Claude Code session and start fresh, so that I can reduce token usage when context gets bloated without restarting the server.
+
+## Acceptance Criteria
+
+- [ ] '{bot_name} reset' kills the current Claude Code session
+- [ ] A new session starts immediately with clean context
+- [ ] Memories persist via the file system (auto-memory directory is unchanged)
+- [ ] Bot confirms the reset with a short message
+- [ ] Registered in the command registry so it appears in help output
+- [ ] Handled at bot level without LLM invocation
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/352_bug_ambient_on_off_command_not_intercepted_by_bot_after_refactors.md

@@ -0,0 +1,30 @@
+---
+name: "Ambient on/off command not intercepted by bot after refactors"
+---
+
+# Bug 352: Ambient on/off command not intercepted by bot after refactors
+
+## Description
+
+The ambient on/off bot command stopped being intercepted by the bot after the recent refactors (328 split commands.rs into modules, 330 consolidated chat transports into chat/ module). Messages like "timmy ambient off", "ambient off", and "ambient on" are being forwarded to the LLM instead of being handled at the bot level. The ambient toggle was previously handled in bot.rs before the command registry dispatch — it may not have been properly wired up after the code was moved to the chat/ module structure.
+
+## How to Reproduce
+
+1. Type "timmy ambient off" in a Matrix room where ambient mode is on
+2. Observe that the message is forwarded to Claude instead of being intercepted
+3. Same for "timmy ambient on", "ambient off", "ambient on"
+
+## Actual Result
+
+Ambient toggle commands are forwarded to the LLM as regular messages.
+
+## Expected Result
+
+Ambient toggle commands should be intercepted at the bot level and toggle ambient mode without invoking the LLM, with a confirmation message sent directly.
+
+## Acceptance Criteria
+
+- [ ] 'timmy ambient on' toggles ambient mode on and sends confirmation without LLM invocation
+- [ ] 'timmy ambient off' toggles ambient mode off and sends confirmation without LLM invocation
+- [ ] Ambient toggle works after refactors 328 and 330
+- [ ] Ambient state persists in bot.toml as before

.storkit/work/5_done/353_story_add_party_emoji_to_done_stage_notification_messages.md

@@ -0,0 +1,19 @@
+---
+name: "Add party emoji to done stage notification messages"
+---
+
+# Story 353: Add party emoji to done stage notification messages
+
+## User Story
+
+As a project owner, I want to see a party emoji in the Matrix/chat notification when a story moves to done, so that completions feel celebratory.
+
+## Acceptance Criteria
+
+- [ ] Stage notification for done includes a party emoji (e.g. 🎉)
+- [ ] Only the done stage gets the emoji — other stage transitions stay as they are
+- [ ] Works across all chat transports (Matrix, WhatsApp, Slack)
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/130_bug_permission_approval_returns_wrong_format_tools_fail_after_user_approves.md

@@ -10,7 +10,7 @@ The `prompt_permission` MCP tool returns plain text ("Permission granted for '..
 
 ## How to Reproduce
 
-1. Start the story-kit server and open the web UI
+1. Start the storkit server and open the web UI
 2. Chat with the claude-code-pty model
 3. Ask it to do something that requires a tool NOT in `.claude/settings.json` allow list (e.g. `wc -l /etc/hosts`, or WebFetch to a non-allowed domain)
 4. The permission dialog appears — click Approve

.storkit/work/6_archived/139_story_retry_limit_for_mergemaster_and_pipeline_restarts.md

@@ -6,7 +6,7 @@ name: "Retry limit for mergemaster and pipeline restarts"
 
 ## User Story
 
-As a developer using story-kit, I want pipeline auto-restarts to have a configurable retry limit so that failing agents don't loop infinitely consuming CPU and API credits.
+As a developer using storkit, I want pipeline auto-restarts to have a configurable retry limit so that failing agents don't loop infinitely consuming CPU and API credits.
 
 ## Acceptance Criteria