keep

name: keep description: "Living /knowledge layer for a code repo — specs, ADRs, ideas, with runbook and architecture as tags, and anchored facts that drift-detection verifies deterministically. CONSULT whenever the user asks how the system works, why a decision was made, what conventions exist, or whether a change is safe — even without naming KEEP. ALSO trigger on non-trivial changes that affect behavior/architecture/operations in a /knowledge-enabled repo, brownfield doc cordoning, parked ideas ('not now but', 'what if we'), pre-merge drift checks, and questions about anchor coverage. SKIP for generic programming Q&A, library docs, pure mechanical refactors, and repos without /knowledge."

KEEP — Knowledge Engine for Engineering Persistence

KEEP turns a code repository into a living knowledge graph an LLM agent both consults and maintains. Code is the execution layer; /knowledge/ is the memory layer; the agent is the reasoning layer. The skill is successful when a new contributor (human or agent) can answer how and why the system evolved without re-deriving everything from code, and when changes to code automatically surface as proposed changes to knowledge.

When to trigger

KEEP is failing if it triggers only on code changes. The read path — consulting knowledge when answering questions — is what compounds value.

Read — run /keep-ask first, before answering, on prompts like:

• "how does X work?", "why did we choose Y?", "what did we decide about Z?"
• "is there a convention for", "where does X live", "what happens when"
• "are we using X or Y?", "is there already something for", "is it safe to change"

The user is reaching for information that should be in /knowledge. Even if the answer is also in code, the knowledge layer has the why (rationale, rejected alternatives, edge cases) that code does not. Antipattern: answering from memory or grep.

Decision-grade cross-check. When the user is about to act on the answer (merge, deploy, debug-in-progress), /keep-ask consults /knowledge first then verifies anchored load-bearing claims against code — a spec can drift between merges, and the user deserves the warning before they act. Cues: "sto per mergeare", "is this still true", "safe to deploy?". See references/commands/keep-ask.md.

Write — run /keep-compile after non-trivial code changes in a /knowledge-enabled repo: new features, dependency/framework swaps, topology changes, post-incident fixes, runtime-affecting config changes.

Drift — run /keep-check-drift before merging, before declaring a task complete, or when the diff touches code referenced by any spec.

Idea — run /keep-idea when the user explicitly does NOT want to implement now: "not now but", "park this", "what if we", "come back to this later".

Skip for trivial edits, generic programming Q&A, and questions answered by a top-level README without touching architecture. When in doubt, lean toward triggering — under-triggering is the dominant failure mode.

Core principles

1. Memory, not narration. Capture rationale, edge cases, rejected alternatives, operational learnings. Skip walkthroughs that re-narrate the code.
2. Knowledge has a consumer and an enforcement mechanism, or it is a lie. Every file in /knowledge has YAML frontmatter so /keep-ask finds it, INDEX.md lists it, and /keep-check-drift matches anchors against code. Files without frontmatter are unverified artifacts.
3. Conservative compilation. Never invent intent. Stick to what the diff and existing docs support. The agent's compulsion to elaborate is the enemy of trustworthy knowledge.
4. Minimal diffs. Updates preserve human wording verbatim. Never rewrite whole files.
5. Ask before writing low-confidence content. A diff shows what, rarely why. For high-stakes fields the diff cannot establish (ADR rejected alternatives, spec edge cases, runbook root cause), stop and ask — structured multiple-choice or batch elicitation, see ## Asking the user below.

Repository structure

/knowledge
├── docs/
│   ├── specs/             ← what the system should do (per-domain subdirs)
│   │                        spec + tag:runbook       — failure modes / operational
│   │                        spec + tag:architecture  — topology / boundaries
│   └── decisions/         ← ADRs (flat, ADR-NNNN-slug.md)
├── ideas/                 ← half-formed proposals (status: draft → promoted or deprecated)
└── INDEX.md               ← auto-generated by scripts/build_index.py

Type vocabulary is deliberately small — spec, adr, idea. Runbooks and architecture docs are specs with a tag, not separate types. Execution state (work in progress) belongs in your ticket tracker; KEEP only stores durable knowledge.

Full frontmatter schema and templates per type: references/file_formats.md. Monorepo conventions: references/monorepo.md.

The seven commands

