Skip to content

Commit 4851f8c

Browse files
Jammy2211claude
authored and
Jammy2211
committed
docs: the pyautoscientist RTD source — 13 pages, docs CI, CONTRIBUTING (Phase 2, PyAutoBrain#68)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 58ef4ed commit 4851f8c

21 files changed

Lines changed: 768 additions & 1 deletion

‎.github/workflows/docs.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Docs
2+
3+
# Docs build check is defined once, centrally, in PyAutoHeart's reusable
4+
# workflow (Heart owns all health/readiness checking). This thin caller
5+
# builds the Sphinx docs on PRs and fails on warning-count regression
6+
# against docs/sphinx_warning_baseline.txt. PyAutoBrain is not a pip
7+
# package, so it uses the workflow's docs-only mode.
8+
9+
on:
10+
push:
11+
branches: [main]
12+
paths:
13+
- "docs/**"
14+
- ".readthedocs.yaml"
15+
- ".github/workflows/docs.yml"
16+
pull_request:
17+
paths:
18+
- "docs/**"
19+
- ".readthedocs.yaml"
20+
- ".github/workflows/docs.yml"
21+
workflow_dispatch:
22+
23+
jobs:
24+
docs:
25+
uses: PyAutoLabs/PyAutoHeart/.github/workflows/docs-build.yml@main
26+
with:
27+
package: pyautoscientist
28+
secrets: inherit

‎.readthedocs.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: 2
2+
3+
build:
4+
os: ubuntu-22.04
5+
tools:
6+
python: "3.12"
7+
8+
python:
9+
install:
10+
- requirements: docs/requirements.txt
11+
12+
sphinx:
13+
configuration: docs/conf.py
14+
fail_on_warning: false

‎CONTRIBUTING.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Contributing
2+
3+
The PyAutoScientist organs (PyAutoBrain, PyAutoMind, PyAutoHeart,
4+
PyAutoBuild, PyAutoMemory) are a **living reference implementation** — the
5+
maintainer's daily working system, not a stable library.
6+
7+
What that means in practice:
8+
9+
- **`main` moves fast** — hundreds of commits a quarter — and there are
10+
**no compatibility promises**. Anything may be renamed, rewired or
11+
removed when the live system needs it.
12+
- **Adopt by fork-and-pull, never by tracking.** Fork the organs, confine
13+
your changes to the declared config surfaces, and pull upstream at your
14+
own pace — the model is documented in the
15+
[adoption guide](https://pyautoscientist.readthedocs.io/en/latest/adoption/guide.html).
16+
Pin what you depend on.
17+
- **Issues and PRs are welcome**, and read with interest — but triage pace
18+
is set by the live instance's needs, and PRs that genericise working
19+
production prompts (`skills/*.md`) or add abstraction for hypothetical
20+
users will be declined.
21+
- The best contribution while the project is young: **adopt it, and report
22+
the friction** you hit following the adoption guide.
23+
24+
Docs: <https://pyautoscientist.readthedocs.io> · the organism:
25+
[ORGANISM.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/ORGANISM.md)

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,4 +30,6 @@ bash bin/install.sh # symlink every organ's skills into ~/.claude
3030

3131
Runs straight from its checkout — no pip install. Agent contracts and the
3232
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).
33+
a human is the autonomy contract, [AUTONOMY.md](AUTONOMY.md). The full
34+
organism documentation — including how to fork and run your own — is at
35+
<https://pyautoscientist.readthedocs.io> (source: `docs/`).

‎docs/_static/pyauto.css‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
/* PyAuto shared docs brand layer — identical file in PyAutoFit, PyAutoGalaxy,
2+
PyAutoLens (docs/_static/pyauto.css). The per-project accent is set via
3+
Furo's color-brand-* variables in each repo's conf.py; this file carries
4+
the elements common to the whole stack. */
5+
6+
/* The PyAuto family signature: a thin gradient strip across the top of every
7+
docs page, running through the three stack accents (Fit / Galaxy / Lens). */
8+
body::before {
9+
content: "";
10+
position: fixed;
11+
top: 0;
12+
left: 0;
13+
right: 0;
14+
height: 3px;
15+
background: linear-gradient(90deg, #c2410c 0%, #0f766e 50%, #7c4dff 100%);
16+
z-index: 1000;
17+
pointer-events: none;
18+
}
19+
@media (prefers-color-scheme: dark) {
20+
body:not([data-theme="light"])::before {
21+
background: linear-gradient(90deg, #f28c38 0%, #2dd4bf 50%, #9d7aff 100%);
22+
}
23+
}
24+
body[data-theme="dark"]::before {
25+
background: linear-gradient(90deg, #f28c38 0%, #2dd4bf 50%, #9d7aff 100%);
26+
}
27+
28+
/* Project wordmark in the sidebar. */
29+
.sidebar-brand-text {
30+
font-weight: 700;
31+
letter-spacing: -0.01em;
32+
}

‎docs/adoption/config_surfaces.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# The declared config surfaces
2+
3+
A fork's diff should touch these — and only these. Everything else in the
4+
framework organs is domain-free logic you pull from upstream.
5+
6+
## The primary surfaces
7+
8+
| Surface | Organ | What it declares |
9+
|---------|-------|------------------|
10+
| `repos.yaml` | Mind (yours) | The body map — every repo's GitHub home, category, role. The single source the rest are checked against. |
11+
| `config/repos.yaml` | Heart | What to poll and gate: repo groups, required CI workflows, thresholds, dirty-file noise patterns. |
12+
| `pre_build.sh` — the `run_workspace` table | Hands | One row per workspace: repo, package, flags, parent library. |
13+
| `agents/faculties/sizing/_sizing.py` | Brain | The library/workspace repo sets and aliases used to size and route tasks. |
14+
| `agents/conductors/intake/_intake.py` — `TARGET_SIGNALS` | Brain | Keyword → target-repo routing for raw ideas. |
15+
| `agents/conductors/release/` — the library tuple + `nightly.sh` | Brain | Which libraries the release path drives. |
16+
| `agents/faculties/memory/` — the wiki keyword map | Brain | Topic keywords → your Memory's sub-wikis. |
17+
| `heart/readiness.py` — `DEFAULT_LIBRARIES`; `heart/checks/version_skew.py` — the workspace→(library, package) map | Heart | The release-gate repo sets. |
18+
| `autobuild/run_all.py`, `autobuild/slow_skip_check.py`, navigator maps | Hands | Which workspaces the validation pipeline runs and skips. |
19+
20+
The honest state: some of these are clean policy files (Heart's
21+
`config/repos.yaml`), others are constant tables inside code files. A
22+
demand-gated later phase teaches `repos_sync --write` to stamp the tables
23+
from the body map; until then, replacing them by hand is a one-time cost at
24+
fork, and the drift checks below make sure they can't disagree afterwards.
25+
26+
(tenant-firewall)=
27+
## The tenant firewall
28+
29+
`PyAutoMind/scripts/repos_sync.py --check` includes a **tenant-firewall
30+
check**: it scans every `*.py` / `*.sh` file in Brain, Heart and Hands for
31+
*instance facts* — satellite repo names from the body map, GitHub owners,
32+
the workspace home path — and fails on any occurrence outside a frozen
33+
per-file allowlist (`FIREWALL_ALLOWLIST`, which *is* the machine-checked
34+
inventory of the surfaces above plus the legacy remainder scheduled for
35+
extraction).
36+
37+
Two firing modes: a **new** instance fact in an allowlisted file, or **any**
38+
instance fact in a new file. Together they guarantee the property adoption
39+
depends on: as upstream churns daily, no new code path can silently
40+
hardcode the live instance — so your fork's `git pull` stays a config-diff
41+
pull.
42+
43+
## What is *not* a config surface
44+
45+
- **`skills/*.md`** — the Brain's skill bodies are production prompts. They
46+
mention the live instance in worked examples; that is deliberate and
47+
harmless (they parameterise through the body map at the points that
48+
matter). Never run a "genericisation pass" over them.
49+
- **`AGENTS.md` / `ORGANISM.md` / `AUTONOMY.md`** — doctrine, shared as-is.
50+
- **Markdown generally** — the firewall scans code, not prose; generated
51+
doc blocks (`repos_sync:begin/end` markers) restamp from *your* body map
52+
when you run `--write`.

‎docs/adoption/guide.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Adopting PyAutoScientist
2+
3+
The adoption model is a **config-diff fork**: one upstream (the live
4+
organs), N private organisms downstream. You fork the framework organs,
5+
confine your diff to the declared config surfaces, and `git pull` upstream
6+
improvements cleanly forever after. There is deliberately no shared
7+
deployment, no "generic edition", and no stability promise on `main` — see
8+
{ref}`the disclaimer <stability>` below.
9+
10+
## Prerequisites — what PyAutoScientist *is*
11+
12+
These are the product, not incidental choices. If they don't fit how you
13+
work, this system is not for you (and that's fine):
14+
15+
- **Claude Code** as the agent harness — the Brain's skills and verb
16+
commands install into `~/.claude` and are written for it.
17+
- **The GitHub CLI (`gh`)** and GitHub-hosted repos — issues, PRs and CI
18+
state are read and written through it.
19+
- **A trunk-based, single-maintainer flow** with task worktrees under a
20+
common workspace root (`~/Code/<YourLabs>/` + `<YourLabs>-wt/`).
21+
- **GitHub Actions + PyPI** for the release pipeline, if you release
22+
packages.
23+
24+
## The walkthrough
25+
26+
1. **Fork Brain, Heart, Hands** (keep the repo names — they are framework
27+
identity).
28+
2. **Create your Mind** with the documented shape
29+
([PyAutoMind/REFERENCE.md](https://github.com/PyAutoLabs/PyAutoMind/blob/main/REFERENCE.md)):
30+
the registry files, the work-type prompt folders, a copy of `scripts/`,
31+
and — the load-bearing part — **your own `repos.yaml` body map** listing
32+
your libraries, workspaces and their categories per the
33+
{doc}`category contract <../satellites>`.
34+
3. **Replace the config surfaces** in your forks with rows for your repos —
35+
the complete inventory with file paths is {doc}`config_surfaces`. The
36+
big three: Heart's `config/repos.yaml` (what to poll and gate), the
37+
Hands' `run_workspace` table in `pre_build.sh` (what the pipeline runs),
38+
and the Brain's constant tables (sizing sets, routing keywords, the
39+
release library tuple).
40+
4. **Regenerate and check.** `python3 <YourMind>/scripts/repos_sync.py
41+
--write` stamps the generated doc blocks from your body map; `--check`
42+
verifies every mirror agrees — including the tenant firewall, which
43+
fails if an upstream instance fact survives anywhere outside the
44+
declared surfaces you just replaced.
45+
5. **Install the command surface**: `bash <YourBrain>/bin/install.sh`
46+
symlinks every organ's skills into `~/.claude`.
47+
6. **Create your Memory when you need it** — the shape is documented in
48+
{doc}`the Memory page <../organs/memory>`; the organism runs fine
49+
without one until your domain knowledge accumulates.
50+
7. **Go.** Write your first prompt in your Mind and run `/start_dev` on it.
51+
52+
## Staying current
53+
54+
Because your diff is confined to config surfaces, `git pull upstream main`
55+
in each framework organ stays clean: you take every improvement the
56+
upstream ships, and your instance facts never collide with it. The tenant
57+
firewall is what keeps this true over time — upstream runs it in `--check`,
58+
so new upstream code cannot silently hardcode an instance fact that would
59+
land in your fork.
60+
61+
(stability)=
62+
## The stability disclaimer
63+
64+
The upstream organs are a **living reference implementation** — the
65+
maintainer's daily working system, moving fast (hundreds of commits a
66+
quarter), with no compatibility promises on `main`. Fork-and-pull at your
67+
own pace; pin what you depend on; expect churn. Issues and PRs are welcome,
68+
but the pace is set by the live instance's needs. Each organ carries this
69+
disclaimer in its `CONTRIBUTING.md`.

‎docs/concepts/agents.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Conductors and faculties
2+
3+
The Brain hosts the specialist agents, split into two tiers by a single
4+
question: **does it act, or only opine?**
5+
6+
- **Conductors** (`agents/conductors/<name>/`) are the front doors a human
7+
drives. They decide *and* act — a plan driven into development, a build, a
8+
release. Each is a directory with an `AGENTS.md` (what it reasons about)
9+
and a deterministic entrypoint script, so its behaviour is invoked
10+
identically by humans and CI rather than re-derived from prose each time.
11+
- **Faculties** (`agents/faculties/<name>/`) are read-only opinions the
12+
conductors consult. They return a judgment and stop — never dispatch,
13+
never mutate.
14+
15+
The live conductor set: **intake** (raw idea → formal Mind prompt),
16+
**feature** (plan the next growth task), **bug** (classify and route a
17+
repair), **refactor** (behaviour-preserving restructuring), **profiling**
18+
(the organism's sense of its own effort), **build**, **release**, and
19+
**health** (the clinician loop toward GREEN). The faculties behind them:
20+
**vitals** (the only component that talks to Heart), **review** (the
21+
automatic-review leg of the ship gate), **memory** (cited digests over the
22+
Memory organ), and **samplers** (domain expertise for the live instance).
23+
24+
## The consult graph is a DAG
25+
26+
Conductors consult faculties; each faculty reads its sensor organ; **only
27+
the vitals faculty talks to Heart**. A conductor never consults another
28+
conductor — if it wants one's opinion, that opinion should be extracted
29+
into a faculty. (A conductor may *delegate execution* to another organ,
30+
which is the normal call chain, not consultation.)
31+
32+
This shape is what keeps a society of agents debuggable: opinions are
33+
side-effect-free and reusable, actions have exactly one owner, and there is
34+
never a hidden path to an organ.
35+
36+
## The growth rule
37+
38+
New capability grows as a **faculty** by default — one directory, one doc,
39+
one script. A conductor is added only when a genuinely new human-driven verb
40+
earns it, and a new *organ* must own state or effects no existing organ can.
41+
The conductor set stays small and human-meaningful; faculties multiply
42+
behind them. Symmetry is never a reason to add an agent.
43+
44+
## The command surface
45+
46+
Humans don't type agent names — they type short verbs (`/intake`, `/bug`,
47+
`/feature`, `/health`, `/route`) or plain natural language, and the Brain
48+
routes to the right agent. The command bodies are the Brain's `skills/`
49+
directory, installed into the agent harness (Claude Code's `~/.claude`) by
50+
`bin/install.sh`. The skills are **production prompts**: battle-tested
51+
operating procedure, not documentation. This site describes them; it never
52+
restates them.

‎docs/concepts/organism.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# The organism
2+
3+
The system is organised as a body: each repository is an **organ** with one
4+
job, and the boundaries between them are load-bearing. The canonical
5+
definition lives in the Brain repo as
6+
[ORGANISM.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/ORGANISM.md)
7+
— one page every organ links to instead of restating. This page summarises
8+
it and adds the framework/instance distinction an adopter needs.
9+
10+
| Organ | Repo | Job |
11+
|-------|------|-----|
12+
| **Mind** | PyAutoMind | Decides *what* — intent, goals, priorities, workflow state, the prompt registry, and the body map (`repos.yaml`). |
13+
| **Brain** | PyAutoBrain | Figures out *how* — reasoning, planning, routing; hosts the specialist agents. Owns no state, no health checks, no execution mechanics. |
14+
| **Heart** | PyAutoHeart | Decides whether the organism is *healthy*. `pyauto-heart readiness` is the authoritative GREEN/YELLOW/RED release gate. An observer: never writes into other repos, never triggers a build. |
15+
| **Hands** | PyAutoBuild | *Does* — packaging, tagging, notebook generation, PyPI releases. A pure executor: never re-derives a gate decision. |
16+
| **Memory** | PyAutoMemory | *Knows* — long-term domain knowledge: literature wikis, concepts, bibliographies. Pull-only; consulted, never load-bearing at runtime. |
17+
18+
Everything else — the libraries being developed, their example workspaces,
19+
test suites, tutorials — is a **satellite**: a capability the organism works
20+
*on*, not part of the organism itself. The satellite kinds and what the
21+
organism expects of each are the {doc}`category contract <../satellites>`.
22+
23+
## The call chain
24+
25+
```
26+
Brain → Heart (gate) → Hands (execute)
27+
```
28+
29+
Always in that order. The Brain asks Heart for the readiness verdict,
30+
reasons over it, and only on GREEN triggers the Hands. Heart never triggers
31+
a build; the Hands never re-check readiness. Each boundary exists so that no
32+
organ has to be trusted to police itself.
33+
34+
## Framework vs instance
35+
36+
The five organs split on one line that matters for adoption:
37+
38+
- **Framework organs — Brain, Heart, Hands.** Code, agents, checks,
39+
pipelines. Domain facts appear only in declared config surfaces (tables
40+
and policy files, not logic), and a drift check — the
41+
{ref}`tenant firewall <tenant-firewall>` — keeps it that way.
42+
- **Instance organs — Mind, Memory.** Committed state and knowledge. These
43+
are *inherently yours*: an adopter never forks the upstream Mind or Memory
44+
content, they create their own repos with the same documented shape.
45+
46+
One more principle worth knowing before you read anything else:
47+
**one canonical page per fact.** Organ boundaries live in ORGANISM.md;
48+
autonomy rules live in
49+
[AUTONOMY.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/AUTONOMY.md);
50+
repo identity lives in the Mind's `repos.yaml`. Everything else links. When
51+
prose is duplicated it rots, and an agent acting on rotten prose does real
52+
damage — so the system treats duplication as a bug, and backs the important
53+
cases with machine drift-checks.

‎docs/concepts/workflow.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# The development workflow
2+
3+
Every task follows the same lifecycle, whatever its size:
4+
5+
```
6+
idea → prompt file → issue → worktree → PR(s) → merge → registry
7+
(Mind) (GitHub) (isolated) (gated) (human) (Mind)
8+
```
9+
10+
1. **Intent is written down first.** A task starts as a markdown file in the
11+
Mind under `<work-type>/<target>/<name>.md` — plain English, no template.
12+
The work-type folder (`feature/`, `bug/`, `refactor/`, `docs/`, …) tells
13+
the Brain what kind of reasoning the task needs.
14+
2. **`start_dev`** routes the prompt through the Brain's Feature Agent:
15+
classify, plan at two levels (human bullets + a detailed plan a fresh
16+
session could resume from), survey the affected branches, create a
17+
tracked GitHub issue, and register the task in the Mind's `active.md`.
18+
3. **Work happens in a task worktree** (`~/Code/PyAutoLabs-wt/<task>/`) on a
19+
`feature/<task>` branch across every claimed repo, so parallel tasks
20+
never collide. `active.md` records the claim; a conflict check blocks
21+
double-claiming a repo.
22+
4. **`ship_*`** gates the finish: test suites, the review faculty, and the
23+
Heart readiness verdict. GREEN ships; YELLOW needs an explicit human
24+
acknowledgement; RED stops. One PR per repo, always.
25+
5. **Merge is always human.** After merge, the task entry moves from
26+
`active.md` to `complete.md` — the organism's operational history.
27+
28+
The registry files (`active.md`, `planned.md`, `complete.md`) are shared
29+
state in the Mind repo, so any machine or session — laptop, web, CI — can
30+
read the current picture and resume an in-flight task with no handoff
31+
ceremony.
32+
33+
## The autonomy contract
34+
35+
How much of that lifecycle runs without a human is not ad-hoc: it is defined
36+
once, in
37+
[AUTONOMY.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/AUTONOMY.md).
38+
Each prompt carries `Autonomy: safe | supervised | human-required`; each
39+
work-type has a cap; the effective level is the minimum of the two, and it
40+
binds only when a run is explicitly launched with `--auto`. The contract
41+
pins the invariants: merge is always human, autonomous runs end at PR-open,
42+
Heart RED always stops, and a `safe` run's four-leg ship gate (tests, smoke,
43+
automatic review, Heart) must pass before anything is pushed. Every
44+
autonomous run appends to a calibration log, and raising a cap requires
45+
citing it.
46+
47+
## Model tiers
48+
49+
The workflow splits across model tiers, not named models: a **judgment
50+
tier** (the strongest available model) does planning, risk calls, and any
51+
prose a reader will learn from; an **execution tier** (a fast, cheap model)
52+
runs the mechanical shell/git phases as subagents. The doctrine survives
53+
model generations changing underneath it.

0 commit comments

Comments
 (0)