PirateBao

PirateBao be a Bun-first, TypeScript-first pirate rig for terse AI coding replies. Commands, code, paths, versions, risk notes, stack traces, and test results stay nailed to the mast. Greeting foam, hedge fog, and apology barnacles get keelhauled on sight. Kraken eats boilerplate; cargo stays lashed. Parrot squawks; token bill shrinks.

Default sail: kraken. Main flags: /piratebao, $piratebao, /piratebao:compress. Goal: fewer tokens, same technical cargo, less polite sea-tax.

Explain Like I'm 5

AI answers spend doubloons on hello, read the map thrice, then polish the plank until the plank demands equity. PirateBao heaves chatter overboard and lashes treasure to the mast: command, file, bug, fix.

Before	After
"Sure, I would be happy to help. The issue is likely caused by a new object reference on each render."	"New object ref each render. Use useMemo."

Same treasure map. Smaller scroll. Faster ship. Fewer invoices dressed as parrots. No "hope this helps" barnacle unless it actually fixes the failing test. Politeness is ballast; the kraken knows what to eat.

flowchart LR
  A["Long answer"] --> B["PirateBao removes ceremony"]
  B --> C["Short technical answer"]
  C --> D["Fewer tokens"]
  D --> E["Lower cost + faster replies"]

Loading

Three questions a five-year-old pirate would ask:

Question	Answer
What is it?	A skill plus hooks that make an AI coding agent answer short without dropping technical cargo.
What does it cost me?	Nothing at runtime. It removes words, not facts. Committed eval gate: 77% average saved, 68% worst saved.
What can it break?	Nothing in your code. It shapes replies. Security, publish, and data-loss warnings stay long on purpose.

Quick Start

bun install --frozen-lockfile
bun run build
bash hooks/install.sh

Then say /piratebao in Claude Code. Say stop PirateBao when the parrot needs a nap.

What It Ships