This table is the index, not the contract. Each command's full behavior — phases, hard rules, output format — lives in references/commands/<name>.md (bundled inside the skill, so it travels with skill-only installs as well as the full plugin); read the relevant one before executing a command. The skill body deliberately keeps only the two cross-cutting distinctions that span commands (below); everything command-specific is in the contracts. Behavior is identical whether the command is invoked as a slash command or in natural language.

<skill-path> convention. The contracts invoke scripts as <skill-path>/scripts/<name>.py. <skill-path> is the directory that contains this SKILL.md — resolve it from where you're reading the skill from, never hardcode it. KEEP is installed at different paths depending on the host (~/.claude/skills/keep, a plugin dir, or vendored into a repo as .agents/skills/keep), so a literal path like skills/KEEP/scripts/… only works inside the KEEP source repo and breaks everywhere else. The scripts locate their own siblings (_keep.py, coverage.py) internally, so they run correctly from any location once you invoke them with the right <skill-path>.

/keep-compile — pre-existing docs as source

When the source is a file or folder of pre-existing markdown (not a git diff), the agent never writes silently. It asks — with structured multiple-choice options and a safe default — whether to migrate or cordon. Folder default: cordon (one ADR declares the folder out of scope). Single-file default: cordon. When the user picks migrate, the agent runs a verify-and-curate pass against current code before writing. Full protocol in references/brownfield.md.

/keep-check-drift vs /keep-govern

Drift is correctness now on a specific diff (blocks merge). Govern is hygiene over time on the whole knowledge base (non-blocking). A file can pass drift but fail govern.

YAML frontmatter is mandatory

