@panaversity/ksor 0.0.1 → 0.0.2

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

@@ -0,0 +1,46 @@
+---
+name: intake-interview
+description: The first conversation with the owner of this Knowledge System of Record — five questions that define what it is authoritative for, 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.1.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 five 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.)"
+
+## 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. Do not touch the frontmatter keys.
+- 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,43 @@
+---
+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.1.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.
+
+## 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,39 @@
+---
+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.1.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.
+- `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.