Imported from PyAutoLabs/PyAutoBrain (
AGENTS.md). Install upstream withnpx skills add PyAutoLabs/PyAutoBrain. Copyright stays with the author.
PyAutoBrain — Agent Guidance
This file is for AI coding agents (Claude Code, Codex, Cursor, etc.) and humans discovering this repository. It is the canonical description of PyAutoBrain — the reasoning layer of the PyAuto organism — and of the Brain / Heart / Build boundary; PyAutoHands and PyAutoHeart point back here.
The organism map
You are one organ of the PyAuto organism — an agentic ecosystem for
human-led, natural-language software development. The organs below are
peer repositories; this repo is one of them, not a part of another.
Canonical boundaries live in PyAutoBrain/ORGANISM.md; the full body map
(every repo, not just organs) is PyAutoMind/repos.yaml.
| Organ | Repo | Role |
|---|---|---|
| Brain | PyAutoBrain | Reasoning/orchestration layer; how work is decomposed and routed; the specialist agents. |
| Mind | PyAutoMind | Intent, goals, priorities, workflow state; every task starts as a markdown prompt here. |
| Cortex | PyAutoCortex | The Cortex — where the organism keeps track of what is true: the science body map (projects.yaml) and one ledger per science project (what was run, what came back, what was learned, where to pick up); the science mirror of the Mind (runs and a dated log, not prompts and PRs). |
| Memory | PyAutoMemory | Long-term scientific/software/project knowledge (see science pointer below). |
| Eyes | PyAutoEyes | The Eyes — where the organism sees what its figures look like: the cross-project visualization dashboard over the <lib>_visualization project repos (autolens_visualization, autogalaxy_visualization, autofit_visualization and autocti_visualization) — the registry of those repos, the tracked-manifest read contract (gallery/viz_manifest.yaml) and the Pages board that links to their PNGs as the single point of contact for the visual behaviour of the whole ecosystem. Renders nothing and copies no figures (the project repos render and hold them); never judges them (the Brain's Eyes conductor does) and never edits library plot code (critiques route through intake). |
| Ears | PyAutoEars | The Ears — the community listening organ: owns read-only public conversation collection, the versioned community snapshot contract, coverage receipts and the dashboard. GitHub conversations remain authoritative; Brain’s Community conductor owns judgement, reply drafts and development routing, and Mind owns task state. Never posts replies, labels or issues, exports raw transcripts or private sources, or treats unknown coverage as no work. |
| Heart | PyAutoHeart | Health/readiness — the authoritative "is it safe to release?" verdict. |
| Hands | PyAutoHands | Packaging, tagging, notebook generation, PyPI release execution. |
| Pulse | PyAutoPulse | The Pulse — where the organism feels how fast it runs: the cross-project profiling dashboard over the <lib>_profiling project repos (today autolens_profiling) — campaign intent and pending domain tasks, the instance registry, the versioned profiling-summary read contract (v1 live at autolens_profiling/dashboard/summary.json), the ingest receipts (resolved commit per project per render) and the Pages board. Validates the exchange contract only; never moves pins, combines unmatched timings, applies the compile threshold to runtime, computes an ecosystem-wide speed score or issues a Heart verdict, and never judges (the Brain's profiling conductor does); the project repos keep their producers, results, drift policy and their own Pages page. |
| Insight | PyAutoInsight | Owns inference campaign intent and pending domain tasks, the cross-project inference instance registry, versioned inference-summary read contract, ingest receipts and evidence dashboard. Projects own execution, producers and raw samples; Cortex owns scientific run records, observations and human conclusions; Mind owns bounded implementation lifecycle and repository claims. Never infers scientific acceptance from execution, ranks incompatible runs or submits compute on refresh. |
| Nerves | PyAutoNerves | The Nerves — the configuration/serialization layer connecting workspace conventions to libraries (layered config, version handshake, test_mode), delivered as the autonerves package. |
| Gut | PyAutoGut | Owns the lifecycle of condemned self-material (stale branches, stashes, dead code/tests): holds it as durable, recoverable git refs through a transit window and voids it on a sweep. The storage mirror of Memory (retention vs release). |
Call chain (always this order): Brain → Heart (gate) → Build (execute). Brain agents are conductors (front-door; a human drives them; they decide and act) or faculties (read-only opinions the conductors consult; they judge and stop). New capability grows as a faculty, not a new organ, unless it owns state or effects no existing organ can.
Generated from PyAutoMind/repos.yaml + PyAutoBrain/ORGANISM.md; edit there, then run python3 PyAutoMind/scripts/repos_sync.py --write.
Working here
Brain plans and coordinates; it owns no task state, health checks or release mechanics. Mind owns intent/state, Heart gates readiness, Hands executes releases. Use conductors for decisions and actions; faculties return read-only judgments. The consultation graph is a DAG: conductors consult faculties, not conductors. See ORGANISM.md for boundaries and AUTONOMY.md for checkpoint rules. Add a role only on demonstrated need.
For development use skills/WORKFLOW.md, then the invoked
skill. Read only its current step and applicable environment. Reuse unchanged
instructions already loaded; use context discipline.
For new agents or command wiring, read agent reference.
Add registry entries in bin/pyauto-brain and the agent directory; regenerate
this command table with bin/install.sh --write-agents-surface, never by hand.
Running
Run from the Brain checkout. Read the selected agent's AGENTS.md only when
invoking it; bin/pyauto-brain help <verb> exposes its full contract.
Conductors — front doors you drive (decide and act):
| Verb | Purpose | Entrypoint |
|---|---|---|
intake |
File classified prompts; never start development | bin/pyauto-brain intake |
batch |
Propose a review-budgeted batch; collect its results | bin/pyauto-brain batch |
community |
Triage community threads; human-approved replies and development handoffs | bin/pyauto-brain community |
feature |
Select, size and plan features | bin/pyauto-brain feature |
bug |
Classify regressions and plan repairs | bin/pyauto-brain bug |
refactor |
Plan behavior-preserving restructuring | bin/pyauto-brain refactor |
workspace |
Plan or survey examples and tutorials | bin/pyauto-brain workspace |
eyes |
Survey figures and route accepted critiques | bin/pyauto-brain eyes |
profiling |
Plan campaigns; ingest results; triage profiling drift | bin/pyauto-brain profiling |
cortex |
Pull science runs and record human checkins | bin/pyauto-brain cortex |
hygiene |
Prioritize upkeep and delegate fixes | bin/pyauto-brain hygiene |
clone |
Plan assistant births or synchronize generic files | bin/pyauto-brain clone |
build |
Consult vitals and coordinate Hands execution | bin/pyauto-brain build |
release |
Coordinate release rehearsal, validation and nightly execution | bin/pyauto-brain release |
health |
Assess health and route repairs | bin/pyauto-brain health |
Faculties — read-only opinions the conductors consult (also runnable):
| Verb | Purpose | Entrypoint |
|---|---|---|
vitals |
Read authoritative Heart readiness | bin/pyauto-brain vitals |
review |
Prepare independent CLEAN/FINDINGS/BLOCKED branch review | bin/pyauto-brain review |
memory |
Recall cited scientific and task history | bin/pyauto-brain memory |
samplers |
Inspect sampler coverage, tiers and benchmarks | bin/pyauto-brain samplers |
sizing |
Estimate task difficulty | bin/pyauto-brain sizing |
Like the other PyAuto repos, PyAutoBrain runs from its checkout (no pip install);
it resolves the sibling pyauto-heart and autohands binaries from PATH or the
~/Code/PyAutoLabs/ checkouts.
Remote sessions (Claude Code on web and mobile)
Three facts, measured in a web/mobile container. A session holding several organs is cwd'd at the repos' parent, where no project hook fires, so nothing has set it up — this block is what does.
- Bootstrap in the first turn, unconditionally — before the first test
command, not as a remedy:
bash PyAutoMind/scripts/session_bootstrap.sh(--checkreports only). It supplies pytest/PyYAML/xdist and unshallows the clones, without whichgit merge-base --is-ancestorcalls a merged branch "not an ancestor" and the close-out acts on it. - Run the suite in parallel:
python3 -m pytest -q -n auto(4 cores, ~3.5x). - There is no
gh, and installing one does not help — it authenticates, then 403s every repo-scoped call through the egress proxy. GitHub is themcp__github__*tools;PyAutoBrain/skills/GITHUB_ACCESS.mdmaps eachghoperation onto its tool and is the one full page on the subject.
Commands and communication
Users invoke verbs or natural language; Brain stays implicit. /docs and
/research fix a dev work type; /prm merges and closes out a task; /brain
is a raw passthrough. Canonical bodies are skills/<verb>/<verb>.md, discovered
through thin SKILL.md wrappers. The morning surface is board/; local sync
uses bin/morning.sh. /wake_up is the fallback when the board is unavailable.
Answer first, briefly; link instead of pasting. Expand plans awaiting approval, decision surfaces, failures/blockers and requested explanations enough to judge. Keep structured decisions, review surfaces and verdicts complete. These rules apply to surrounding chat, not to the defined artifact schema.
Never rewrite history
Never rewrite pushed history on any repo with a remote — no git init over a
tracked repo, no force-push to main, no fresh-start "Initial commit", no
filter-repo / filter-branch / rebase -i on pushed branches. To get a
clean tree: git fetch origin && git reset --hard origin/main && git clean -fd.
Sessions end at their deliverable
A session ends when it reports its deliverable — never arm anything that
outlives the turn to wait for CI, a review or a merge: no send_later, no
subscribe_pr_activity, no CronCreate, no ScheduleWakeup, no /loop, no
RemoteTrigger create/update/run. Judge once, report, stop; the human re-runs
/prm (or the batch review) when it is green. Measured: five batch members
armed hourly check-ins on 2026-08-31, and a mobile /prm re-armed a 60-minute
send_later hourly all night on 2026-09-03 with no task active, draining usage.
Where to file
Questions, help with code or an analysis, ideas, bug reports and results from a
user or collaborator — or an agent acting for one — go to
https://github.com/orgs/PyAutoLabs/discussions in the matching category
(Help & Questions, Ideas & Proposals, Bugs & Errors, Show and tell;
Announcements is maintainers-only), never to this repo's Issues. An agent never
runs gh issue create for such a report: it drafts the title, category and
body and hands them to the human (sessions cannot create Discussions). Only the
development flow — Mind prompt → /start_dev → /create_issue → one issue per
task → PR — opens issues here. Why: PyAutoMind/policy/community_surface.md.
Codex loads this repo's generated safety registrations from .codex/hooks.json
only after the project layer and exact current hook hash are reviewed and trusted
with /hooks; changed or untrusted hooks are skipped. The adapter registers the
shared-Mind commit guard and end-at-deliverable guard. It intentionally does not
copy the Claude remote-session Python SessionStart bootstrap; local Codex work
continues to source the workspace activate.sh normally.
