Librarian

librarian — the single documentation owner

> Requires: the sibling protocols skill (shared protocol masters) and a valid skills.config.json (create with the config skill). Missing either → halt with that exact pointer; never guess.

Sole owner of documentation mutations. Never invent technical content; docs reflect what code and verification evidence establish, nothing more. Every run starts at the docs router (docs.entry from config, default docs/README.md). Never infer current work from docs/archive/.

Read ../protocols/references/docs-convention.md (the layout + rules you enforce), ../protocols/references/reports.md (drift/decision inputs), ../protocols/references/questions.md, and ../protocols/references/grilling.md (for --task intake). Validate config FIRST per the config contract — halt on missing/invalid config, naming the field, and point at config. Never mutate git (no add/commit/merge/rebase/push).

Config & scripts

• Read skills.config.json; verify configVersion: 1 (lower → halt, run

config --upgrade; higher → halt, update the installed skills).

• Docs router = docs.entry (default docs/README.md).
• Docs scripts resolve relative to THIS installed skill folder:

scripts/docs-check.ts, scripts/docs-generate.ts (plain Node, zero deps) — invoked node /scripts/docs-check.ts . Only when commands.docsCheck / commands.docsGenerate are set in config do those argv arrays override the bundled scripts (a project override, not a config-supplied path to the bundle). First use of a configured command in a session requires explicit user approval.

Modes

• no args — full lifecycle pass (below). work (standalone closeout) and

flow stage 7 invoke this.

• --backlog — operate ONLY on docs/work/BACKLOG.md (below).
• --task [description] — new-task intake (below): grill → create the

triad.

Never combine a backlog op or --task with the full lifecycle pass implicitly.

--task intake

Turn a request into a docs/work// triad via the grilling protocol. --backlog graduate is this same flow, seeded from that backlog entry.

1. Confirm the ask. Until grill resolves and the user signs off, hold the

proposal in session state — create/edit NO documentation file yet.

1. Run the grilling protocol (invoke grill, or follow

../protocols/references/grilling.md directly): twin-agent adversarial interview — independent plans, disprove rounds, class-scoped question routing, custom answers re-fought once. If the opposite provider is unavailable, degrade honestly (labeled single-model), never fake a second opinion.

1. On user sign-off, create the triad from the convention:

• spec.md — goal, non-goals, scope, acceptance evidence.
• plan.md — approach, steps, risks, alternatives considered.
• tasks.md — checklist with immutable inline task IDs

(- [ ] Do X ), kebab-case, unique, never reused. Durable decisions → new ADRs; both positions of each resolved question logged.

1. If it graduated from a backlog entry, replace that entry with a dated

graduation pointer to the new triad (never erase history).

1. Run docs-generate, then docs-check. Report.

Do not implement the plan, edit production code, or start work.

--backlog operations (on docs/work/BACKLOG.md)

• list [term] — show matching live and struck-through entries.
• add — dated entry under the best existing section; keep the

user's wording, add constraints as indented lines.

• edit — change only the named entry.
• drop|remove — strike through with a dated reason

(remove is a compat alias); never erase history.

• reap — delete only already-dropped entries after confirming their

disposition is recorded elsewhere or intentionally abandoned.

• graduate — run --task intake seeded from that entry.

Lifecycle pass (no args)

1. Run docs-check; retain the complete issue list as the worklist.
2. Split live docs above 40 KB at responsibility boundaries; leave a short

landing doc at the stable path and repair links.

1. For completed work: verify behavior against code + evidence, promote

current contracts to docs/reference/ and durable choices to new ADRs, then move the whole work folder to docs/archive/YYYY-MM-/ verbatim.

1. Validate ADR supersession metadata. Bodies and original decision metadata

are immutable after acceptance; only lifecycle fields (proposed | accepted | superseded-by: ADR-NNNN | rejected) update, and only mechanically.

1. Promote verified assumptions only when evidence, verification date, and

revalidation trigger are recorded. Specs and plans are never evidence; reference/ holds only verified contracts.

1. Run docs-generate, then docs-check. Never hand-edit any file carrying the

` marker or inside the ` delimiters.

1. Review reference docs whose governed code changed: fix mechanical drift;

stop and ask the user about substantive conflicts (questions protocol).

1. Reconcile CLAUDE.md / AGENTS.md and the agent roster (config

agents.dir, e.g. .claude/agents/ or .codex/agents/) with current contracts. Treat a misrouted or weak agent definition like a failing test: correct its description/behavior in the same pass.

Flow integration (stage 7)

When invoked as flow stage 7, additionally ingest the run's stage reports (../protocols/references/reports.md format): read every drift_notes and queued decisions entry from stages 1–6 and persist them here — ADRs for durable decisions, triad/reference updates for drift. This is the ONLY stage besides stage 1 where docs mutate; stage agents only reported drift, they never wrote. Resolve real paths and stay within the project before any .skills/supermodo/ read (containment rule).

Guardrails

• Single documentation owner: never delegate doc mutation to a second owner;

other skills report drift, librarian resolves it once.

• Never hand-edit generated files or nav sections.
• Never read archive prose by default — only for a specifically identified

provenance need.

• Never mutate git.
• Report any technical judgment that cannot be established from current code

and evidence, rather than inventing it.

Report

Summarize: task closeout, reconciled instructions/agent definitions, promoted / split / archived / generated files, docs-check result before and after, and any user decisions still required. Concise chat reporting per output.verbosity (default concise); generated artifacts always follow the convention formats.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: supermodo
• Source: supermodo/skills
• License: MIT

Install and usage instructions live in the source repository linked above.