penguin-harness/CONTRIBUTING.md

Contributing to PenguinHarness

Thanks for helping build PenguinHarness! This guide covers the workspace setup, daily commands, quality gates, and the repo's working rules.

Prerequisites

• Node >= 24
• pnpm 11 (corepack enable or npm install -g pnpm)

Setup and daily commands

pnpm install
pnpm build       # build first: core's exports point at dist/

pnpm dev         # backend + web app together (prefixed logs, deps built once)
pnpm dev:server  # backend at 127.0.0.1:7368 (not the installed server's 7364)
pnpm dev:web     # web app (Vite) at 127.0.0.1:7365, /api proxied to 7368
pnpm dev:docs    # docs site (Vite) at 127.0.0.1:7367
pnpm dev:landing # landing page (Vite) at 127.0.0.1:7366
pnpm penguin ... # CLI from source; `penguin web` serves at 127.0.0.1:7369

BASE_PATH=/ pnpm build:site   # assemble landing + docs exactly like the Pages deploy

Every dev command runs scripts/dev-prebuild.mjs first, which (behind a lock that serializes concurrent invocations) keeps pnpm install current automatically — a fresh clone or a pulled lockfile change installs before starting, and an up-to-date tree pays nothing (the lockfile hash is stamped) — then prebuilds the workspace deps (skills, core) with back-to-back builds deduped: starting dev:server and dev:web at the same time (or just pnpm dev) installs and builds exactly once. When that build changes skills/core output, the prestep also clears the web app's Vite dep cache (packages/web/node_modules/.vite), which is keyed by lockfile/config only and would otherwise keep serving the browser the previous core. dev:docs / dev:landing run the install check only (--install-only).

One rule when bypassing the dev commands: rebuild skills/core through pnpm, in that order (pnpm build, or restart pnpm dev) — the workspace uses injected dependencies (injectWorkspacePackages in pnpm-workspace.yaml), so web/server consume snapshot copies that only re-sync when the package's build script runs via pnpm (syncInjectedDepsAfterScripts). A bare npx tsup in packages/core updates packages/core/dist but leaves those snapshots — and any already-populated Vite dep cache — on the old build; if a running dev web app still serves stale core after a manual rebuild, delete packages/web/node_modules/.vite and restart.

Dev entry points that touch data (pnpm dev, pnpm dev:server, pnpm penguin) default to a separate data root, ~/.penguin/dev-data, kept apart from the installed CLI/server's ~/.penguin/data — hacking on the repo never mixes state with your real agents. Export PENGUIN_HOME to point them anywhere else; an explicit value always wins.

Copy .env.example to .env for model credentials in development.

Repo layout

A pnpm monorepo (TypeScript, Node >= 24). One install ships four layers that share a single data directory (~/.penguin/data) and a single message protocol (OmniMessage):

Package	Name	Role
packages/core	@prismshadow/penguin-core	SDK & engine: ReAct loop, OmniMessage protocol, LLM/Environment interface contracts, Agent State, Trace
packages/cli	@prismshadow/penguin-cli	The penguin command: REPL, one-shot runs, model & vault config, service launcher
packages/server	@prismshadow/penguin-server	Web backend: HTTP API + SSE streaming, multi-user auth, Project authorization, usage stats
packages/web	@prismshadow/penguin-web	Web App: multi-session chat, Agent/skill/model management, Trace observability, evaluation center
packages/skills	@prismshadow/penguin-skills	Built-in skill library (agent creation, benchmarking, evaluation, optimization, …)
packages/landing	—	Product landing page (this repo's website)
packages/docs	—	Documentation site (bilingual, deployed under /docs/)

Responsibilities split by source of truth: the SDK owns protocol and execution (message parsing, the agent loop, tools), the Server owns the multi-user runtime (auth, SSE streaming, scheduled tasks), and the file layer under ~/.penguin/data owns everything editable and recorded (prompts, Skills, secrets, Traces). The full map is in Architecture → Division of responsibilities.

Quality gates

CI runs all of these on every PR — run them locally before pushing:

pnpm format:check   # prettier
pnpm typecheck
pnpm test           # unit suites for every package

End-to-end suites (optional locally, slower):

npx playwright install chromium                      # once
pnpm --filter @prismshadow/penguin-web test:e2e      # browser e2e against a mock LLM
pnpm test:e2e                                        # core live-model e2e, needs DEEPSEEK_API_KEY

Working rules

• English is the repository's working language — code, comments, error/log messages, test names and fixtures, package metadata, and developer docs. Chinese appears only where it is the content itself: zh i18n catalogs and fields (strings.ts dictionaries, CLI i18n.ts, titleZh, short_description_zh), *.zh.md documents, and test literals that assert zh i18n output or exercise CJK-specific behavior.
• Every change ships with a changelog entry: add changelog/<version>/YYYY-MM-DD-<semantic-id>.md under the next unreleased version (released versions' folders are frozen) — an H1 title, a one-sentence summary paragraph, then details — and add a one-line link for it to that version's index, changelog/<version>/README.md. The layout is documented in changelog/README.md. Related changes may share one entry file (extending its details) instead of opening a new file per small change.
• A release ships its own announcement: changelog/<version>/RELEASE.md is published verbatim as the GitHub Release body. Write it during release preparation and commit it before creating the tag — the release workflow reads it from the tag's checkout, so a file added later never reaches the Release page. Without it the workflow falls back to GitHub's auto-generated notes.
• Release prep bumps the repo version: the same release: X.Y.Z PR that renames changelog/unreleased/ also bumps the root and every packages/*/package.json version, plus core's VERSION constant (packages/core/src/index.ts), to the release version. The release workflow refuses a tag push whose version does not match the repo's, so a forgotten bump fails before anything is published (v0.2.1 was tagged with a 0.2.0 repo, and every dev build nagged about an update until the repo caught up).
• README assets under assets/readme/ are generated — the benchmark charts from the landing benchmark data, and the demo screenshots via node packages/landing/scripts/capture-readme-demo.mjs (build first; needs Playwright chromium). Regenerate rather than hand-editing.

Pull requests

• Branch from main; keep PRs focused on one topic.
• Make sure CI is green (build, format, typecheck, tests) and describe user-visible changes in the PR body.
• New user-facing behavior should come with tests, and with docs updates when it changes documented behavior (README, docs site).