ADR-007 — What goes into the repository

Date: 2026-09-03 · Status: accepted · Scope: repository, tooling

Context

A project that sells the idea that tasks are ordinary files in git had itself grown full of things that did not belong in git. Measured before this decision:

So 80% of the repository had nothing to do with the product, and the consequences were not cosmetic:

• git clone pulled 3.8 MB of someone else's library to get a 30 KB CLI;
• .serena/project.yml carried absolute paths from the author's machine, so it conflicted for anyone who opened it;
• compiled Python bytecode from a third-party skill had arrived along with it;
• real changes drowned in the diff of a pull request.

The old .gitignore was four lines and covered neither .DS_Store nor .env nor coverage output.

Decision

What goes into git is whatever is needed to reproduce or understand the product. Everything else does not.

Committed: src/, test/, the build script, package.json and the lock file, tsconfig.json, docs/, SPEC.md, README.md, CHANGELOG.md, LICENSE, CI workflows, AGENTS.md and .kadence/README.md — the tool-agnostic contract for AI agents — and .kadence/events/, which is the product's own data.

Not committed: node_modules/ and dist/ (both reproducible, and a checked-in bundle would conflict on every merge), .kadence/state.json (derived, and keeping it would mean two sources of truth), developer tooling like .claude/ and .serena/ (different for everyone, full of absolute paths), secrets, OS and editor leftovers, and test artefacts.

The rule for any new file is one question: could someone else reproduce or understand the product without it?

Consequences

• 94 files in git instead of 491, and a pull request diff that shows product changes rather than a third-party library.
• A contributor no longer gets the /eng-* commands with a clone and installs their own tooling. Acceptable: AGENTS.md describes how to work with the project without naming a tool.
• git rm --cached removed the files from the index but not from history, so .git stays 18 MB. Rewriting history on a published repository breaks every clone for space we do not lack.
• What would make us revisit it: a permanent team with an identical agent environment would make .claude/ part of the process — and then it comes back whole, skills included, not half of it.