PyAutoBrain

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').

See the PyAutoBrain Dashboard for agents and workflows, a starting point for unspecified tasks, overnight exceptions and maintenance. Brain interprets intent and coordinates work; operational evidence stays with its owning organ.

How PyAutoBrain works

You drive it in plain English, through discoverable skills in Codex or slash commands in Claude Code chat: /intake to file an idea, /start_dev to begin a task, /health for a check-up — or just /route <what you want> and the Brain picks the right door. The generated table in AGENTS.md is the roster — every conductor and faculty, regenerated from the router.

1. A task arrives. Usually from the Mind's backlog — pick a task on the PyAutoMind dashboard 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/) 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/) 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) → Build (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 — 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):

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                        # install shared skills for Claude Code and Codex

Project discovery is generated separately from the registered repository body map. For example, after adding an assistant skill:

bash bin/install.sh --write-project-discovery autolens_assistant
bash bin/install.sh --check-project-discovery autolens_assistant

Without repository arguments these commands cover registered checkouts with canonical skills/ content. Flat assistant skills keep their Claude names and get namespaced Codex adapters; workspace skills use neutral skills/<name>/SKILL.md bodies. Codex discovery descriptions are bounded summaries; the linked canonical file retains the full instructions. Commit the generated adapters with the skill. Regeneration checks name collisions across the installed repository inventory and refuses conflicting user-owned destinations.

The eleven organs the Brain coordinates — Brain (reasoning), Mind (intent), Cortex (learning what is true), Memory (knowledge), Eyes (seeing the figures), Ears (community listening), Heart (health), Hands (release), Pulse (feeling how fast it runs), Insight (inference campaigns and evidence), Nerves (configuration), Gut (shedding) — are defined once in ORGANISM.md, which this repo hosts. Agent contracts and the generated command table are in AGENTS.md. The full organism documentation — including how to fork it and lead your own — is at https://pyautoscientist.readthedocs.io, whose source lives here in docs/.