Repo Cleanliness
hermit/ and reverie/ are clean, focused implementation repositories.
They contain product source, product tests, build configuration, and minimal
curated documentation — nothing else. Coordination state, experiments, research
notes, and heavy artifacts live in the dev-hermit parent workspace, not
here.
This skill is the standing rule for what may enter these repos and the
pre-commit check that enforces it. It applies to both hermit/ and reverie/
(each carries its own copy, since they are separate Git histories).
Why this matters
A product repo that accumulates experiment dumps, stray logs, vendored clones,
and binary blobs becomes slow to clone, hard to review, and impossible for a new
contributor to read. Meta exports these repos upstream; churn and slop leak into
that export. Keep the signal-to-noise ratio high: every tracked file should be
something a maintainer would knowingly keep.
What belongs in hermit/ and reverie/
- Product source and public APIs.
- Product tests and regression coverage (at the narrowest useful layer).
- Build and lint configuration (
Cargo.toml, Cargo.lock, CI workflows, etc.).
- Curated, minimal reference documentation:
AGENTS.md, README.md,
CONTRIBUTING.md, docs/ that a new contributor actually needs.
- Product skills under
.claude/skills/, surfaced to Claude through
.llms/skills and to stock Codex through structured .agents/skills
entrypoints (see "Cross-client skill layout" below).
What does NOT belong here
- Experiments and their outputs. Reproducible experiments live in the parent
at
~/work/dev-hermit/experiments/. Do not create hermit/experiments/ or
reverie/experiments/. If you need to measure something, run it from a slot
and record the durable result in the parent experiments/ tree.
ai_docs slop. Bulk AI research notes, design dumps, transient handoffs,
and status logs belong in the parent ~/work/dev-hermit/ai_docs/. Any
ai_docs/ kept inside a product repo must be minimal, curated, durable
reference — not a scratch pad.
- Binary files. No compiled executables, object files (
.o, .a, .so),
archives (.tar*, .tgz, .gz, .zip, .zst), images, PDFs, database
dumps, core dumps, profiler captures, VM images (.img, .qcow2, .raw,
.iso), kernels (bzImage, vmlinux), or initramfs*.cpio*. Git LFS is not
a workaround.
- Nested / vendored Git repositories. Never embed another project's clone
(a nested
.git) inside these repos. To depend on external code, record its
source URL and exact commit SHA for reproducibility; do not vendor the
checkout. (This is exactly how a 433M experiments/gvisor/ clone with a 361M
nested .git almost got swallowed into the parent — record hashes, never
embed clones.)
- Large or transient logs. No multi-megabyte run logs,
*.perf.data,
coverage output, or __pycache__/. Keep evidence as summarized text
(README/CSV/JSON) or in an ignored scratch dir.
- Generated build artifacts.
target/ and other build trees stay ignored.
Where things actually go
| Artifact |
Correct home |
| Experiment + results |
~/work/dev-hermit/experiments/<name>_YYYYMMDD/ |
| AI research / design / handoff |
~/work/dev-hermit/ai_docs/ |
| Disposable notes, logs, probes |
~/work/dev-hermit/scratch/ or an ignored/ dir |
| Heavy/binary evidence |
ignored scratch or external store + a text manifest |
| Product source / test / doc |
the owning submodule (hermit/ or reverie/) |
An experiment is durable only when another engineer can repeat it: record the
question, method, exact command, repo SHAs, host facts, seed, and text/CSV/JSON
results. Reference external code by URL + commit SHA — never by vendoring it.
Cross-client skill layout
Skills are written once as real files and surfaced through client-specific
entrypoints, so there is a single source of truth:
.claude/skills/<name>/ holds each real skill package, including its
canonical SKILL.md and any package-local resources.
.llms/skills is a directory symlink to ../.claude/skills for the existing
Claude/LLMS hook.
.agents/skills/<name> is a whole-package symlink to the matching canonical
directory. Stock Codex discovers the shared SKILL.md through that link.
CLAUDE.md is a symlink to AGENTS.md for the same reason.
Keep instruction bodies canonical under .claude/skills/; never copy the body
into an adapter or link only the SKILL.md file. Run
scripts/check-skill-discovery.rs after changes. The LiteInst subtree follows
the same package pattern with canonical bodies under
reverie-liteinst/.llms/skills/.
Pre-commit protocol
Before every commit, audit exactly what you are about to stage. Misplaced files
are cheap to fix before a commit and expensive to remove after.
git status --short # what's staged / untracked
git diff --cached --name-only # exact staged paths
git diff --cached --numstat # line counts — flag anything huge/binary
Verify, and fix before committing if any check fails:
- Right repo, right path. Every staged file belongs in this repo and at a
sensible path. Product code/tests/docs only. Nothing under
experiments/ or
a bulk ai_docs/.
- No experiments. No
hermit/experiments/ or reverie/experiments/
additions — move them to ~/work/dev-hermit/experiments/.
- No ai_docs slop. Any
ai_docs/ change is minimal, curated, durable
reference — not a scratch dump.
- No binaries. Scan
git diff --cached --numstat; a - in the line-count
columns means a binary file. Inspect suspicious paths with file and du.
Do not stage binaries or artifacts >2 MiB of text without coordinator
approval.
- No nested git repos / vendored clones.
git diff --cached --name-only | grep -E '/\.git(/|$)' must be empty. Record external deps as URL + SHA.
- Only task-owned paths. Do not sweep in another agent's in-flight changes.
If the working tree is dirty with work you did not create, stage only your
own paths explicitly — never
git add -A past your ownership.
If a misplaced file is already staged: git restore --staged <path> (and move
it to its correct home) before committing. Never "commit now, clean up later."
Quick audit
# From a product repo root — all of these should print nothing:
git ls-files | grep -E '^(experiments/|.*/experiments/)' # stray experiments
git ls-files | grep -E '\.(o|a|so|tar|tgz|gz|zip|zst|img|qcow2|raw|iso|bin)$' # binaries
git ls-files | grep -E '(^|/)\.git(/|$)' # nested repos
find . -name .git -not -path './.git' -prune -print # embedded checkouts
A finding here is a cleanliness defect: relocate the file to the parent
workspace or an ignored dir, add a .gitignore guard, and keep the product repo
focused.
1---2name: repo-cleanliness3description: "Keep hermit/ and reverie/ clean, focused implementation repos — no experiments, no ai_docs slop, no binaries, no vendored/nested git repos. Use before every commit and whenever staging files or deciding where an artifact belongs."4metadata:5 source: https://skillmd.com/skills/facebookexperimental/repo-cleanliness6---78# Repo Cleanliness910`hermit/` and `reverie/` are **clean, focused implementation repositories**.11They contain product source, product tests, build configuration, and minimal12curated documentation — nothing else. Coordination state, experiments, research13notes, and heavy artifacts live in the `dev-hermit` **parent** workspace, not14here.1516This skill is the standing rule for what may enter these repos and the17pre-commit check that enforces it. It applies to both `hermit/` and `reverie/`18(each carries its own copy, since they are separate Git histories).1920## Why this matters2122A product repo that accumulates experiment dumps, stray logs, vendored clones,23and binary blobs becomes slow to clone, hard to review, and impossible for a new24contributor to read. Meta exports these repos upstream; churn and slop leak into25that export. Keep the signal-to-noise ratio high: every tracked file should be26something a maintainer would knowingly keep.2728## What belongs in hermit/ and reverie/2930- Product source and public APIs.31- Product tests and regression coverage (at the narrowest useful layer).32- Build and lint configuration (`Cargo.toml`, `Cargo.lock`, CI workflows, etc.).33- **Curated, minimal** reference documentation: `AGENTS.md`, `README.md`,34 `CONTRIBUTING.md`, `docs/` that a new contributor actually needs.35- Product skills under `.claude/skills/`, surfaced to Claude through36 `.llms/skills` and to stock Codex through structured `.agents/skills`37 entrypoints (see "Cross-client skill layout" below).3839## What does NOT belong here4041- **Experiments and their outputs.** Reproducible experiments live in the parent42 at `~/work/dev-hermit/experiments/`. Do not create `hermit/experiments/` or43 `reverie/experiments/`. If you need to measure something, run it from a slot44 and record the durable result in the parent `experiments/` tree.45- **`ai_docs` slop.** Bulk AI research notes, design dumps, transient handoffs,46 and status logs belong in the parent `~/work/dev-hermit/ai_docs/`. Any47 `ai_docs/` kept inside a product repo must be **minimal, curated, durable48 reference** — not a scratch pad.49- **Binary files.** No compiled executables, object files (`.o`, `.a`, `.so`),50 archives (`.tar*`, `.tgz`, `.gz`, `.zip`, `.zst`), images, PDFs, database51 dumps, core dumps, profiler captures, VM images (`.img`, `.qcow2`, `.raw`,52 `.iso`), kernels (`bzImage`, `vmlinux`), or `initramfs*.cpio*`. Git LFS is not53 a workaround.54- **Nested / vendored Git repositories.** Never embed another project's clone55 (a nested `.git`) inside these repos. To depend on external code, record its56 **source URL and exact commit SHA** for reproducibility; do not vendor the57 checkout. (This is exactly how a 433M `experiments/gvisor/` clone with a 361M58 nested `.git` almost got swallowed into the parent — record hashes, never59 embed clones.)60- **Large or transient logs.** No multi-megabyte run logs, `*.perf.data`,61 coverage output, or `__pycache__/`. Keep evidence as summarized text62 (README/CSV/JSON) or in an ignored scratch dir.63- **Generated build artifacts.** `target/` and other build trees stay ignored.6465## Where things actually go6667| Artifact | Correct home |68|----------------------------------|------------------------------------------------|69| Experiment + results | `~/work/dev-hermit/experiments/<name>_YYYYMMDD/`|70| AI research / design / handoff | `~/work/dev-hermit/ai_docs/` |71| Disposable notes, logs, probes | `~/work/dev-hermit/scratch/` or an `ignored/` dir |72| Heavy/binary evidence | ignored scratch or external store + a text manifest |73| Product source / test / doc | the owning submodule (`hermit/` or `reverie/`) |7475An experiment is durable only when another engineer can repeat it: record the76question, method, exact command, repo SHAs, host facts, seed, and text/CSV/JSON77results. Reference external code by URL + commit SHA — never by vendoring it.7879## Cross-client skill layout8081Skills are written **once** as real files and surfaced through client-specific82entrypoints, so there is a single source of truth:8384- `.claude/skills/<name>/` holds each **real** skill package, including its85 canonical `SKILL.md` and any package-local resources.86- `.llms/skills` is a directory symlink to `../.claude/skills` for the existing87 Claude/LLMS hook.88- `.agents/skills/<name>` is a whole-package symlink to the matching canonical89 directory. Stock Codex discovers the shared `SKILL.md` through that link.90- `CLAUDE.md` is a symlink to `AGENTS.md` for the same reason.9192Keep instruction bodies canonical under `.claude/skills/`; never copy the body93into an adapter or link only the `SKILL.md` file. Run94`scripts/check-skill-discovery.rs` after changes. The LiteInst subtree follows95the same package pattern with canonical bodies under96`reverie-liteinst/.llms/skills/`.9798## Pre-commit protocol99100Before every commit, audit exactly what you are about to stage. Misplaced files101are cheap to fix before a commit and expensive to remove after.102103```bash104git status --short # what's staged / untracked105git diff --cached --name-only # exact staged paths106git diff --cached --numstat # line counts — flag anything huge/binary107```108109Verify, and **fix before committing** if any check fails:1101111. **Right repo, right path.** Every staged file belongs in *this* repo and at a112 sensible path. Product code/tests/docs only. Nothing under `experiments/` or113 a bulk `ai_docs/`.1142. **No experiments.** No `hermit/experiments/` or `reverie/experiments/`115 additions — move them to `~/work/dev-hermit/experiments/`.1163. **No ai_docs slop.** Any `ai_docs/` change is minimal, curated, durable117 reference — not a scratch dump.1184. **No binaries.** Scan `git diff --cached --numstat`; a `-` in the line-count119 columns means a binary file. Inspect suspicious paths with `file` and `du`.120 Do not stage binaries or artifacts >2 MiB of text without coordinator121 approval.1225. **No nested git repos / vendored clones.** `git diff --cached --name-only |123 grep -E '/\.git(/|$)'` must be empty. Record external deps as URL + SHA.1246. **Only task-owned paths.** Do not sweep in another agent's in-flight changes.125 If the working tree is dirty with work you did not create, stage only your126 own paths explicitly — never `git add -A` past your ownership.127128If a misplaced file is already staged: `git restore --staged <path>` (and move129it to its correct home) before committing. Never "commit now, clean up later."130131## Quick audit132133```bash134# From a product repo root — all of these should print nothing:135git ls-files | grep -E '^(experiments/|.*/experiments/)' # stray experiments136git ls-files | grep -E '\.(o|a|so|tar|tgz|gz|zip|zst|img|qcow2|raw|iso|bin)$' # binaries137git ls-files | grep -E '(^|/)\.git(/|$)' # nested repos138find . -name .git -not -path './.git' -prune -print # embedded checkouts139```140141A finding here is a cleanliness defect: relocate the file to the parent142workspace or an ignored dir, add a `.gitignore` guard, and keep the product repo143focused.