Area	Contract
Runtime	Claude Code hooks compile to dist/hooks/*.js; session start hauls no tsx anchor.
Skills	Canonical behavior lives in skills/piratebao/SKILL.md; copies synced and verified — drift walks the plank.
Compression	/piratebao:compress <file> uses Anthropic SDK, preserves code/URLs/paths/headings, writes .original.md backup.
OpenCode	Native .opencode/skills/<name>/SKILL.md and .opencode/commands/*.md; no plugin dependency in this pass.
Docs site	docs/ is a static GitHub Pages surface with its own headless-browser test.
npmjs	package.json exports compiled TypeScript cargo and gates the payload with npm pack --dry-run --json. No imaginary barrels aboard.
.bao	bao/piratebao.manifest.json is a cargo ledger, not an archive format. The quartermaster checks it.
CI	.github/workflows/ci.yml runs the gate on every push and pull request to main.

What It Does Not Ship

Not aboard	Reason
Retired aliases	Break rename is intentional. Old names are barnacles — scrape them.
CLI substitute for compression	Missing ANTHROPIC_API_KEY fails directly. Ghost oars cost maintenance and sometimes row toward prod.
.bao archive builder	This pass counts barrels and checks labels only. No archive builder lurks below deck.
Runtime TypeScript loader for hooks	Hooks run compiled JS. Ship does not stop to compile at dawn.
Registry gate inside CI	checkNpmRegistry fails once a version exists in the registry. That is publish-time truth, not pull-request truth, so CI leaves it on the dock.

日本語 README

PirateBao

PirateBao は Bun-first / TypeScript-first の海賊リグです。AI コーディング返答から挨拶の泡、遠慮の霧、謝罪のフジツボを斬り捨てます。コード、コマンド、パス、バージョン、危険、スタックトレース、テスト結果はマストに釘打ちます。クラーケンは boilerplate を食べ、TypeError は残します。オウムは騒ぐ。token は金貨。礼儀に銀貨を払う船長はおらぬ。

5歳向け説明

AI は宝箱の前で長々と挨拶し、地図を三度読み直し、甲板を磨いて磨いて磨きがちです。PirateBao は泡を海に捨て、宝だけマストに残します: コマンド、ファイル、バグ、修正。金貨で霧を買わぬ。海賊は礼儀に銀を払わぬ。

flowchart LR
  A["長い返答"] --> B["前置きを捨てる"]
  B --> C["短い技術返答"]
  C --> D["token削減"]
  D --> E["速い航海"]

Loading

技術メモ

項目	内容
既定の帆	kraken
主要コマンド	/piratebao, /piratebao:compress <file>, /piratebao-help
日本語モード	nihon-skiff, nihon-brig, nihon-kraken
検証	bun run check が TypeScript、Vitest、.bao、OpenCode、npmjs dry-run を通す
CI	.github/workflows/ci.yml が main への push と pull request で門を開く
積荷台帳	bao/piratebao.manifest.json に README と OpenCode 積荷を載せる

bun install --frozen-lockfile
bun run check

船長向け結論: これは翻訳された飾りではなく、日本語の短縮モードと検証対象の README です。nihon-kraken は短く切る。rm -rf と npm publish の危険は切りすぎない。髑髏は少なめ、検証は多め。

Schwiizerdütsch README

PirateBao

PirateBao isch es Bun-first, TypeScript-first Pirat-Rigg für churzi AI-Coding-Antworte. Code, Befehle, Pfäd, Versione, Risiko, Stacktraces und Testresultat bliibe am Mascht feschtgnaglet. Begrüessigs-Schaum, Hättegli-Nebel und Entschuldigungsmuschele gönd über Bord — kielholt ohni Gnade. De Chrottekrake frisst Boilerplate, nöd Fehlermeldige. De Papagei chiflet; d token-Rechnig schrumpft. Höflichkeit isch Ballascht.

Für Chind erklärt

AI redt mängisch hoi, list d Charte drüümal und poliert s Brett bis es nach Büro riecht. PirateBao seit: Ladig bhalte, Blabla ab is Wasser. Tokens sind Münze; mir zahled nöd für Nebel mit Schnauz. De Hafemeister nickt; de Papagei chrächzt.

flowchart LR
  A["Langi Antwort"] --> B["Blabla usem Logbuech streiche"]
  B --> C["Kurzi Technik-Antwort"]
  C --> D["weniger Tokens"]
  D --> E["schnäller Hafe"]

Loading

Technik

Teil	Sinn
Standard-Segel	kraken
Befehle	/piratebao, /piratebao:compress <file>, /piratebao-help
Schwiizerdütsch-Modi	swiss-skiff, swiss-brig, swiss-kraken
Gate	bun run check prüeft TypeScript, Vitest, .bao, OpenCode und npmjs dry-run
CI	.github/workflows/ci.yml lauft bi jedem push und pull request uf main
Ladigslischte	bao/piratebao.manifest.json listet README und OpenCode-Fracht

bun install --frozen-lockfile
bun run check

Kurz: kei lackierts Fass. Es isch e technischi README-Kopie mit eigenem Pirateton, Sprachmodi und Gate. swiss-kraken schneidet hart; bi Security, Publish und Dateverlust blibt er nüchtern. De Chäpten unterschriibt mit trockene Stiefel und em Schwert am Gurt.

Install

Bun is the package manager of record. npm is used only where npmjs itself is the thing being tested, because even pirates respect the harbor office and its tiny clipboard of pain.

Harbor	Command	Checks
Install deps	bun install --frozen-lockfile	Uses bun.lock; fails if package.json drifted.
Typecheck	bun run typecheck	tsconfig.json and tsconfig.tests.json, both --noEmit.
Lint	bun run biome	Biome check over src and tests.
Build	bun run build	Emits dist/ JS, declarations, and source maps.
Test	bun run test	Builds, packs piratebao.skill, runs Vitest.
Verify all	bun run verify	Sync, .bao, OpenCode, stale-name scan, npm registry, npm pack dry-run.
Complete gate	bun run check	Typecheck, lint, build, tests, verify, registry, pack dry-run.
Post-publish bunx smoke	bunx -p piratebao piratebao-verify	Runs the npmjs binary from Bun's package runner after the crate exists in the registry.

Agent installs:

Agent	Install
Claude Code	claude plugin marketplace add d4551/piratebao && claude plugin install piratebao@piratebao
Codex	Clone repo, open Codex, install local plugins/piratebao
OpenCode	Clone repo; OpenCode reads .opencode/skills/*/SKILL.md and .opencode/commands/*.md
Gemini CLI	gemini extensions install https://github.com/d4551/piratebao
Cursor/Windsurf/Cline/Copilot	npx skills add d4551/piratebao

Standalone Claude Code hooks:

bun install --frozen-lockfile
bun run build
bash hooks/install.sh

Uninstall:

bash hooks/uninstall.sh

Windows uses hooks/install.ps1 and hooks/uninstall.ps1 with the same contract.

Commands

Command	Loot
/piratebao	default kraken mode
/piratebao skiff	light terse prose
/piratebao brig	strong terse prose
/piratebao kraken	maximum terse prose
/piratebao jade-skiff	light classical Chinese terse mode
/piratebao jade-brig	strong classical Chinese terse mode
/piratebao jade-kraken	maximum classical Chinese terse mode
/piratebao nihon-skiff	light Japanese terse mode
/piratebao nihon-brig	strong Japanese terse mode
/piratebao nihon-kraken	maximum Japanese terse mode
/piratebao swiss-skiff	light Swiss German terse mode
/piratebao swiss-brig	strong Swiss German terse mode
/piratebao swiss-kraken	maximum Swiss German terse mode
/piratebao-commit	terse Conventional Commit message
/piratebao-review	one-line review findings
/piratebao:compress <file>	compress natural-language memory file
/piratebao-help	command card
$piratebao	Codex skill trigger

Deactivate with stop PirateBao or normal mode.

The six command strings the .bao ledger tracks live in src/config/pirateBaoCommands.ts. Manifest drift against that file fails verifyVersionSsot, so the ledger cannot invent a command the code never answers.

Mode Matrix

Family	Modes	Output contract
English	skiff, brig, kraken	shorter prose, same technical payload, stricter ceiling as sail gets heavier
Classical Chinese	jade-skiff, jade-brig, jade-kraken	terse classical Chinese phrasing, examples gated by token monotonicity
Japanese	nihon-skiff, nihon-brig, nihon-kraken	Japanese terse mode with the same no-filler/no-self-reference rules
Swiss German	swiss-skiff, swiss-brig, swiss-kraken	Swiss German terse mode with the same compression ceilings

Word ceilings from skills/piratebao/SKILL.md: skiff ≤45, brig ≤30, kraken ≤20. The jade/nihon/swiss families use sentence ceilings instead: skiff ≤2 short sentences, brig ≤1, kraken ≤1 fragment. tests/evals.test.ts re-counts every family's example with js-tiktoken and fails if a heavier sail somehow grows.

Config precedence for the default sail:

flowchart LR
  Env["PIRATEBAO_DEFAULT_MODE"] --> Pick["chartDefaultSail"]
  Cfg["~/.config/piratebao/config.json"] --> Pick
  Fallback["built-in default"] --> Pick
  Pick --> Mode["kraken unless overridden"]

Loading

All families forbid self-announcements like mode banners unless the user explicitly asks. PirateBao steers the ship; it does not give a speech from the crow's nest. The best compression is the sentence never emitted. The second best is the sentence that lost its adjectives at sea.

Repo Map

flowchart TD
  subgraph Canonical["Canonical sources — edit these"]
    Skill["skills/*/SKILL.md"]
    Rule["rules/piratebao-activate.md"]
    Manifest["bao/piratebao.manifest.json"]
  end
  subgraph Code["TypeScript — src/"]
    Hooks["hooks/ — session + prompt + statusline"]
    Dumpling["dumpling/ — compressor + seal"]
    Shipyard["shipyard/ — sync, pack, verify"]
    Evals["evals/ — token accounting"]
    Cfg["config/ + constants/ + runtime/"]
  end
  subgraph Generated["Generated — do not hand-edit"]
    Copies[".opencode/ .cursor/ .windsurf/ .clinerules/ plugins/"]
    Dist["dist/"]
    Zip["piratebao.skill"]
  end
  Skill --> Copies
  Rule --> Copies
  Manifest --> Copies
  Code --> Dist
  Skill --> Zip
  Dist --> Gate["verifyHarbor"]
  Copies --> Gate
  Zip --> Gate
  Manifest --> Gate