---
id: SPEC-auth-jwt
title: "JWT validation"
description: "Behavioral spec for JWT issuer/audience validation, expiry handling, and refresh flow on /auth/* endpoints"
status: accepted               # draft | accepted | deprecated | superseded
type: spec                     # spec | adr | idea
domain: auth
tags: [auth, jwt, security]    # 'runbook' and 'architecture' are reserved tags — specs only, never on ADRs/ideas; one role per spec, never both
related:
  - adr:ADR-0014
  - test:internal/auth/*_test.go matching TestJWT*
  - code:internal/auth/jwt.go
---

description is the most load-bearing field — it is the search snippet /keep-ask matches against. "Auth stuff" is bad; "Behavioral expectations for JWT validation: issuer/audience checks, expiry, secret rotation. Covers refresh flow and grace window." is good.

related uses convention-based references: test:internal/auth/*_test.go matching TestJWT* is a pattern, not a hard-coded list — so it survives renames.

Full schema, supersession protocol, anchor block: references/file_formats.md.

Anchors and coverage

A spec may declare an anchors: block — structured claims (kind: const | function | test | manual) that scripts/check_drift.py verifies deterministically against source. Anchoring is opt-in per spec; specs without anchors still work but sit outside the drift gate.

/keep-compile proposes anchor candidates from concrete values in the diff by default — anchor proposal is part of writing the spec, not an optional add-on. Rule: no anchor without evidence (only propose anchors for values present in the diff), not "no anchor at all".

scripts/coverage.py reports the silent KPI of a KEEP-enabled repo: what fraction of load-bearing code symbols are referenced by at least one anchor. The /keep dashboard surfaces the aggregate.

Why coverage stalls, and the loop that grows it. Anchors get proposed at spec-birth, from the values in one diff. That alone leaves coverage near zero forever: the diff that introduces a spec rarely touches every symbol the spec is about, and nothing revisits it afterward. Coverage only climbs if something periodically asks "what does the knowledge layer already claim to describe, but not enforce?" — and that gap has a precise, non-theater definition: a spec whose related: already points at a code file or test, where that symbol has no anchor. The spec asserts it matters; drift can't see it. Those are the high-value candidates, and they're load-bearing by construction — you are not inventing importance to bump a number, you are closing the gap between what a spec says it covers and what drift actually verifies. /keep-govern runs this check periodically and proposes anchoring them; the /keep dashboard surfaces it when coverage is low. Anchoring symbols no spec references would be the theater the rule against "no anchor without evidence" exists to prevent — don't.

Asking the user

Several KEEP flows need user input: /keep-init consent, migrate-vs-cordon for legacy docs, contradictions during migration, rejected-alternatives for new ADRs. Structured questions get fast decisive answers; open-ended ones get slow vague ones. Hierarchy:

1. Binary: yes/no with default marked. Scaffold /knowledge/? [y/N]
2. 2-4 named options: lettered list, one-line each, default marked. Accept the letter, the keyword, or natural language.
3. Granular in batch: one turn, multiple rows, same small action set per row. Accept shorthand like 1b 2a 3c. Cap ~5 rows per batch.
4. Free-form: only when the user's exact words are the value (ADR ## Context, idea body). Show a tentative draft alongside the question — "here's what I'd write from the diff alone — does this miss anything?" gets faster, better answers than "what's the context?".

For ADRs and new specs, default to batch mode: gather 2-3 correlated fields in one turn, then write in one pass. Cap at 3 questions per turn. If a commit message already contains explicit rationale ("switched from KServe because of CRD complexity"), quote it verbatim — don't re-ask. If the user declines to answer, omit the section and insert <!-- TODO(KEEP): ... --> for /keep-govern to surface later.

CI / pre-commit (recommended, not auto-installed)

/keep-check-drift is deterministic and CI-friendly — exit 1 blocks merge. It becomes a real enforcement gate only when wired into pre-commit or CI. KEEP does not install hooks or workflows itself (that's invasive). references/setup.md carries copy-paste templates; /keep-init mentions them once and lets the user opt in.

The standard workflow

First time on a repo:
  /keep                             dashboard. If /knowledge missing, points to /keep-init.
  /keep-init                        scaffold + install SPEC-000-keep + append AGENTS.md snippet (asks consent)
  /keep-compile ./docs/             agent asks: cordon the folder, or walk file-by-file?
  /keep-compile docs/auth/jwt.md    agent asks per file: migrate (with verification) or cordon?

Every session, before answering:
  /keep-ask <user's question>       MANDATORY on read triggers

Every code change worth keeping:
  /keep-compile                     classify + propose anchors + write + regen INDEX
  /keep-compile --dry               (or: preview without writing)

Before merge:
  /keep-check-drift                 deterministic gate (exit 1 blocks merge)

Capture without commitment:
  /keep-idea <user's thought>

Periodic:
  /keep                             dashboard / status check
  /keep-govern                      hygiene, weekly at most

AGENTS.md snippet — install in the repo

/keep-init (via scripts/init.sh) appends a KEEP snippet to whichever entry file exists at the repo root (AGENTS.md / CLAUDE.md / .cursorrules). The snippet routes the agent to /keep-ask before answering, /keep-compile after non-trivial changes, /keep-check-drift before merge, and /keep-idea for parked thoughts.

The verbatim text lives in exactly one place: the heredoc in scripts/init.sh. It is deliberately not duplicated here — two copies drift, and the one that actually gets written is init.sh's. Read or edit it there.

Why the wording is intentionally hard: softening it (e.g. "some of these" instead of "ANY of these", dropping "Mandatory") measurably reduces read-path triggering — the agent stops consulting /knowledge and silently falls back to generic knowledge, which is the single failure mode KEEP exists to prevent. If you ever audit an entry file and find a softened snippet, restore the canonical one from init.sh.

Anti-goals

KEEP must not become a documentation generator, a project management/ticketing system, a heavyweight SDD framework, an AI wiki that drowns the repo in auto-generated text, or a workflow engine with lifecycle states and approval gates. The value comes from staying small. Push back on requests that pull in any of those directions.

Reference files

• references/file_formats.md — full YAML frontmatter schema, anchors block, templates per type, linking convention, ADR supersession protocol. Read when creating or updating any knowledge file.
• references/brownfield.md — /keep-compile against pre-existing docs: the ask flow (migrate vs cordon), the verify-and-curate migration pass, classification heuristics, cordon ADR template. Read before invoking /keep-compile on anything other than a git diff.
• references/monorepo.md — monorepo layout and per-package routing. Read when adopting on a monorepo.
• references/setup.md — AGENTS.md adoption notes, common mistakes, copy-paste CI/pre-commit templates. Read once at adoption.
• references/commands/<name>.md — per-command contracts for all seven commands (keep, keep-init, keep-ask, keep-compile, keep-check-drift, keep-idea, keep-govern). Read the relevant one when executing or explaining a command, whether invoked as a slash command or in natural language.
• references/templates/SPEC-000-keep.md — self-spec installed by /keep-init so KEEP's conventions outlast the skill.