agentleFS
FiredMosquito831FiredMosquito831/my-writing-companion/skills/series/SKILL.md

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.

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
  1. Very specific:

    All subcommands accept --root <library-root>.

    line 72
  2. Very specific:

    All canon truth for a field is the explicit by-book map in series/bible.json.

    line 113
  3. Distinctive:

    Verify compatibility: run the full v0.1.1 command surface against the book.

    line 210

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Vellum: Series

The series skill is the operator's manual for the library / series layer (vellum v0.2.0). It owns:

  • The library subcommand 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 --apply transactions.
  • The §10 detection catalog — load references/checks.md for 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-in series-id: line (join key); canon truth lives in series/bible.json only.
  • @continuity-checker — when a book is linked, run library retcon-check as the series companion to vellum 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 frontmatter

Subcommand 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.

SubcommandWhat it doesWhen
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 validateRead-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 timelineRead-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.

  1. Detect — library retcon-check emits findings. Deterministic rows are reproducible; judgment rows go to muse/kb-lead.
  2. Plan — library retcon-plan produces a markdown report. The author fills new_by_book and author_words for each row. Set approved: true in frontmatter only after author review.
  3. Apply — library retcon --apply <plan-file> applies each row as a separate transaction. Per-row, not one mega-transaction. Against a published book, the default proposal is retcon record required (draft loses, canon frozen); the author must explicitly approve a change to frozen canon, and the row is marked kind: errata if 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 --apply refuses rows proposed against a published book unless the plan frontmatter carries approved: true with override_published: true (explicit author override for published canon). The same override is required for any row whose new_by_book changes 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 is retcon record required (draft loses), never later-wins.
  • draft — retcon proposals are expected; retcon-plan produces them freely; retcon --apply accepts 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 --apply flushes it when a retcon changes that entity's canon, so the author re-decides against the new canon.
  • expires_on_entity_hash binds the dismissal to the book kb entity's entity_hash at 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.json dismissals whose entities later enter series scope are not auto-migrated. They stay book-scope. On first library retcon-check of a newly linked book, series findings start undismissed; the author dismisses them fresh in the library.
  • library dismiss requires 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.

  1. 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.)
  2. Link the book (no story.md edit, no schema bump): cd <library> && library link <abs path to book> Generates book_uuid in manifest + .vellum/series-link.json.
  3. Bootstrap (deterministic capture): library bootstrap <book-root> --plan → review the report; resolve [?] rows with the author's words; library bootstrap <book-root> --apply writes series-id: only to resolved entities and seeds by-book maps.
  4. Verify compatibility: run the full v0.1.1 command surface against the book; the series layer does not change any v0.1.1 output.
  5. Second book: repeat link + bootstrap for the new ordinal; retcon --apply of cross-book retcons adds by-book entries for the new ordinal; old book's by-book values are frozen if its status is published.
  6. Uninstall if needed: library unlink <book-root> per book; delete the library root. Removes sidecar; leaves inert series-id: lines in kb (harmless to v0.1.1). vellum state reverts to byte-identical v0.1.1.

Skill cross-references

  • /story-ledgers — the optional series-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-check and library state are 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 in series/bible.json; book kb files carry only the opt-in series-id: join key.
  • /series-bible — the data-dialect reference: bible/manifest/retcon/ exemption schemas, field encodings (value vs by-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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.