Loading

dist/ is committed on purpose. hooks/install.sh can install without a clone by pulling compiled files straight from raw GitHub, so deleting compiled cargo from version control would strand every remote installer. .github/workflows/sync-skill.yml keeps it in step on main.

Runtime Flow

flowchart TD
  Prompt["agent prompt"] --> Hook["readCaptainOrder"]
  Hook --> Flag["~/.claude/.piratebao-active"]
  Session["session start"] --> Raise["raiseJollyRoger"]
  Raise --> Skill["skills/piratebao/SKILL.md"]
  Skill --> Filter["mode-specific rule filter"]
  Filter --> Agent["agent context"]
  Flag --> Status["paintStatusFlag"]
  Status --> Badge["statusline badge PIRATEBAO:KRAKEN"]

Loading

SessionStart loads the compiled hook and canonical skill once per invocation. UserPromptSubmit updates the mode flag. Statusline reads the flag and prints a small badge. This keeps startup work bounded; the ship does not inspect every barrel on each wave or bill you for barnacle inventory.

Shipyard Flow

flowchart TD
  Skill["skills/piratebao/SKILL.md"] --> Sync["syncTreasureMap"]
  Sync --> Copies["OpenCode/Cursor/Windsurf/Copilot/plugin copies"]
  Skill --> Pack["packSkillCargo"]
  Pack --> Zip["piratebao.skill"]
  Schema["schemas/piratebao-bao-manifest.schema.json"] --> Gate["verifyHarbor"]
  Manifest["bao/piratebao.manifest.json"] --> Gate
  Copies --> Gate
  Zip --> Gate
  Gate --> Release["npmjs-ready package"]

