Skip to content

Commit 26944c8

Browse files
Jammy2211claude
authored and
Jammy2211
committed
docs: add canonical AGENTS.md, reduce CLAUDE.md to import stub
Migrate the agent docs to one agent-agnostic AGENTS.md (uniform skeleton) with CLAUDE.md as a 4-line @AGENTS.md stub. Document the real CI gates (smoke_tests + navigator_check + url_check on Python 3.12 & 3.13, PyAutoBuild as sibling, same-named library branches), the navigator catalogue, and the full-resolution dataset policy (no PYAUTO_SMALL_DATASETS). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 82e0e3b commit 26944c8

2 files changed

Lines changed: 114 additions & 117 deletions

File tree

‎AGENTS.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# HowToGalaxy — Agent Instructions
2+
3+
This is the **HowToGalaxy** tutorial lecture series for **PyAutoGalaxy**, a Python library for galaxy
4+
morphology modeling. Tutorials teach new users how to model galaxy light from first principles. It is
5+
the teaching companion to `../autogalaxy_workspace`. These are the canonical, agent-agnostic
6+
instructions for this repo.
7+
8+
## Repository Structure
9+
10+
- `scripts/` — Runnable Python tutorial scripts:
11+
- `chapter_1_introduction/` — Grids, light profiles, galaxies, data, fitting
12+
- `chapter_2_modeling/` — Non-linear searches, Bayesian inference, galaxy modeling
13+
- `chapter_3_search_chaining/` — Search chaining, prior passing, automated pipelines
14+
- `chapter_4_pixelizations/` — Pixelized reconstruction, inversions, regularization
15+
- `chapter_optional/` — Alternative searches and advanced topics
16+
- `simulators/` — Simulator scripts that generate the tutorial datasets at runtime
17+
- `notebooks/` — Jupyter versions, generated from `scripts/` (do not edit directly)
18+
- `config/` — PyAutoGalaxy configuration YAML
19+
- `dataset/` — Empty in the repo; written at runtime by the simulator scripts
20+
- `output/` — Model-fit results (generated at runtime, not committed)
21+
22+
## Running Scripts
23+
24+
Scripts are run **from the repo root** so relative paths to `dataset/` and `output/` resolve. A
25+
tutorial that needs a dataset invokes the matching `scripts/simulators/` script via `subprocess` if
26+
the dataset folder is absent — no manual simulate-then-run step.
27+
28+
```bash
29+
python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
30+
```
31+
32+
Fast mode for integration: `PYAUTO_TEST_MODE=1` skips sampling (`=2` also bypasses; combine with
33+
`PYAUTO_SKIP_FIT_OUTPUT=1 PYAUTO_SKIP_VISUALIZATION=1 PYAUTO_SKIP_CHECKS=1 PYAUTO_FAST_PLOTS=1` for a
34+
fast smoke run). **Dataset realism:** `PYAUTO_SMALL_DATASETS` is deliberately **not** used in
35+
HowToGalaxy — tutorials assume the full-resolution simulated datasets (unlike the workspaces, which
36+
cap grids/masks).
37+
38+
## Testing
39+
40+
On CI, every PR is gated on Python **3.12 and 3.13** by `smoke_tests.yml` (runs
41+
`python .github/scripts/run_smoke.py`, driven by `smoke_tests.txt` + `config/build/env_vars.yaml` —
42+
the definition of green), `navigator_check.yml` (PyAutoBuild's reusable navigator-catalogue check;
43+
see *Notebooks vs Scripts*), and `url_check.yml` (link checking). The smoke and navigator jobs check
44+
out **PyAutoBuild** as a sibling and run the PyAuto* libraries from the **same-named branch** of each
45+
source repo, so a HowToGalaxy PR is validated against matching library branches.
46+
47+
## Sandboxed / restricted runs
48+
49+
If `numba` or `matplotlib` cannot write to the default cache locations, point them at writable dirs:
50+
51+
```bash
52+
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
53+
```
54+
55+
## Notebooks vs Scripts
56+
57+
Notebooks in `notebooks/` are **generated** from the `.py` scripts via PyAutoBuild. **Always edit the
58+
`.py` scripts, never the `.ipynb` directly.** The `# %%` marker alternates code and markdown cells.
59+
Regenerate from the repo root:
60+
61+
```bash
62+
PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py howtogalaxy
63+
```
64+
65+
The `howtogalaxy` project target is registered in PyAutoBuild (`run_all.py`, `navigator.py`,
66+
`config/`). The navigator catalogue — `llms-full.txt` + `workspace_index.json` — is what
67+
`navigator_check.yml` gates; it is rebuilt by the same PyAutoBuild generate/merge flow that builds
68+
the notebooks. Commit regenerated notebooks and catalogue alongside the script changes.
69+
70+
## Bulk-edit safety
71+
72+
When editing the same region across many scripts in one pass, only rewrite the targeted region.
73+
**Never produce a whole-file write unless you have read the entire current file** — a whole-file
74+
write from a header skim silently deletes every section below the header.
75+
76+
## Scientific Context
77+
78+
When a tutorial benefits from framing a galaxy concept against a real scientific application —
79+
light profiles + MGE, regularisation, pixelisation, bulge/halo decomposition, kinematics — pull from
80+
the `autolens_assistant` literature wiki at https://github.com/PyAutoLabs/autolens_assistant
81+
(`wiki/literature/` — concepts, entities, sources). If cloned as a sibling, read it locally at
82+
`../autolens_assistant/wiki/literature/`. It is currently lensing-focused, but several galaxy-modelling
83+
concepts (source reconstruction, bulge/halo decomposition) are directly useful.
84+
85+
## Related Repos
86+
87+
- `../PyAutoGalaxy` — source library.
88+
- `../autogalaxy_workspace` — the user-facing workspace (tutorials point here as the next destination).
89+
- `../PyAutoBuild` — notebook generation + CI tooling.
90+
- `../autolens_assistant` — science-assistant workspace (literature wiki; see *Scientific Context*).
91+
92+
## Task Workflows
93+
94+
**`[API Update]` issues:** find every renamed/moved/removed/changed public API, update each tutorial
95+
script (preserving the teaching prose), run `python .github/scripts/run_smoke.py`, and fix `[FAIL]`
96+
entries until the summary passes; regenerate notebooks + catalogue after. **General issues:** edit
97+
only files in `scripts/` (never `notebooks/`), preserve docstrings and explanations, test, then
98+
regenerate. Flag any change that affects `autogalaxy_workspace` or the source libraries in your PR.
99+
100+
## Clean state
101+
102+
Never rewrite history on a repo with a remote (no `git init` over a tracked tree, no force-push to
103+
`main`, no rebasing pushed shared branches). To reset a dirty tree the only correct sequence is:
104+
105+
```bash
106+
git fetch origin
107+
git reset --hard origin/main
108+
git clean -fd
109+
```

