juspay/kolu-dev

Write a kolu blog post grounded in the real build history — mine the Claude Code session logs behind a feature for the actual story (for large efforts, fan out over the transcripts with an ultracode workflow), draft it in the author's voice, and wire it into the Astro site. Use when asked to write a blog post or engineering essay about something that was built, especially one that should read as a narrative of what actually happened rather than invented marketing copy.

Launch the kolu dev server on two RANDOM free ports so it never collides with the running production kolu.service, remember the ports for the rest of the session, and tear down only the dev instance. Load before running the app locally — for evidence capture, driving a live kolu with the chrome-devtools MCP, or any just dev you'd otherwise run by hand. Triggers on "run kolu locally", "launch the dev server", "boot kolu", "drive a live kolu", "start the app to screenshot it", or before pointing chrome-devtools at a local kolu.

The Dock's agent-state folds — one fenced source of truth in @kolu/terminal-vocab, the load-bearing order≠colour split, and the one "is something happening" question. Use when editing agentProjection or the canvas dock.

E2E test conventions — semantic selectors, arrange-steps that prove the process started, runtime markers that cannot match the shell echo, and absolute-path tool invocations. Use when writing or changing a .feature scenario under packages/tests.

Produce visual PR evidence — a screenshot or video — whenever a change has on-screen impact. Tests are never a substitute; a change can be backend by cause and visible by effect. Capture via the project's e2e harness on a pu box, or by driving a live kolu with the chrome-devtools MCP; host on a GitHub release and post a ## Evidence comment. Triggers on "post evidence", "screenshot the change", "record a video of this", "show it working", "prove it", or finishing any change whose effect is visible on screen.

Audit an implementation against its plan with a hostile peer agent, debate findings to consensus, and drive fix waves until the auditor runs dry. Use when a done-claim needs verification the implementer cannot game ("hostile review", "adversarial audit", "is this PR faithful", "find the escape hatches") — the loop that beats the laziness bias with its own game theory.

kolu's client component conventions: SolidJS patterns, UI component rules, and toast notifications. Use when building or changing a client component, a store, a subscription, or a toast.

Kolu, Padi, Kaval, and vendored agent-distro logo assets — favicon, PWA icons, website palette, screenshots, and app identity. Use when changing a logo, an icon, or the website's colour tokens.

Run an autonomous overnight campaign to find, prove, fix, and document CI flakes. Use when the user asks to stabilize CI through repeated full-pipeline runs and leave an evidence-backed draft PR.

Kolu's project-wide default for filesystem monitoring is @parcel/watcher. Reach for this skill when adding or modifying any code that watches files or directories — recursive subtree watching, single-file observation, fs.watch alternatives, chokidar replacement, inotify/FSEvents/watchman backend selection, ignore globs, watcher debouncing, or refcounted shared subscriptions. Covers backend dispatch, the watchman invocation path, ignore handling, post-install reconciliation, and the failure modes Kolu's logger surfaces.

Diagnose Kolu client-side performance issues (memory leaks, high GPU, slow interactions) using chrome-devtools MCP + the Debug → Diagnostic info dialog + heap-snapshot analyzers. Triggers on "memory leak", "GPU memory", "tab bloat", "why is kolu slow", "debug performance", "zombie canvas", "WebGL leak", or any

Use Pierre Computer Company's @pierre/trees (path-first file tree) and @pierre/diffs (shiki-based code/diff renderer) in Kolu. Pierre ships Preact/vanilla cores with optional React wrappers — Kolu consumes the vanilla classes and wraps them in thin SolidJS components. Trigger when: wiring up a file tree, rendering unified diffs or syntax-highlighted files, replacing @git-diff-view, or any mention of @pierre/trees / @pierre/diffs / "pierre library".

Cut a kolu release — tag master, promote the Unreleased changelog entry, publish a GitHub release. ONLY invoke when the user explicitly types /release or $release; never auto-select from a natural-language request.

Test kolu's remote-host features (multi-host / padi-remote) in a real browser against a real remote box — the ONLY full end-to-end harness for this surface (real ssh provision, no mock). Covers the isolated nix-run invocation (or just dev, which bakes the same agent source), ssh- provisioning a real remote box without touching production or another user's box, the chrome-devtools drive sequence for host-switch / split / code-browser / per-host-canvas, PID-exact teardown, and the reproduce- first rule for any bug the feature surfaces. Triggers on "test remote hosts", "test multi-host", "test padi-remote", "verify the host switch", "browser-test a remote host change", or before claiming a remote-host fix works.

Persistent state schema migration requirements — the one schema, one migration ladder, and the fail-fast host-map membership rule. Use when changing anything that is persisted.

Cross-file invariants for surface streaming members — the retry fence, server snapshot-then-deltas, and the captured-input hazard. Use when touching any streaming member in the client, server, or common packages.

How a downstream app consumes the shared @kolu/surface stack (@kolu/surface · surface-app · surface-remote · surface-mcp) — declaring a typed reactive surface, serving it, consuming it (SolidJS hooks or a CLI), and mirroring a remote surface over ssh. Grounded in the real consumers: kolu, drishti, odu, and the TUIs. Load when wiring a surface server/client/mirror, or reaching for makeSession / a link / the .use() hooks. CHANGING the framework is gated separately — see "Changing the framework" below (a paired, CI-green drishti PR pinned to final kolu HEAD).

Run this repo's tests scoped to the current changes — the unit lane (just test-unit / a --filtered vitest run) and the e2e lane (.feature files selected from git diff, run via just test-quick), plus which lane a diff needs and where it is safe to run. Triggers on "run tests", "test this", "check if it works", "unit tests", "vitest", "e2e", "test the changes".

List features added to Kolu during a timeframe, grouped by product area and linked to PRs. Use when asked "what changed in kolu since …" or to draft release notes.