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.
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 |
|---|---|---|
| Mind | PyAutoMind | Intent, goals, priorities, workflow state; every task starts as a markdown prompt here. |
| Brain | PyAutoBrain | Reasoning/orchestration layer; how work is decomposed and routed; the specialist agents. |
| Hands | PyAutoHands | Packaging, tagging, notebook generation, PyPI release execution. |
| Heart | PyAutoHeart | Health/readiness — the authoritative "is it safe to release?" verdict. |
| Memory | PyAutoMemory | Long-term scientific/software/project knowledge (see science pointer below). |
| 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). |
| Nerves | PyAutoNerves | The Nerves — the configuration/serialization layer connecting workspace conventions to libraries (layered config, version handshake, test_mode), delivered as the autonerves package. |
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.
PyAutoBrain is the reasoning layer of the PyAuto ecosystem as it grows into a software organism. It figures out how work should be done and coordinates the organs that do it. It hosts specialist reasoning agents — each a documented role plus a deterministic entrypoint script — that read intent (from PyAutoMind and the developer), reason about it, and drive the health/execution machinery at the right points.
PyAutoBrain owns no state, no health checks, and no execution mechanics. It only reasons and delegates: it asks PyAutoHeart whether the organism is healthy, decides whether and how to proceed, and tells PyAutoHands to execute when it should.
The organs, their boundaries, and the Brain → Heart (gate) → Build (execute)
call chain are defined once in ORGANISM.md — this repo
hosts that canonical page; every other organ links to it. In one line: the
Mind decides what, the Brain (this repo) figures out how, the Heart gates,
the Hands build, Memory knows what the science says.
Brain agents are not limited to driving organs — they can consult each other. The canonical example is the Build Agent, which does not query Heart directly: it consults the vitals faculty, and only the vitals faculty talks to the Heart organ. So the Build Agent's full chain is:
Mind → Build Agent → vitals faculty → Heart → GREEN/YELLOW/RED
→ Build Agent → Build (execute)
The consult graph is a DAG (see ORGANISM.md): conductors
consult faculties; faculties read their sensor organ; a conductor never
consults another conductor — if it wants one's opinion, that opinion should be
a faculty. The Build Agent is the reusable template for this pattern.
How much human checkpointing a workflow run needs is defined once in
AUTONOMY.md — the autonomy contract mapping each Mind-prompt
Autonomy: level to behaviour at every checkpoint.
Agents live in two tiers under agents/, distinguished by one question —
does it act, or only opine?
- Conductors (
agents/conductors/<name>/) — front-door agents a human drives. They decide and act, delegating execution to the organs. They have side effects in the world (a plan driven into dev, a build, a release). This is the small, curated set of things you invoke and converse with. - Faculties (
agents/faculties/<name>/) — read-only reasoning capabilities the conductors consult. They only opine — return a judgment and stop; they never dispatch or mutate. They are sinks in the consult graph (everything reaches into them; they reach out only to their sensor organ). Not chat-first surfaces, though they stay runnable for a quick read.
The rule of thumb: keep the conductor set small and human-meaningful; let faculties multiply behind them. A side-effecting decider is a conductor; a side-effect-free opinion is a faculty.
Each agent is a directory with an AGENTS.md (what it reasons about + how to run
it) and a deterministic entrypoint script (*.sh / *.py) — the part CI and
humans invoke identically, so behaviour isn't re-derived from prose each time.
New agents are added on demonstrated need, never for symmetry. Place by
tier: a side-effecting decider you drive → agents/conductors/<name>/; a
read-only opinion the conductors consult → agents/faculties/<name>/. Follow
the Build Agent's shape (a concise AGENTS.md opening with its Tier: line, a
deterministic entrypoint, and a capability audit of any organ it drives — the
Feature Agent's MIND_TAXONOMY.md is that audit for the PyAutoMind/PyAutoMemory
surface). Keep the conductor set small; prefer a faculty when the new thing
only reasons.
Scaling invariant. The per-agent roster is not maintained here. Adding an
agent touches only bin/pyauto-brain (the registry) and the agent's own
directory (agents/<tier>/<name>/ with its AGENTS.md + entrypoint). The verb
tables below are generated from that registry by
bin/install.sh --write-agents-surface — never hand-edit this file's roster,
and read each agent's own AGENTS.md for its full role.
The PyAuto command surface — every agent verb, runnable on any tool (Claude,
Codex, Cursor; CLI or web) as bin/pyauto-brain <verb>. This block lives once in
PyAutoBrain's auto-loaded AGENTS.md, which is present in every session, so the
full verb set is always in context — no per-organ copy needed. Invoking a verb
runs its entrypoint here in PyAutoBrain. On Claude Code the same verbs are also
the /<verb> slash commands.
Conductors — front doors you drive (decide and act):
| Verb | Purpose | Entrypoint |
|---|---|---|
intake |
Conceive a task: turn raw input into a formal, headed PyAutoMind prompt (files it; never starts dev) | bin/pyauto-brain intake |
community |
The ears — the organism's receptive function: scan/triage user-filed GitHub issues + PRs and review requests across the repos; drafts stay human-gated, dev work routes via start_dev_for_user (never posts) | bin/pyauto-brain community |
feature |
Reason over PyAutoMind feature tasks: select, size, phase, plan for start_dev | bin/pyauto-brain feature |
bug |
The immune system: classify a bug/regression/Heart finding, locate the fix, plan the repair | bin/pyauto-brain bug |
refactor |
The renewal function: plan behaviour-preserving restructuring — RefactorDecision; default-safe under --auto | bin/pyauto-brain refactor |
workspace |
The voice — the organism's expressive function: plan/survey workspace + HowTo example authorship (workspace|howto registers) — WorkspaceDecision (never writes) | bin/pyauto-brain workspace |
eyes |
The perceptive function — the organism's sense of its own appearance: survey/review a visualization workspace's figure surface, critiques route to intake/start_dev — EyesSurvey/EyesReviewSurface (never renders, never edits) | bin/pyauto-brain eyes |
profiling |
The proprioceptive function — the organism's sense of its own effort: campaign/ingest/triage plans over the autolens_profiling workspace — ProfilingDecision | bin/pyauto-brain profiling |
hygiene |
The maintenance function — the organism's sense of its own upkeep: code-quality debt (dev-loop cost + tidiness), delegating fixes — HygieneDecision | bin/pyauto-brain hygiene |
clone |
The Mitosis Agent: partition the reference assistant, analyze the domain, emit the CloneDecision; --apply --mode lightweight-seed delegates the seed birth to Build; 'clone sync' patches the reference's generic-file diff onto the born siblings (dry run by default; rejected hunks are a human decision) | bin/pyauto-brain clone |
build |
Coordinate execution: consult the vitals faculty, then delegate to PyAutoHands | bin/pyauto-brain build |
release |
Release door → the Build Agent release mode (single gate); 'release rehearse'/'release validate' drive release validation; 'release nightly' is the scheduled-nightly driver | bin/pyauto-brain release |
health |
The organism's clinician: run the health loop with a human, dispatch by dispatch, toward green | bin/pyauto-brain health |
Faculties — read-only opinions the conductors consult (also runnable):
| Verb | Purpose | Entrypoint |
|---|---|---|
vitals |
Read-only: read the Heart's pulse — the PyAutoHeart readiness verdict (consulted by the conductors) | bin/pyauto-brain vitals |
review |
Read-only: prepare the branch ReviewSurface — the reviewing agent maps it to CLEAN/FINDINGS/BLOCKED (the ship gate's review leg) | bin/pyauto-brain review |
memory |
Read-only: recall what the organism knows — a cited digest over PyAutoMemory, autolens_assistant and Mind history | bin/pyauto-brain memory |
samplers |
Read-only: the motor faculty — SamplerSurface digest over the sampler script tiers, the PyAutoFit search catalogue and the benchmark record | bin/pyauto-brain samplers |
sizing |
Read-only: the SizingSurface — a difficulty estimate for a PyAutoMind prompt; the single heuristic the intake and feature conductors both consult | 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.
Three facts, all measured in a web/mobile container, where this file is loaded and little else is. They ride in every organ because a session may hold any subset of them — and the session that needs this most is the one holding several, which is exactly the session no hook fires in.
-
Bootstrap in the first turn, unconditionally — before the first test command, not as a remedy once something looks wrong:
bash PyAutoMind/scripts/session_bootstrap.sh # ~10s cold, ~1s warm bash PyAutoMind/scripts/session_bootstrap.sh --check # report onlyA session holding several organs registers no SessionStart hook — Claude Code reads project hooks from the project directory, which in that layout is the repos' parent, not a repo — so nothing has set this session up. It was once phrased as a remedy keyed to
No module named pytestor collectionImportErrors namingyaml; that symptom stopped appearing when the container image moved to Python 3.12, while the environment is still wrong in ways that read like a bad command rather than a stale session (pytest -n auto→unrecognized arguments: -n). The bootstrap also unshallows the clones: a remote session clones shallow, andgit merge-base --is-ancestorthen answers "not an ancestor" for a commit whose ancestry is merely absent — the answer the ship and close-out procedures act on when proving a branch merged. -
Then run the suite in parallel. 4 cores, subprocess-heavy suites, no single slow test: about 3.5x.
python3 -m pytest -q -n auto, withpytest-xdistsupplied by the bootstrap above. -
There is no
gh, and installing one does not help. A remote session reaches GitHub through themcp__github__*tools, already scoped to the session's repos.ghinstalls in two seconds and is a trap: it authenticates, then 403s every repo-scoped call, because the egress proxy serves neither the REST repo paths nor GraphQL beyond a pinned set of PR-review operations — a binary that looks healthy and fails everything that matters. It also defeats the surface probe, which keys offgh auth status. ReadPyAutoBrain/skills/GITHUB_ACCESS.mdat the top of any run that touches GitHub; it maps eachghoperation onto its MCP tool. Spell that path from the workspace root, as written: a multi-organ session is cwd'd at the repos' parent, so a bareskills/…reads as a missing file rather than a missing repo prefix.
The verb table above is the machinery; humans drive it through short commands
(/intake, /feature, …) in Claude Code, or discoverable skills in Claude and
Codex. The Brain stays implicit — you type a verb, or plain natural language
via /route, and it routes to the right agent; normal usage never says
"PyAutoBrain". A few commands are compositions rather than single agents:
/docs and /research route through the dev-flow with their PyAutoMind
work-type fixed (no dedicated conductor — added only on demonstrated need, never
for symmetry); /prm composes the
end-of-task close-out (CI green → merge → issue closed → Mind active/ →
complete/ → dashboard reconciled and regenerated → worktree and local branches
removed); /brain <agent> is the raw passthrough. Every command routes through the Brain;
none replaces it.
The morning routine is not a command at all: the Brain board
(board/_board.py, published to the Brain's GitHub Pages URL each morning by
brain_board.yml) carries what /wake_up used to assemble — overnight runs,
readiness, community, resume, upkeep — as one-tap 📋 payloads, and
bin/morning.sh is the local sync/clean leg you run in a terminal.
/wake_up remains only as the fallback door when the board is unreachable.
The command bodies live in skills/<verb>/<verb>.md; thin SKILL.md wrappers
make the same canonical workflows discoverable to skill-aware harnesses.
bin/install.sh installs both surfaces without duplicating their bodies. Shared
architecture prose is in skills/COMMANDS.md; the
work-type taxonomy the router uses is PyAutoMind/ROUTING.md.
The default register for chat replies is concise — every harness and every session (Claude Code CLI, web, mobile; Codex; Cursor). A reply is the smallest thing that answers the question and says what changed. It is not a report on the work.
- Answer first. Lead with the answer, the verdict, or what you did. No preamble, no restatement of the request, no summary of the summary.
- A few lines is the default length. One line is a good answer. Prose paragraphs, file-by-file inventories and "what I did / why / next steps" scaffolding are opt-in, not the baseline.
- Don't narrate the work. Skip the tool-by-tool commentary, the list of files read, and any recap of a diff the human can read on the branch or PR.
- Link, don't paste. Point at the file, the issue, the PR, the prompt under
PyAutoMind/draft/; quote only the lines being discussed.
Four things are never compressed: a plan awaiting approval, a decision surface a human must judge, a failure or blocker (say exactly what broke and where), and anything the human asked to have explained. Brevity is not a licence to drop the detail a decision needs.
The escape hatch is a word — "expand", "in full", "explain" — and it applies to that reply, not the session; the register comes back on the next turn.
Agent output is not chat and keeps its defined shape: a *Decision, a
ReviewSurface, a vitals verdict, the board digest are structured artefacts
this register does not trim. It governs the prose around them. On Claude Code
the same default can also be pinned per-tool with an output style, but the
register above is the portable one — it travels with the repo to every harness.
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.