‎CLAUDE.md‎

Lines changed: 5 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,5 @@
1-
# HowToGalaxy
2-
3-
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.
4-
5-
## Scientific Context
6-
7-
Adjacent science — strong-lensing concepts that overlap galaxy modelling
8-
(light profiles + MGE, regularisation, pixelisation, kinematics,
9-
bulge/halo decomposition) — lives in the lensing sub-wiki at
10-
[`PyAutoLabs/PyAutoPaper`](https://github.com/PyAutoLabs/PyAutoPaper),
11-
locally at `../PyAutoPaper/lensing_wiki/`. The wiki is lensing-focused
12-
but tutorials that want to frame a galaxy concept against a real
13-
scientific application can pull from it (e.g.
14-
`concepts/source-reconstruction.md` for pixelisation,
15-
`concepts/bulge-halo-decomposition.md` for SLaM-style decomposition).
16-
Start at `../PyAutoPaper/lensing_wiki/index.md`.
17-
18-
## Repository Structure
19-
20-
- `scripts/` — Runnable Python tutorial scripts
21-
- `chapter_1_introduction/` — Grids, light profiles, galaxies, data, fitting
22-
- `chapter_2_modeling/` — Non-linear searches, Bayesian inference, galaxy modeling
23-
- `chapter_3_search_chaining/` — Search chaining, prior passing, automated pipelines
24-
- `chapter_4_pixelizations/` — Pixelized galaxy reconstruction, inversions, regularization
25-
- `chapter_optional/` — Alternative non-linear searches and advanced topics
26-
- `simulators/` — Simulator scripts that generate the tutorial datasets at runtime
27-
- `notebooks/` — Jupyter notebook versions of scripts (generated from `scripts/`, do not edit directly)
28-
- `config/` — `PyAutoGalaxy` configuration YAML files
29-
- `dataset/` — Empty in the repo; tutorial datasets are written here at runtime by the simulator scripts
30-
- `output/` — Model-fit results (generated at runtime, not committed)
31-
32-
## Running Scripts
33-
34-
Scripts are run from the repository root so relative paths to `dataset/` and `output/` resolve correctly:
35-
36-
```bash
37-
python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
38-
```
39-
40-
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.
41-
42-
**Integration testing / fast mode**: set `PYAUTO_TEST_MODE=1` to skip non-linear search sampling:
43-
44-
```bash
45-
PYAUTO_TEST_MODE=1 python scripts/chapter_2_modeling/tutorial_1_non_linear_search.py
46-
```
47-
48-
**Fast smoke tests**: combine test mode with the skip flags:
49-
50-
```bash
51-
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
52-
```
53-
54-
Note: `PYAUTO_SMALL_DATASETS` is deliberately **not** used in HowToGalaxy. Tutorials assume the full-resolution simulated datasets that the simulator scripts produce.
55-
56-
**Codex / sandboxed runs**: set writable cache directories so `numba` and `matplotlib` do not fail on unwritable home paths:
57-
58-
```bash
59-
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
60-
```
61-
62-
## Core API Patterns
63-
64-
Imports used throughout the tutorials:
65-
66-
```python
67-
import autofit as af
68-
import autogalaxy as ag
69-
import autogalaxy.plot as aplt
70-
```
71-
72-
## Notebooks vs Scripts
73-
74-
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.
75-
76-
### Building Notebooks
77-
78-
Run from the workspace root:
79-
80-
```bash
81-
PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py howtogalaxy
82-
```
83-
84-
The `howtogalaxy` project target needs to be added to `PyAutoBuild/autobuild/config.yaml`. This is a known follow-up from the initial bootstrap.
85-
86-
## Relationship to autogalaxy_workspace
87-
88-
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.
89-
90-
## Related Repos
91-
92-
- **PyAutoGalaxy** source: `../PyAutoGalaxy`
93-
- **autogalaxy_workspace**: `../autogalaxy_workspace` — main user-facing workspace
94-
- **PyAutoBuild**: `../PyAutoBuild` — notebook generation and CI/CD tooling
95-
## Never rewrite history
96-
97-
NEVER perform these operations on any repo with a remote:
98-
99-
- `git init` in a directory already tracked by git
100-
- `rm -rf .git && git init`
101-
- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset
102-
for AI workflow", or any equivalent message on a branch with a remote
103-
- `git push --force` to `main` (or any branch tracked as `origin/HEAD`)
104-
- `git filter-repo` / `git filter-branch` on shared branches
105-
- `git rebase -i` rewriting commits already pushed to a shared branch
106-
107-
If the working tree needs a clean state, the **only** correct sequence is:
108-
109-
git fetch origin
110-
git reset --hard origin/main
111-
git clean -fd
112-
113-
This applies equally to humans, local Claude Code, cloud Claude agents, Codex,
114-
and any other agent. The "Initial commit — fresh start for AI workflow" pattern
115-
that appeared independently on origin and local for three workspace repos is
116-
exactly what this rule prevents — it costs ~40 commits of redundant local work
117-
every time it happens.
1+
# HowToGalaxy — agent instructions
2+
The canonical, agent-agnostic instructions live in `AGENTS.md`. Claude Code loads them
3+
via the import below; if your tool does not process `@`-imports, open `AGENTS.md` in
4+
this directory and read it directly.
5+
@AGENTS.md

0 commit comments

Comments
 (0)