compress-onboarding

Compressing onboarding files

Instruction files load every session, so every saved token compounds. Compress

prose aggressively while never touching the technical payload - and never trading

away clarity where ambiguity is dangerous.

Announce at start: "Using compress-onboarding on <file> at level <level>."

Usage: compress-onboarding <file> [--level off|lite|full|ultra]

Default file: the repo's AGENTS.md. Works under any SKILL.md-compatible runtime.

Levels (sticky per repo)

Resolve the level from --level if given, else `.aiboarding/config.json:

compression_level, else full. When --level` is given, persist it back to

config.json - the level is a per-repo decision, not per-run.

• off - no rewriting. Still run the size report (step 5) so bloat is visible.
• lite - remove filler, pleasantries, hedging, and restatement. Full sentences

kept. ("In order to build the project, you should run…" → "To build, run…")

• full (default) - additionally drop articles, compress to fragments and

short synonyms, allow X → Y notation. ("The dev server can be started with

npm run dev" → "Dev server: npm run dev.")

• ultra - telegraphic; every non-load-bearing word goes. Use only when the

effective instruction-chain audit needs it; confirm with the user before first use.

Byte-preservation invariants (hard guarantees)

Compression must NEVER alter: fenced code blocks (including the fence lines),

inline backtick spans, shell commands, URLs, file paths, identifiers and symbol

names, quoted error strings, <!-- aiboarding-* --> markers, YAML frontmatter, and

table structure. If a protected span is wrong, fixing it is an update, not a

compression - route it through update-agent-onboarding.

While rewriting, keep commands/identifiers/paths/error strings backtick-quoted (add

backticks where the source lacks them - adding protection is allowed; removing it

is not). The checker treats backtick spans as protected.

High-consequence preservation

Before rewriting, classify complete high-consequence regions. Preserve every

identified region verbatim, byte-for-byte, by default. full or ultra never

authorize rewriting one.

Always classify complete Agent Guardrails and Escalation - Ask the User When

sections. Outside those headings, classify smallest complete paragraph, list item,

warning, or ordered procedure needed to retain context when it governs security,

authorization, approval or escalation, destructive or irreversible actions, or

required ordering or prerequisites for destructive or migration work. Record each

region's source section or line location and category. Do not classify ordinary

project purpose, architecture, domain, or routine descriptive prose solely because

it is important or technical; compress that prose at selected level.

If user asks to rewrite identified high-consequence content, name affected regions

and obtain explicit opt-in for selected regions in current operation. Level choice

and final diff approval do not count. Do not persist consent. Rewrite only selected

regions, retain unselected regions verbatim, preserve all protected spans, and keep

behavioral force unambiguous. Then show final diff and obtain normal approval.

Procedure

1. Snapshot. Copy the target file to a temp path (before).
2. Classify and compress. Identify high-consequence regions, report their

locations and categories, and copy them verbatim unless current-operation,

per-region explicit opt-in permits rewriting. Compress remaining prose at

resolved level.

1. Verify. Run .aiboarding/tools/check-preservation <before> <after> (fall

back to the plugin's templates/tools/check-preservation if not installed).

Fix every reported span and re-run until clean. Never hand-wave this step.

1. Approval gate. Show the user a diff of the compressed file against the

original. Write only after approval.

1. Receipt. Measure before/after: exact bytes and lines always; token counts

with a real tokenizer if one is available in the environment (e.g. Python

tiktoken), otherwise tokens_approx = bytes / 4, explicitly labeled

approximate. Append to .aiboarding/state.json:receipts (one object per line,

keeping the file hook-readable):

   { "file": "AGENTS.md", "level": "full", "bytes_before": 8123, "bytes_after": 4310, "lines_before": 190, "lines_after": 121, "tokens_before_approx": 2031, "tokens_after_approx": 1078, "high_consequence_regions": [{ "location": "Agent Guardrails", "category": "guardrails", "outcome": "preserved", "explicit_opt_in": false }], "measured_at": "2026-07-02" }

high_consequence_regions is optional for backward compatibility. Each entry

records location, category, outcome (preserved or rewritten), and explicit

opt-in status; never copy instruction text. Include [] when classification

verified no such regions. Report same evidence to user.

Report the saving to the user; since the file loads every session, note the

per-session saving - never claim unlabeled exact token numbers without a real

tokenizer.

Also write a compact compression-verification record with the subject, level,

measurements, preservation and size outcomes through write-evidence. Keep the

legacy receipt unchanged; a failed preservation or size check is recorded when

possible and never authorizes a sync-pointer advance.

1. Size check. Run .aiboarding/tools/check-size-budget <file> as a local

sensor. It does not prove chain safety; run

.aiboarding/tools/audit-onboarding-evidence <repo-root> before claiming an

effective Codex chain fits. If local guidance still WARNs after full, suggest

moving detail to .claude/rules/ or nested AGENTS.md files rather than jumping

to ultra.

Writing into shared files

When compression output must land inside a file that also has user-owned content

(e.g. a hand-written CLAUDE.md), write only within the aiboarding marker fence

via .aiboarding/tools/inject-fenced - re-runs stay idempotent and uninstall stays

clean.