knowledge-layer

Give any repo a memory. A Claude Code skill that scaffolds a code-side knowledge layer into a project — a build-documentation system that survives session-to-session: a curated wiki, an append-only per-session journal, ADR decision records, a roadmap parking lot, and a commit-triggered hook that auto-journals every git commit.

The problem it solves

Build sessions surface rationale — why an architecture was chosen, why an approach was abandoned, what's still open. That reasoning gets parked verbally and then lost. The next session (or the same person three months later) re-litigates settled decisions because the why never made it next to the code.

A knowledge layer captures that why next to the source, append-only, so intent gets reconstructed instead of re-argued. For a solo dev or a small team, strong documentation isn't bureaucracy — it's the survival strategy.

What it creates

knowledge/
  CLAUDE.md              orientation — the three rules, code-map protocol, formats
  wiki/                  curated reference — one article per subsystem, append-only context logs
  wiki/_codemap.md       auto-generated structural index (symbols + imports by file)
  _codemap.json          machine copy of the structural index
  journal/               per-session ADR-flavored entries, written continuously
  decisions/             atomic decision records (ADR format)
  wiki/roadmap.md        the parking lot
.claude/
  hooks/journal-breadcrumb.sh   auto-journals each git commit + nudges the agent
  hooks/codemap-refresh.sh      regenerates _codemap on source-file commits (background)
  settings.json                 wires both hooks (PostToolUse, gated to `git commit`)
.gitattributes                  union merge-driver on _codemap files (never conflicts)

wiki/ is the curated layer — curated WHY. _codemap.md is the structural WHAT/HOW, auto-maintained, never hand-edited. journal/ + decisions/ are the firehose. The split is the whole point: write hot and often to the firehose, compile cold and deliberately to the wiki.

The three rules

1. Journal continuously, wiki at the end. The journal is append-only firehose — write to it as you go, especially right after each git commit. The commit-breadcrumb hook automates the cadence so nobody has to remember. The wiki only changes via an explicit end-of-session compile pass.
2. Wiki updates need a real trigger — only three: a new subsystem was added; a documented decision is now contradicted; or someone explicitly said "document this." No "just in case" rewrites.
3. Append-only, [[wikilinks]] everywhere. Never edit prior entries — if something's wrong, append a correction linking the contradicting source.

The commit hooks

Two hooks fire on every source-advancing git commit:

Journal breadcrumb — appends time, short hash, subject, and changed files to today's journal entry, then nudges the agent to write the why while it's fresh. A HEAD-comparison guard means failed commits never breadcrumb and reruns never double-write.

Code-map refresh — if source files changed, regenerates wiki/_codemap.md + _codemap.json in the background (time-boxed, swallows errors). Doc-only commits are skipped. Never blocks the commit.

Both are breadcrumb + nudge, not blocking gates — flow is never interrupted.

Install

Clone into your Claude Code skills directory:

git clone https://github.com/inkxel/knowledge-layer.git ~/.claude/skills/knowledge-layer

Then, from inside Claude Code, just ask: "set up the knowledge layer in this project." The skill activates, scaffolds the structure, adapts the orientation file to your repo, and seeds it from the project's current state.

Or run the scaffold directly

bash ~/.claude/skills/knowledge-layer/scripts/init.sh [repo-path]

It's idempotent and merge-aware — safe to re-run, won't clobber an existing knowledge/ or overwrite an existing .claude/settings.json (it merges the hook in). Requires jq.

After scaffolding, open /hooks once (or restart the session) so Claude Code re-reads the config and the breadcrumb hook goes live.

How it works (the full skill)

• SKILL.md — the skill itself: when to use it, how to run it, how the hooks work.
• references/formats.md — worked examples plus confidence: field, compile-pass handoff, and EXTRACTED/INFERRED claim tags.
• assets/knowledge-CLAUDE.md.tmpl — the orientation file template dropped into each project.
• assets/journal-breadcrumb.sh — the commit breadcrumb hook.
• assets/codemap-refresh.sh — the code-map refresh hook (runs in background on source commits).
• scripts/init.sh — the scaffolder (idempotent, wires both hooks + merge-driver).
• scripts/codemap.py — the code-map generator (tree-sitter, no LLM; run via uv).
• references/roadmap-codemap.md — design rationale for the code-map feature (items 1–5 built).

Why a skill and not a template repo

A template you copy once goes stale the moment you stop thinking about it. A skill carries the discipline — the three rules, the cadence, the formats — into every session, and the hook enforces the cadence automatically. The structure is the easy part; keeping it alive is the hard part, and that's what the skill is for.

---

Built by Tucker. MIT licensed — take it, adapt it, make your repos remember.