Skip to content

Guidelines for AI coding agents: coding rules in the repo, usage guide shipped with the package (struphy agents) - #797

Merged
spossann merged 6 commits into
develfrom
agents-md
Oct 19, 2026
Merged

Guidelines for AI coding agents: coding rules in the repo, usage guide shipped with the package (struphy agents)#797
spossann merged 6 commits into
develfrom
agents-md

Conversation

@spossann

@spossann spossann commented Oct 19, 2026

Copy link
Copy Markdown
Member

Guidance for AI coding agents (Claude Code, Codex, Copilot, Cursor, ...), split into coding guidelines (for changing Struphy, repo only) and usage guidelines (for using Struphy, shipped with the pip package).

Coding guidelines (repository only)

  • AGENTS.md at the root: repository layout, branches/PRs, code style, MPI rules (maybempi, collectives on all ranks), Pyccel kernel pitfalls, tests (CI shards, mpi_skip, rank counts), performance pitfalls, feectools submodule workflow. CLAUDE.md imports it (@AGENTS.md).
  • src/struphy/models/AGENTS.md: how to add a model (structure of StruphyModel, the 8 doc_* methods, models-all.rst, build-init-files, api/models/__init__.py, default-options tests, verification tests, examples).
  • src/struphy/propagators/AGENTS.md: how to add a propagator (Variables/Options/allocate/__call__, docstring, propagators-avail.rst, particle kernel folders, tests).
  • Each nested guide has a one-line CLAUDE.md, and the root AGENTS.md tells agents to read them before creating a model or propagator.

