agentleFS
mischa76mischa76/vault-agent/.claude/skills/project-docs/SKILL.md

project-docs

Skill2 starsChanged 4 months agoMITView on GitHub

How to maintain this project's knowledge base — where a new fact goes, how to close a work package with a log entry, when something earns a place in CLAUDE.md, and how to run the lint pass. Use when closing a WP, recording a measurement or finding, adding an ADR or spec, updating the index, or when CLAUDE.md is growing.

22 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use test-audit, to-issues and 3 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • BlockSkill

    test-audit

    Invoke whenever writing, changing, reviewing, or sweeping tests in buzz-app. Authoring gate for new tests plus audit workflow for low-value, implementation-coupled, or duplicative tests and the test-only production seams they demand.

    Also in 3 projects that use this

  • GoogleSkill

    to-issues

    Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.

    Also in 3 projects that use this

  • GoogleSkill

    to-prd

    Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

    Also in 3 projects that use this

  • Google CloudSkill

    triage

    Gather context on a change or bug and plan the implementation.

    Also in 3 projects that use this

  • BlockSkill

    frontend-design

    Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 18 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask in this order and stop at the first yes.

    line 14
  2. Distinctive:

    Write what changed, *why it was wrong before*, what is proven live versus keyless only, and what you deliberately did not do.

    line 29
  3. Very specific:

    If the WP added or changed a document, add it to docs/index.md.

    line 32
  4. Distinctive:

    If it changed a count, threshold or version that a doc repeats, update that doc in the same commit — or better, replace the value with a …

    line 33
  5. Distinctive:

    Only then consider CLAUDE.md (next section).

    line 35
  6. Very specific:

    Verify with git -C eval/results status -sb (nothing ahead) and git -C eval/results ls-remote origin naming the commit.

    line 52
  7. Very specific:

    Not rsync: every key of the git user on tank is restricted to git-shell since 2026-11-12, so rsync, scp and a shell are refused — …

    line 61
  8. Very specific:

    Never put in CLAUDE.md: counts, versions, thresholds, test totals, "N tests green", file inventories, or anything derivable from the code.

    line 84
  9. Distinctive:

    Run periodically, and after any batch of doc changes.

    line 89

“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Maintaining the vault-agent knowledge base

The structure and its rationale: docs/methodology/llm-wiki-mapping.md. This file is the procedure. It loads only when you are actually maintaining something, which is why the procedure is not in CLAUDE.md.

Where a new fact goes

Ask in this order and stop at the first yes.

  1. Would an agent silently do the wrong thing without it? → an invariant in CLAUDE.md, in trigger/action/evidence form. See the admission rule below — this is the expensive layer.
  2. Is it true only while working on one subsystem? → .claude/rules/<topic>.md with a paths: glob, so it loads only when a matching file is read.
  3. Is it a decision with alternatives and consequences? → a new ADR in docs/architecture/adrs/, numbered, from ADR-template.md.
  4. Is it work to be done? → a spec plus kick-off under docs/architecture/backlog-2026-07/.
  5. Otherwise → an entry in docs/log.md. This is the default, and most things belong here.

Closing a work package

  1. Definition of done first: uv run pytest, uv run ruff check, bare uv run mypy.
  2. Append one entry to docs/log.md: ## [YYYY-MM-DD] WPnn — one line. Newest at the bottom. Write what changed, why it was wrong before, what is proven live versus keyless only, and what you deliberately did not do. Corrections to earlier entries go in this entry, never into the earlier one.
  3. If the WP added or changed a document, add it to docs/index.md.
  4. If it changed a count, threshold or version that a doc repeats, update that doc in the same commit — or better, replace the value with a pointer to the code.
  5. Only then consider CLAUDE.md (next section). Most WPs change nothing there.

Securing the evidence of a paid run

eval/results/ (result JSON, step files, review.json, LLM transcripts, ablation comparisons) is git-ignored and exists only on this machine, yet every measurement entry in docs/log.md cites it by stamp. Since 2026-11-14 the directory is a git repository of its own (remote tank:/tank/git/vault-agent-eval-results.git, branch master). After recording a run — or at the latest in the same session — commit and push it:

git -C eval/results pull --ff-only     # a second machine (ZEUS) pushes there too
git -C eval/results add -A
git -C eval/results commit -m "<what was run, with its stamp>"
git -C eval/results push               # never --force: the remote refuses it, by the owner's setting

Verify with git -C eval/results status -sb (nothing ahead) and git -C eval/results ls-remote origin naming the commit. On a checkout without the directory: git clone tank:/tank/git/vault-agent-eval-results.git eval/results. Kept projects of a run (--keep-outputs) go under eval/results/kept-outputs/<case>/<stamp>/ without dbt's target/. A script kept there as evidence is stored as .py.txt: bare mypy reads eval/ and takes a .py file for project code (2026-11-15). The repository is the evidence's second copy, not a dataset: nothing reads it back, and it never goes to GitHub.

Not rsync: every key of the git user on tank is restricted to git-shell since 2026-11-12, so rsync, scp and a shell are refused — deliberately; do not look for a way round it. A new repository on tank is the owner's to create. The repository holds every run since 2026-07-08 (ZEUS's 858 files were merged in on 2026-11-14) and is the only copy besides the working machines: the former rsync mirror on tank was removed by the owner on 2026-11-15, without a file-by-file comparison. The remote has receive.denyNonFastForwards and receive.denyDeletes set — do not test that with a real force-push.

The admission rule for CLAUDE.md

Budget: 250 lines (200 until 2026-10-09, raised by the owner: condensing at 200 had started to cost knowledge), and it is a real limit, not an aspiration — the file is loaded in full on every request, and the documented guidance is that longer files reduce adherence.

An entry is admitted only if both hold:

  • there is a concrete incident where an agent did the wrong thing without it — name it; and
  • it can be phrased as trigger / action / evidence. If it cannot, it is a fact, not a rule, and facts go in the log or the index.

At budget, an addition requires an eviction: say which rule leaves and why it is no longer earning its place (usually because a gate, a type or a test now enforces it mechanically — that is the good outcome).

Never put in CLAUDE.md: counts, versions, thresholds, test totals, "N tests green", file inventories, or anything derivable from the code. /doctor will propose trimming exactly these.

The lint pass

Run periodically, and after any batch of doc changes. It is a reading task, not a script.

  • Contradictions — two documents stating incompatible things. Newer wins; record the correction as a new dated entry, do not edit the older. Check the maintained pages against the record, not only against each other: CLAUDE.md's "Open items" is the likeliest place for a claim that a later log entry or findings document has already overtaken. The first lint pass missed exactly this by comparing maintained pages among themselves.
  • Derivable facts stored as values — gate counts, version pins, caps, thresholds in prose. Replace with a pointer. This is the failure mode this project has hit most often.
  • Stale status — a document claiming live verification whose subject has changed since. Downgrade the claim in a new entry; say what is now merely keyless-tested.
  • Orphans — files in docs/ that docs/index.md does not list, and index entries whose file no longer exists.
  • Rules without a trigger — entries in CLAUDE.md that read as memories rather than rules. They are eviction candidates.
  • Budget — wc -l CLAUDE.md against 250 (200 until 2026-10-09).

Report findings; apply only the mechanical ones (index, pointers) without asking. Anything that changes meaning is the human's call.

Ownership — append-only

docs/architecture/ (ADRs, specs, kick-offs, reviews, spike memos) and docs/log.md are dated records. Index them, link them, quote them. Never revise them, never "clean them up", never fix a claim inside them — a new dated entry does that. Their value is precisely that they show what was believed when, which is what makes a later correction legible.

Maintained and rewritable: docs/index.md, CLAUDE.md, .claude/rules/, this skill.

Frontmatter for new documents

New documents under docs/ carry:

---
type: adr | spec | kickoff | review | memo | guide | log | index
status: verified-live | keyless-only | not-measured | superseded
updated: YYYY-MM-DD
supersedes: <path>#<section>   # optional
---

status is the axis this project argues about most — say which claims are live-proven and which are only keyless-tested. Existing documents were not retrofitted: adding frontmatter to a dated record would mean editing it, which the ownership rule forbids.

The guard that protects the move

tests/test_log_completeness.py asserts that every paragraph of the pre-retrofit CLAUDE.md still exists verbatim in docs/log.md. If you ever restructure the log, that test must keep passing — the log is append-only, so it only ever gets stricter.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.