Skip to content

v1.36.0 ·

A pointer costs the file it lands on

The problem

The emitted .aidlc/skills/aidlc-overview.md is 24,564 bytes. It was 22,902 when the item was filed a week ago and 18.6KB a week before that. Skills send readers to it for one rule at a time — counted across packages/content/skills/:

  • The always-read rule — 12 cross-references, 1,556 bytes of rule
  • The context rule — 8 cross-references, 2,443 bytes
  • The constitution rule — 3 cross-references, 982 bytes
  • Creating an Instance — 3 cross-references, 2,998 bytes
  • Question Protocol — 3 cross-references, 3,790 bytes
  • Lifecycle or Skill? — 2 cross-references, 2,108 bytes

Following any one of them costs the whole 24.5KB. And on Cursor the overview is emitted with alwaysApply: true (line 86 of packages/cli/src/compile/adapters/cursor.ts), so there it is resident on every turn of every session — that is the user-facing cost, not only a lifecycle one.

How it could be solved

Three decisions, and the first one looked like a formatting question until it was measured.

The roadmap item suggested making each rule addressable inside the overview, since the cross-references already named sections like The context rule. That would have changed nothing. An agent following a pointer reads the file the pointer lands on, whole, so a heading inside a 24KB file still costs 24KB. The rules had to become files of their own. They go in .aidlc/resources/rules/, beside the question rendering file that set the precedent, and aidlc update writes and prunes them like every other framework-owned file.

The second was what the overview keeps. A short summary of each rule would have read nicely and been a second copy by another name, which is how the drift this project already paid for starts. So each moved section keeps its heading and one line: what the rule governs and where it lives. A test now fails if any sentence of a rule shows up in a skill, and it was checked the only way that counts, by pasting three lines of a rule back into the overview and watching it fail.

The third was how to measure it. The item warned against counting bytes on disk and suggested aidlc cost context. That reports one session's whole carry, and a fair comparison needs two fresh sessions doing the same work. What a cross-reference costs is the size of the file it lands on, so that is what the tests pin: the overview under 12,000 bytes, every rule under 4,500. The overview came out at 11,739, down from 24,564. On Cursor, where the overview is applied to every turn, that is the part a user feels.

How AIDLC solves it

The overview skill stops carrying the six rules other skills send readers to. Each one is now its own file, so following one cross-reference costs that rule instead of the whole overview.

  • Six rule files. aidlc init and aidlc update write .aidlc/resources/rules/ with always-read.md, constitution.md, context.md, creating-an-instance.md, lifecycle-or-skill.md and question-protocol.md. Each is marked framework-owned; a marked file the package stops shipping is removed on the next update, an unmarked one is left alone.
  • The overview is half the size. Emitted, it goes from 24,564 to 11,739 bytes. It keeps every heading, with one line per moved rule naming its file. On Cursor the overview is always applied, so that is also what every turn stops carrying.
  • Cross-references name the file. 31 of them across 14 skills. The most-cited one, the always-read rule (12 citations), now costs 1,643 bytes to follow instead of 24,564.
  • Still one copy of each rule. The text moved without being reworded, and a test fails if any sentence of a rule reappears in a skill.
  • The website overview page renders all six rules after the overview, read from the same files.

No state format or config key changes. The content package gains loadRules() and the Rule type — additive. Minor rather than patch because every installing project gets a new directory and a rewritten overview on aidlc update.