Document the knowledge repository and the agent setup by finsberg · Pull Request #74 · scientificcomputing/dolfinx-adjoint

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.

finsberg · 2026-08-27T07:54:15Z

The design records, specs, reference papers and agent memory now live in
dolfinx-adjoint-knowledge
rather than in this repository, which keeps this one free of files most contributors do not
need — but left no trace of where they went. This says where, and how to pick them up.

In the contributor guidelines rather than the README: it is setup for people working on the
project, not something someone installing the package needs, and it sits beside the existing
notes on what CI expects.

It covers linking the knowledge repository in, what a coding agent then picks up automatically,
where per-project agent memory lives, and where the repository-scoped skills come from.

Two things that are easy to get wrong are called out explicitly, because both fail quietly:

The linking step has to add the paths to .git/info/exclude. That file is per-clone and is
not itself versioned, so a fresh clone does not inherit the exclusions and would offer the
symlinks up for commit — the one thing the separation exists to prevent.
Those patterns must not carry a trailing slash. .scratch/ matches a directory and stops
matching once the path is a symlink, which is exactly what happened here when the files moved.

The knowledge repository is private, so the section says so and makes clear nothing here depends
on it: you can build, test and contribute without it.

Separate from #71 deliberately — that one is about checkpointing and this is unrelated
documentation.

Note on CI

Check formatting fails on this branch, and it is not from this change: this branch is
documentation-only, cut from main, and main is currently red. ruff reports two
import-sorting errors in src/dolfinx_adjoint/blocks/interpolation.py and
src/dolfinx_adjoint/types/function.py, introduced with the nonmatching interpolation work.
Both are already fixed on the branch for #71, so merging that turns main green again.

🤖 Generated with Claude Code

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.