The problem: instructions are programs that cost tokens
Every agent that works on this repository reads a growing library of instruction files — SKILL.md documents, workflow.md orchestration, AGENTS.md policy, self.md model rules. They are not essays. They are control programs written in Markdown. The longer they get, the more context window they consume, the slower inference becomes, and the more likely the model is to miss a critical constraint buried on line 847.
We needed a compiler for these programs. Something fast, deterministic, auditable, and portable. Something that could strip the markup equivalent of dead code without changing behavior.
That is the Compact Instruction Compiler, or CIC.
High-level walkthrough
CIC is a tiny compiler that lives in scripts/lib/cic/. It takes a Markdown instruction file, lowers it into a line-oriented intermediate representation called PIR (Prompt Intermediary Representation), and then emits a compact Markdown file with the same structure but fewer tokens.
-i flag writes the compact result back over the source file.The build tree is intentionally CMake-like: all generated artifacts live under build/cic/, mirroring the source path. The PIR file goes to build/cic/pir/<rel-path>/BaseName.pir; the final compact Markdown goes to build/cic/md/<rel-path>/BaseName.md. Nothing is committed. The source stays canonical.
Why we made it
The /compact-instructions skill existed before CIC. It compressed files by reading, analyzing, and rewriting them with the agent. That worked, but it was expensive. Every compression pass consumed model tokens, and the process was hard to reproduce across sessions. We wanted a tool that could do the obvious, mechanical cleanup first, leaving the agent free for the semantic rewrite.
There was a second reason. We wanted an instruction representation that was not tied to Markdown. Markdown is a presentation format. It is good for humans, fragile for tools. An intermediate representation would let us validate, lint, syntax-highlight, and eventually transform agent instructions the same way a compiler manipulates a source language.
CIC is the answer to both needs. It is the mechanical pre-pass and the compiler scaffold for a new instruction language.
How it works
Three files implement the pipeline:
md2pir and pir2md, handles directories, verbose reports, and in-place install.@c markers, preserving structure..pir file, installs a VS Code extension, and configures editor settings.The cic.sh interface is small:
scripts/lib/cic/cic.sh -v input.md # verbose build
scripts/lib/cic/cic.sh -a -v input.md # aggressive slash-list compression
scripts/lib/cic/cic.sh -i -v input.md # install compact .md over source
scripts/lib/cic/cic.sh -o out.md input.md # override final output
scripts/lib/cic/cic.sh -v some/dir # compile all .md under a directory
scripts/lib/cic/cic-schema.sh --grammar
scripts/lib/cic/cic-schema.sh --validate file.pir
scripts/lib/cic/cic-schema.sh --install-vscode ~/.vscode/extensions/pir-syntaxThe md2pir parser normalizes structure first. It collapses blank lines, preserves frontmatter, turns headings into @h directives, bullets into @b, numbered lists into @n, code fences into @c blocks, and paragraphs into @p. Tables are emitted as @t rows. This is the lowering step: from a human-facing markup language to a machine-facing instruction language.
The pir2md compiler then applies a fixed set of token-reduction passes on the way back to Markdown. It removes conversational filler words, strips redundant labels like **Example**:, collapses comma/semicolon lists into slash lists, and removes leading articles. With the -a aggressive flag, it also slashes conjunctions outside of parentheses. After these passes, the file is written into the build tree and, if requested, copied back over the source.
The PIR language
PIR is a line-oriented domain-specific language. It is not meant to be written by hand (though it could be). It is the compiler's internal currency. Every PIR directive starts with @ followed by a single letter and a space, with one notable exception: @c code blocks are delimited by a matching @c line, and the content between them is treated as raw code.
| Directive | Meaning | Markdown source |
|---|---|---|
@f key value | Frontmatter field | --- key/value pairs |
@h level text | Heading | ## text |
@p text | Paragraph | Plain prose |
@b text | Bullet | - text |
@n text | Numbered item | 1. text |
@c [lang] / @c | Code fence | ```lang ... ``` |
@t row | Table row | | a | b | |
Why is PIR important? Because it separates three concerns that Markdown conflates:
cic-schema.sh --validate checks every directive against the schema and reports unclosed code blocks.PIR is a compiler IR, not a prompt format. It is lossless with respect to document structure. That is the point: you can compress, lint, and transform the language without worrying that a stray asterisk will turn a bullet into bold text.
Code and instruction examples
Here is a deliberately verbose agent instruction, the PIR that CIC produces from it, and the compact Markdown that comes back. The example was generated with the real toolchain in the repository.
---
title: Verbose Agent Guide
tag: Engineering
---
# How to use the agent
This document provides a very detailed and comprehensive explanation of the
various things that the agent should essentially do, and it is really quite
important that you basically read all of it very carefully before beginning any
work at all. Please understand that the agent is an autonomous system that needs
clear and concise instructions in order to operate effectively and efficiently
at all times.
## The build process
In order to build the project, you will need to follow a series of steps that
are described below. First of all, please ensure that you are currently running
from the root of the repository, because many of the scripts that are used in
this process make the assumption that the current working directory is the
repository root. After you have verified that you are in the correct directory,
you should then run the build script by executing the following command, which
will compile all of the engine and game code for the default Linux debug preset.
```bash
./scripts/build.sh
```
If the build completes and is successful, then you should proceed to run the
unit tests in order to verify that the compiled code is functioning correctly
and that no regressions have been introduced. However, if the build fails for
any reason, you should stop and carefully examine the error output in order to
determine the root cause of the failure.
## Important warnings
- Do not commit secrets to the repository under any circumstances.
- Do not use interactive command-line tools inside scripts.
- Avoid making destructive changes without explicit confirmation.@f title Verbose Agent Guide
@f tag Engineering
@h 1 How to use the agent
@p This document provides a very detailed and comprehensive explanation of the various things that the agent should essentially do, and it is really quite important that you basically read all of it very carefully before beginning any work at all. Please understand that the agent is an autonomous system that needs clear and concise instructions in order to operate effectively and efficiently at all times.
@h 2 The build process
@p In order to build the project, you will need to follow a series of steps that are described below. First of all, please ensure that you are currently running from the root of the repository, because many of the scripts that are used in this process make the assumption that the current working directory is the repository root. After you have verified that you are in the correct directory, you should then run the build script by executing the following command, which will compile all of the engine and game code for the default Linux debug preset.
@c bash
./scripts/build.sh
@c
@p If the build completes and is successful, then you should proceed to run the unit tests in order to verify that the compiled code is functioning correctly and that no regressions have been introduced. However, if the build fails for any reason, you should stop and carefully examine the error output in order to determine the root cause of the failure.
@h 2 Important warnings
@b Do not commit secrets to the repository under any circumstances.
@b Do not use interactive command-line tools inside scripts.
@b Avoid making destructive changes without explicit confirmation.---
title: Verbose Agent Guide
tag: Engineering
---
# How to use the agent
This document provides a detailed/comprehensive explanation of the various things that the agent should do/it is important that you read all of it carefully before beginning any work at all. Please understand that the agent is an autonomous system that needs clear/concise instructions to operate effectively/efficiently at all times.
## build process
In order to build the project/you will need to follow a series of steps that are described below. First of all/ ensure that you are currently running from the root of the repository/because many of the scripts that are used in this process make the assumption that the working directory is the repository root. After you have verified that you are in the correct directory/you should then run the build script by executing the following command/which will compile all of the engine/game code for the default Linux debug preset.
```bash
./scripts/build.sh
```
If the build completes/is successful/then you should proceed to run the unit tests to verify that the compiled code is functioning correctly/that no regressions have been introduced. However/if the build fails for any reason/you should stop/carefully examine the error output to determine the root cause of the failure.
## Important warnings
It is extremely important that you do not commit secrets or credentials to the repository/because doing so would create a significant security risk. Additionally/you should avoid using interactive commands/you should not modify the repository's security settings. Finally/ remember to be careful when performing destructive operations/as these actions cannot be undone.
- Do not commit secrets to the repository under any circumstances.
- Do not use interactive command-line tools inside scripts.
- Avoid making destructive changes without explicit confirmation.The mechanical pass removed filler words, collapsed some comma lists into slash lists, stripped leading articles from headings, and left code blocks untouched. The -a flag added the slash compression outside of parentheses. This is fast, auditable, and safe. The remaining long sentences are the domain of the agent rewrite pass.
Expected results
CIC's mechanical pass is intentionally conservative. It will not rewrite meaning. It removes low-hanging entropy. The /compact-instructions workflow uses CIC as Phase 0, then applies a semantic rewrite for files that still exceed token budgets. The combined result depends on file type:
| File type | CIC mechanical | Full /compact-instructions | Why the gap? |
|---|---|---|---|
| Prose-heavy instructions | 5-15% | 50-60% | CIC strips fillers; agent rewrites sentences. |
| Bullet/policy files | 1-5% | 3-10% | Already dense. Gains come from grouping paths. |
| Code-heavy files | 0% | 0% | Code blocks are never compressed. |
These numbers are measured, not aspirational. CIC itself ran at roughly 6.4% on the example above, 2.1% on the already compact .devin/skills/compact-instructions/SKILL.md, and 0% on a code-dense file. The tool is honest about what it can and cannot do.
Research and context
CIC sits in a larger research field called prompt compression. A 2025 survey from ACL Anthology divides the field into two families: hard-prompt methods that remove or rephrase tokens while keeping the output human-readable, and soft-prompt methods that compress prompts into continuous learned embeddings. CIC is squarely a hard-prompt method. It is not learned, it is not model-specific, and it does not require a GPU.
The survey reports that hard-prompt methods work by removing low-information content and that the compression ratio is simply the original token count divided by the compressed token count. Soft-prompt methods like 500xCompressor and ICAE can reach much higher ratios but produce embeddings that cannot be inspected. The trade-off is interpretability for compression ratio. We chose interpretability.
Other projects have also proposed intermediate representations for prompts. Imprompt defines a stack-based IR with explicit LM-interaction primitives. Cave Prompt compiles raw prompts into a semantic IR plus an optimized execution prompt. SoftPrompt-IR is a declarative IR for encoding constraint strength and priority. These are close cousins: they all recognize that treating prompts as raw text is a liability and that a compiler-like middle layer can improve reliability and portability. PIR is narrower: it targets the specific domain of Markdown instruction files for long-running agents.
- Prompt Compression for Large Language Models: A Survey — ACL Anthology 2025. Hard vs. soft prompt compression taxonomy.
- 500xCompressor: Generalized Prompt Compression for Large Language Models — ACL 2025. Soft-prompt, 6x-500x compression.
- Imprompt: A Language Framework for Prompt Programming — arXiv 2607.22683. Prompt IR with LM-interaction primitives.
- Cave Prompt — GitHub. Semantic prompt compiler with IR and execution prompt.
- SoftPrompt-IR — GitHub. Declarative symbolic IR for LLM instruction priority.
Cross-links and related work
CIC is one piece of the CatGame agent infrastructure. It feeds the /compact-instructions workflow, which feeds /update-self, which feeds the agent's long-term instruction improvement. The relevant portals and posts are below.
Why PIR matters, in one sentence
Conclusion
CIC is not a model. It is a tool: a small, transparent compiler that turns Markdown instructions into PIR, compresses them deterministically, and emits compact Markdown. It does not replace the agent. It makes the agent more efficient by removing the mechanical 5-15% before the semantic 50% begins.
The .pir language is the more important long-term bet. It gives the project a structured instruction representation that can be validated, syntax-highlighted, and compiled to multiple targets. Today the back-end is Markdown. Tomorrow it could be something else. A compiler makes that future possible.
The files are in scripts/lib/cic/. The skill is /compact-instructions. The build command is scripts/lib/cic/cic.sh -v <file>. If instructions are programs, they deserve a compiler.