Knowledge Architecture — Development skill for Claude Code

Knowledge Architecture

**0.2.0** — a typed system for project knowledge that humans and coding agents share. Latest published release: **v0.2.0**. Published tags are immutable.

Most repositories that coding agents work in end up with conflicting `AGENTS.md`, `CLAUDE.md`, TODO, and notes files, and nothing tells an agent which of them is true. This project gives each kind of knowledge one home: how to operate, what we decided, what we are doing now. Each kind has an authority level, and a small linter keeps the result honest.

• Kernel: the one-page version. Start here.
• Full specification: the model, the layout, and the edge cases.
• Implementation prompt: hand it to an agent to apply the spec to a repository.
• scripts/lint_knowledge.py: a single file that checks the tree, scaffolds a new repository, and gates decision changes in pull requests.

This repository [applies the architecture to itself](docs/this-repo.md).

Requirements

Python **3.10+**, standard library only. Git is needed for the decision gate. There is nothing to install.

Use it in a repository

Pick the case that matches the target repository. Always use the same release (`v0.2.0` below) for the linter and the documents.

1. New repository, or no agent files yet

From the target repository, run:

curl -fsSL --create-dirs -o scripts/lint_knowledge.py \
  https://raw.githubusercontent.com/AndysTMC/knowledge-architecture/v0.2.0/scripts/lint_knowledge.py
python3 scripts/lint_knowledge.py --init --test "pytest"
python3 scripts/lint_knowledge.py --strict

Replace `pytest` with the real test command; `--install`, `--dev`, and `--lint-command` are optional. Init creates a README if there is none, an `AGENTS.md` hub, the three tool pointers (`CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`), and the vendored linter. It never creates empty `docs/` folders, and it never overw