Loading

Canonical files are edited once, then synced. verifyHarbor rejects copy drift, stale brand tokens, missing OpenCode cargo, malformed plugin manifests, missing compiled artifacts, wrong zip contents, and README drift. The quartermaster is boring on purpose; comedy belongs in prose, not package invariants. The gate has no sense of humor and no parrot.

Run bun run sync after editing any canonical skill or rule file. bun run verify runs the same walk with --check and fails instead of writing.

End-to-End Gate

Use this before publishing or after touching docs, skills, hooks, manifests, or compression logic:

bun install --frozen-lockfile
bun run typecheck
bun run build
bun run test
bun run verify
bun run pack:dry

Or one rope for the whole rig:

bun run check

flowchart LR
  TC["typecheck"] --> LN["biome"]
  LN --> BD["build"]
  BD --> PK["packSkillCargo"]
  PK --> VT["vitest"]
  VT --> SY["sync --check"]
  SY --> VH["verifyHarbor"]
  VH --> RG["checkNpmRegistry"]
  RG --> DR["npm pack --dry-run"]

Loading

CI runs every step of that chain except checkNpmRegistry. That gate fails by design once a version already exists on npmjs, which is correct at publish time and wrong on a pull request, so it sails only in bun run check and .github/workflows/publish.yml.

Workflow	Trigger	Job
.github/workflows/ci.yml	push + pull request on main	typecheck, lint, build, Chromium, tests, sync check, harbor verify, pack dry-run
.github/workflows/sync-skill.yml	push on main touching canonical files	rebuilds, syncs copies, commits drift back
.github/workflows/publish.yml	tag v*	full verify chain plus npm publish --access public

Runtime smoke for standalone Claude Code hooks:

tmp_home="$(mktemp -d)"
HOME="$tmp_home" bash hooks/install.sh --force
HOME="$tmp_home" node "$tmp_home/.claude/hooks/piratebao-dist/hooks/raiseJollyRoger.js"
printf '{"prompt":"/piratebao swiss-kraken"}' | HOME="$tmp_home" node "$tmp_home/.claude/hooks/piratebao-dist/hooks/readCaptainOrder.js"
cat "$tmp_home/.claude/.piratebao-active"
HOME="$tmp_home" bash hooks/uninstall.sh
rm -rf "$tmp_home"

Expected smoke result: install succeeds, session hook emits PirateBao rules, prompt hook writes swiss-kraken, uninstall removes hook cargo. No bottle note required.

Tests

Eight Vitest files, forty tests, no live model calls. The only shell-out is the npm publish dry-run inside verifyHarbor, which tests/publicSurface.test.ts exercises for real.

File	Cargo checked
tests/decodeJson.test.ts	typed JSON decoding boundary; no raw parse in shipping code
tests/docs.browser.test.ts	real headless Chromium against docs/: hero, stylesheet, clipboard, toggles, clean console
tests/dumpling.test.ts	prose-vs-code detection, fence stripping, and every committed compressor scroll in tests/piratebao-compress/
tests/evals.test.ts	locks the 77%/68% snapshot gate and mode-example token monotonicity
tests/hooks.test.ts	session/prompt hooks, mode flag writes, statusline badge
tests/publicSurface.test.ts	exported config surface plus a live verifyHarbor() run
tests/shipyard.test.ts	.bao shape, deterministic zip, OpenCode cargo, sync targets
tests/wireClaudeSettings.test.ts	Claude settings wiring without JSON.parse in shell

tests/piratebao-compress/ holds real compressor output: each <name>.original.md and its compressed <name>.md. The suite feeds every pair to sealBaoScroll and fails on any lost code block, URL, or heading, then checks the pair still saves at least 20% of its tokens. Fixtures that stop compressing, or start eating cargo, get caught.

The browser test needs a Chromium build. Provision one with bunx playwright install chromium, or point PIRATEBAO_CHROMIUM_PATH at an existing binary. With no Chromium anywhere the suite skips instead of failing, so a clone without browsers still runs the rest of the gate — CI installs Chromium so the docs surface is genuinely exercised there.

OpenCode Native Support

OpenCode support is project-native:

File	Purpose
opencode.json	Points OpenCode at AGENTS.md and allows piratebao* skills.
.opencode/skills/piratebao/SKILL.md	Synced main skill.
.opencode/skills/piratebao-commit/SKILL.md	Synced commit skill.
.opencode/skills/piratebao-review/SKILL.md	Synced review skill.
.opencode/skills/piratebao-help/SKILL.md	Synced help skill.
.opencode/skills/piratebao-compress/SKILL.md	Synced compressor skill.
.opencode/commands/piratebao.md	/piratebao command template.
.opencode/commands/piratebao-commit.md	Platform-safe /piratebao-commit; uses $ARGUMENTS.
.opencode/commands/piratebao-review.md	Platform-safe /piratebao-review; uses $ARGUMENTS.
.opencode/commands/piratebao-help.md	Platform-safe /piratebao-help.
.opencode/commands/piratebao-compress.md	Platform-safe compress command; uses $ARGUMENTS.

Command filenames avoid : for cross-platform safety. Frontmatter descriptions are verified. This is not a TypeScript OpenCode plugin; no extra runtime hook hides in the bilge wearing a false moustache.

TypeScript Rig

Pinned current stack, verified on 2026-08-04:

Tool	Version	Role
Bun	1.3.14	install/scripts; lockfile authority
TypeScript	7.0.2	strict compile for src/ and tests
Node	>=24.11.0	runtime target for compiled hooks/CLIs
Biome	2.5.4	lint/format gate
Vitest	4.1.10	behavior tests
Playwright	1.61.1	docs browser contract
AJV	8.20.0	.bao schema validation
Anthropic SDK	0.112.1	compressor API client
js-tiktoken	1.0.21	token evals

