From 9ca9693acaa9665198b4d06959218ddc9198a86e Mon Sep 17 00:00:00 2001 From: Henrik Finsberg Date: Thu, 27 Aug 2026 10:00:29 +0200 Subject: [PATCH] Document the knowledge repository and the agent setup The design records, specs, reference papers and agent memory now live in dolfinx-adjoint-knowledge rather than here, which keeps this repository free of files most contributors do not need but leaves no trace of where they went. Put it in the contributor guidelines rather than the README: it is setup for people working on the project, not information someone installing the package needs, and it sits naturally beside the existing notes on what CI expects. Covers linking the knowledge repository in, what an agent then picks up automatically, where per-project agent memory lives, and where the skills come from. Two things that are easy to get wrong are called out: the linking step has to add the paths to .git/info/exclude, because that file is per-clone and unversioned so a fresh clone would offer the symlinks up for commit; and those patterns must not carry a trailing slash, which matches a directory and silently stops matching a symlink. --- CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d0ca28..b6b3586 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,6 +32,78 @@ Note that for a pull request to be accepted, it has to pass all the tests on CI, - `pytest`: Successfull execution of all tests in the `tests` folder. +## Design notes, and working with coding agents + +The reasoning behind the design — a domain glossary, architecture decision records, feature +specs, the papers the algorithms follow, and memory for coding agents — is kept in a separate, +internal repository, +[dolfinx-adjoint-knowledge](https://github.com/scientificcomputing/dolfinx-adjoint-knowledge), +so that this one stays free of files most contributors do not need. + +**None of it is required.** You can build, test and contribute without it, and nothing in the +package imports or reads it. + +### Linking it in + +If you have access, clone it *beside* this repository and link it in from the repository root. +The paths it provides are the ones this project's tooling and agent instructions already look +for, so linking them makes everything resolve in place: + +```bash +git clone git@github.com:scientificcomputing/dolfinx-adjoint-knowledge.git ../dolfinx-adjoint-knowledge + +ln -s ../dolfinx-adjoint-knowledge/CONTEXT.md CONTEXT.md +ln -s ../dolfinx-adjoint-knowledge/CLAUDE.md CLAUDE.md +ln -s ../dolfinx-adjoint-knowledge/scratch .scratch +ln -s ../dolfinx-adjoint-knowledge/references references +ln -s ../../dolfinx-adjoint-knowledge/adr docs/adr +ln -s ../../dolfinx-adjoint-knowledge/agents docs/agents + +# Keep them out of this repository's history. `.git/info/exclude` is per-clone and is not +# itself versioned, so this has to be done again in every clone. Do not give the patterns a +# trailing slash: `.scratch/` matches a directory and stops matching once it is a symlink. +printf '%s\n' CONTEXT.md CLAUDE.md .scratch references docs/adr docs/agents >> .git/info/exclude +``` + +The development container mounts only this repository, so these links point outside the mount +and are not readable from inside it. That is harmless — building and testing touch only `src/`, +`tests/` and `demos/`. + +### What an agent picks up once it is linked + +[Claude Code](https://claude.com/claude-code) reads most of this on its own: + +| Path | What it gives the agent | +| ------------- | -------------------------------------------------------------------------- | +| `CLAUDE.md` | Project instructions, read automatically at the start of every session. | +| `CONTEXT.md` | The domain glossary: the words this project uses, and the ones it avoids. | +| `docs/adr/` | Why things are the way they are, so decisions are not silently re-litigated.| +| `docs/agents/`| Where issues live, and the triage vocabulary the skills expect. | +| `.scratch/` | Specs and issues, one directory per feature. | +| `references/` | The papers to follow rather than improvising. | + +Agent memory is stored per project outside the repository, and is symlinked to the knowledge +repository so that it is versioned rather than left in a cache directory: + +```bash +# The directory name is the absolute path to your checkout with "/" replaced by "-" +ln -s "$PWD/../dolfinx-adjoint-knowledge/memory" \ + ~/.claude/projects/"$(pwd | tr / -)"/memory +``` + +### Skills + +The repository-scoped skills the agent instructions refer to — `grilling`, `domain-modeling`, +`code-review`, `to-spec` and others — are vendored under `.agents/skills/`, exposed to Claude +Code through `.claude/skills/`, and pinned in `skills-lock.json`. They come from +[mattpocock/skills](https://github.com/mattpocock/skills) and are not part of the knowledge +repository, since they are upstream content rather than anything specific to this project. + +`setup-matt-pocock-skills` scaffolds the per-repository configuration those skills assume — the +issue tracker layout, the triage vocabulary and the domain doc paths, which is what +`docs/agents/` contains. It configures the repository; it does not install the skills. + + ### Our Pledge In the interest of fostering an open and welcoming environment, we as