Kitsoki

Capture external browser views (GitHub tickets, JIRA, Teams threads) using rrweb and Playwright, applying spotlights and captions, and embedding them into slidey decks.

Produce a deterministic, no-LLM demo / tour video of the kitsoki web UI (plus per-scene screenshots and a shareable MP4 / GIF / contact sheet) by driving a real `kitsoki web` server through Playwright. Use when asked to make, record, refresh, or author a tour demo video, feature-spotlight tour, walkthrough video, demo, or screen-capture of the kitsoki browser UI — whether a tour of one feature (golden example: agent-actions), the generic onboarding tour, or a full-product walkthrough. Also covers turning a REAL LLM-driven dogfood session into a deterministic demo: generating the no-LLM flow fixture + host cassette from a recorded trace via `kitsoki trace to-flow` (no hand-authoring, no LLM re-interpretation). Triggers on phrasings like "make a tour demo video", "record a demo of <feature>", "feature tour video", "walkthrough video", "turn this dogfood trace/session into a demo video".

Validate UI evidence (a screenshot for simple cases, a video for complex flows) against the bug or plan being verified plus usage scenarios — the inverse of kitsoki-ui-demo. Picks the evidence form by complexity, extracts deterministic frames, has a read-only `claude` vision agent judge each scenario against cited frames AND whether the evidence is complete for the stated bug/plan, adversarially re-checks every pass, and emits a gated qa-report.md + verdict.json. Use when asked to QA / review / validate / sign off on a demo, walkthrough, screenshot, or bug-fix proof, or to gate one in CI.

Run or refine the Kitsoki product-journey QA pipeline: generate 10-GitHub-repo natural-use matrices, create persona/scenario run bundles, drive or hand off visual/Kitsoki MCP evidence capture, run no-LLM replay/dogfood gates, review/validate bundles, and produce Slidey decks with playback evidence. Use when asked to dogfood onboarding, bugfix, PRD/design, feature implementation, product-discovery, product-bug, personas, or the reusable product-journey QA agent/story.

Drive a Kitsoki story as a skeptical practitioner and validate the exploratory QA path against local project corpora. Use when asked to inspect a product flow, run a skeptical walkthrough, or validate an exploratory QA pass against one or more open source projects with reproducible evidence and a written report.

Tune and validate a provider/model task in Kitsoki with a controlled, repeatable harness. Use when a model performs poorly on a story step, when a provider quota/rate behavior needs task hardening, or when the user asks to improve GLM/GPT/Claude performance with traceable artifacts. Produces an offline-scored benchmark report, a Slidey deck, and concrete story/prompt/tool changes without calling live LLMs from tests.

Mine the user's Claude Code chat history for ideas/feedback/pain about a specific topic, synthesize a ranked themed brief, then optionally cross-reference against existing docs and file tickets. Use when the user says "review all my chats/sessions for ideas about X", "what have I said about Y across my history", "mine my conversations for feedback on Z", or wants to harvest scattered design notes / complaints / abandoned threads about a focus area. This is FOCUSED topical mining (local, not shared) — distinct from the shareable pattern-mining in tools/session-mining/README.md.

Run a controlled matrix comparison of approaches over a set of tasks — e.g. the kitsoki pipeline vs a naive single prompt, across a harness/model candidate matrix — scoring outcome, compliance, cost, and time, adjudicating implementation-coupled oracles, then regenerating a report + slidey deck offline with zero re-spend. Use when the user says "bake-off", "compare kitsoki vs single-prompt", "run a matrix comparison", "which model/harness is best at X", "kitsoki-vs-X study", "benchmark these approaches on these tasks", or wants an evidence-backed, cost-accounted comparison of contenders across a model grid. Generalises tools/bugfix-bakeoff (the reference implementation).