Usage guidelines (shipped in the package)

  • src/struphy/agent_guides/USAGE.md: entry point (installation check, CLI, running with MPI, ground rules, docs links).
  • src/struphy/agent_guides/skills/setup-simulation/ (moved from .claude/skills/, now independent of a source checkout) and the new skills/postprocess-simulation/ (Output API).
  • Package data in pyproject.toml: only these files; the coding AGENTS.md/CLAUDE.md are not shipped (checked with a wheel build).
  • .claude/skills/* in the repo are relative symlinks to the shipped skills, so there is one copy.

New command struphy agents

  • struphy agents prints the guide, the paths of the skills and the examples URL for the installed version.
  • struphy agents --path prints the folder of the guide.
  • struphy agents --install [DIR] copies the skills to DIR/.claude/skills/ and adds a pointer to DIR/AGENTS.md and DIR/CLAUDE.md. It is idempotent: a second run refreshes the skills and leaves the pointers unchanged. It does nothing in the Struphy repository itself.
  • Tests in console/tests/test_agents.py (mpi_skip).

README (README.qmd and README.md, edited by hand since they have diverged) and the quickstart (doc/sections/quickstart.rst) get a section on how to use the agent files.

Notes for reviewers

  • src/struphy/api/models/__init__.py currently misses CurlCurl and ToyDrift, and the template Options in propagators/base.py has a tuple default (opt1: str = ("implicit",)). Both are left for a separate PR; the propagator guide tells agents not to copy the template.
  • The examples URL uses the release tag (v3.4.0), which lacks newer examples until the next release.
  • Symlinks in .claude/skills/ need core.symlinks on Windows checkouts.

🤖 Generated with Claude Code

spossann and others added 6 commits October 19, 2026 10:12
@spossann @claude
Add AGENTS.md with coding guidelines for agents, imported by CLAUDE.md
83f7237 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@spossann
reviewed AGENTS.md
82fdfcc
@spossann @claude
Add agent guides for new models and propagators, referenced from root…
1a89379 
… AGENTS.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@spossann
reviewed model and propagator instructions
27cb101
@spossann @claude
Ship a usage guide for AI coding agents with the package, add struphy…
7098078 
… agents

Split usage from coding guidelines: src/struphy/agent_guides/ (USAGE.md and the
setup-simulation and postprocess-simulation skills) is package data, so pip
installs get the guide of their version. struphy agents prints it, --install
copies the skills into a project and points its AGENTS.md/CLAUDE.md to it.
The repo's .claude/skills link to the shipped copies. README and quickstart
explain the workflow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@spossann @claude
struphy agents: handle symlinked skills and the repo itself; review f…
432f433 
…ixes

--install keeps skills that already link to the installed version, replaces
other symlinks, and does nothing in the Struphy repository itself (whose
.claude/skills link to the guides). examples_url falls back to devel when
struphy is not installed. --path and --install are mutually exclusive. Tests
for symlinks and the argparse wiring. Guide wording fixes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@spossann spossann mentioned this pull request Oct 19, 2026
Merged
@spossann
spossann requested a review from max-models October 19, 2026 13:55
@spossann
spossann merged commit 183b618 into devel Oct 19, 2026
28 checks passed
@spossann
spossann deleted the agents-md branch October 19, 2026 14:09
spossann added a commit that referenced this pull request Oct 19, 2026
@spossann @claude
Export CurlCurl/ToyDrift in struphy.api.models; fix model docstring a…
f2f8416 
…nd propagator Options template (#798)

Closes #793, closes #794, closes #795.

- **#793**: `struphy.api.models` now also exports `CurlCurl`, `ToyDrift`
and `IncompressibleNavierStokesSPH` (the last one was missing too). A
new test in `api/tests/test_public_api.py` parses
`api/models/__init__.py` (without importing every model). It checks that
`__all__` matches `struphy.models.__all__` and `_LAZY_IMPORTS`, and that
each name is imported from its defining module. So a model that is
missing from the hand-maintained api file now fails CI.
- **#794**: the `StruphyModel` docstring no longer points to
`fluid.py`/`kinetic.py`/... It now says one module per model, regenerate
`struphy/models/__init__.py` with `struphy build-init-files`, and add
the model by hand to `struphy/api/models/__init__.py`.
- **#795**: the template `Propagator.Options` now declares `opt1:
OptsTemplate = "implicit"`, the same pattern as the real propagators
(e.g. `implicit_diffusion.py`). It used to be `opt1: str =
("implicit",)`. `check_option` accepts tuples on purpose (list-valued
options), which is why the old default never failed.
- **CI**: `src/struphy/api/tests/` was in no test shard, so its tests
never ran in CI. It is now in shard-2 of `reusable-unit-testing.yml` and
`reusable-scheduled.yml` and in `struphy test unit`. Its tests are
marked `mpi_skip`, and the folder gets an `__init__.py` like the other
test folders.

Follow-up for #797: once this is merged, the line "Don't copy the
template in `base.py` literally: its `opt1` default is a tuple." in
`src/struphy/propagators/AGENTS.md` can be removed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
spossann added a commit that referenced this pull request Oct 21, 2026
@spossann @claude
Guidelines for AI coding agents: coding rules in the repo, usage guid…
63e1cda 
…e shipped with the package (struphy agents) (#797)

Guidance for AI coding agents (Claude Code, Codex, Copilot, Cursor,
...), split into **coding guidelines** (for changing Struphy, repo only)
and **usage guidelines** (for using Struphy, shipped with the pip
package).

## Coding guidelines (repository only)

- `AGENTS.md` at the root: repository layout, branches/PRs, code style,
MPI rules (`maybempi`, collectives on all ranks), Pyccel kernel
pitfalls, tests (CI shards, `mpi_skip`, rank counts), performance
pitfalls, feectools submodule workflow. `CLAUDE.md` imports it
(`@AGENTS.md`).
- `src/struphy/models/AGENTS.md`: how to add a model (structure of
`StruphyModel`, the 8 `doc_*` methods, `models-all.rst`,
`build-init-files`, `api/models/__init__.py`, default-options tests,
verification tests, examples).
- `src/struphy/propagators/AGENTS.md`: how to add a propagator
(`Variables`/`Options`/`allocate`/`__call__`, docstring,
`propagators-avail.rst`, particle kernel folders, tests).
- Each nested guide has a one-line `CLAUDE.md`, and the root `AGENTS.md`
tells agents to read them before creating a model or propagator.

## Usage guidelines (shipped in the package)

- `src/struphy/agent_guides/USAGE.md`: entry point (installation check,
CLI, running with MPI, ground rules, docs links).
- `src/struphy/agent_guides/skills/setup-simulation/` (moved from
`.claude/skills/`, now independent of a source checkout) and the new
`skills/postprocess-simulation/` (`Output` API).
- Package data in `pyproject.toml`: only these files; the coding
`AGENTS.md`/`CLAUDE.md` are not shipped (checked with a wheel build).
- `.claude/skills/*` in the repo are relative symlinks to the shipped
skills, so there is one copy.

## New command `struphy agents`

- `struphy agents` prints the guide, the paths of the skills and the
examples URL for the installed version.
- `struphy agents --path` prints the folder of the guide.
- `struphy agents --install [DIR]` copies the skills to
`DIR/.claude/skills/` and adds a pointer to `DIR/AGENTS.md` and
`DIR/CLAUDE.md`. It is idempotent: a second run refreshes the skills and
leaves the pointers unchanged. It does nothing in the Struphy repository
itself.
- Tests in `console/tests/test_agents.py` (`mpi_skip`).

README (`README.qmd` and `README.md`, edited by hand since they have
diverged) and the quickstart (`doc/sections/quickstart.rst`) get a
section on how to use the agent files.

## Notes for reviewers

- `src/struphy/api/models/__init__.py` currently misses `CurlCurl` and
`ToyDrift`, and the template `Options` in `propagators/base.py` has a
tuple default (`opt1: str = ("implicit",)`). Both are left for a
separate PR; the propagator guide tells agents not to copy the template.
- The examples URL uses the release tag (`v3.4.0`), which lacks newer
examples until the next release.
- Symlinks in `.claude/skills/` need `core.symlinks` on Windows
checkouts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
spossann added a commit that referenced this pull request Oct 21, 2026
@spossann @claude
Export CurlCurl/ToyDrift in struphy.api.models; fix model docstring a…
05added 
…nd propagator Options template (#798)

Closes #793, closes #794, closes #795.

- **#793**: `struphy.api.models` now also exports `CurlCurl`, `ToyDrift`
and `IncompressibleNavierStokesSPH` (the last one was missing too). A
new test in `api/tests/test_public_api.py` parses
`api/models/__init__.py` (without importing every model). It checks that
`__all__` matches `struphy.models.__all__` and `_LAZY_IMPORTS`, and that
each name is imported from its defining module. So a model that is
missing from the hand-maintained api file now fails CI.
- **#794**: the `StruphyModel` docstring no longer points to
`fluid.py`/`kinetic.py`/... It now says one module per model, regenerate
`struphy/models/__init__.py` with `struphy build-init-files`, and add
the model by hand to `struphy/api/models/__init__.py`.
- **#795**: the template `Propagator.Options` now declares `opt1:
OptsTemplate = "implicit"`, the same pattern as the real propagators
(e.g. `implicit_diffusion.py`). It used to be `opt1: str =
("implicit",)`. `check_option` accepts tuples on purpose (list-valued
options), which is why the old default never failed.
- **CI**: `src/struphy/api/tests/` was in no test shard, so its tests
never ran in CI. It is now in shard-2 of `reusable-unit-testing.yml` and
`reusable-scheduled.yml` and in `struphy test unit`. Its tests are
marked `mpi_skip`, and the folder gets an `__init__.py` like the other
test folders.

Follow-up for #797: once this is merged, the line "Don't copy the
template in `base.py` literally: its `opt1` default is a tuple." in
`src/struphy/propagators/AGENTS.md` can be removed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@max-models max-models Awaiting requested review from max-models

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@spossann