plugin
Open on GitHub
keep-the-why — GitHub Copilot plugin: what it does, how to install
This plugin records the reasoning behind code changes, including rejected options and workarounds. It helps agents and maintainers recover project context later.
Install into GitHub Copilot · Command from the source
All methods and platforms ↓
copilot plugin install keep-the-why@awesome-copilotWhat keep-the-why does
keep-the-why adds a repository-level memory layer for decisions that source code cannot explain. It captures architectural choices, discarded alternatives, workarounds, incident lessons, and operational constraints. The records are plain Markdown under context/, committed with the project so the reasoning follows its Git history.
The plugin works through the agent’s normal development conversation. Decisions and trade-offs from a task can become context for later sessions, giving another agent more than the code alone reveals. On an existing repository, history, issues, and implementation details recover only part of the reasoning, so a maintainer must supply the rest. That makes initial backfilling a real part of adopting it.
What it helps with
- preserve the reasons behind architecture choices
- record alternatives that the team rejected
- document workarounds and incident lessons
- give later agents repository context
- recover decision history in a legacy codebase
Example prompts for the agent
- Record in
context/why this architecture was chosen over the alternatives. - Add a note explaining why the workaround in
src/retry.tsmust stay during the refactor. - Read the existing entries in
context/before changing this module.
How to install keep-the-why
Command from the source
copilot plugin install keep-the-why@awesome-copilotStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about keep-the-why
How do I install keep-the-why in GitHub Copilot?
Run copilot plugin install keep-the-why@awesome-copilot.
What does keep-the-why do?
It stores the reasoning around architecture decisions, rejected approaches, workarounds, incidents, and operational constraints in context/. Later agent sessions can use that material alongside the code.
What should I expect when adding it to an existing repository?
Git history, issues, and code reveal only part of the original reasoning. A maintainer needs to add the remaining context.
Source text
SKILL.md · MIT
[](https://github.com/oliver-zehentleitner/keep-the-why/releases)
[](https://www.npmjs.com/package/keep-the-why)
[](https://pypi.org/project/keep-the-why-lint/)
[](https://pypi.org/project/keep-the-why-dashboard/)
[](https://keepthewhy.com/license/)
[](https://github.com/marketplace/actions/keep-the-why-lint)
[](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/validate-skill.yml)
[](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/ktw-lint.yml)
[](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/lint-package.yml)
[](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/black.yml)
[](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/link-check.yml)
[](https://skillsllm.com/security-check/IPmNycVdbOyq)
[](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/hol-scanner.yml)
[](https://hol.org/registry/plugins/oliver-zehentleitner%2Fkeep-the-why)
[](https://keepthewhy.com/)
[](https://t.me/unicorndevs)
[](https://x.com/keep_the_why)
[](https://bsky.app/profile/keep-the-why.bsky.social)
[](https://mastodon.social/@keep_the_why)
[](https://keepthewhy.com/dashboard/live/)
<a href="https://keepthewhy.com"><img src="https://keepthewhy.com/assets/logo.png" alt="Keep the Why — because "ask Bob" is not documentation."></a>
# Keep the Why
Keep a Changelog records what changed. Keep the Why preserves why it changed.
<!-- ktw-intro:start -->
**Keep the Why** is the why layer of [repo-native project memory](https://oliver-zehentleitner.github.io/repo-native-project-memory/): your repository already holds what the project is, how it works and what changed; this is the agent skill, and the file convention it maintains, that preserve the one thing it was missing — [the reasoning behind a codebase](https://keepthewhy.com/dashboard/live/#thoughts) — architecture decisions, rejected alternatives, workarounds, incident learnings, operational constraints that the code alone can't explain — in the repo. That memory is plain Markdown in `context/`, committed with the code, so Git already provides the storage, the history and the distribution: it travels with every clone, branch and fork, and a pull request shows the reasoning diff beside the code diff. It captures that reasoning as a byproduct of working with your agent, so every later session can use it. Your agent, and every other agent that works in the repository, understands not just the code but everything around it: why it is the way it is, what was tried and rejected, which constraints the source doesn't show. So does the next person. Onboarding gets faster, legacy projects become tractable again. It works continuously as you develop, where the reasoning comes for free.
It pays off most where re-debated decisions, forgotten workarounds and departed knowledge cost the most: maintainers and teams running coding agents on long-lived codebases. Starting on an existing repository works too, within limits — history, issues and code give back only part of the why, a maintainer has to fill in the rest, and that takes real effort. It is never too late to begin, though.
<!-- ktw-intro:end -->
**The payoff, made concrete:** a new hire, or an AI agent that's never touched the codebase before, doesn't have to track down whoever wrote the original code — and doesn't just repeat what was already tried and rejected. That part is measured: twenty fresh agent sessions, the same codebase, the same request to simplify a retry wrapper. Without a recorded reason, seven of ten offered the already-rejected simplification again; with one `context/` entry, all ten found it and none did ([the experiment](https://blog.technopathy.club/what-happens-when-a-coding-agent-forgets-why-a-change-was-rejected), [transcripts and grades](https://github.com/oliver-zehentleitner/keep-the-why/tree/main/experiments/rejected-change)). Every wrong turn the agent doesn't take is work nobody has to do and undo — it saves time, money in tokens, and nerves. The same context makes changes safer across the board — no more guessing whether an odd piece of code is a [Chesterton's Fence](https://en.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fence) worth keeping or just cruft nobody got around to removing — turning a legacy project back into something tractable instead of a black box only one person ever understood. "Ask Bob" stops being the fallback.
Documentation is normally extra work that happens after the code is done — reload the reasoning from memory, write it down again, file it somewhere else: a wiki, an ADR, a PR description nobody reopens. That's exactly why it so often doesn't happen. When an agent is already how you work — deciding, weighing trade-offs, explaining itself in the same conversation that produces the change — the reasoning shows up for free, as a byproduct of that conversation, not separate effort. Keep the Why's actual job is narrower than it sounds: don't let that reasoning get thrown away.
<!-- ktw-tested-with:start -->
**Tested with:** Claude Code, opencode, Pi, Hermes, and more — see the [full eval suite](https://keepthewhy.com/evals/) and the [agent × model matrix](https://keepthewhy.com/agent-matrix/) for what's actually been run against what, and how.
<!-- ktw-tested-with:end -->
**Installable [with one command](#install) on Claude Code, Codex, GitHub Copilot, Cursor, OpenClaw, Hermes Agent, Cline, OpenCode, Pi, Antigravity and 60+ more agents.**
Website: [https://keepthewhy.com](https://keepthewhy.com/) · [llms.txt](https://keepthewhy.com/llms.txt) for AI agents/assistants looking up this project
## The problem
Important project knowledge gets created in conversation — with a teammate, or with an AI coding agent — and then evaporates once the conversation ends. The code shows *what* was built. It rarely shows *why*. Tests preserve expected behavior; they don't preserve the reasoning behind it — a project can be fully tested and still hard to maintain because nobody can explain why any of it works the way it does. Missing reasoning costs you in four concrete ways:
- **Re-debate** — the same architecture question gets re-litigated because nobody remembers it was already settled.
- **Silent regression** — someone "cleans up" a workaround that looks unnecessary, not knowing it's the fix for a bug that then comes back.
- **Onboarding stall** — new contributors (human or AI) don't touch code they don't understand, so progress slows out of caution.
- **Repeated agent mistakes** — a fresh AI session, with no memory of the last one, proposes or re-implements something already tried and rejected, because nothing on disk records that it was.
## How it works
<p align="center">
<img src="https://keepthewhy.com/assets/keep-the-why-readme-project-memory.gif"
alt="Keep the Why captures the reason an attempted retry-wrapper simplification was abandoned, stores it as versioned Markdown in context/retries.md, and lets a later agent session retrieve that reasoning instead of repeating the mistake."
width="900">
</p>
Keep the Why's agent skill is `SKILL.md`-based — an open, cross-agent format (Claude Code, Codex CLI, Gemini CLI, Cursor, and others). It operates in four modes:
1. **Continuous capture** — during normal development, the agent notices rationale worth keeping and records it alongside the code as it happens.
2. **Retrospective recovery** — pointed at an existing or legacy repository, the agent reconstructs what it can from git history, issues, and code, and is explicit about what it couldn't.
3. **Knowledge-transfer interview** — before a maintainer's knowledge becomes unavailable (leaving, retiring, changing teams), the agent analyzes the codebase first, then either asks targeted questions about exactly what the code couldn't explain, or — for someone whose knowledge is broad and tacit after many years on one system — just listens while they narrate freely and extracts the rationale from that instead.
4. **Maintenance** — existing rationale docs get kept current: contradictions resolved, superseded entries marked, oversized files split.
**What you do: tell your agent to install it and set up the project — [one sentence](#install), for any of 70+ agents; "default settings" is a complete answer. Then work as usual.** The defaults are the fully integrated setup: capture is `proactive`, the agent writes when the reasoning is clear and asks only when it is genuinely unsure, and the project carries its own start path, so every later session in that directory loads the skill by itself. You never have to tell it what to write down, and a project that was set up once stays set up: the start path is committed with it, so everyone who works in that directory gets the skill loaded — a new collaborator answers one short list of personal preferences the first time, and that is all. The longer version, with what that changes for pull requests and for teams: [Keep the Why is not another workflow](https://blog.technopathy.club/keep-the-why-is-not-another-workflow).
**Works for autonomous agents too, with no human in the loop.** Declare the session [unattended](https://keepthewhy.com/setup/#personal-defaults-and-the-global-ask-vs-accept-policy) and the agent doesn't ask into the void or drop what it found: it writes the entry and flags it `pending-confirmation` — recorded now, confirmed by the next person who looks.
That first activation runs a short one-time setup instead of guessing at defaults — where the why-knowledge should live, how to start, proactive or explicit-only capture, how much confirmation is needed before something gets written, whether to actively ask for a related issue or ticket, whether to periodically check for skill updates or `context/` staleness, whether to wire the structural [linter](https://keepthewhy.com/linting/) into the project's CI or publish the [dashboard](https://keepthewhy.com/dashboard/) on the project's site (both optional, offered with the default no), whether the agent should run that linter locally on what it writes (installing it from PyPI — the default — or asking first), and how the skill gets loaded in future sessions (by default the project asks, through a section in its entry-point file and a hook where the platform has one). The defaults are the fully integrated setup, one word away; each wizard is one list with the defaults filled in, and whoever wants less picks less. See [`references/setup.md`](https://keepthewhy.com/setup/).
**Set up the way the wizard proposes, the skill is loaded in every session — measured, and in my own daily use.** Loading is the agent's job, and the skill hands it over explicitly: a skill package is instructions; no agent tool, and nothing in the open Agent Skills spec, gives a skill a way to load itself at session start. So the setup wizard asks how this project wants the skill loaded and has the agent set up what its own platform offers. [`references/autostart.md`](https://keepthewhy.com/autostart/) defines three start paths — every session machine-wide, the project asks (a hook, or a "Keep the Why" section in the project's `AGENTS.md`), or only when a developer asks — and lists per agent tool what is verified how. With a start path in place, loading does not depend on the conversation happening to match the skill's description — it is not a sometimes thing: Claude Code loads it in every measured session, by the hook (10/10 on the sessions that had gone 0/10 without one) and by the entry-point section (3/3, against 0/3 without it); Codex CLI, opencode and Cline load it by the section (3/3 each, against 0 or 1 of 3 without it); Hermes Agent by a live run. A tool that is not listed has not been measured, not failed — a pull request with a verified example is welcome any time; for anything else, [open a new issue](https://github.com/oliver-zehentleitner/keep-the-why/issues/new).
Because it's just Markdown in the repo, a `context/` update ships in the same commit or PR as the code change it explains — reviewed the same way, versioned the same way, no separate system to trust or keep in sync. Git and your host do the rest: who may write the why is who may write the code (branch protection, `CODEOWNERS` on `context/` if you want a named owner), every clone, branch and fork carries it, and `git blame` and `git log` are the audit trail — who recorded an entry, when its Status changed, where it is cited. Permissions, distribution, review, forks, branches, blame, card by card: [Git does the rest](https://keepthewhy.com/#git-does-the-rest); in one answer, with what blame does not show: [FAQ](https://keepthewhy.com/faq/).
The skill's behavior is exercised by a suite of eval cases, executed for real — a fixture project per case, a fresh agent session, LLM-judged verdicts. Full-suite numbers (case count, results, an honest failure analysis, the stated caveats) are tracked against Claude Code specifically: [Evals](https://keepthewhy.com/evals/). Which other agents and models the skill has actually been run against, and how: [agent & model matrix](https://keepthewhy.com/agent-matrix/). What changed per release, including what the evals found: [CHANGELOG](https://github.com/oliver-zehentleitner/keep-the-why/blob/main/CHANGELOG.md); open problems and ideas, one issue each: [issues](https://github.com/oliver-zehentleitner/keep-the-why/issues). One controlled experiment on the core claim — twenty fresh sessions asked to simplify a retry wrapper, ten with the rejected alternative recorded in `context/` and ten without: [What happens when a coding agent forgets why a change was rejected?](https://blog.technopathy.club/what-happens-when-a-coding-agent-forgets-why-a-change-was-rejected), with every transcript, diff and grade under [`experiments/rejected-change/`](https://github.com/oliver-zehentleitner/keep-the-why/tree/main/experiments/rejected-change).
Where the captured knowledge actually lives, and how it relates to everything else a project already has, is one coherent picture — see "Where this fits" below.
## Install
**Your agent is the interface.** Tell it:
> Install the Keep the Why skill — pick the best installation method for you from https://keepthewhy.com/installation/ — then set up Keep the Why in this project with default settings, including autostart.
That is the whole setup: the skill is the one part a project needs. Three components are optional — the agent knows how to set up each one, offers them where they fit, and does it only when you say so:
| Say to your agent | What you get |
|---|---|
| "Set up the Keep the Why linter in CI." | [`keep-the-why-lint`](https://keepthewhy.com/linting/) checks the structure of `context/` on every push: a GitHub workflow, a GitLab CI job, or the generic snippet for any other CI. |
| "Publish the Keep the Why dashboard." | Your project's own [dashboard](https://keepthewhy.com/dashboard/) and live badge, on GitHub Pages or GitLab Pages, or added to a docs build you already have. The agent writes the workflow or the `pages` job and names the settings that stay yours (GitHub: Pages source *GitHub Actions*; GitLab: Pages visibility *Everyone*). |
| "List this project in the Keep the Why registry." | A one-line pull request to the [registry](https://keepthewhy.com/registry/), so every published dashboard's globe can find your project. |
### By hand
`main` is active development, not guaranteed release-ready — pin to `latest` instead of tracking it directly (moved automatically by CI to the newest release; use an exact [tag](https://github.com/oliver-zehentleitner/keep-the-why/releases) instead for full reproducibility).
**Recommended — [skills CLI](https://skills.sh/)** (via `npx`, needs [Node.js](https://nodejs.org/en/download) — `npx` ships with it, nothing extra to install):
```bash
npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why
```
Prompts you to select one of 70+ supported agents ([Claude Code](https://keepthewhy.com/installation/#also-installable-claude-code-plugin), [Codex](https://keepthewhy.com/installation/#also-installable-codex-plugin), [GitHub Copilot](https://keepthewhy.com/installation/#also-installable-github-copilot-cli-plugin), [Cursor](https://keepthewhy.com/installation/#also-installable-cursor-plugin), [Pi](https://keepthewhy.com/installation/#also-installable-pi-package), [Antigravity](https://keepthewhy.com/installation/#recommended-skills-cli), [OpenCode](https://keepthewhy.com/installation/#recommended-skills-cli), [OpenClaw](https://keepthewhy.com/installation/#recommended-skills-cli), [Hermes Agent](https://keepthewhy.com/installation/#recommended-skills-cli), [Cline](https://keepthewhy.com/installation/#recommended-skills-cli), and more) and choose whether to install the skill at project or personal scope, then symlinks or copies the skill package in. Also listed on [skills.sh](https://skills.sh/oliver-zehentleitner/keep-the-why/keep-the-why). Start a new session afterward so the skill is picked up, then tell your agent something like "initialize Keep the Why in this project" — a Skill activates when something in the conversation matches it, not automatically on session start, and setup on a brand-new project only runs from a request like this one, never from an unrelated question the skill's description happens to match. This is only needed once: setup creates a `.keep-the-why` file at the project root, checked directly by this skill at the start of every later session — later sessions pick the project back up without needing to be told again.
<details markdown="1">
<summary>Other install methods — GitHub CLI, manual clone, agent-specific paths</summary>
**Also recommended — [GitHub CLI](https://cli.github.com/) (`gh` v2.90.0+):**
```bash
gh skill install oliver-zehentleitner/keep-the-why keep-the-why@latest
```
Prompts for which agent and scope (project or personal) to install for. This installs just the skill package (`skills/keep-the-why/`), not the whole repo — no docs/, mkdocs config, or CI files end up in your project.
**Also installable via [asm](https://luongnv.com/asm/)** (agent-skill-manager):
```bash
asm install "github:oliver-zehentleitner/keep-the-why#latest:skills/keep-the-why" --tool all --scope global
```
`--tool all` installs one shared copy to `~/.agents/skills/` and links it into every agent asm knows — Claude Code, Codex, OpenCode, Cursor, GitHub Copilot, Gemini CLI, Cline and more. For one agent only, replace `all` with its name (`claude`, `codex`, `opencode`, `cline`, `gemini`, … — `asm install --help` lists them); `--scope project` installs into the current project instead of your home.
**Also installable as a Claude Code plugin** — the repository is its own one-plugin marketplace (`.claude-plugin/plugin.json` and `marketplace.json` at the repo root): `claude plugin marketplace add oliver-zehentleitner/keep-the-why --sparse .claude-plugin skills`, then `claude plugin install keep-the-why@keep-the-why` (tested on Claude Code 2.1.273; `/plugin …` inside a session is the same). **As a GitHub Copilot CLI plugin** — `copilot plugin install keep-the-why@awesome-copilot`, from the Awesome Copilot marketplace, which pins a release tag (the root `plugin.json` serves that format). **And as a Codex plugin** — the repository is its own one-plugin marketplace: `codex plugin marketplace add oliver-zehentleitner/keep-the-why`, then `codex plugin add keep-the-why@keep-the-why` (tested on Codex CLI 0.149.0; details and pinning on the [installation page](https://keepthewhy.com/installation/)). **And as a Cursor plugin** — `.cursor-plugin/plugin.json` plus one always-on rule that loads the skill in a workspace carrying a `.keep-the-why` file and does nothing elsewhere; marketplace submission pending.
**Fallback — manual clone**, if neither of the above is available. The skill lives under `skills/keep-the-why/` in this repo, not at the root, so clone to a scratch location and copy just that folder rather than cloning straight into your agent's skills directory (cloning the whole repo there would nest an embedded git repository inside yours, and pull in unrelated project files):
```bash
git clone --branch latest https://github.com/oliver-zehentleitner/keep-the-why.git /tmp/keep-the-why
cp -r /tmp/keep-the-why/skills/keep-the-why <target-directory>/keep-the-why
rm -rf /tmp/keep-the-why
```
Where `<target-directory>` is your agent's skills directory — the folder name must stay `keep-the-why`:
| Agent | Project-scoped | Personal |
|---|---|---|
| Claude Code | `.claude/skills/keep-the-why` | `~/.claude/skills/keep-the-why` |
| Cline | `.cline/skills/keep-the-why` | `~/.cline/skills/keep-the-why` |
| Cursor | `.cursor/skills/keep-the-why` | — (no personal directory) |
| Gemini CLI | `.gemini/skills/keep-the-why` | `~/.gemini/skills/keep-the-why` |
| GitHub Copilot | `.github/skills/keep-the-why` | `~/.copilot/skills/keep-the-why` |
| Kimi Code | `.kimi/skills/keep-the-why` | `~/.kimi/skills/keep-the-why` |
| Pi | `.pi/skills/keep-the-why` | `~/.pi/agent/skills/keep-the-why` |
Codex CLI, Antigravity, Amp, OpenCode, Warp, and more read the shared `.agents/skills/keep-the-why` path at project scope (Codex scans it from your current directory up to the repository root) and `~/.agents/skills/keep-the-why` personally — check whether yours does before falling back to a vendor path. Pi and Kimi Code also fall back to this same shared path (project and personal) if their own brand directory above doesn't have it.
Also compatible with Windsurf, Goose, Roo Code, Trae, Factory, JetBrains Junie, and other tools supporting the open Agent Skills format — the directory convention varies, check your tool's own docs.
</details>
Full install detail for every method, including tools without a skill runtime at all: [`docs/installation.md`](docs/installation.md) or [https://keepthewhy.com/installation/](https://keepthewhy.com/installation/).
### Then fill it
A new `context/` starts empty and fills itself as you work. What the project already knows — scattered across commit messages, pull requests, issues, old docs and people's heads — can be gathered right away, one sentence each:
| Say to your agent | What it does |
|---|---|
| "Go through the git history, pull requests, issues and existing docs, and collect the reasoning that is already there into `context/`." | A retrospective pass: reconstructs decisions, rejected alternatives and workarounds from what the repository already holds. What it cannot back up is marked `unknown`, never made up. |
| "Carry the decisions from our ADRs into `context/` — leave the ADR files untouched." | A migration pass over an existing decision-record folder: one entry per ADR that still matters, its `Source` naming the ADR file it came from and its Status as the ADR states it; the originals stay as they are — nothing deleted, nothing retagged. |
| "Interview me about this project — ask about what the code can't explain." | Analyzes the repository first, then asks targeted questions about the gaps it found. |
| "I'll tell you about this project — listen, and record the decisions." | Free narration, for broad knowledge built up over years: the agent extracts the decisions and their alternatives, then closes the gaps with questions. |
| "Check `context/` for entries that are stale or contradict the code." | Maintenance: contradictions surfaced, superseded entries marked, oversized files split. |
### Keep it current
A new release of the skill can ask something of a project — a new field, a renamed file, a check the linter now makes. Two sentences, in two sessions:
| Say to your agent | What it does |
|---|---|
| "Update the Keep the Why skill to the latest release." | Re-runs the install command the skill came with ([updating](https://keepthewhy.com/installation/#updating)). The new version is loaded from the next session on — a session already running keeps the one it started with. |
| "Migrate this project to the installed Keep the Why version." | In a new session after the update: compares the project's `context-schema` in `.keep-the-why` with the skill's version, applies what the [migrations](https://keepthewhy.com/migrations/) list for the versions in between — asking where a step needs a decision — and raises `context-schema`. A session that notices the project is behind offers this by itself; the sentence is for when you want it now. |
A project can also pin the version it runs, whatever is installed on the machine — a copy of the skill in the repository and two lines in `.keep-the-why`; a global install then follows that copy: [pinning a project](https://keepthewhy.com/installation/#pinning-a-project-to-one-skill-version).
## Example
```text
You: We're changing the retry mechanism because the previous
implementation caused duplicate orders. Make sure future
maintainers understand this.
```
Keep the Why updates the relevant topic file in `context/` (or creates one if none exists), records the reason, and marks the old approach as superseded — without you having to ask for documentation separately.
Weeks later, a new maintainer — human or agent — can just ask:
```text
You: Why does the retry mechanism track state instead of just retrying?
```
and get the real answer instead of reverse-engineering it from the diff.
**What if nothing gets changed at all?**
```text
You: This retry wrapper looks over-engineered — a plain retry loop
would do the same thing. Let's simplify it.
```
Working through *why* it could be simplified surfaces a real constraint (the gateway's rate limiter needs that backoff behavior) — the change gets abandoned before it happens. No commit, no diff, no PR ever results, so normally nothing would capture that reasoning at all. Keep the Why records it anyway, so the next person with the same instinct doesn't rediscover it the hard way — see [`examples/abandoned-change.md`](https://github.com/oliver-zehentleitner/keep-the-why/blob/latest/skills/keep-the-why/examples/abandoned-change.md) for the full walkthrough.
See [`examples/`](https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why/examples) for continuous, retrospective, and interview-mode walkthroughs.
## Where this fits
A project's documentation is one coherent group of files, not a single practice: each answers a different question, has a clear and non-overlapping scope, and knowing which is which is what keeps you from ending up with duplicates. A project missing any one of them still has a real gap. The full argument — the repository as the project's memory, `context/` as the row it was missing, and where that argument is thin — is a page of its own: [repo-native project memory](https://oliver-zehentleitner.github.io/repo-native-project-memory/).
| Element | The question it answers | Who reads it | Who maintains it today |
|---|---|---|---|
| `README.md` | "What is this, should I care, how do I start?" | evaluators, new developers, agents on first contact | humans and agents |
| `docs/` | "How do I configure, operate, troubleshoot?" | users, agents doing the work | humans and agents |
| `CHANGELOG.md` ([Keep a Changelog](https://keepachangelog.com/)) | "What changed, in which version?" | upgraders, reviewers, agents reconstructing the past | humans and agents |
| `CONTRIBUTING.md` | "How does a change get in, which conventions apply?" | contributors, agents about to change code | humans |
| `LICENSE`, `SECURITY.md`, `CODE_OF_CONDUCT.md` | "Under which terms, how do I report, how do we behave?" | everyone | humans |
| `tests/` | "What is the code supposed to do, executably?" | developers, CI, agents checking their own work | humans and agents |
| `pyproject.toml`, `package.json`, `Cargo.toml`, … | "What does this depend on, how is it built and published?" | build too...
© Oliver Zehentleitner · MIT · oliver-zehentleitner/keep-the-why
Similar plugins
All plugins for Agent setup: memory, context, orchestration →
ponytail ponytail steers Claude Code toward small, direct solutions and away from abstractions nobody asked for. Use it when you want the agent to build on what the project already has.
★ 177,259repo stars
impeccable Hands your agent a designer's vocabulary: 24 commands like polish, audit and bolder, so UI feedback stops being “make it pretty”.
★ 89,321repo stars
last-30-days-skill Searches the web for what people posted about a topic in the last month and turns it into one structured brief.
★ 65,596repo stars
claude-hud Shows context usage, rate limits, running tools and todo progress under your input line. Useful when a session runs long and you want to watch the spend.
★ 28,914repo stars
understand-anything Turns codebases or markdown wikis into an interactive knowledge graph with a browser dashboard. Helps navigate unfamiliar repositories without reading files blindly.
★ 88,429repo stars
mem0 Adds persistent memory to Claude Code so your agent retains project context across terminal sessions.
★ 67,869repo stars
