Skip to content

docs: consolidate agent instructions into canonical AGENTS.md #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jammy2211 merged 1 commit into from
Jun 23, 2026
+114 −117
Merged

docs: consolidate agent instructions into canonical AGENTS.md #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# HowToGalaxy — Agent Instructions

This is the **HowToGalaxy** tutorial lecture series for **PyAutoGalaxy**, a Python library for galaxy
morphology modeling. Tutorials teach new users how to model galaxy light from first principles. It is
the teaching companion to `../autogalaxy_workspace`. These are the canonical, agent-agnostic
instructions for this repo.

## Repository Structure

- `scripts/` — Runnable Python tutorial scripts:
- `chapter_1_introduction/` — Grids, light profiles, galaxies, data, fitting
- `chapter_2_modeling/` — Non-linear searches, Bayesian inference, galaxy modeling
- `chapter_3_search_chaining/` — Search chaining, prior passing, automated pipelines
- `chapter_4_pixelizations/` — Pixelized reconstruction, inversions, regularization
- `chapter_optional/` — Alternative searches and advanced topics
- `simulators/` — Simulator scripts that generate the tutorial datasets at runtime
- `notebooks/` — Jupyter versions, generated from `scripts/` (do not edit directly)
- `config/` — PyAutoGalaxy configuration YAML
- `dataset/` — Empty in the repo; written at runtime by the simulator scripts
- `output/` — Model-fit results (generated at runtime, not committed)

## Running Scripts

Scripts are run **from the repo root** so relative paths to `dataset/` and `output/` resolve. A
tutorial that needs a dataset invokes the matching `scripts/simulators/` script via `subprocess` if
the dataset folder is absent — no manual simulate-then-run step.

```bash
python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
```

Fast mode for integration: `PYAUTO_TEST_MODE=1` skips sampling (`=2` also bypasses; combine with
`PYAUTO_SKIP_FIT_OUTPUT=1 PYAUTO_SKIP_VISUALIZATION=1 PYAUTO_SKIP_CHECKS=1 PYAUTO_FAST_PLOTS=1` for a
fast smoke run). **Dataset realism:** `PYAUTO_SMALL_DATASETS` is deliberately **not** used in
HowToGalaxy — tutorials assume the full-resolution simulated datasets (unlike the workspaces, which
cap grids/masks).

## Testing

On CI, every PR is gated on Python **3.12 and 3.13** by `smoke_tests.yml` (runs
`python .github/scripts/run_smoke.py`, driven by `smoke_tests.txt` + `config/build/env_vars.yaml` —
the definition of green), `navigator_check.yml` (PyAutoBuild's reusable navigator-catalogue check;
see *Notebooks vs Scripts*), and `url_check.yml` (link checking). The smoke and navigator jobs check
out **PyAutoBuild** as a sibling and run the PyAuto* libraries from the **same-named branch** of each
source repo, so a HowToGalaxy PR is validated against matching library branches.

## Sandboxed / restricted runs

If `numba` or `matplotlib` cannot write to the default cache locations, point them at writable dirs:

```bash
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
```

## Notebooks vs Scripts

Notebooks in `notebooks/` are **generated** from the `.py` scripts via PyAutoBuild. **Always edit the
`.py` scripts, never the `.ipynb` directly.** The `# %%` marker alternates code and markdown cells.
Regenerate from the repo root:

```bash
PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py howtogalaxy
```

The `howtogalaxy` project target is registered in PyAutoBuild (`run_all.py`, `navigator.py`,
`config/`). The navigator catalogue — `llms-full.txt` + `workspace_index.json` — is what
`navigator_check.yml` gates; it is rebuilt by the same PyAutoBuild generate/merge flow that builds
the notebooks. Commit regenerated notebooks and catalogue alongside the script changes.

## Bulk-edit safety

When editing the same region across many scripts in one pass, only rewrite the targeted region.
**Never produce a whole-file write unless you have read the entire current file** — a whole-file
write from a header skim silently deletes every section below the header.

## Scientific Context

When a tutorial benefits from framing a galaxy concept against a real scientific application —
light profiles + MGE, regularisation, pixelisation, bulge/halo decomposition, kinematics — pull from
the `autolens_assistant` literature wiki at https://github.com/PyAutoLabs/autolens_assistant
(`wiki/literature/` — concepts, entities, sources). If cloned as a sibling, read it locally at
`../autolens_assistant/wiki/literature/`. It is currently lensing-focused, but several galaxy-modelling
concepts (source reconstruction, bulge/halo decomposition) are directly useful.

## Related Repos

- `../PyAutoGalaxy` — source library.
- `../autogalaxy_workspace` — the user-facing workspace (tutorials point here as the next destination).
- `../PyAutoBuild` — notebook generation + CI tooling.
- `../autolens_assistant` — science-assistant workspace (literature wiki; see *Scientific Context*).

## Task Workflows

**`[API Update]` issues:** find every renamed/moved/removed/changed public API, update each tutorial
script (preserving the teaching prose), run `python .github/scripts/run_smoke.py`, and fix `[FAIL]`
entries until the summary passes; regenerate notebooks + catalogue after. **General issues:** edit
only files in `scripts/` (never `notebooks/`), preserve docstrings and explanations, test, then
regenerate. Flag any change that affects `autogalaxy_workspace` or the source libraries in your PR.

## Clean state

Never rewrite history on a repo with a remote (no `git init` over a tracked tree, no force-push to
`main`, no rebasing pushed shared branches). To reset a dirty tree the only correct sequence is:

```bash
git fetch origin
git reset --hard origin/main
git clean -fd
```
122 changes: 5 additions & 117 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,117 +1,5 @@
# HowToGalaxy

