kolu

Drive one AI agent from another through kolu's terminals: spawn a Claude Code / Codex / opencode session in a PTY, prompt it, watch the screen for its reply, read it, and prompt again. PRIMARY PATH: the kolu MCP server's tools (`lifecycle_create`/`lifecycle_sendInput` with named keys, the `wait_outputSettled`/`wait_agentState` done-signals, `screen_text`, the `terminals` resource) — configured in this repo's .mcp.json as `kolu mcp`. FALLBACK when the MCP is unavailable: the `kaval-tui`/`padi-tui` CLIs, same verbs, same discipline. Triggers on "drive another agent", "send a prompt to a terminal agent", "have one agent prompt another", "agent drives agent", "orchestrate agents in terminals", "make Claude drive Codex", "prompt the agent running in that terminal", or wiring a loop where one coding agent supervises another.

Running memory of the coordination rules for an orchestrator agent driving implementing agents on kolu terminals — authorization boundaries, the dispatch protocol (MCP-first via the kolu skill, with its TUI fallback), verification discipline, and how to communicate with the human. Load whenever coordinating a multi-agent campaign (dispatching briefs to agents in kolu PTYs, tracking their PRs, verifying their claims), or when acting as the coordinator in a padi/surface-style campaign. Triggers on "orchestrate the agents", "coordinate the campaign", "dispatch to the agents", "act as coordinator", or driving multiple implementing agents from one supervising session.

Running memory of the coordination rules for an orchestrator agent driving implementing agents on kolu terminals — authorization boundaries, the dispatch protocol (MCP-first via the kolu skill, with its TUI fallback), verification discipline, and how to communicate with the human. Load whenever coordinating a multi-agent campaign (dispatching briefs to agents in kolu PTYs, tracking their PRs, verifying their claims), or when acting as the coordinator in a padi/surface-style campaign. Triggers on "orchestrate the agents", "coordinate the campaign", "dispatch to the agents", "act as coordinator", or driving multiple implementing agents from one supervising session.

Modern, interactive alternative to `/do` — clarify intent up front, then take a task end-to-end with a serial AI review gauntlet (lens debate (lowy ⇄ hickey) → codex debate → simplify → code-police, each editing the branch in turn) → CI → evidence. ONLY invoke when the user explicitly types `/be` or `$be`; never auto-select from a natural-language request.

Run an automated codex⇄Claude debate to consensus — no round cap, no deadlock exit. Two explicit subcommands. `review` (also the bare/back-compat default) — codex critiques the current diff and Claude (author) fixes/disputes, looping until they agree, and the trail is committed + posted to the PR. `answer` — Claude and codex each answer a freeform prompt, then cross-check until they agree, and a unified answer is returned. The debate runs over a LIVE codex session in a split terminal beside you (driven per the /kolu skill), not a headless workflow. Use when the user types `/codex-debate`, asks to "have codex review this", "run the codex debate", "review this PR with codex", "argue this with codex until you agree", or passes a question to "have Claude and codex debate/answer until they agree".

Run an automated codex⇄Claude debate to consensus — no round cap, no deadlock exit. Two explicit subcommands. `review` (also the bare/back-compat default) — codex critiques the current diff and Claude (author) fixes/disputes, looping until they agree, and the trail is committed + posted to the PR. `answer` — Claude and codex each answer a freeform prompt, then cross-check until they agree, and a unified answer is returned. The debate runs over a LIVE codex session in a split terminal beside you (driven per the /kolu skill), not a headless workflow. Use when the user types `/codex-debate`, asks to "have codex review this", "run the codex debate", "review this PR with codex", "argue this with codex until you agree", or passes a question to "have Claude and codex debate/answer until they agree".

Run /be's review gauntlet SERIALLY — architecture-first-principles FIRST (framework/structure diffs), then /lens-debate (lowy ⇄ hickey), then /codex-debate, then /simplify, then code-police, each editing and committing on the live branch in turn. Use from /be §4, or when the user asks to "run the review gauntlet". Requires Claude Code's Skill tool.

Run a structural-review debate between two lenses — lowy (volatility-based decomposition) and hickey (structural simplicity) — on the current diff. Each reviews independently, then the reviews are reconciled (cross-lens agreements settle with zero debate) and only genuinely contested findings debate in parallel per-file threads until the lenses agree; the agreed fixes are applied. Use when the user types `/lens-debate`, or asks to "have lowy and hickey review this", "run the lens debate", "debate this diff structurally", or "argue the structure of this PR until the lenses agree".

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.

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 — `.claude/rules/surface.md` (a paired, CI-green drishti PR pinned to final kolu HEAD).

