@panaversity/ksor 0.0.1 → 0.0.3

package/templates/scaffold/.agents/skills/intake-interview/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: intake-interview
+description: The first conversation with the owner of this Knowledge System of Record — six questions that define what it is authoritative for and who may read it, then write instance.md together. Use when the owner asks to set up, configure, or "get started with" this project, when instance.md still contains its scaffold placeholder text, or when the scope of the corpus is unclear.
+metadata:
+  version: "1.2.0"
+---
+
+# Intake interview
+
+`instance.md` is the identity of this Knowledge System of Record, and its
+prose will one day be the agent surface's system prompt. Do not draft it from
+guesses — interview the owner, one question at a time, and write down what
+they actually say.
+
+## The six questions
+
+Ask these one at a time; follow up until each answer is concrete enough to
+act on:
+
+1. **Authority** — "What should this record be the _final word_ on? Finish
+   the sentence: when someone here disagrees with this corpus, the corpus
+   wins about ___."
+2. **Boundary** — "What is explicitly _outside_ it — near-miss topics people
+   will ask about that this record should refuse rather than guess at?"
+3. **Audience** — "Who reads it — people, agents, both? In what situations,
+   making what decisions?"
+4. **Sources** — "Which existing materials are authoritative inputs (name
+   the actual documents, systems, people), and which are explicitly _not_
+   trusted?"
+5. **Strictness** — "When the record doesn't cover a question, how firmly
+   should it decline? ('Not in this corpus' is a correct answer here —
+   confirm the owner wants that behavior and where they want it softened.)"
+6. **Audiences** — "Does every reader of this record see every document? If
+   not, what are the audiences, from most public to most restricted?" A yes
+   is the common answer and the whole answer: write no `audiences:` key and
+   nothing about the project changes. A list means writing it into
+   `instance.md`'s frontmatter — ordered least- to most-restricted with
+   `public` first, plus `default_visibility:` naming the audience a document
+   takes when it says nothing (there is no safe guess, so the checker
+   requires it). Tell the owner what the key does and does not do:
+   documents carry `visibility:` and builds are made per audience, but
+   anyone who can clone the repository reads everything in it — if someone
+   must not read a document and can clone, that document belongs in a
+   different repository.
+
+## Then write
+
+- Rewrite `instance.md`'s body from the answers: first the `# H1` — the
+  record's **display title**, the human name every page will lead with
+  ("Acme Operations Handbook", not the slug) — then the authority sentence,
+  boundary, audience, and strictness — plain prose, written for a reader
+  who must act on it. Leave the frontmatter keys alone, with one exception:
+  an audience model from question 6 is written there as `audiences:` (a
+  list) and `default_visibility:`, and `pnpm check` will hold the record to
+  it from that moment on.
+- Restart `pnpm dev` afterwards so the site picks the new title up, and
+  show the owner their name on the page.
+- Offer to capture the source list from question 4 as the first real
+  documents (the add-sources skill takes it from there).
+- Read the result back to the owner and get an explicit yes before
+  finishing. Their words, tightened — never your invention.

