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 at 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.
3. 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.
4. Approval gate. Show the user a diff of the compressed file against the original. Write only after approval.
5. 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.
6. 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.