CEP Retrofit

Overview

Every CEP consumption contract (CONSUMING-CONTEXT-PACKAGE.md, CONSUMING-COMPILED-GUIDELINES.md, CONSUMING-CODE-GRAPH.md) already says it's meant to be "referenced by a one-line pointer from each consuming skill's SKILL.md/.prompt.md rather than copied into each one." That's cheap in principle. In practice, adding that pointer to an existing skill library — correctly, one skill at a time, in a format that matches the library's own conventions — takes someone who has read PROTOCOL.md and the relevant contract(s) end to end. For a library with a dozen or more skills, that friction is real, and it sits squarely between CEP and "every retrofitted library becomes a live adoption story for free."

This skill inventories an existing skill library — any shape, seen or unseen — asks a human which skills should consume which contract(s), then drafts the minimal pointer insertion, previews every change, and writes only what's confirmed. It invents no new consumption mechanism. It reuses the three CONSUMING-*.md contracts verbatim; if a real retrofit need doesn't map to any of them, that's a gap in CEP itself to raise separately (see "What this skill deliberately does not do").

The one hard rule: zero hardcoded knowledge of any specific library

This skill must run identically against a library it has never seen, in a format nobody has described to it yet, and against the author's own private skill collections. Concretely:

• No real library's name, skill name, or path fragment ever appears in this skill's own instructions, its helper script, or its tests — not even as "for example, in a library like...". Every example anywhere in this skill is a fabricated placeholder (example-skill/, widget-reviewer/).
• Detection heuristics are shape-based, with one narrow, documented exception: a small set of root-level filenames (AGENTS.md, README.md, etc. — a broadly used, cross-project convention, not any specific library's own name) are excluded by literal name, but only at the target root itself, never at any nested depth. "Does this directory contain a file matching SKILL.md/skill.md" is fine; "if the file is literally named X" for any real, private X is not.
• scripts/cep_retrofit.py owns every heuristic that can be made deterministic (inventory, description extraction, recommendation signals, idempotency checking, insertion-point detection) so those rules live in one tested place, not re-derived ad hoc per run. All ledger- style mechanical work goes through the script — never hand-roll a directory walk or a frontmatter regex inline. See the script's own module docstring for the exact subcommand surface.

Flow

Step 1 — Locate the target library

Ask for a path. Run cep_retrofit.py inventory <path> — if it errors because the path isn't a readable directory, say so concretely and re-ask. No default guessed silently: an unconfirmed guess about where someone's skill library lives is worse than just asking.

Step 2 — Inventory candidate skill units

cep_retrofit.py inventory <path> returns {"units": [...], "unclaimed_dirs": [...], "tier_counts": {...}} — the union of three shape-based heuristics (skill-directory, manifest-directory, flat-file), never a single winner, so a library mixing conventions (skill directories and flat prompt files coexisting as real siblings — this repo's own shape) doesn't silently lose one convention's files. Conventional generated/dependency/VCS directories are excluded by default; symlinked directories are inventoried one level deep with their real path recorded, never followed further. Each unit also carries a tier ("canonical" for a real skill-dir/manifest-dir marker, "supplementary" for a bare flat-file guess) and, for a supplementary unit sitting directly under a directory named docs, a note flagging that weaker signal — group/filter by tier rather than treating every unit as equally confident.

If unclaimed_dirs is non-empty, show it to the human and ask how a "skill" is delimited for those directories — don't guess a fourth heuristic. Always show the full resulting inventory (units plus any human-clarified additions) and get explicit confirmation/correction before continuing. Never silently commit to a possibly-wrong or incomplete parse of an unfamiliar library.

Step 3 — Summarize each candidate

For each confirmed unit, run cep_retrofit.py describe <primary_file> to get {"name", "description"} (frontmatter field → first heading + paragraph → first non-blank line, in that order). Present the confirmed inventory as a numbered list of name + one-line description.

Step 4 — Ask which skills to retrofit, and with which contract(s)

Per confirmed skill, run cep_retrofit.py recommend --description "<extracted description>" to get {"code_related": bool, "task_related": bool, "matched_code_terms": [...], "matched_task_terms": [...]}. This is a signal, not a decision.

On Windows/PowerShell (or any shell, if the description hasn't been visually confirmed quote-free), prefer cep_retrofit.py recommend --description-file <path> instead: write the extracted description to a temp file and pass its path. A description containing embedded double quotes (e.g. asks to "review since X") can be silently mangled or truncated by PowerShell's argument quoting before the script ever sees it, producing a false "neither" classification with no error — confirmed for real against a third-party library, where two real skills' descriptions both contained embedded quotes. --description and --description-file are mutually exclusive. Turn it into a recommendation grounded directly in each contract's own stated trigger, since CONSUMING-COMPILED-GUIDELINES.md and CONSUMING-CODE-GRAPH.md open with the identical literal sentence about their own scope (they are not mutually exclusive with each other):

• code_related: true → recommend both CONSUMING-COMPILED-GUIDELINES.md and CONSUMING-CODE-GRAPH.md.
• task_related: true → recommend CONSUMING-CONTEXT-PACKAGE.md.
• Neither true → present all three with no default recommendation; let the human choose freely, including "none."

Either way it's recommendation only — the human picks the final answer per skill: accept, override, add/drop contracts, or none. Most substantive dev-facing skills will end up with two or three recommended contracts at once; that's expected, not a bug in the heuristic. This mirrors trip-wire's own tier-is-a-recommendation-never-an-autoapply pattern (PROTOCOL.md §7): the matching step is deterministic and mechanical, the judgment call stays human.

Step 5 — Resolve where CEP itself lives relative to the target library

The pointer written into each retrofitted file needs a real, resolvable reference, and its shape depends on the answer — ask, don't assume. v1 scope is deliberately narrow, to the two cases with real precedent elsewhere in this repo's own conventions:

• Same repo as the target library → a relative path.
• Installed as a plugin (mirrors the claude-plugin/ manifest convention already shipped here) → the plugin-qualified reference (/context-engineering-protocol:ult-context-generate style).

For a target library that vendors CEP at a subpath, or references it from an entirely separate location with no vendoring — ask for a stable reference the human is confident will keep resolving; if none exists yet, say so and skip that skill rather than write a pointer already known to be dead on arrival. Cross-repo referencing into a CONSUMING-*.md contract isn't something PROTOCOL.md itself defines today for that harder case — treat it as a real open protocol question worth raising on its own, not something to quietly settle here.

Step 6 — Draft the insertion, per confirmed skill

Combine every contract confirmed for a given skill in Step 4 into one pass, not one pass per contract:

1. Idempotency check first, by contract identity: run cep_retrofit.py check-pointer <file> --contracts <comma-separated contract filenames>. It matches on the bare contract filename appearing anywhere in the text — a same-repo relative path today and a plugin-qualified reference tomorrow both count as "already has this pointer," so a later re-run under a different reference shape doesn't duplicate it. Already present for a given contract → report "already retrofitted for <contract>," drop just that contract from this file's draft; any other newly-confirmed contract not yet present still proceeds.
2. Find the insertion point: run cep_retrofit.py find-insertion-point <file>. It checks, in order, an existing See Also/References/Related section, the end of YAML frontmatter, a heading that reads as overview/process content, then a "prepend near the top" fallback — always returning a method (find-insertion-point never declines outright), but the calling skill is still free to skip a file entirely if, for example, every confirmed contract for it is already idempotency-satisfied and nothing remains to insert.
3. Draft the text: a sentence or two per remaining contract plus the resolved path from Step 5 — not a copy of the contract's own content, matching the "referenced by pointer, not copied" principle the contracts already state about themselves. Write it to blend with the target file's own existing voice and structure, not CEP's — this skill is a guest in someone else's library.
4. If a given skill has multiple remaining contracts, insert them together as one combined block at one insertion point, in a fixed stable order (CONSUMING-CONTEXT-PACKAGE.md, then CONSUMING-COMPILED-GUIDELINES.md, then CONSUMING-CODE-GRAPH.md) — never as separate passes that could each compute a different insertion point and scatter pointers through the file.

Step 7 — Preview before writing

Show every drafted change as a diff, batched, before anything touches disk. Nothing is written until explicit confirmation. Human confirms per-file or in one batch, their choice.

Step 8 — Write confirmed changes, report a summary

Write only what was confirmed. Report: N retrofitted, M skipped (no confident insertion point / already retrofitted / declined by the human), and per-file which contract(s) each got. A write failure on one file is reported for that file and does not abort the rest of the batch.

Step 9 — Explicit non-actions

Doesn't commit, doesn't open a PR, doesn't validate that a retrofitted skill actually behaves correctly with CEP at runtime (that's the target skill's own subsequent real usage). If the target library is one the human doesn't own or maintain — a third-party collection without write access — that's a real possible misuse: flag it once, before Step 7's write, as a caution rather than a block.

What this skill deliberately does not do

• It never invents a new consumption mechanism. It reuses CONSUMING-CONTEXT-PACKAGE.md, CONSUMING-COMPILED-GUIDELINES.md, and CONSUMING-CODE-GRAPH.md verbatim. If a retrofit need genuinely doesn't map to any of the three — trip-wire's own institutional_memory_hits[] field is a known live example: CONSUMING-CONTEXT-PACKAGE.md's current field list doesn't instruct a consuming skill to read it yet, even though it rides inside the same package — that's a real gap in CEP itself, worth a separate explicit pass to close (either by extending CONSUMING-CONTEXT-PACKAGE.md's own field list, or by writing a dedicated CONSUMING-DECISION-LEDGER.md), not something this skill should paper over with bespoke logic.
• It never auto-applies a recommendation. Every inventory item, every contract match, every insertion point, and every write is human-confirmed. recommend's output is a signal, never a selection.
• It is not a validator. It doesn't check that a retrofit "worked" — that's the retrofitted skill's own subsequent real usage and test suite.
• It is not a general-purpose file-refactoring or codemod tool, and it doesn't lint or judge the target library's own conventions or quality beyond what's needed to place a pointer.
• It doesn't touch the target library's version control. Reads and writes plain files only — the human's own VCS workflow handles commits, same as every other skill in this repo.

When something doesn't fit the flow

If unclaimed_dirs from Step 2 turns out to be most of the library — a format this skill's three heuristics genuinely don't fit — say so plainly rather than forcing a match. Ask the human to describe their own convention once, apply it consistently for the rest of that run, and note in the Step 8 summary that this run used a human-supplied convention rather than the built-in heuristics, so a future re-run (which won't remember that conversation) is warned to ask again rather than silently guess.

If Step 5's reference resolution turns up a case this skill's v1 scope doesn't cover (CEP vendored at a subpath, or living in an entirely separate, unvendored location), don't invent a resolution — skip the affected skill(s), report why, and treat it as a real open protocol question rather than something this skill quietly settles on its own.