Run a bug-fix bake-off on ANY external/open-source repo to answer "should I use kitsoki for my project?" — find real filed-issue bugs with regression-test PRs, pin reproducible baselines, onboard the repo, drive the kitsoki bugfix pipeline LIVE under one or more non-Claude provider profiles (GPT-5.5 / GLM-5.2 / …), grade each fix deterministically against the PR's own hidden oracle, and produce a report + slidey deck comparing models and cost vs the real maintainer fix. Use when the user says "bake off <repo>", "benchmark kitsoki on this repo", "should I use kitsoki for my project", "compare <modelA> vs <modelB> fixing bugs in <repo>", "run the external bake-off", or wants to evaluate kitsoki's prompts/patterns on real third-party code. Covers onboarding AND the live-drive tuning needed to get good working cases. Distinct from dogfood-marathon (kitsoki's OWN bugs over the MCP-driver agent) and matrix-task-comparison (kitsoki-vs-naive-prompt on fixed tasks).

Diagnose kitsoki-dev dogfood / bugfix / feature-story bugs. Use when the user reports "going back to idle", "silent bounce", "stuck at <state>", or any "this room didn't do what I expected" complaint. Drives the same state machine the TUI uses, against the real on-disk repo state, without spinning up a session. Surfaces the underlying host-call errors that the TUI's `on_error:` arcs swallow.

Author, scope, and decompose kitsoki proposals using the templates under docs/proposals/templates/. Use when the user wants to write a new proposal, pick the right template for a change, split a large/raw proposal into focused reviewable pieces, or keep a proposal's Status line / lifecycle honest. Covers the four focused kinds (story, runtime, tui, tracing), the epic-decomposition flow, the shared spine, and the trim-on-ship / delete-when-done lifecycle.

Debug and test the Kitsoki studio MCP server and its tools from the repo checkout. Use when working on `kitsoki mcp`, `cmd/kitsoki/mcp_test_client.go`, `internal/mcp/studio`, MCP tool registration, stdio MCP handshake failures, visual MCP tools (`visual.open`, `visual.observe`, `visual.act`), `mcp-test` output, or when the user wants to verify studio MCP changes without reloading an LLM client.

Write, review, and validate Starlark — the small deterministic Python dialect (go.starlark.net runtime) embedded in kitsoki as the `host.starlark.run` glue capability. Use when authoring or debugging a `.star` glue script for a kitsoki story (the `main(ctx) -> dict` contract, the `.star.yaml` sidecar, `ctx.inputs`/`ctx.world`/`ctx.http`, HTTP cassettes), embedding the Starlark interpreter in Go (Thread, FileOptions, custom Value types, exposing Go builtins), choosing a validation toolchain (buildifier / starcheck / starlark CLI / `kitsoki test flows`), or diagnosing a "this is valid Python but errors in Starlark" surprise (strings aren't iterable, no while/recursion/classes/exceptions, globals can't be reassigned).

Process a backlog of real cases (bugs / deliveries / ship-its / tickets) by driving a kitsoki story (bugfix, delivery-tail, ship-it, …) LIVE over each one via the kitsoki-mcp-driver agent, independently verifying every deliverable, capturing friction as findings, and hardening the story/prompts for GENERAL use WITHOUT OVERFITTING to the cases in the run. Use when the user says "run a dogfood marathon", "smash these bugs through bugfix", "process this backlog live", "dogfood <story> over these tickets and fix the pipeline", or wants a marathon report (outcomes / verdicts / cost / fixes shipped / findings). Distinct from story-coverage-mining (transcript-driven coverage) and matrix-task-comparison (harness×model bake-off on fixed tasks).

Build and tune Kitsoki free-text routing fixtures. Use when a user reports a phrase routing to the wrong room, asks to benchmark route quality against a live profile/model, or wants session-mined phrases turned into intent fixtures.

Organize, review, document, or validate Kitsoki media artifacts, including product-site tour demo videos, rrweb captures, staged VitePress media, complete-product-tour sections, and Slidey decks with embedded rrweb clips. Use when Codex is asked to find demo videos, clean up media layout, add media validation to tests, decide where a demo/deck artifact belongs, update docs/media guidance, or troubleshoot product-site media staging without recording live LLM runs.

Heuristic UI layout & usability review of the kitsoki web UI. Walks the onboarding tour manifest at mobile/tablet/desktop, runs a deterministic DOM-geometry + axe-core audit per step, then fans the frames out across MULTIPLE read-only claude vision agents (one per surface, so no single agent holds every image) that critique each surface against a Nielsen-based heuristic catalog, adversarially re-checked, and emits a gated review-report.md + verdict.json with concrete fixes. Use when asked to review / critique / find layout, usability, responsive, or accessibility problems in the kitsoki web UI — distinct from kitsoki-ui-qa (which checks "does the demo SHOW scenario X").

Author and edit kitsoki stories — the YAML state machines under `stories/<name>/`. Use when the user wants to add or modify a room, intent, transition, effect, host call, world var, view, prompt, flow fixture, import, exit, or phase template. Covers YAML shape, effect/host vocabulary, typed view elements, style guide, load-time invariants, and the authoring loop. For "this room misbehaves / bounced to idle" reach for `kitsoki-debugging` instead.

Use when debugging TUI layout issues, writing regression tests for rendering problems, or analyzing View() output structure with RenderingAnalyzer.

Drive a kitsoki story's tests + features from real Claude Code transcripts. Mine the intents users actually drove, recover each command's real outcome and whether the user corrected it, then map each in-scope intent to a coverage verdict (CONFORMS / DIVERGES / FIXTURE-GAP / COVERAGE-GAP / OUT-OF-SCOPE) and ticket the gaps. Use when the user says "what does <story> actually cover", "mine transcripts for <story> gaps", "drive <story>'s fixtures from real sessions", "what is <story> missing or getting wrong", or wants evidence-backed conformance for a story. This is STORY-DRIVEN coverage mining — distinct from session-idea-mining (topical scatter) and the shareable pattern-mining in tools/session-mining/README.md.

Write or review the documentation for a Go package under internal/ to the kitsoki standard. Use when adding a new package, when a package's doc.go / exported-symbol comments / runnable examples need writing or auditing, or when the user asks "is this package documented well", "bring this up to the doc standard", or "review the docs for <pkg>". Covers the eight-point rubric (doc.go, sections, non-goals, per-symbol "why", contracts, named constants, Example tests, live references), the paragon to copy, and the verification commands.

Debug problems with the kitsoki web UI (`make web-dev` / `kitsoki web`). Use when the user reports 504s, blank pages, SSE stream stalls, session errors, proxy failures, or wants to inspect web server logs. Covers log locations, common failure patterns, proxy/backend interaction, and the RPC surface.

Reconstruct "what we've been working on lately" from the current repo's actual Claude Code transcripts. Use when the user opens with "we've been working on…", "what were we doing", "catch me up", "remind me where we left off", or after a /clear and wants recent work restored. Thin trigger that delegates to the Haiku `session-recap` subagent so the transcript bulk never enters this context.

Turn an accepted kitsoki proposal (or an epic + its children) into a validated, reviewed YAML decomposition of right-sized agent briefs. Use when the user wants to decompose work into briefs, "break this proposal into tickets/tasks", produce a decomposition.yaml, or check out the brief-manifest shape from docs/proposals/work-decomposition.md before that pipeline is built as a story. Drives discovery → manifest → deterministic structural lint → adversarial feasibility/completeness review, by hand.