Consult

Consult the masters — review the entire katulong codebase through the lens of great software engineers.

## Phase 0: Mine the History with diwa

Before reading any code, mine the project's git history for context. The review agents in Phase 2 give grounded advice only when they know which approaches have already been tried, which decisions were deliberate, and which patterns have been reverted. Without this, they cheerfully recommend dead ends the team already walked down once.

This phase invokes the `diwa` skill (see `~/.claude/skills/diwa/SKILL.md`) and applies its iterate-and-fork pattern fully — do not stop at one search.

1. **Confirm indexed.** Run `diwa ls`. If this project isn't listed, **skip Phase 0 entirely** and note in the final report that history grounding was unavailable. Use the project's name as it appears in `diwa ls` for `<repo>` below.

2. **Run several seed searches in parallel.** Different angles on the same codebase:
   - `diwa search katulong "architecture decisions and rationale"`
   - `diwa search katulong "bug fixes incidents postmortems"`
   - `diwa search katulong "reverted approaches things tried that failed"`
   - `diwa search katulong "tmux session lifecycle and ClientHeadless"`
   - `diwa search katulong "auth WebAuthn security hardening"`
   - `diwa search katulong "drag jitter touch handling iOS Safari"`
   - `diwa search katulong "garbled text TUI resize SIGWINCH"`

3. **Follow the strings.** For each interesting `[sha]` returned, run `git -C <project-path> show <sha>` and mine the diff and commit message for clues — other SHAs, PR numbers, branch names, file paths, "follows up on…" / "reverts" / "see also" phrases, co-authors. Each clue is a candidate follow-up `diwa search`. Iterate until the tree converges (~3 hops max).

4. **Fork independent threads.** If the searches surface multiple non-overlapping rabbit holes (different subsystems, different time periods), spawn parallel subagents — one `Agent` call per thread, `subagent_type: "Explore"`, briefed with the diwa workflow (search → git show → iterate → stop on convergence), the seed SHAs, the thread it owns, and the threads it should *not* touch (the other agents own those — no duplicate work). Ask each for a tight (<300 word) synthesis. Launch them in a single message.

5. **Produce a history brief.** Synthesize everything into a concise 200–400 word document capturing:
   - **Major decisions & rationale** — key architectural choices and the *why*, with SHAs
   - **Known traps** — patterns tried and reverted, with SHAs and a one-line "don't redo this" warning
   - **Recent direction** — what is actively changing in the codebase right now
   - **Open tensions** — unresolved questions, known debts, or deferred decisions visible in the history

The history brief is the **primary input to Phase 2**. Every review agent must receive it verbatim in their shared context block so they can avoid recommending dead ends.

## Phase 1: Map the Codebase

Thoroughly explore the full project structure. Use Glob and Grep to build a complete picture:

1. **Source code** — find all `.js` files in `lib/`, `server.js`, `bin/katulong`
2. **Frontend** — all files in `public/` including `public/lib/`, `public/vendor/`
3. **Configuration** — `package.json`, `CLAUDE.md`, `nodemon.json`, `playwright.config.js`, `config.json`
4. **Tests** — all files in `test/` and `test/e2e/`
5. **Infrastructure** — `Dockerfile`, `docker-compose.yml`, `.husky/`, `scripts/`

Read ALL source files. Every module, every component, every test. Do not skip files or skim — each agent needs the full picture to give meaningful advice. This is intentionally thorough.

## Phase 2: Launch Review Agents in Parallel

Send a single message with 8 Task tool calls so they run concurrently. Each agent should be `subagent_type: "general-purpose"` so it has access to all file-reading tools.

**IMPORTANT**: Tell each agent to read the source files directly rather than trying to pass all file contents in the prompt. The prompt should describe the project structure and direct the agent to the relevant directories.

Shared context to include in every agent prompt:

Katulong is a self-hosted web terminal that gives remote shell access via HTTP/WebSocket. It manages terminal sessions through tmux and serves an xterm.js frontend. Key directories: lib/ (server modules), public/ (SPA frontend), test/ (comprehensive test suite). Security-critical: this app provides direct terminal access to the host machine. Backend: Node.js ESM, WebSocket (ws), tmux control mode, WebAuthn (@simplewebauthn/server). Frontend: Vanilla JS, xterm.js, web components, all vendor deps self-hosted in public/vendor/.

Read ALL source files before forming your review. Report your top 5 findings ranked by impact. For each finding, cite the specific file and line. Do NOT suggest changes that would reduce capabilities or fight Node.js/JavaScript idioms. Cross-reference your findings against the Phase 0 history brief — do not recommend approaches that have already been tried and reverted. If a finding matches a known trap, drop it or explain what's different now. Cite SHAs from the brief.

**Before launching the agents, append the full Phase 0 history brief verbatim to the shared context block above so every agent receives it.**

### Agent 1: Rich Hickey — Simplicity & Data Orientation

You are channeling Rich Hickey (creator of Clojure, author of "Simple Made Easy").

Review the entire katulong codebase for:

1. **Complecting** — Are independent concerns entangled? Is auth logic mixed with session management? Is WebSocket handling mixed with business logic? Name the specific things being complected.
2. **Data over abstractions** — Could plain objects/maps replace classes? Are there methods that should be functions operating on data? Is the Session class earning its keep or hiding data?
3. **State and identity** — Is mutable state used where immutable values would be clearer? Are there atom