Add Source

---
name: add-source
version: 1.1.0
description: "Wire a new agent-CLI Source adapter into pixtuoid (a new coding CLI whose sessions become office sprites). Use when the user says 'add support for <CLI>', 'add a source for <tool>', or 'integrate <agent CLI>'. Orchestrates the cross-crate checklist whose steps have TEST TEETH — the ones a diff-scoped edit silently misses (site manifest bridge, per-source badge hue, home-dir fn, plus the two `pixtuoid/tests/*` integration goldens that `-p <crate> --lib` never builds)."
metadata:
  scope: "pixtuoid repo only"
---

# add-source (v1)

Adding an agent CLI is **not a single-file change** — it spans `pixtuoid-core`
(decoder + registry + tests), the `pixtuoid` binary (runtime wiring + install
target + badge hue), and the site manifest. Several steps have **test teeth**
that only `just preflight`'s FULL run catches, not the targeted source/install
suites — so an agent that stops at "it compiles" ships a red PR.

## When to use

- "Add support for <CLI>" / "integrate <agent tool>" / "add a source for X".
- A new transcript-bearing OR hook-only coding CLI should show up as sprites.

## The authoritative checklist

The complete, current step list lives in **[`crates/pixtuoid-core/CLAUDE.md`](../../../crates/pixtuoid-core/CLAUDE.md)**
("multi-source decoding" / "Adding a new agent CLI") — read it first; it is the
source of truth and stays current. The Copilot-format summary is
[`.github/prompts/add-source.prompt.md`](../../../.github/prompts/add-source.prompt.md).
Before you start, decide **transcript-bearing vs hook-only** (invariant #3): a
hook-only CLI (Reasonix/CodeWhale/opencode/Cursor) sets `transcript: None`, skips
the runtime wiring + `Source` impl, and ships a `hook.custom` decoder + an
`install/` target instead.

## The test-teeth steps agents miss

These are the ones with a failing test attached — do NOT stop before them:

- **`site/src/sources.json` row** — a manifest bridge test fails until it exists;
  then `just gen-readme` to sync the README.
- **Per-source badge hue** — a `Theme::source` (`SourceColors`) field in EVERY
  theme file + a `dashboard_line` match arm; two guard tests fail otherwise.
- **`pub fn <cli>_home()`** if the CLI has a custom config root — one fn honoring
  its `*_HOME` precedence, called from BOTH the watcher's `default_paths()` AND the
  installer's `default_config_path()` so they can't disagree. **Audit that precedence against the
  CLI's OWN resolver per axis first** (#880; axis list in `CONTRIBUTING.md` step
  1) — guessed rather than read, it is fail-silent.
- **A captured fixture** under `tests/sources/fixtures/<name>/<scenario>/`
  exercising the **SessionStart hook** — the conformance test forces one, and its
  one-AgentId assertion guards against the reason-field ghost.
- **`sources --json` CLI golden** — `crates/pixtuoid/tests/snapshots/cli/sources.json`,
  the real-binary end-to-end golden the Raycast `--json` contract rides. The new
  source's row must appear or `cli_json::sources_json_lists_every_source_in_an_isolated_home`
  reds; regenerate with `SNAPSHOTS=overwrite cargo test -p pixtuoid --test cli_json`.
- **`wire_to_pixels` matrix row** — `crates/pixtuoid/tests/wire_to_pixels.rs`: add a
  `WireCase` (reuse your SessionStart fixture; a hook-only source uses
  `DecodeKind::Hook` + `Transport::Hook`, like cursor/hermes — a transcript source
  the JSONL variant) AND the per-source `<name>_..._renders_a_painted_sprite` test,
  or `wire_matrix_covers_every_registered_source` reds ("registration is not
  coverage").

**Those last two live in `pixtuoid/tests/*.rs` INTEGRATION BINARIES that
`-p <crate> --lib` never builds** — the #692 (kimi) miss: a green `--lib` run AND a
multi-lens review BOTH passed while these two were red, caught only by the pre-push
`just preflight`. Run `cargo nextest run --workspace` / `just test` (NOT just
`--lib`) before declaring green — a targeted `--lib` run is not the full suite.

(The exact test names + full step list are in `crates/pixtuoid-core/CLAUDE.md`
"Adding a new agent CLI" and `add-source.prompt.md` — this skill headlines the
teeth, those own the specifics.)

## Finish

- Wire it into `runtime/driver.rs::build_source_set` (transcript-bearing only —
  the one construction site, called by `run_async`). This step HAS teeth:
  `build_source_set_wires_every_transcript_bearing_source_plus_the_hook_router`
  (`driver.rs`) FAILS for a registered source left unwired, so `just preflight`
  catches the miss — don't make it wait that long.
- Capture the real wire shape and set `verified_version` (`"unknown"` until a
  byte-real capture anchors it). Drift-watch it — what earns a row is in
  `docs/CONTRIBUTING.md` "Adding a new agent CLI" (four steps, every one
  test-gated), the row SHAPE in `scripts/check_upstream_drift.py`'s `SURFACE_ROWS`,
  and the emitter in each crate's `src/drift_surface.rs` — `just
  gen-drift-surface` after.
- `just gen-contract` only if you touched the `--json`/`SourceStatus`/`OutcomeRow`
  SHAPE (adding a row doesn't).
- `just preflight` before the PR, then run the **two-lens-review** skill.