This is the **HowToGalaxy** tutorial lecture series for `PyAutoGalaxy`, a Python library for galaxy morphology modeling. Tutorials teach new users how to model galaxy light from first principles.

## Scientific Context

Adjacent science — strong-lensing concepts that overlap galaxy modelling
(light profiles + MGE, regularisation, pixelisation, kinematics,
bulge/halo decomposition) — lives in the lensing sub-wiki at
[`PyAutoLabs/PyAutoPaper`](https://github.com/PyAutoLabs/PyAutoPaper),
locally at `../PyAutoPaper/lensing_wiki/`. The wiki is lensing-focused
but tutorials that want to frame a galaxy concept against a real
scientific application can pull from it (e.g.
`concepts/source-reconstruction.md` for pixelisation,
`concepts/bulge-halo-decomposition.md` for SLaM-style decomposition).
Start at `../PyAutoPaper/lensing_wiki/index.md`.

## Repository Structure

- `scripts/` — Runnable Python tutorial scripts
- `chapter_1_introduction/` — Grids, light profiles, galaxies, data, fitting
- `chapter_2_modeling/` — Non-linear searches, Bayesian inference, galaxy modeling
- `chapter_3_search_chaining/` — Search chaining, prior passing, automated pipelines
- `chapter_4_pixelizations/` — Pixelized galaxy reconstruction, inversions, regularization
- `chapter_optional/` — Alternative non-linear searches and advanced topics
- `simulators/` — Simulator scripts that generate the tutorial datasets at runtime
- `notebooks/` — Jupyter notebook versions of scripts (generated from `scripts/`, do not edit directly)
- `config/` — `PyAutoGalaxy` configuration YAML files
- `dataset/` — Empty in the repo; tutorial datasets are written here at runtime by the simulator scripts
- `output/` — Model-fit results (generated at runtime, not committed)

## Running Scripts

Scripts are run from the repository root so relative paths to `dataset/` and `output/` resolve correctly:

```bash
python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
```

Tutorials in chapters 1 and 2 that need a dataset invoke the relevant script in `scripts/simulators/` via `subprocess` if the dataset folder does not already exist — there is no manual simulate-then-run step.

**Integration testing / fast mode**: set `PYAUTO_TEST_MODE=1` to skip non-linear search sampling:

```bash
PYAUTO_TEST_MODE=1 python scripts/chapter_2_modeling/tutorial_1_non_linear_search.py
```

**Fast smoke tests**: combine test mode with the skip flags:

```bash
PYAUTO_TEST_MODE=2 PYAUTO_SKIP_FIT_OUTPUT=1 PYAUTO_SKIP_VISUALIZATION=1 PYAUTO_SKIP_CHECKS=1 PYAUTO_FAST_PLOTS=1 python scripts/chapter_1_introduction/tutorial_5_summary.py
```

Note: `PYAUTO_SMALL_DATASETS` is deliberately **not** used in HowToGalaxy. Tutorials assume the full-resolution simulated datasets that the simulator scripts produce.

**Codex / sandboxed runs**: set writable cache directories so `numba` and `matplotlib` do not fail on unwritable home paths:

```bash
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
```

## Core API Patterns

Imports used throughout the tutorials:

```python
import autofit as af
import autogalaxy as ag
import autogalaxy.plot as aplt
```

## Notebooks vs Scripts

Notebooks in `notebooks/` are generated from the `.py` files in `scripts/` using `generate.py` from the `PyAutoBuild` repo. **Always edit the `.py` scripts**, never the notebooks directly. The `# %%` marker alternates between code and markdown cells.

### Building Notebooks

Run from the workspace root:

```bash
PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py howtogalaxy
```

The `howtogalaxy` project target needs to be added to `PyAutoBuild/autobuild/config.yaml`. This is a known follow-up from the initial bootstrap.

## Relationship to autogalaxy_workspace

HowToGalaxy is the teaching companion to `autogalaxy_workspace`. Many tutorials (particularly in chapters 2–4) point users to `autogalaxy_workspace` scripts (e.g. `scripts/imaging/modeling.py`, `scripts/guides/...`) as the next destination after the relevant concept has been introduced. Those cross-references use absolute paths like `autogalaxy_workspace/scripts/...` and refer to the separate `autogalaxy_workspace` repository — not to anything inside HowToGalaxy.

## Related Repos

- **PyAutoGalaxy** source: `../PyAutoGalaxy`
- **autogalaxy_workspace**: `../autogalaxy_workspace` — main user-facing workspace
- **PyAutoBuild**: `../PyAutoBuild` — notebook generation and CI/CD tooling
## Never rewrite history

NEVER perform these operations on any repo with a remote:

- `git init` in a directory already tracked by git
- `rm -rf .git && git init`
- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset
for AI workflow", or any equivalent message on a branch with a remote
- `git push --force` to `main` (or any branch tracked as `origin/HEAD`)
- `git filter-repo` / `git filter-branch` on shared branches
- `git rebase -i` rewriting commits already pushed to a shared branch

If the working tree needs a clean state, the **only** correct sequence is:

git fetch origin
git reset --hard origin/main
git clean -fd

This applies equally to humans, local Claude Code, cloud Claude agents, Codex,
and any other agent. The "Initial commit — fresh start for AI workflow" pattern
that appeared independently on origin and local for three workspace repos is
exactly what this rule prevents — it costs ~40 commits of redundant local work
every time it happens.
# HowToGalaxy — agent instructions
The canonical, agent-agnostic instructions live in `AGENTS.md`. Claude Code loads them
via the import below; if your tool does not process `@`-imports, open `AGENTS.md` in
this directory and read it directly.
@AGENTS.md
Loading