Penguin Harness Dev

Developing PenguinHarness

PenguinHarness is a TypeScript monorepo: an Agent SDK (packages/core), an HTTP server (packages/server), a Web App (packages/web), a CLI (packages/cli), an Electron shell (packages/desktop), the landing and docs sites, and the shipped plugin library — one npm package per plugin under the repo root's plugins/, with packages/plugins as the loader that depends on them all. It consumes LLM providers through @prismshadow/mmsp (MMSP, formerly @prismshadow/agenthub) and implements no provider clients of its own.

This page is the part that applies to every change. The reference files carry the detail, read them when the task reaches them:

No AI slop — every time something is rendered or written

Whatever you add to the UI or the copy, check it before you call it done: decide before you decorate; one accent, one voice; hierarchy from scale and space; subtract first; specific beats punchy; decoration must mean something. No gradients, glows, emoji, pill spam, cards in cards, coloured keywords or "it's not just X — it's Y". Reuse the theme tokens and lib/tone.ts; status is an icon plus a tooltip; sections are ruled, not boxed. Run node .agents/skills/penguin-harness-dev/reference/ai-slop/scan.mjs <what you touched> and triage every hit. reference/ai-slop.md has the repo's own decisions and the full catalogue.

Repo shape — read before your first edit

Two repositories sit side by side: the implementation repo (penguin-harness) and the design repo (penguin-harness-design). Three paths inside the implementation repo are symlinks into the design repo and are gitignored here:

• design/ → the design repo, so specs are reachable as design/specs/…
• AGENTS.md → design/AGENTS.md
• CLAUDE.md → AGENTS.md

Editing AGENTS.md, CLAUDE.md or anything under specs/ edits the design repo's files. Commit them there, on their own branch, in their own PR. They can never appear in an implementation-repo PR. A fresh clone has none of the three links; recreate them by hand. A clone with no design repo beside it — the normal state for a remote or throwaway environment — has nothing to link to, so it carries no AGENTS.md at all and these skills are its whole contract.

Both repos take changes through branch + PR against main, squash-merged. Do not push to main, and gh pr create --base main — not dev, whatever a sibling repo does.

Branches are feat/<topic>, fix/<topic>, docs/<topic> in both repos. Some older branches here read docs-<topic> instead: a remote branch literally named docs once held that ref namespace and made the slashed form unpushable. It is gone — if a push is ever rejected as a directory/file conflict again, git ls-remote --heads origin names the branch responsible.

Independent changes each get their own git worktree under ../penguin-harness-wt/<topic>/ so several can run in parallel.

Keep searches inside the worktree you are working in. Scanning the home directory or the whole disk is rarely worth it: it is slow, and what it turns up outside the tree is usually another checkout's copy of the file you are already looking at. When a path does not resolve, prefer narrowing — reason about the package layout, ask git ls-files, follow the conventions above — over widening the root. The only paths outside the worktree worth reading are the siblings named here: ../penguin-harness-design for specs, ../penguin-harness-wt/* for another topic's tree, and ../agenthub for MMSP where it is checked out (the checkout keeps the library's former name). Reach them by name; never find them by scanning. Say all of this to every subagent you dispatch — widening the search root is the first move a subagent makes when a path does not resolve.

Tests prove behaviour, not the source

Before a test, write its scenarios (Given / When / Then) in the file header; one it per scenario, named as the behaviour. Assert only what the caller can observe — and look first for what must not happen (a retry that must not duplicate, a refusal that must not write). Never test a constant, a copied table, a UI string against its dictionary, or which private helper ran. Fake only at the system's edge with the package's shared helpers (one fetch fake, one mock LLM, createTestApp, real temp dirs, fake timers); do not vi.mock the package's own modules. Every branch a change adds is taken by a scenario; pruning never lowers branch coverage. No real sleeps, no per-test servers. reference/testing.md has the rules and the checklist.

Verify what you changed

Node must be >= 24. In each worktree, pnpm install --frozen-lockfile first.

The full chain CI runs is pnpm build, pnpm format:check, pnpm typecheck, pnpm test, sh scripts/test-installer.sh. Do not reach for pnpm test by reflex — it is nine packages and ~2500 tests, minutes per run, and for a docs-only diff it proves nothing the narrow run does not. Pick the narrowest evidence that would actually fail for this change's regression:

pnpm --filter @prismshadow/penguin-core exec vitest run test/model-catalog.test.ts   # one file, ~1s
pnpm --filter @prismshadow/penguin-web test                                          # one package

Always cheap, always worth it: git diff --check, and pnpm format + format:check on any diff at all.

Run the whole chain in exactly three cases: the change spans the repo widely enough that nothing narrower is credible, you are diagnosing a CI failure, or you are asked to. There are no coverage thresholds in this repo, so nothing forces a wider run than the behavior needs.

Tests run on this machine unless the user asks otherwise. Moving a suite to another host is something they request in so many words, not an optimisation to take on your own — see reference/verification.md for how, and for why a difference between two machines is a finding rather than something to paper over.

Once the evidence you chose passes, commit and push to the current branch without asking. Force-pushes and reverting someone else's commits still need confirmation.

When a test fails in a way that does not match your diff, when CI reads green too easily, or when a fake or an assertion looks like it proves nothing, read reference/verification.md before spending a second round on it.