series
Skill2 starsChanged 25 days agoApache-2.0View on GitHub
Load for any series-layer workflow: linking a book to a library, bootstrap and retcon lifecycle, the retcon detection catalog, the do-not-re-explain register, handoff generation, and the series state card. Owns the `library` subcommand dispatch surface (§8) and is the operator's manual for the series layer. Does NOT add a fourth gate; findings are advisory-only.
In this repository33 other files it gives its agents.
- character-simSkill
- cold-readSkill
- creative-researchSkill
- creative-writing-craftSkill
- creative-writing-modesSkill
- creative-writing-museSkill
- demolitionSkill
- exportSkill
- gatesSkill
- grill-with-docsSkill
- information-hierarchySkill
- intent-modelingSkill
- kb-integritySkill
- kb-managementSkill
- knowledge-layersSkill
- llm-writingSkill
- md-validationSkill
- project-setupSkill
- qi-layerSkill
- reader-simSkill
- reflectSkill
- series-bibleSkill
- shared-daoSkill
- story-ledgersSkill
- story-memorySkill
- story-planningSkill
- story-reviewSkill
- structured-artifactSkill
- style-guardrailsSkill
- voiceSkill
- writing-principlesSkill
- writing-staffingSkill
- zoom-outSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 72
All subcommands accept --root <library-root>.
- Very specific: line 113
All canon truth for a field is the explicit by-book map in series/bible.json.
- Distinctive: line 210
Verify compatibility: run the full v0.1.1 command surface against the book.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Vellum: Series
The series skill is the operator's manual for the library / series layer (vellum v0.2.0). It owns:
- The
librarysubcommand dispatch — what each subcommand does, when to run it, exit codes, and the contracts in §8. - The retcon lifecycle — plan → author approval (verbatim words) →
per-row
retcon --applytransactions. - The §10 detection catalog — load
references/checks.mdfor the agent-facing copy of every check code. - The do-not-re-explain register and the series state card (§8.8).
- Handoff generation for the next book in the series.
It does not load any new gate logic. The three hard gates are unchanged
(see /gates). Findings from library retcon-check are informational,
never blockers — exit codes are 0/1/2 as documented in §8, never a gate
exit.
When to load this skill
- Author or muse — linking a book to a library, bootstrapping canon, planning or applying retcons, generating handoff for the next book, reading the series state card.
@kb-lead— when a book is linked, series capture and retcon application are routed through the library commands, not through direct kb/ edits to canon. The book kb entity frontmatter may carry an opt-inseries-id:line (join key); canon truth lives inseries/bible.jsononly.@continuity-checker— when a book is linked, runlibrary retcon-checkas the series companion tovellum ledger check; the book-local commands are unchanged in contract.
How it fits the project
The series layer is an optional library root outside every book project.
A vellum project without a linked library is byte-identical to v0.1.1 — no
sidecar, no schema bump, no kb/story.md edit. See the project-setup skill
for the link/bootstrap/unlink migration path for existing projects (including
CARTE2).
<library-root>/ # created by library init; never inside a book
library.json # manifest — engine-written only
series/
bible.json # series canon — single source of truth
retcons.jsonl # append-only retcon audit log
exemptions.json # series-scope dismissals (engine-written)
errata.md # printed-vs-canon decisions (human-owned)
reports/ # generated retcon plans
handoff/ # generated handoff docs
.lock # advisory lockfile
<book-root>/ # unchanged by the link; inert additions only
.vellum/
series-link.json # inert pointer sidecar (regenerated by validate)
kb/<entities>/*.md # optional series-id: line in entity frontmatterSubcommand quick reference
All subcommands accept --root <library-root>; if omitted the command
refuses (no walk-up discovery, spec 8). Running from the library root
confers nothing — --root is always mandatory (only library init also
accepts the positional <library-root> form documented in spec 8.1, e.g.
library init ./<library-name>). Exit codes: 0 success · 1
findings/artifact produced · 2 usage or schema error.
| Subcommand | What it does | When |
library init <library-root> | Creates the empty library tree + manifest. Refuses if the target contains kb/, manuscript/, or state/ (exit 2). | One-time, outside any book project. |
library link <book-root> | Writes .vellum/series-link.json sidecar first, then adds the books[] entry to the manifest. Generates a book_uuid stored in manifest + sidecar only — never in kb/story.md. Idempotent-completing: if the sidecar exists but the manifest entry is missing, re-running completes. | After init, once per book. |
library unlink <book-root> | Marks unlinked_at in manifest; canon entries retained (orphan-book semantics). Regenerates or removes the sidecar. Emits series:orphan-book-ref advisories. | When detaching a book; full uninstall = unlink all books then delete library root. |
library validate | Read-only. Checks half-linked states, path resolution, manifest + bible JSON schema conformance (unknown keys rejected, exit 2), established-in coordinate resolution, series-id: frontmatter resolution, errata retcon refs, engine-version lag. --fix regenerates stale sidecars and rewrites counters only. Orphan-sidecar detection covers the manifest's own books, sidecars passed as explicit positional book roots, and sidecar-carrying books that are direct siblings of the library root — a linked book living elsewhere that lost its manifest entry is only flagged when passed as a positional argument (there is no filesystem walk-up, spec 1.4). | After any library-side change; before retcon-check or bootstrap. |
library bootstrap <book-root> | Deterministic diff of a linked book's kb against series/bible.json. Three match tiers: exact (auto-join), alias (auto-join + advisory series:id-mismatch), [?] (ambiguity row — writes nothing, human resolution required). --plan writes a report; --apply refuses unless the plan frontmatter carries approved: true plus the author's verbatim resolution notes for each [?] row. Matching runs on frontmatter fields and kb entity names only — never on chapter prose. | After link, to establish starting canon for the book. |
library retcon-check <book-root> | Runs the §10 detection catalog deterministically. Emits findings to stdout using the shared finding schema without a version bump (additive optional fields book, series_scope: true). Judgment-flagged rows are never engine-resolved; they are emitted with resolution: judgment and routed to muse/kb-lead. | After every chapter acceptance in a linked book; before export. |
library retcon-plan <book-root> | Produces reports/retcon-plan-<ts>.md from templates/retcon-plan.md: one row per divergence, with old_by_book, new_by_book (author fills), coordinate, and free-text author_words field. | When retcon-check surfaces divergences the author wants to resolve. |
library retcon --apply <plan-file> | Refuses unless the plan frontmatter is approved: true and every row has non-empty author_words. Each applied row is one retcon transaction: acquire lock → append JSONL row → merge the supplied new_by_book entries onto the existing by-book map (omitted ordinals are preserved) → bump next_retcon_id → flush matching stale exemptions.json entries → release. A row that changes a published or archived ordinal also requires override_published: true in the plan frontmatter. Partial-apply on crash is recovered by library validate. | After author approves a plan. |
library state <book-root> | Prints the series state card (hard-capped at 12 KB, fixed sections). Injected into the existing vellum state output when a book is linked — not a separate command. | Every session start (via the session-start hook) and on demand. |
library timeline | Read-only. Emits the E### events table sorted by when (ISO-8601, structured — not prose-parsed). Unparseable when is flagged. Events are minted only through retcon --apply rows of kind: established-before (which require an explicit coordinate); bootstrap never ingests kb timeline tables. | On demand; after a retcon that adds timeline events. |
library handoff <book-root> | Generates handoff/handoff-<ordinal>.md for the next book: frozen canon snapshot, iron facts, do-not-re-explain register, open retcons, errata posture. Read-only w.r.t. bible. | Before starting the next book in the series. |
library dismiss <finding-id> --reason "<author words>" | Records a series-scope dismissal in series/exemptions.json. Refuses if author words are empty. Marks expires_on_entity_hash for entity-bound findings. For a per-chapter finding that is intentional for the whole series (e.g. a recurring apparition of a deceased character), dismiss the wildcard form series:deceased-as-of-start:<series-id>:* once instead of once per chapter. | When the author confirms a series finding is intentional. |
The retcon lifecycle
Retcons flow through three stages. The engine does classification, never invention; the author's words are recorded verbatim and never edited.
- Detect —
library retcon-checkemits findings. Deterministic rows are reproducible; judgment rows go to muse/kb-lead. - Plan —
library retcon-planproduces a markdown report. The author fillsnew_by_bookandauthor_wordsfor each row. Setapproved: truein frontmatter only after author review. - Apply —
library retcon --apply <plan-file>applies each row as a separate transaction. Per-row, not one mega-transaction. Against apublishedbook, the default proposal isretcon record required(draft loses, canon frozen); the author must explicitly approve a change to frozen canon, and the row is markedkind: errataif it touches published-canon wording.
Canonical truth: by-book maps
All canon truth for a field is the explicit by-book map in
series/bible.json. There is no log-walk effective-at-N, no ambiguity
when two retcons share a from_book, no ordinal-order dependency. The
effective value at ordinal N for any by-book field is:
value = bible.entities[<id>].fields[<field>].by-book.get(str(N),
bible.entities[<id>].fields[<field>].value)The by-book map is authored by library retcon --apply and library
bootstrap --apply; it is never reconstructed. The retcon log
(series/retcons.jsonl) is the audit trail only.
Freeze doctrine — book status semantics
library.json per-book status ∈ draft | published | archived.
- published — canon is frozen.
retcon --applyrefuses rows proposed against a published book unless the plan frontmatter carriesapproved: truewithoverride_published: true(explicit author override for published canon). The same override is required for any row whosenew_by_bookchanges a value pinned to a published or archived ordinal, even when the plan itself belongs to a draft book. The default merge behavior against published fiction isretcon record required(draft loses), never later-wins. - draft — retcon proposals are expected;
retcon-planproduces them freely;retcon --applyaccepts an approved plan with author words. - archived — treated as frozen for writes (no new canon rows) but exempt from all divergence and history findings — fully quiet.
Frozen books never get their own kb silently edited by the layer. library
bootstrap --apply does not touch published bibles unless it is a new
ordinal being linked for the first time (bootstrap for a newly linked
published book is allowed to establish its starting canon, but does not
change already-pinned by-book values from an earlier ordinal).
Exemptions — series scope
Series-scope dismissals live and die in series/exemptions.json. They are
never written to a book's kb/exemptions.json. This preserves the
book/library boundary.
- Each dismissal targets exactly one finding id (precise key), not a whole
entity. An explicit wildcard form,
series:<code>:<series-id>:*, is accepted for findings whose key embeds a per-chapter coordinate: it suppresses every sub-key of that code+entity for the life of the series (the spec 10 #1 exempt list — "the apparition is intentional"). A wildcard is a standing entry recorded without an entity hash;retcon --applyflushes it when a retcon changes that entity's canon, so the author re-decides against the new canon. expires_on_entity_hashbinds the dismissal to the book kb entity'sentity_hashat the moment of dismissal. If the author edits that kb entity directly, the hash changes → the dismissal is stale and the finding re-fires. This applies to all series exemptions equally.- Existing
kb/exemptions.jsondismissals whose entities later enter series scope are not auto-migrated. They stay book-scope. On firstlibrary retcon-checkof a newly linked book, series findings start undismissed; the author dismisses them fresh in the library. library dismissrequires the reason in the author's own words.
The do-not-re-explain register
The series state card (§8.8, section 2) carries one line per scope:
shared fact with established-in ordinal < current book:
Established before this book — do not re-explain.
This is a reader-facing register, not a prohibition on referencing. It tells the author what the series has already committed to and what the next book's reader already knows. Use it when planning chapters and when the muse routes capture work.
Errata — printed-vs-canon posture
For published books, reader-facing decisions about printed-vs-canon are
recorded once in series/errata.md (human-owned, never engine-written).
library validate only checks that every R### referenced exists in
retcons.jsonl. This is the single recorded place for the posture
decision, not something re-derived per check.
Existing projects (CARTE2 and others)
Migration is zero-downtime and reversible. The book remains a valid v0.1.1 project throughout.
- Create the library outside the book project:
cd <some dir not inside the book> && library init ./<library-name>(Refused if run inside the book project — exit 2.) - Link the book (no story.md edit, no schema bump):
cd <library> && library link <abs path to book>Generatesbook_uuidin manifest +.vellum/series-link.json. - Bootstrap (deterministic capture):
library bootstrap <book-root> --plan→ review the report; resolve[?]rows with the author's words;library bootstrap <book-root> --applywritesseries-id:only to resolved entities and seedsby-bookmaps. - Verify compatibility: run the full v0.1.1 command surface against the book; the series layer does not change any v0.1.1 output.
- Second book: repeat link + bootstrap for the new ordinal;
retcon --applyof cross-book retcons addsby-bookentries for the new ordinal; old book'sby-bookvalues are frozen if its status ispublished. - Uninstall if needed:
library unlink <book-root>per book; delete the library root. Removes sidecar; leaves inertseries-id:lines in kb (harmless to v0.1.1).vellum statereverts to byte-identical v0.1.1.
Skill cross-references
/story-ledgers— the optionalseries-id:line in entity frontmatter is an opt-in join key (absent = entity invisible to the layer). No change to ledger file schemas./kb-integrity— when a book is linked,library retcon-checkandlibrary stateare the series companions; the book-local commands are unchanged in contract./gates— the series layer does not add a fourth gate. Findings are advisory-only./kb-management— canon truth lives inseries/bible.json; book kb files carry only the opt-inseries-id:join key./series-bible— the data-dialect reference: bible/manifest/retcon/ exemption schemas, field encodings (valuevsby-book,iron), coordinate conventions, effective-at-N resolution, and how kb maintenance maps onto series canon./story-planning— plan chapters with the do-not-re-explain register and the series state card in context.
Plan approval
library bootstrap --apply and library retcon --apply refuse unless the
plan file frontmatter carries approved: true. For bootstrap, the author's
verbatim resolution notes for each [?] row are also required. For retcon,
every row must have non-empty author_words (verbatim, recorded to the
retcon log). Plans are generated by the engine; approval is the author's
step. Never set approved: true without the author's explicit word.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