Create, update, or finalize a note in the kolu Atlas (docs/atlas) — frontmatter, the MDX component kit, build + check-sync, and the preview/share links. Use whenever authoring or editing an Atlas note (e.g. a /be plan-of-record), so the mechanics live in one place.

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.

Evaluate an architecture against foundational principles of state, change, and time — five grounded principles PLUS a fixed set of named, executable review checks (C1–C7) run as a Workflow fan-out over a diff: ecosystem duplicates, consumer ergonomics, graduation sweep, one-hop depends-on, fresh-eyes, state-and-time, project conventions. Theory and execution in one skill; per-repo specifics live in .agency/architecture-first-principles.md. Use when designing/reviewing state models, from /be-review (runs FIRST on framework/structure diffs), or on any architecture/electricity review ask.

Classify, write, and audit documentation per Diátaxis (diataxis.fr) — the four-quadrant method (tutorials · how-to guides · reference · explanation). Encodes the compass as a decision procedure, each quadrant's contract as hard rules, and an executable mixed-mode audit. Project-agnostic; per-repo doc-location mapping lives in .agency/diataxis.md. Use when writing any user-facing doc, structuring a docs site, or auditing existing docs for mixed modes.

Adversarial "perfection" review — hold a change to an *ideal* bar, not just a correct one, assuming eternal time, unlimited energy, and no ship pressure. Use when the user asks to review "for perfection", to make a defect "impossible to express", or to hunt where a defect "relocates" across review rounds. Grounds every claim in the diff, fans out adversarial verifiers via Workflow, and reports residual surfaces with a structural fix for each. ONLY invoke when the user explicitly asks for a perfection / ideal-bar review.

Evaluate architecture and module boundaries for volatility-based decomposition using Juval Lowy's framework (from "Righting Software", building on Parnas 1972). Use when reviewing module splits, service boundaries, new abstractions, or any decomposition decision. Trigger on phrases like "where should this boundary be", "how to split this", "module boundaries", "encapsulate change", "volatility", or references to Lowy, Parnas, or "Righting Software". Complements /hickey (interleaved concerns) with a different lens (change encapsulation).

Test kolu's remote-host features (multi-host / padi-remote) in a real browser against a real remote box — the ONLY harness that can reach this surface, since the dev server can't bind a remote padi at all. Covers the isolated nix-run invocation, 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.

Run e2e tests relevant to the current changes. Selects `.feature` files based on `git diff`, runs `just test-quick`, and skips e2e when changes are server-only with no UI impact. Triggers on "run tests", "test this", "check if it works", "e2e", "test the changes".

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.

Produce visual PR evidence — a screenshot or a video — whenever a change has on-screen impact. If exercising the change would make the screen look different (a rendered view, an error/empty/loading/blocked state, a panel, layout, an icon, motion, a live update) a visual artifact is MANDATORY, not optional. A change can be backend by cause and visible by effect: tests are never a substitute for a visual artifact when there is on-screen impact. Capture rides the project's own Cucumber + Playwright e2e harness on an ephemeral pu box (video of a flow, or a still pulled from the clip), or drives a live kolu with the chrome-devtools MCP for a state no scenario reaches. Then transcode (ffmpeg), host on a GitHub release, and post a `## Evidence` comment. Triggers on "post evidence", "screenshot the change", "PR evidence", "record a video of this", "capture the UI", "show it working", "prove it", or finishing any change whose effect is visible on screen.

Run at the end of a /be run (or when the user types `/self-improve`): mine this session's JSONL transcript for every point a human had to intervene and engineer it out, so the next run finishes autonomously. Produces nothing unless a lesson durably recurs; then ships a small, evidence-cited edit to the `.apm/skills/*` sources as a separate draft PR a human reviews — never on the /be branch, never merged. Never auto-select from a natural-language request.

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.

Write essays, articles, and blog posts in Paul Graham's voice — plain, spoken prose that reasons out loud and lands surprising true claims, not AI filler. Use when asked to write or rewrite something "like Paul Graham", "in PG's style", or to make a piece read like a person thinking on the page rather than generated text. Built from a stylistic model of 18 of his essays (see SOURCES.md).

chrome-devtools-mcp launcher — a single bash script that resolves Playwright's bundled Chrome-for-Testing and Node.js directly through Nix. See repo README for usage, override mechanisms, and version compatibility.

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

pnpm + Nix build conventions. Covers fetchPnpmDeps hash management and dependency workflow.

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