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.

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.

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).

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.

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").

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.

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".

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.

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.

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.

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.

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.

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

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).

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).

Invoke when the user asks to author or review any SDLC artifact or run an SDLC kit operation — write/revise a PRD, ADR, DESIGN, DECOMPOSITION, or FEATURE; implement a FEATURE in code; review or report status on a GitHub PR; or migrate OpenSpec artifacts. Kit `sdlc` extensions — artifacts: ADR, CODEBASE, DECOMPOSITION, DESIGN, FEATURE, PRD (+ PR review/status templates); workflows: doc-prd, doc-adr, doc-design, decompose, doc-feature, implement, change-impact-analysis, reverse-engineer, migrate-openspec, pr-review, pr-status.

Debug Slidey render, layout, CLI, MCP, browser, rrweb/video, PDF/PNG/MP4, and deck-output failures. Use when Codex needs to diagnose a broken or ugly Slidey deck, bad scene layout, render/audit/check failure, stale render bundle, Puppeteer/browser issue, MCP slidey tool problem, timing/narration overrun, or mismatch between viewer and exported output.

Author and iterate on declarative videos using the slidey pipeline (a JSON scene spec rendered to a narrated MP4). Use when the user asks to create a new video, add/edit a scene, tweak narration, adjust visuals, re-cut a video, or generate an MP4 from a JSON spec. Covers the iteration loop, scene-type vocabulary, narration budgeting, and the gotchas accumulated across many cuts.

Invoke when user asks to do something with Cypilot, or wants to analyze/validate artifacts, or create/generate/implement anything using Cypilot workflows, or plan phased execution. Core capabilities: workflow routing (plan/analyze/generate/auto-config); deterministic validation (structure, cross-refs, traceability, TOC); code↔artifact traceability with @cpt-* markers; spec coverage measurement; ID search/navigation; init/bootstrap; adapter + registry discovery; auto-configuration of brownfield projects (scan conventions, generate rules); kit management (install/update with file-level diff); TOC generation; agent integrations (Windsurf, Cursor, Claude, Copilot, OpenAI).

Artifacts: ADR, CODEBASE, DECOMPOSITION, DESIGN, FEATURE, PR-CODE-REVIEW-TEMPLATE, PR-REVIEW, PR-STATUS-REPORT-TEMPLATE, PRD; Workflows: migrate-openspec, pr-review, pr-status