|
1 | 1 | # PyAutoBrain |
2 | 2 |
|
3 | | -The **reasoning layer** of the PyAuto organism. PyAutoBrain figures out *how* |
4 | | -work should be done: it hosts specialist **reasoning agents** that reason over |
5 | | -the health verdict from [PyAutoHeart](https://github.com/PyAutoLabs/PyAutoHeart) |
6 | | -and delegate execution to [PyAutoBuild](https://github.com/PyAutoLabs/PyAutoBuild). |
7 | | - |
8 | | -It owns no state, no health checks, and no release mechanics — it only reasons |
9 | | -and delegates. |
10 | | - |
11 | | -## The organism |
12 | | - |
13 | | -The PyAuto ecosystem is a software organism; each repo is an organ with one job: |
14 | | - |
15 | | -| Organ | Repo | Role | |
16 | | -|-------|------|------| |
17 | | -| **Mind** | PyAutoMind | Decides *what* should be done — intent, goals, priorities. | |
18 | | -| **Brain** | **PyAutoBrain** | Figures out *how* — reasoning, planning, orchestration. | |
19 | | -| **Hands** | PyAutoBuild | Builds and releases the software — packaging, tagging, notebooks, PyPI. | |
20 | | -| **Heart** | PyAutoHeart | Determines whether the organism is healthy. | |
21 | | -| **Memory** | PyAutoMemory | Long-term scientific / software / project knowledge. | |
22 | | - |
23 | | -In one line each: **Mind** decides what, **Brain** figures out how, **Hands** |
24 | | -build and release the software, **Heart** says whether it is healthy. |
25 | | - |
26 | | -## The split |
27 | | - |
28 | | -| Repo | Role | |
29 | | -|------|------| |
30 | | -| **PyAutoHeart** | Health authority. `pyauto-heart readiness` is the authoritative green/yellow/red release gate. Observer-only. | |
31 | | -| **PyAutoBuild** | Executor (Hands). Packaging, tagging, notebooks, PyPI via `release.yml`. No checks. | |
32 | | -| **PyAutoBrain** | Reasoning layer. Reasons over Heart's verdict, delegates execution to Build. | |
33 | | - |
34 | | -Call chain, always in this order: |
35 | | - |
36 | | -``` |
37 | | -Brain → Heart (gate) → Build (execute) |
38 | | -``` |
39 | | - |
40 | | -## Specialist reasoning agents |
41 | | - |
42 | | -Agents live in **two tiers** under `agents/`, split by one question — *does it |
43 | | -act, or only opine?* **Conductors** (`agents/conductors/`) are front doors you |
44 | | -drive: they decide *and* act, delegating execution to the organs. **Faculties** |
45 | | -(`agents/faculties/`) are read-only reasoning capabilities the conductors |
46 | | -consult: they only return a judgment and stop. Keep the conductor set small; let |
47 | | -faculties multiply behind them. |
48 | | - |
49 | | -**Conductors:** |
50 | | - |
51 | | -- **`agents/conductors/intake/`** — the conceptive function: turns raw input (an |
52 | | - idea, a bug report, an `ideas.md` bullet) into a formal, headed PyAutoMind |
53 | | - prompt. Files it; never starts dev — the step before `start_dev`. |
54 | | -- **`agents/conductors/feature/`** — the growth function: reasons over PyAutoMind |
55 | | - `feature/*` intent and plans how the organism grows. |
56 | | -- **`agents/conductors/bug/`** — the immune system: recognises a bug / regression / |
57 | | - failing test / PyAutoHeart finding, classifies it, decides where the fix belongs |
58 | | - (source-first, never degrading a user-facing script), and plans the repair. |
59 | | -- **`agents/conductors/build/`** — the executive function for execution work. |
60 | | - Consults the vitals faculty, reasons over the verdict, and on a healthy result |
61 | | - delegates to PyAutoBuild. Has `build` / `deploy` / `release` modes. |
62 | | -- **`agents/conductors/release/`** — reasons over `pyauto-heart readiness` → on |
63 | | - green, runs the PyAutoBuild release executor; also orchestrates release |
64 | | - validation (`release rehearse` / `release validate`). |
65 | | -- **`agents/conductors/health/`** — the organism's clinician: runs the health |
66 | | - loop with a human — assess → triage → (on your go-ahead) dispatch a validation |
67 | | - leg → re-judge — until Heart goes green. Consults the vitals faculty and |
68 | | - delegates dispatch to the release conductor. (Skeleton; validation + recommend.) |
69 | | - |
70 | | -**Faculties:** |
71 | | - |
72 | | -- **`agents/faculties/vitals/`** — read-only: reads the Heart's pulse — adopts the |
73 | | - PyAutoHeart readiness verdict and explains it. The single component that talks |
74 | | - to Heart. |
75 | | - |
76 | | -Brain agents **consult one another**: a conductor doesn't query Heart directly — |
77 | | -it asks the vitals faculty, which is the only agent that talks to the Heart |
78 | | -organ. |
79 | | - |
80 | | -``` |
81 | | -Mind → Build Agent → vitals faculty → Heart → GREEN/YELLOW/RED |
82 | | - → Build Agent → Build (execute) |
83 | | -``` |
84 | | - |
85 | | -Release is a **mode** of the Build Agent today (because PyAutoBuild owns |
86 | | -release/build/deploy execution), isolated so it can split into a dedicated |
87 | | -**Release Agent** later — one agent now, clean seam for two later. |
88 | | - |
89 | | -## Usage |
| 3 | +The reasoning layer of the PyAuto organism. Brain figures out *how* work |
| 4 | +gets done: it classifies incoming tasks, plans them, and routes them to |
| 5 | +specialist agents, delegating execution to the other organs. It holds no |
| 6 | +state, runs no health checks, and never releases anything itself. |
| 7 | + |
| 8 | +The organism is described once in [ORGANISM.md](ORGANISM.md). The short |
| 9 | +version: |
| 10 | + |
| 11 | +| Organ | Repo | Job | |
| 12 | +|-------|------|-----| |
| 13 | +| Mind | PyAutoMind | what to do — intent, priorities, workflow state | |
| 14 | +| Brain | PyAutoBrain (this repo) | how to do it — reasoning, planning, routing | |
| 15 | +| Heart | PyAutoHeart | is it healthy — the release-readiness verdict | |
| 16 | +| Hands | PyAutoBuild | do it — packaging, tagging, PyPI releases | |
| 17 | +| Memory | PyAutoMemory | what we know — long-term scientific knowledge | |
| 18 | + |
| 19 | +Agents live under `agents/` in two tiers: **conductors** (front doors a |
| 20 | +human drives; they decide and act) and **faculties** (read-only judgments |
| 21 | +the conductors consult). Humans mostly reach them through short slash |
| 22 | +commands — `/intake`, `/feature`, `/bug`, `/health`, `/route` — whose |
| 23 | +bodies live in `skills/`. |
90 | 24 |
|
91 | 25 | ```bash |
92 | | -bin/pyauto-brain help # list agents |
93 | | -bin/pyauto-brain build # consult vitals, then delegate execution to Build |
94 | | -bin/pyauto-brain release # reason about readiness, then release on green |
95 | | -bin/pyauto-brain health # (conductor) run the health loop with a human, toward green |
96 | | -bin/pyauto-brain vitals # (faculty) one tick + the unified dashboard card (raw read) |
| 26 | +bin/pyauto-brain help # list the agents |
| 27 | +bin/pyauto-brain vitals # one health tick + the dashboard card |
| 28 | +bash bin/install.sh # symlink every organ's skills into ~/.claude |
97 | 29 | ``` |
98 | 30 |
|
99 | | -PyAutoBrain runs from its checkout (no pip install), resolving the sibling |
100 | | -`pyauto-heart` and `autobuild` binaries from PATH or `~/Code/PyAutoLabs/`. |
101 | | - |
102 | | -`bin/` also hosts the cross-organ Claude skill **installer** (`install.sh`) and |
103 | | -line-count **guard** (`check_skill_line_counts.sh`) — organism-wide infrastructure |
104 | | -that used to live in `admin_jammy/skills/`. Run `bash PyAutoBrain/bin/install.sh` |
105 | | -to (re-)symlink every organ's skills/commands into `~/.claude/`. See |
106 | | -[`bin/README.md`](bin/README.md). |
107 | | - |
108 | | -## The command surface (Brain implicit) |
109 | | - |
110 | | -Humans drive the CLI above through short verb commands installed into |
111 | | -`~/.claude/commands/`. The Brain stays **implicit**: you type a verb (or plain |
112 | | -natural language) and it routes to the right agent — normal usage never says |
113 | | -"PyAutoBrain". |
114 | | - |
115 | | -> **Users speak in short commands; PyAutoBrain performs the routing.** |
116 | | -
|
117 | | -- **Real conductors:** `/intake` → Intake Agent (files a Mind prompt, before |
118 | | - `start_dev`), `/feature` → Feature Agent, `/bug` → Bug Agent, `/build` → |
119 | | - Build Agent, `/health` → Health Agent (each → vitals/Heart/Build as needed). |
120 | | -- **Work-type entries:** `/refactor` `/docs` `/research` route through the Brain |
121 | | - dev-flow (`start_dev`) with their PyAutoMind work-type fixed — honest interim |
122 | | - doors until each earns its own conductor. |
123 | | -- **Router + debug:** `/route <text>` infers the work-type and dispatches; |
124 | | - `/brain <agent>` is the raw passthrough. Every command routes **through** the |
125 | | - Brain; none replaces it. |
126 | | - |
127 | | -Bodies live in `skills/<verb>/<verb>.md`; shared prose in |
128 | | -[`skills/COMMANDS.md`](skills/COMMANDS.md). |
129 | | - |
130 | | -See [`AGENTS.md`](AGENTS.md) for the full description. |
| 31 | +Runs straight from its checkout — no pip install. Agent contracts and the |
| 32 | +organ boundary are in [AGENTS.md](AGENTS.md); how much a run may do without |
| 33 | +a human is the autonomy contract, [AUTONOMY.md](AUTONOMY.md). |
0 commit comments