Compiler flags are strict on purpose: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, verbatimModuleSyntax, noUnusedLocals, noUnusedParameters, and skipLibCheck: false. Biome bans any, @ts-ignore, and non-null assertions.

No direct env reads outside config modules. No any in implementation/tests. No TypeScript suppressions. If the mast cracks, the compiler gets first complaint, not a postmortem parrot. Types are the rigging; if they fray, the sail falls before the wind arrives.

.bao Contract

PirateBao validates manifest contract. .bao is cargo ledger, not archive chest. The verifier counts barrels, then complains like a sober quartermaster.

Item	Path
schema	schemas/piratebao-bao-manifest.schema.json
manifest	bao/piratebao.manifest.json
validator	src/shipyard/validateBaoChest.ts
full gate	src/shipyard/verifyHarbor.ts
OpenCode cargo	.opencode/skills/*/SKILL.md + .opencode/commands/*.md
spec	BAO-MANIFEST-SPEC.md

Gate checks manifest schema, key order, referenced files, README inclusion, synced skill copies, OpenCode files, plugin metadata, stale brand tokens, compiled artifacts, shell scripts, npmjs package files, and piratebao.skill contents.

flowchart LR
  M["manifest"] --> S["schema validate"]
  S --> F["referenced files exist"]
  F --> O["OpenCode cargo present"]
  O --> Z["zip contains piratebao/SKILL.md"]
  Z --> P["package files checked"]
  P --> OK["ship"]

Loading

The ledger is also the sync map. syncedCopies names each canonical source and every copy it owns, with optional frontmatter prefixes for Cursor and Windsurf. Add a copy there and bun run sync starts maintaining it; forget to list it and verifyHarbor says so.

npmjs Package

Package name: piratebao. Registry gate checks availability before publish. npm dry-run checks payload, not vibes. The harbor rejects imaginary treasure; the verifier checks labels before the crate reaches the dock. Painted barrels without rum get thrown back.

Required npmjs fields are set: named exports only (no main/types/"."), plus bin, files, license, repository, bugs, publishConfig, packageManager.

Export	Compiled entry
piratebao/hooks	dist/hooks/raiseJollyRoger.js
piratebao/dumpling	dist/dumpling/stuffDumpling.js
piratebao/shipyard	dist/shipyard/verifyHarbor.js
piratebao/config	dist/config/captainConfig.js
piratebao/decode-json	dist/runtime/decodeJson.js

Binary	Job
piratebao-compress	compress a natural-language memory file
piratebao-pack	rebuild piratebao.skill
piratebao-registry	check npmjs name/version availability
piratebao-sync	refresh synced skill/rule copies
piratebao-verify	run the harbor gate

Dry-run before publish:

bun run check

Post-publish binary smoke:

bunx -p piratebao piratebao-verify
npx -p piratebao piratebao-verify

Use -p piratebao because the npm package is piratebao while the binary names are specific tools like piratebao-verify and piratebao-compress. That is not a riddle; it is just npm making the plank longer.

package.json files includes README, .bao manifest/schema cargo, OpenCode files, agent plugin files, compiled dist/, shell hooks, and piratebao.skill. Painted barrels without files fail verification. CLI bin entries use npm-normalized paths and shebang-bearing JS so npm does not quietly saw the rudder off during publish dry-run.

Compressor

/piratebao:compress <file> is for natural-language memory files: agent notes, project instructions, todos, and preference docs. It preserves code blocks, inline code, URLs, paths, headings, commands, versions, and proper nouns. It removes prose barnacles, not your mast. If a paragraph is mostly velvet rope, it becomes rope.

Set:

export ANTHROPIC_API_KEY=...
export PIRATEBAO_MODEL=claude-sonnet-4-5-20250929

No CLI substitute. Missing key fails with direct error. No ghost oar under the floorboards, no mystery subprocess paddling toward a rate limit.

flowchart TD
  File["memory file"] --> Detect["inspectFilling"]
  Detect -->|prose| Call["Anthropic Messages API"]
  Detect -->|code/config| Skip["skip"]
  Call --> Backup["write .original.md"]
  Backup --> Validate["sealBaoScroll"]
  Validate -->|ok| Done["compressed file"]
  Validate -->|bad| Fix["targeted fix prompt"]
  Fix --> Validate

Loading

sealBaoScroll is the honest part. Heading-count drift and any changed code block or lost URL are errors. Changed path sets and large bullet swings are warnings. A compressor that quietly eats a stack trace is not a compressor; it is a leak with a hat.

Docs Site

docs/ is a dependency-free static page for GitHub Pages: index.html, piratebao.css, favicon.svg, and .nojekyll. Inline <style> blocks are banned, the stylesheet must be linked, and the token claims baked into the page must match the committed eval snapshot — verifyDocsCargoMap checks all of it, down to the bar widths in CSS.

tests/docs.browser.test.ts then drives the real page in headless Chromium and asserts the console stays empty, which is how the missing favicon was found.

Environment

Variable	Effect
PIRATEBAO_DEFAULT_MODE	Overrides the default sail; must name a known mode.
PIRATEBAO_MODEL	Model for /piratebao:compress; defaults to claude-sonnet-4-5-20250929.
ANTHROPIC_API_KEY	Required by the compressor and the live benchmark. Never committed — .gitignore blocks .env files.
PIRATEBAO_CHROMIUM_PATH	Optional Chromium binary for the docs browser test.

Config file: ~/.config/piratebao/config.json (XDG_CONFIG_HOME and Windows APPDATA are honored). Active mode flag: ~/.claude/.piratebao-active.

Source Map

Path	Loot
skills/piratebao/SKILL.md	canonical behavior
skills/piratebao-{commit,review,help}/SKILL.md	canonical command skills
piratebao-compress/SKILL.md	canonical compressor skill
rules/piratebao-activate.md	always-on rule text
bao/ + schemas/	.bao ledger and its JSON Schema
.opencode/	native OpenCode commands + skills
src/hooks/	compiled Claude Code hooks
src/dumpling/	compressor + token logic
src/evals/	js-tiktoken snapshot accounting
src/shipyard/	sync, packaging, .bao, verify
src/config/, src/constants/, src/runtime/	typed config, path SSOT, JSON decoding
src/benchmarks/	live Anthropic benchmark runner
hooks/	shell/PowerShell installer + statusline entrypoints
commands/	Codex command definitions
plugins/piratebao/	Codex plugin payload and brand assets
docs/	static GitHub Pages surface
tests/	Vitest suites and compressor fixtures
piratebao.skill	deterministic skill zip containing piratebao/SKILL.md

Token Bench

Eval snapshots live in evals/snapshots/results.json. Current committed gate: 77% average saved, 68% worst saved. README claims must come from committed snapshot output. No treasure-map fiction; the sea already has enough myths, several consultants, and a kraken who cannot count.

bun run build
node dist/evals/countTreasureTokens.js

That command rewrites evals/README.md from the snapshot, so the table and the numbers cannot drift apart by hand. tests/evals.test.ts pins the pair at 77/68 and verifyDocsCargoMap re-checks the same numbers against the docs page.

Live benchmark needs ANTHROPIC_API_KEY and writes TSV rows to the git-ignored benchmarks/results/:

node dist/benchmarks/runTreasure.js

It reads its ten prompts from benchmarks/prompts.json and stamps each run with a hash of the skill file, so a result can always be traced back to the sail that produced it.

Publish Checklist

bun install --frozen-lockfile
bun run check
npm publish --access public

Before publish, confirm piratebao.skill contains only piratebao/SKILL.md, .opencode files appear in npm pack --dry-run --json, README token numbers match evals/README.md, and npm publish --dry-run --access public --json emits no npm auto-correction warnings. Then ship. Quietly. Pirates can be professionals; the cannon is for bugs.