package/templates/scaffold/.claude/skills/add-sources/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: add-sources
+description: Turn source material — documents, pages, pasted text, notes — into governed knowledge in knowledge/. Use when the owner shares material to add, says "add this to the knowledge base", or asks how to get existing content in. Not for editing the site.
+metadata:
+  version: "1.2.0"
+---
+
+# Add sources
+
+Converting material into the record is the everyday work of this project.
+The rules that make it _governed_ rather than merely stored:
+
+## Placement and shape
+
+- One document per topic, under `knowledge/`, path = identity: lowercase,
+  hyphens, a folder per natural grouping. Plain CommonMark `.md` — if the
+  source is rich (tables, images), tables become markdown tables and images
+  land _beside the document_ with relative links.
+- A folder's front page is `<folder>/index.md`; reading order is the
+  `order:` frontmatter key (ordered documents first, ascending; the rest
+  follow alphabetically) — never `meta.json` or `sidebar_position`.
+- Frontmatter: `title` and `status: draft` always; add `owner` (who stands
+  behind this content) and `provenance` (a list naming the actual sources —
+  file names, systems, people, dates) whenever the owner can tell you.
+  Precision matters: "Finance policy manual §4.2, 2025 edition" governs;
+  "internal docs" does not.
+- When `instance.md` declares `audiences:`, ask the owner which audience the
+  new material belongs to and write it as `visibility:` — never guess that
+  restricted material is public.
+
+## Fidelity rules
+
+- **Copy load-bearing values exactly** — numbers, thresholds, dates, names.
+  Never round, never paraphrase a figure.
+- **Two disagreeing sources stay two statements**, each with its provenance
+  — never smooth a conflict into one invented truth; flag it to the owner.
+- **Do not fill gaps from general knowledge.** If the source doesn't cover
+  something, the record doesn't either — that boundary is the product.
+- A document replacing an older one: mark the old one `status: superseded`
+  with `superseded_by:` pointing at the new — never delete it.
+
+## Finish every batch
+
+Run `pnpm check` and fix what it reports (its errors explain themselves),
+then show the owner the rendered result (`pnpm dev`) — the site is the
+review surface: you write, they check.

package/templates/scaffold/.claude/skills/format-checker/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: format-checker
+description: The record's format rules as a runnable check — frontmatter, filenames, links, structure. Use before handing off any change to knowledge/, when a check fails and you need to fix it, or when unsure whether a document is well-formed. Run with `pnpm check` (or node .agents/skills/format-checker/check.mjs).
+metadata:
+  version: "1.2.0"
+---
+
+# Format checker
+
+`pnpm check` runs `check.mjs` — dependency-free Node, owned by this repo. It
+enforces what AGENTS.md states in prose:
+
+- `knowledge/` holds CommonMark `.md` and images only — no `.mdx`, no
+  `meta.json`, no other file types — and it is never empty; a record with no
+  documents stands behind nothing.
+- Every document carries `title` + `status` (level-0 requirement); the full
+  allowed key set is closed; a `superseded` document names a `superseded_by`
+  that resolves to a document that exists.
+- Filenames are portable identities: lowercase, Windows-safe, no spaces, no
+  case-collisions, no `foo.md` + `foo/index.md` pairs, no parentheses.
+  (`.DS_Store` and friends are skipped, never reported.)
+- Relative links resolve and never leave `knowledge/` — inline,
+  `<angle-bracketed>`, and reference-style (`[text][label]` with its
+  `[label]: target` definition) alike. Links inside code spans and fenced
+  blocks are code, not links, and are ignored.
+- `instance.md` exists, is `format: 1`, and carries only the keys the format
+  defines — an unknown key is named, never ignored.
+- The audience model, when there is one: `audiences:` is ordered least- to
+  most-restricted with `public` first, no duplicates, and never without
+  `default_visibility:`; a document's `visibility:` names one of the declared
+  audiences; and no link or `superseded_by:` points from a wider audience at a
+  narrower one — the leak no single build can catch, since the build that
+  publishes the pointer has already dropped its target. A record that declares
+  no `audiences:` is checked exactly as it was before the key existed.
+- `CLAUDE.md` stays a one-line pointer; `.agents/skills/` and
+  `.claude/skills/` hold the same files byte for byte **in both directions**
+  (a file only one tree carries is a rule nobody reviewed); the site contains
+  no content files.
+
+Every failure prints what is wrong, why the rule exists, and the fix — obey
+the printed fix literally; if it doesn't resolve the problem, that is a bug
+worth reporting to ksor.
+
+When you edit any skill under `.agents/skills/`, re-copy it to
+`.claude/skills/` — the checker holds the two trees identical, and it now
+notices a file added on either side.