diff --git a/AI_POLICY.md b/.github/AI_POLICY.md similarity index 100% rename from AI_POLICY.md rename to .github/AI_POLICY.md diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to .github/CONTRIBUTING.md diff --git a/ORGANISM.md b/ORGANISM.md index 98b3e98..95ec413 100644 --- a/ORGANISM.md +++ b/ORGANISM.md @@ -18,14 +18,14 @@ organs plan, build, test and release it, and you make every judgment call. | **Hands** | PyAutoHands | Builds and releases — packaging, tagging, notebook generation, PyPI via `release.yml`. A pure executor: runs no readiness checks and never re-derives a gate decision. | | **Memory** | PyAutoMemory | Long-term knowledge — *what the science says* (literature wikis, concepts, bibliographies). Operational history — *what the organism did* — lives in Mind (the `complete/` records, issues), not here. | | **Gut** | PyAutoGut | Owns the lifecycle of *condemned self-material* — stale branches, stashes, dead code/tests. Holds each as a durable, recoverable git ref through a transit window and **voids** it on a sweep. The storage mirror of Memory (retention ↔ release); the hygiene conductor drives it, as vitals reads Heart. | -| **Nerves** | PyAutoConf | The configuration/serialization layer (`autoconf`) — layered config with overrides, the workspace↔library version handshake, `test_mode`, FITS/JSON I/O. Connects the organism's conventions to every library; the base layer the scientific libraries all import. The seventh organ. | +| **Nerves** | PyAutoNerves | The configuration/serialization layer (`autonerves`) — layered config with overrides, the workspace↔library version handshake, `test_mode`, FITS/JSON I/O. Connects the organism's conventions to every library; the base layer the scientific libraries all import. The seventh organ. | *Hands* and *Build* name the **same organ** (PyAutoHands) throughout this document: the organ is the **Hands**, and *Build* is the call-chain step it performs. (The Hands repo was renamed PyAutoBuild → PyAutoHands; the *Build* -call-chain shorthand and the `autohands` package/CLI keep their names. -`PyAutoConf` likewise remains the Nerves repo's name, aligned with its -`autoconf` package.) +call-chain shorthand and the `autohands` package/CLI keep their names. The +Nerves repo was likewise renamed PyAutoConf → PyAutoNerves, its package +`autoconf` → `autonerves`.) The scientific libraries (PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens) and the workspaces are **capabilities the organism uses, not organs**. The full @@ -67,6 +67,6 @@ script), not as a repo. A new organ costs an `AGENTS.md`, a `CLAUDE.md` stub, install wiring, a body-map row and boundary prose — it must earn that by owning state or effects no existing organ can. Configuration/signalling is the one standing exception that already earned organ status: it is the **Nerves** -(PyAutoConf), the base config/serialization layer every library imports — new +(PyAutoNerves), the base config/serialization layer every library imports — new config surfaces belong there, not in a new organ. The human interaction layer is the command surface (`/route` + the verb commands), which is part of Brain. diff --git a/README.md b/README.md index 01d052e..a3103be 100644 --- a/README.md +++ b/README.md @@ -6,37 +6,58 @@ [![PyAutoScientist GitHub](https://img.shields.io/badge/%E2%9A%9B%EF%B8%8F%20PyAutoScientist-GitHub-181717?style=flat-square)](https://github.com/PyAutoLabs/PyAutoScientist) [![PyAutoScientist ReadTheDocs](https://img.shields.io/badge/%F0%9F%93%96%20PyAutoScientist-ReadTheDocs-8CA1AF?style=flat-square)](https://pyautoscientist.readthedocs.io) -The reasoning layer of the PyAuto organism. Brain figures out *how* work -gets done: it classifies incoming tasks, plans them, and routes them to -specialist agents, delegating execution to the other organs. It holds no -state, runs no health checks, and never releases anything itself. - -The organism is described once in [ORGANISM.md](ORGANISM.md). The short -version: - -| Organ | Repo | Job | -|-------|------|-----| -| Mind | PyAutoMind | what to do — intent, priorities, workflow state | -| Brain | PyAutoBrain (this repo) | how to do it — reasoning, planning, routing | -| Heart | PyAutoHeart | is it healthy — the release-readiness verdict | -| Hands | PyAutoHands | do it — packaging, tagging, PyPI releases | -| Memory | PyAutoMemory | what we know — long-term scientific knowledge | -| Gut | PyAutoGut | what we shed — condemned branches, stashes and dead code, held recoverably then voided | - -Agents live under `agents/` in two tiers: **conductors** (front doors a -human drives; they decide and act) and **faculties** (read-only judgments -the conductors consult). Humans mostly reach them through short slash -commands — `/intake`, `/feature`, `/bug`, `/health`, `/route` — whose -bodies live in `skills/`. +**PyAutoBrain is the Brain of the PyAutoScientist** — the reasoning layer that +turns intent into shipped software. It decides *how* work gets done: it +classifies each task, plans it, and routes it to specialist agents — and it +delegates everything else: it holds no state (the Mind's job), runs no health +checks (the Heart's), and never releases anything itself (the Hands'). + +You drive it in plain English, through short slash commands in a Claude Code +chat: `/intake` to file an idea, `/start_dev` to begin a task, `/health` for a +check-up — or just `/route ` and the Brain picks the right +door. The full command surface (13 conductors + 5 faculties) is the generated +table in [AGENTS.md](AGENTS.md). + +## How PyAutoBrain works + +1. **A task arrives.** Usually from the Mind's backlog — pick a task on the + [PyAutoMind dashboard](https://pyautolabs.github.io/PyAutoMind/) and paste + its `/start_dev` command — or free-form, via `/route` or any conductor's + own door. +2. **A conductor takes it.** Conductors ([`agents/conductors/`](agents/conductors)) + are the front doors a human drives; they decide *and* act: `intake` + conceives tasks, `feature`/`bug`/`refactor` plan development, `health` + runs the clinic, `release` drives a release, and so on. +3. **Faculties advise.** Faculties ([`agents/faculties/`](agents/faculties)) + are read-only opinions the conductors consult: `vitals` reads the Heart's + verdict, `sizing` estimates difficulty, `memory` recalls what the organism + knows, `review` judges a branch. A conductor never consults another + conductor — an opinion worth sharing becomes a faculty. +4. **The organs execute.** Always in the same order — **Brain → Heart (gate) + → Hands (execute)**: work happens on task worktrees, ships as pull + requests behind the Heart's health verdict, and is packaged and released + by the Hands. +5. **Autonomy is a contract.** How much a run may do without a human is + defined per task in [AUTONOMY.md](AUTONOMY.md) — a safe-capped task may + carry itself to an open pull request; merging and releasing always stay + human. + +## CLI examples + +The same agents are runnable directly — every slash command is a verb of one +CLI, which runs straight from this checkout (no pip install): ```bash -bin/pyauto-brain help # list the agents -bin/pyauto-brain vitals # one health tick + the dashboard card -bash bin/install.sh # symlink every organ's skills into ~/.claude +bin/pyauto-brain help # list every conductor and faculty +bin/pyauto-brain route "fix the failing lens smoke test" # plain English in +bin/pyauto-brain vitals # read the Heart's readiness verdict +bash bin/install.sh # symlink every organ's skills into ~/.claude ``` -Runs straight from its checkout — no pip install. Agent contracts and the -organ boundary are in [AGENTS.md](AGENTS.md); how much a run may do without -a human is the autonomy contract, [AUTONOMY.md](AUTONOMY.md). The full -organism documentation — including how to fork and run your own — is at - (source: `docs/`). +The seven organs the Brain coordinates — Mind (intent), Brain (reasoning), +Heart (health), Hands (release), Memory (knowledge), Gut (shedding), Nerves +(configuration) — are defined once in [ORGANISM.md](ORGANISM.md), which this +repo hosts. Agent contracts and the generated command table are in +[AGENTS.md](AGENTS.md). The full organism documentation — including how to +fork it and lead your own — is at , +whose source lives here in [`docs/`](docs). diff --git a/docs/example.md b/docs/example.md index c741593..50d8fae 100644 --- a/docs/example.md +++ b/docs/example.md @@ -10,7 +10,7 @@ replaces every name below with your own. The live `repos.yaml` declares ~25 repos. The load-bearing categories: -- **Libraries:** PyAutoConf (shared config), PyAutoFit (Bayesian +- **Libraries:** PyAutoNerves (shared config), PyAutoFit (Bayesian inference), PyAutoArray (data structures), PyAutoGalaxy (galaxy modelling), PyAutoLens (strong lensing), PyAutoReduce (data reduction) — a dependency chain released to PyPI nightly when there is new activity. diff --git a/skills/repo_cleanup/SKILL.md b/skills/repo_cleanup/SKILL.md index 452328b..66a0a44 100644 --- a/skills/repo_cleanup/SKILL.md +++ b/skills/repo_cleanup/SKILL.md @@ -54,7 +54,7 @@ this covers residue when that flow is skipped); the start_dev branch survey ## Scope -**Always swept:** library canonical checkouts under `$PYAUTO_MAIN` (PyAutoConf, +**Always swept:** library canonical checkouts under `$PYAUTO_MAIN` (PyAutoNerves, PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens, PyAutoHands); workspaces incl. `_test`/`_developer` variants (autofit/autogalaxy/autolens families, HowToLens); and worktree roots under `$PYAUTO_WT_ROOT`. diff --git a/skills/sampler_pipeline/reference.md b/skills/sampler_pipeline/reference.md index ecb5257..6cef48c 100644 --- a/skills/sampler_pipeline/reference.md +++ b/skills/sampler_pipeline/reference.md @@ -19,7 +19,7 @@ Given a GitHub URL, before writing any adapter code: example (e.g. nessai routes users to a `nessai-bilby` plugin), go to the docs site and examples dir — never guess an API from the package name. 2. **Dependency-compatibility check** against the installed stack *before* - `pip install`: Python floor, JAX pin overlap with PyAutoConf's `[jax]` + `pip install`: Python floor, JAX pin overlap with PyAutoNerves's `[jax]` floor/ceiling, and heavyweight extras (a PyTorch-core sampler like nessai brings CUDA-pinning risk beside the JAX stack). Under-declared floors are real (the nufftax lesson) — check what the code imports, not just diff --git a/skills/ship_library/ship_library.md b/skills/ship_library/ship_library.md index 8ffacc0..2a7260b 100644 --- a/skills/ship_library/ship_library.md +++ b/skills/ship_library/ship_library.md @@ -1,6 +1,6 @@ # Ship Library: Gate, Test, PR -Ship source-library changes (PyAutoConf, PyAutoFit, PyAutoArray, PyAutoGalaxy, +Ship source-library changes (PyAutoNerves, PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens) for every library repo touched by the task. This is **feature-development** work — the commit/push/feature-PR is the dev workflow's own execution, gated by Heart. It is **not** a Build task (Build is diff --git a/skills/start_library/start_library.md b/skills/start_library/start_library.md index a29ec2b..8b76836 100644 --- a/skills/start_library/start_library.md +++ b/skills/start_library/start_library.md @@ -1,6 +1,6 @@ # Start Library: Set Up Library Development -Set up the development environment for **library source-code** work (PyAutoConf, +Set up the development environment for **library source-code** work (PyAutoNerves, PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens). Assumes `/start_dev` already registered the task in `PyAutoMind/active.md`.