tome.yaml draft-01: open questions, asking people who have shipped manifest specs

[olijboyd]

We are drafting tome.yaml, a manifest for bundling AI instruction files (CLAUDE.md, AGENTS.md, .cursorrules, SKILL.md skills) into one portable unit with a lockfile and a security block. It sits a layer above AGENTS.md: AGENTS.md is one file for one tool, tome.yaml declares the bundle and the formats to render it into. We are not trying to replace AGENTS.md or compete with the Agent Rules work; this is the layer up.

We have shipped this on exactly one real bundle so far, our own (this repo), and we are about to ship it on more. Before we lock draft-01 we want input from people who have shipped systems shaped like this in production, because theory is not telling us where it breaks.

Spec: https://tomevault.io/docs/tome-yaml

Four things we cannot answer from theory. Answer any one that matches something you have actually shipped; two sentences of real experience is worth more to us than a long opinion.

1. Portability tier. We are adding a per-component flag marking whether a bundled instruction file is portable to any project or assumes our specific setup (hardcoded paths, internal scripts). Has anyone shipped a per-component portability or scope flag that authors did not simply game by marking everything portable? If you kept the labels honest, what did it: lint, scoring, gating, social pressure, or nothing?

2. Open format enum. Our manifest declares render targets by a format string, left as an open enum so we are not the bottleneck every time a new AI tool ships a new file format. If you maintain a plugin system with an open name field, when did the first divergent-semantics-under-one-name collision actually happen, and what did it cost to fix after the fact versus reserving the namespace on day one?

3. Cross-bundle composition. Right now a bundle cannot depend on another bundle. We deferred it deliberately, to watch real authoring first. If you have shipped manifest-level dependencies (Helm subcharts, Cargo, Bundler, Terraform modules), what was the moment in production you realised your first dependency primitive was wrong, and which way did it bite: too permissive, or too restrictive?

4. Strict security default. Our manifest has a security block: declare what the bundle is allowed to do (read files, network, exec, secrets), deny by default, omit the block entirely and you get deny-all. For anyone who shipped a deny-by-default permissions model (Deno, OPA, a plugin sandbox): did the strict default hold, or did adoption pressure quietly erode it? What kept declarations honest rather than reflexive?

Replies here, or on any thread we have linked from this one, all land in the same place. We will summarise what we change and why, and credit anyone whose input we ship.

[caioribeiroclw-pixel]

Small data point from building/shipping a context/rules sync package (pluribus-context) and running into the same class of problems: I’d avoid treating any of these as author-declared truth. Make them claims that can be falsified by tooling.

1. Portability tier

The label that survives contact with authors is not portable: true; it is something closer to:

portability:
  tier: universal | portable-with-adapters | project-local
  tested_on:
    - claude-code
    - cursor
  required_capabilities:
    - file.read
    - file.write.overwrite
    - shell.exec.git
  project_assumptions:
    - path: justfile
      required: false
  known_lossy_targets:
    - target: claude-ai
      reason: target file tool has different overwrite semantics
  evidence:
    smoke: .tome/smoke/decision-memo.yml
    last_verified: 2026-05-18

Two things keep it honest:

• A static lint that can say “this is project-local” without failing the bundle: absolute paths, repo-specific scripts, internal product names, unscoped env vars, tool names, and destructive semantics are all portability evidence.
• A tiny smoke per claimed target/capability. The assertion should be “the expected capability existed and was used with compatible semantics”, not “the model produced plausible prose”.

The social trick is to make project-local a respected label. If authors feel punished for honesty, they will mark everything universal.

2. Open format enum

I would reserve a namespace before you need it. The collision is usually not name spelling; it is divergent semantics under the same friendly name. Example shape:

format: cursor-rules
format_version: cursor-rules@2026-05
capability_profile: cursor-rules/scoped-mdc-v1
renderer: tomevault/cursor-rules@0.1.0

Open enum is fine, but I’d pair it with a capability/fidelity report. Unknown renderers can skip, but they should not silently imply equivalence. “Rendered, but lost path scoping / alwaysApply / overwrite semantics / tool access semantics” is much more valuable than success/fail.

3. Cross-bundle composition

The first primitive I’d keep very boring:

• exact source + ref + digest in lockfile;
• local/cache render is deterministic and offline by default;
• explicit precedence order (base -> imported bundle -> local override);
• no transitive remote fetch during normal render;
• include graph visible in dry-run.

The mistake I’d avoid in draft-01 is making dependencies feel like package-manager dependencies too early. For AI instruction bundles, semantic override and authority matter more than install convenience. “Which bundle is allowed to define the release process?” is a more dangerous question than “can I fetch this markdown?”

4. Strict security default

Deny-by-default can hold if declarations are partly generated and diffable. If authors manually write permissions from scratch, adoption pressure tends to produce “just grant all”. A better workflow is:

1. scanner proposes permissions from observed content;
2. author accepts/narrows them;
3. lockfile records ruleset version + content digest + permission set;
4. CI/dry-run shows “this component now asks for network/exec/secrets” as a human-visible diff.

So the security block is not just policy; it is also review UX.

If I were narrowing draft-01, I’d optimize for three outputs: a portability lint report, a fidelity/loss report per target, and a lockfile diff that makes new authority/security claims obvious. That gives maintainers something concrete to review instead of trusting manifest prose.

[olijboyd]

This is really helpful, thanks for taking the time over it.

The thing that's stuck with me since reading it is making project-local a respected label instead of a fail. We'd been going round the "what stops everyone just marking everything universal" problem for a while without getting anywhere, and I think you've found why: we'd built it as a grade, so of course people game it. If project-local is just an honest description of a skill and nobody's penalised for using it, most of the incentive to lie goes away. That genuinely changes how we'd write that part of the spec.

Your point on composition did something similar for me. We'd been treating "can a bundle depend on another bundle" as a question of scope, and deferring it because we couldn't decide how far to let it reach. "Which bundle is allowed to define the release process" says the thing we were actually nervous about far better than we had. It isn't about fetching markdown, it's about authority, and we'd been arguing it at the wrong level.

There's one piece I can't size up yet though, and it's the per-target smoke test. It makes complete sense as the honest version, but its cost grows with every format and every component, and we render into a lot of formats, so when you did this for real I'd want to know how you kept it from getting out of hand: smoke every target, a representative few, or only the capabilities you'd already flagged as lossy. That's the part I genuinely don't have a feel for.

Anyway, this is exactly what the RFC was for. If we end up changing the spec off the back of it I'll come back here and say so, and credit you properly.