diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..758f0ff --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Docs + +# Docs build check is defined once, centrally, in PyAutoHeart's reusable +# workflow (Heart owns all health/readiness checking). This thin caller +# builds the Sphinx docs on PRs and fails on warning-count regression +# against docs/sphinx_warning_baseline.txt. PyAutoBrain is not a pip +# package, so it uses the workflow's docs-only mode. + +on: + push: + branches: [main] + paths: + - "docs/**" + - ".readthedocs.yaml" + - ".github/workflows/docs.yml" + pull_request: + paths: + - "docs/**" + - ".readthedocs.yaml" + - ".github/workflows/docs.yml" + workflow_dispatch: + +jobs: + docs: + uses: PyAutoLabs/PyAutoHeart/.github/workflows/docs-build.yml@main + with: + package: pyautoscientist + secrets: inherit diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..e0d9441 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +python: + install: + - requirements: docs/requirements.txt + +sphinx: + configuration: docs/conf.py + fail_on_warning: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..796028a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# Contributing + +The PyAutoScientist organs (PyAutoBrain, PyAutoMind, PyAutoHeart, +PyAutoBuild, PyAutoMemory) are a **living reference implementation** — the +maintainer's daily working system, not a stable library. + +What that means in practice: + +- **`main` moves fast** — hundreds of commits a quarter — and there are + **no compatibility promises**. Anything may be renamed, rewired or + removed when the live system needs it. +- **Adopt by fork-and-pull, never by tracking.** Fork the organs, confine + your changes to the declared config surfaces, and pull upstream at your + own pace — the model is documented in the + [adoption guide](https://pyautoscientist.readthedocs.io/en/latest/adoption/guide.html). + Pin what you depend on. +- **Issues and PRs are welcome**, and read with interest — but triage pace + is set by the live instance's needs, and PRs that genericise working + production prompts (`skills/*.md`) or add abstraction for hypothetical + users will be declined. +- The best contribution while the project is young: **adopt it, and report + the friction** you hit following the adoption guide. + +Docs: · the organism: +[ORGANISM.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/ORGANISM.md) diff --git a/README.md b/README.md index 49c976d..55fdf4a 100644 --- a/README.md +++ b/README.md @@ -30,4 +30,6 @@ bash bin/install.sh # symlink every organ's skills into ~/.claude Runs straight from its checkout — no pip install. Agent contracts and the organ boundary are in [AGENTS.md](AGENTS.md); how much a run may do without -a human is the autonomy contract, [AUTONOMY.md](AUTONOMY.md). +a human is the autonomy contract, [AUTONOMY.md](AUTONOMY.md). The full +organism documentation — including how to fork and run your own — is at + (source: `docs/`). diff --git a/docs/_static/pyauto.css b/docs/_static/pyauto.css new file mode 100644 index 0000000..465d218 --- /dev/null +++ b/docs/_static/pyauto.css @@ -0,0 +1,32 @@ +/* PyAuto shared docs brand layer — identical file in PyAutoFit, PyAutoGalaxy, + PyAutoLens (docs/_static/pyauto.css). The per-project accent is set via + Furo's color-brand-* variables in each repo's conf.py; this file carries + the elements common to the whole stack. */ + +/* The PyAuto family signature: a thin gradient strip across the top of every + docs page, running through the three stack accents (Fit / Galaxy / Lens). */ +body::before { + content: ""; + position: fixed; + top: 0; + left: 0; + right: 0; + height: 3px; + background: linear-gradient(90deg, #c2410c 0%, #0f766e 50%, #7c4dff 100%); + z-index: 1000; + pointer-events: none; +} +@media (prefers-color-scheme: dark) { + body:not([data-theme="light"])::before { + background: linear-gradient(90deg, #f28c38 0%, #2dd4bf 50%, #9d7aff 100%); + } +} +body[data-theme="dark"]::before { + background: linear-gradient(90deg, #f28c38 0%, #2dd4bf 50%, #9d7aff 100%); +} + +/* Project wordmark in the sidebar. */ +.sidebar-brand-text { + font-weight: 700; + letter-spacing: -0.01em; +} diff --git a/docs/adoption/config_surfaces.md b/docs/adoption/config_surfaces.md new file mode 100644 index 0000000..854fff4 --- /dev/null +++ b/docs/adoption/config_surfaces.md @@ -0,0 +1,52 @@ +# The declared config surfaces + +A fork's diff should touch these — and only these. Everything else in the +framework organs is domain-free logic you pull from upstream. + +## The primary surfaces + +| Surface | Organ | What it declares | +|---------|-------|------------------| +| `repos.yaml` | Mind (yours) | The body map — every repo's GitHub home, category, role. The single source the rest are checked against. | +| `config/repos.yaml` | Heart | What to poll and gate: repo groups, required CI workflows, thresholds, dirty-file noise patterns. | +| `pre_build.sh` — the `run_workspace` table | Hands | One row per workspace: repo, package, flags, parent library. | +| `agents/faculties/sizing/_sizing.py` | Brain | The library/workspace repo sets and aliases used to size and route tasks. | +| `agents/conductors/intake/_intake.py` — `TARGET_SIGNALS` | Brain | Keyword → target-repo routing for raw ideas. | +| `agents/conductors/release/` — the library tuple + `nightly.sh` | Brain | Which libraries the release path drives. | +| `agents/faculties/memory/` — the wiki keyword map | Brain | Topic keywords → your Memory's sub-wikis. | +| `heart/readiness.py` — `DEFAULT_LIBRARIES`; `heart/checks/version_skew.py` — the workspace→(library, package) map | Heart | The release-gate repo sets. | +| `autobuild/run_all.py`, `autobuild/slow_skip_check.py`, navigator maps | Hands | Which workspaces the validation pipeline runs and skips. | + +The honest state: some of these are clean policy files (Heart's +`config/repos.yaml`), others are constant tables inside code files. A +demand-gated later phase teaches `repos_sync --write` to stamp the tables +from the body map; until then, replacing them by hand is a one-time cost at +fork, and the drift checks below make sure they can't disagree afterwards. + +(tenant-firewall)= +## The tenant firewall + +`PyAutoMind/scripts/repos_sync.py --check` includes a **tenant-firewall +check**: it scans every `*.py` / `*.sh` file in Brain, Heart and Hands for +*instance facts* — satellite repo names from the body map, GitHub owners, +the workspace home path — and fails on any occurrence outside a frozen +per-file allowlist (`FIREWALL_ALLOWLIST`, which *is* the machine-checked +inventory of the surfaces above plus the legacy remainder scheduled for +extraction). + +Two firing modes: a **new** instance fact in an allowlisted file, or **any** +instance fact in a new file. Together they guarantee the property adoption +depends on: as upstream churns daily, no new code path can silently +hardcode the live instance — so your fork's `git pull` stays a config-diff +pull. + +## What is *not* a config surface + +- **`skills/*.md`** — the Brain's skill bodies are production prompts. They + mention the live instance in worked examples; that is deliberate and + harmless (they parameterise through the body map at the points that + matter). Never run a "genericisation pass" over them. +- **`AGENTS.md` / `ORGANISM.md` / `AUTONOMY.md`** — doctrine, shared as-is. +- **Markdown generally** — the firewall scans code, not prose; generated + doc blocks (`repos_sync:begin/end` markers) restamp from *your* body map + when you run `--write`. diff --git a/docs/adoption/guide.md b/docs/adoption/guide.md new file mode 100644 index 0000000..000391d --- /dev/null +++ b/docs/adoption/guide.md @@ -0,0 +1,69 @@ +# Adopting PyAutoScientist + +The adoption model is a **config-diff fork**: one upstream (the live +organs), N private organisms downstream. You fork the framework organs, +confine your diff to the declared config surfaces, and `git pull` upstream +improvements cleanly forever after. There is deliberately no shared +deployment, no "generic edition", and no stability promise on `main` — see +{ref}`the disclaimer ` below. + +## Prerequisites — what PyAutoScientist *is* + +These are the product, not incidental choices. If they don't fit how you +work, this system is not for you (and that's fine): + +- **Claude Code** as the agent harness — the Brain's skills and verb + commands install into `~/.claude` and are written for it. +- **The GitHub CLI (`gh`)** and GitHub-hosted repos — issues, PRs and CI + state are read and written through it. +- **A trunk-based, single-maintainer flow** with task worktrees under a + common workspace root (`~/Code//` + `-wt/`). +- **GitHub Actions + PyPI** for the release pipeline, if you release + packages. + +## The walkthrough + +1. **Fork Brain, Heart, Hands** (keep the repo names — they are framework + identity). +2. **Create your Mind** with the documented shape + ([PyAutoMind/REFERENCE.md](https://github.com/PyAutoLabs/PyAutoMind/blob/main/REFERENCE.md)): + the registry files, the work-type prompt folders, a copy of `scripts/`, + and — the load-bearing part — **your own `repos.yaml` body map** listing + your libraries, workspaces and their categories per the + {doc}`category contract <../satellites>`. +3. **Replace the config surfaces** in your forks with rows for your repos — + the complete inventory with file paths is {doc}`config_surfaces`. The + big three: Heart's `config/repos.yaml` (what to poll and gate), the + Hands' `run_workspace` table in `pre_build.sh` (what the pipeline runs), + and the Brain's constant tables (sizing sets, routing keywords, the + release library tuple). +4. **Regenerate and check.** `python3 /scripts/repos_sync.py + --write` stamps the generated doc blocks from your body map; `--check` + verifies every mirror agrees — including the tenant firewall, which + fails if an upstream instance fact survives anywhere outside the + declared surfaces you just replaced. +5. **Install the command surface**: `bash /bin/install.sh` + symlinks every organ's skills into `~/.claude`. +6. **Create your Memory when you need it** — the shape is documented in + {doc}`the Memory page <../organs/memory>`; the organism runs fine + without one until your domain knowledge accumulates. +7. **Go.** Write your first prompt in your Mind and run `/start_dev` on it. + +## Staying current + +Because your diff is confined to config surfaces, `git pull upstream main` +in each framework organ stays clean: you take every improvement the +upstream ships, and your instance facts never collide with it. The tenant +firewall is what keeps this true over time — upstream runs it in `--check`, +so new upstream code cannot silently hardcode an instance fact that would +land in your fork. + +(stability)= +## The stability disclaimer + +The upstream organs are a **living reference implementation** — the +maintainer's daily working system, moving fast (hundreds of commits a +quarter), with no compatibility promises on `main`. Fork-and-pull at your +own pace; pin what you depend on; expect churn. Issues and PRs are welcome, +but the pace is set by the live instance's needs. Each organ carries this +disclaimer in its `CONTRIBUTING.md`. diff --git a/docs/concepts/agents.md b/docs/concepts/agents.md new file mode 100644 index 0000000..75e1d77 --- /dev/null +++ b/docs/concepts/agents.md @@ -0,0 +1,52 @@ +# Conductors and faculties + +The Brain hosts the specialist agents, split into two tiers by a single +question: **does it act, or only opine?** + +- **Conductors** (`agents/conductors//`) are the front doors a human + drives. They decide *and* act — a plan driven into development, a build, a + release. Each is a directory with an `AGENTS.md` (what it reasons about) + and a deterministic entrypoint script, so its behaviour is invoked + identically by humans and CI rather than re-derived from prose each time. +- **Faculties** (`agents/faculties//`) are read-only opinions the + conductors consult. They return a judgment and stop — never dispatch, + never mutate. + +The live conductor set: **intake** (raw idea → formal Mind prompt), +**feature** (plan the next growth task), **bug** (classify and route a +repair), **refactor** (behaviour-preserving restructuring), **profiling** +(the organism's sense of its own effort), **build**, **release**, and +**health** (the clinician loop toward GREEN). The faculties behind them: +**vitals** (the only component that talks to Heart), **review** (the +automatic-review leg of the ship gate), **memory** (cited digests over the +Memory organ), and **samplers** (domain expertise for the live instance). + +## The consult graph is a DAG + +Conductors consult faculties; each faculty reads its sensor organ; **only +the vitals faculty talks to Heart**. A conductor never consults another +conductor — if it wants one's opinion, that opinion should be extracted +into a faculty. (A conductor may *delegate execution* to another organ, +which is the normal call chain, not consultation.) + +This shape is what keeps a society of agents debuggable: opinions are +side-effect-free and reusable, actions have exactly one owner, and there is +never a hidden path to an organ. + +## The growth rule + +New capability grows as a **faculty** by default — one directory, one doc, +one script. A conductor is added only when a genuinely new human-driven verb +earns it, and a new *organ* must own state or effects no existing organ can. +The conductor set stays small and human-meaningful; faculties multiply +behind them. Symmetry is never a reason to add an agent. + +## The command surface + +Humans don't type agent names — they type short verbs (`/intake`, `/bug`, +`/feature`, `/health`, `/route`) or plain natural language, and the Brain +routes to the right agent. The command bodies are the Brain's `skills/` +directory, installed into the agent harness (Claude Code's `~/.claude`) by +`bin/install.sh`. The skills are **production prompts**: battle-tested +operating procedure, not documentation. This site describes them; it never +restates them. diff --git a/docs/concepts/organism.md b/docs/concepts/organism.md new file mode 100644 index 0000000..6f70d56 --- /dev/null +++ b/docs/concepts/organism.md @@ -0,0 +1,53 @@ +# The organism + +The system is organised as a body: each repository is an **organ** with one +job, and the boundaries between them are load-bearing. The canonical +definition lives in the Brain repo as +[ORGANISM.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/ORGANISM.md) +— one page every organ links to instead of restating. This page summarises +it and adds the framework/instance distinction an adopter needs. + +| Organ | Repo | Job | +|-------|------|-----| +| **Mind** | PyAutoMind | Decides *what* — intent, goals, priorities, workflow state, the prompt registry, and the body map (`repos.yaml`). | +| **Brain** | PyAutoBrain | Figures out *how* — reasoning, planning, routing; hosts the specialist agents. Owns no state, no health checks, no execution mechanics. | +| **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. | +| **Hands** | PyAutoBuild | *Does* — packaging, tagging, notebook generation, PyPI releases. A pure executor: never re-derives a gate decision. | +| **Memory** | PyAutoMemory | *Knows* — long-term domain knowledge: literature wikis, concepts, bibliographies. Pull-only; consulted, never load-bearing at runtime. | + +Everything else — the libraries being developed, their example workspaces, +test suites, tutorials — is a **satellite**: a capability the organism works +*on*, not part of the organism itself. The satellite kinds and what the +organism expects of each are the {doc}`category contract <../satellites>`. + +## The call chain + +``` +Brain → Heart (gate) → Hands (execute) +``` + +Always in that order. The Brain asks Heart for the readiness verdict, +reasons over it, and only on GREEN triggers the Hands. Heart never triggers +a build; the Hands never re-check readiness. Each boundary exists so that no +organ has to be trusted to police itself. + +## Framework vs instance + +The five organs split on one line that matters for adoption: + +- **Framework organs — Brain, Heart, Hands.** Code, agents, checks, + pipelines. Domain facts appear only in declared config surfaces (tables + and policy files, not logic), and a drift check — the + {ref}`tenant firewall ` — keeps it that way. +- **Instance organs — Mind, Memory.** Committed state and knowledge. These + are *inherently yours*: an adopter never forks the upstream Mind or Memory + content, they create their own repos with the same documented shape. + +One more principle worth knowing before you read anything else: +**one canonical page per fact.** Organ boundaries live in ORGANISM.md; +autonomy rules live in +[AUTONOMY.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/AUTONOMY.md); +repo identity lives in the Mind's `repos.yaml`. Everything else links. When +prose is duplicated it rots, and an agent acting on rotten prose does real +damage — so the system treats duplication as a bug, and backs the important +cases with machine drift-checks. diff --git a/docs/concepts/workflow.md b/docs/concepts/workflow.md new file mode 100644 index 0000000..2f549a3 --- /dev/null +++ b/docs/concepts/workflow.md @@ -0,0 +1,53 @@ +# The development workflow + +Every task follows the same lifecycle, whatever its size: + +``` +idea → prompt file → issue → worktree → PR(s) → merge → registry + (Mind) (GitHub) (isolated) (gated) (human) (Mind) +``` + +1. **Intent is written down first.** A task starts as a markdown file in the + Mind under `//.md` — plain English, no template. + The work-type folder (`feature/`, `bug/`, `refactor/`, `docs/`, …) tells + the Brain what kind of reasoning the task needs. +2. **`start_dev`** routes the prompt through the Brain's Feature Agent: + classify, plan at two levels (human bullets + a detailed plan a fresh + session could resume from), survey the affected branches, create a + tracked GitHub issue, and register the task in the Mind's `active.md`. +3. **Work happens in a task worktree** (`~/Code/PyAutoLabs-wt//`) on a + `feature/` branch across every claimed repo, so parallel tasks + never collide. `active.md` records the claim; a conflict check blocks + double-claiming a repo. +4. **`ship_*`** gates the finish: test suites, the review faculty, and the + Heart readiness verdict. GREEN ships; YELLOW needs an explicit human + acknowledgement; RED stops. One PR per repo, always. +5. **Merge is always human.** After merge, the task entry moves from + `active.md` to `complete.md` — the organism's operational history. + +The registry files (`active.md`, `planned.md`, `complete.md`) are shared +state in the Mind repo, so any machine or session — laptop, web, CI — can +read the current picture and resume an in-flight task with no handoff +ceremony. + +## The autonomy contract + +How much of that lifecycle runs without a human is not ad-hoc: it is defined +once, in +[AUTONOMY.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/AUTONOMY.md). +Each prompt carries `Autonomy: safe | supervised | human-required`; each +work-type has a cap; the effective level is the minimum of the two, and it +binds only when a run is explicitly launched with `--auto`. The contract +pins the invariants: merge is always human, autonomous runs end at PR-open, +Heart RED always stops, and a `safe` run's four-leg ship gate (tests, smoke, +automatic review, Heart) must pass before anything is pushed. Every +autonomous run appends to a calibration log, and raising a cap requires +citing it. + +## Model tiers + +The workflow splits across model tiers, not named models: a **judgment +tier** (the strongest available model) does planning, risk calls, and any +prose a reader will learn from; an **execution tier** (a fast, cheap model) +runs the mechanical shell/git phases as subagents. The doctrine survives +model generations changing underneath it. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..b8b48c6 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,40 @@ +# Sphinx configuration for the PyAutoScientist docs, published on +# ReadTheDocs as the `pyautoscientist` project from PyAutoBrain/docs/. +# The docs describe the whole organism; Brain hosts them because it owns +# the canonical organism prose (ORGANISM.md) and the growth rule says no +# new organs by default. + +project = "PyAutoScientist" +author = "James Nightingale" +copyright = "2026, James Nightingale" + +extensions = ["myst_parser"] +myst_enable_extensions = ["colon_fence"] + +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +html_theme = "furo" +html_title = "PyAutoScientist" +html_short_title = "PyAutoScientist" +html_permalinks_icon = "#" +html_last_updated_fmt = "%b %d, %Y" + +html_show_sourcelink = False +html_show_sphinx = True +html_show_copyright = True + +language = "en" + +html_static_path = ["_static"] +html_css_files = ["pyauto.css"] + +html_theme_options = { + "light_css_variables": { + "color-brand-primary": "#be123c", + "color-brand-content": "#be123c", + }, + "dark_css_variables": { + "color-brand-primary": "#fb7185", + "color-brand-content": "#fb7185", + }, +} diff --git a/docs/example.md b/docs/example.md new file mode 100644 index 0000000..101b2b1 --- /dev/null +++ b/docs/example.md @@ -0,0 +1,53 @@ +# The worked example: the live lensing instance + +Everything on this site is running today, developing the +[PyAuto astronomy stack](https://pyautolabs.github.io). This page is that +instance, labelled as the example — when a concept page says "a library" or +"a workspace", this is what it concretely means upstream. Your organism +replaces every name below with your own. + +## The body + +The live `repos.yaml` declares ~25 repos. The load-bearing categories: + +- **Libraries:** PyAutoConf (shared config), PyAutoFit (Bayesian + inference), PyAutoArray (data structures), PyAutoGalaxy (galaxy + modelling), PyAutoLens (strong lensing), PyAutoReduce (data reduction) — + a dependency chain released to PyPI nightly when there is new activity. +- **Workspaces:** `autofit_workspace`, `autogalaxy_workspace`, + `autolens_workspace` — user-facing examples, notebook-generated, + version-pinned against their libraries. +- **Test workspaces:** the `*_workspace_test` trio — regression, smoke and + parity scripts the release pipeline runs. +- **HowTos:** HowToFit / HowToGalaxy / HowToLens — lecture-style courses. +- **Assistant:** `autolens_assistant` — the curated knowledge pack that + makes any AI assistant a strong-lensing expert. +- **Memory:** sub-wikis on lensing, black holes, detector calibration, + inference methods and galaxy evolution, with a ~600-paper bibliography + layer. + +## A task, end to end + +A representative real task (2026): a prompt file +`feature/autoarray/psf_oversampling.md` written as free prose — "PSF +blurring lives in `@PyAutoArray/.../convolver.py`; modeling should convolve +at higher resolution than the image; here's roughly how" — with typos and +half-decisions left in. `start_dev` classified it (feature, library), +planned it at two levels, opened a tracked issue, and claimed a worktree. +Development touched PyAutoArray and PyAutoGalaxy; the ship gate ran both +test suites, the review faculty, and Heart's verdict; one PR landed per +repo; the workspaces then gained a demonstration script in a follow-up +workspace task. The registry recorded every state transition, and the task +retired to `complete.md`. + +That is the whole pitch: the input was a paragraph of intent, and every +step from there — planning, isolation, testing, gating, releasing, +bookkeeping — was the organism's machinery, with a human approving the plan +and the merge. + +## Scale, honestly + +This system runs tens of active repos with a single human maintainer. In a +typical recent quarter the framework organs themselves took a few hundred +commits — which is exactly why the {ref}`stability disclaimer ` +exists and why adoption is a fork, not a dependency. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..bae8dc5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,68 @@ +# PyAutoScientist + +PyAutoScientist is a working, opinionated reference implementation of an +**AI-agent development organism**: a set of five git repositories — Mind, +Brain, Heart, Hands, Memory — that together let AI coding agents plan, +implement, test, gate and release software across a multi-repo project, +with a human checkpointing the judgment calls. + +It is not a framework you install. It is the live system that develops the +[PyAuto astronomy stack](https://pyautolabs.github.io) every day — tens of +repositories, nightly releases, hundreds of tasks — documented so that you +can **fork it and run your own**, driving projects that have nothing to do +with astronomy. + +## The idea in five lines + +- Every piece of work starts as a plain-English markdown file in the **Mind**. +- The **Brain** classifies it, plans it, and routes it through specialist agents. +- Work happens on task worktrees and ships as pull requests, gated by the + **Heart**'s health verdict. +- The **Hands** package and release what merges. +- The **Memory** holds the long-term domain knowledge the agents consult. + +## What adopting it means + +You fork the three framework organs (Brain, Heart, Hands), replace a small +set of declared config surfaces with your own repositories, write your own +Mind and Memory from the documented shapes, and `git pull` upstream +improvements cleanly from then on. One upstream, N private organisms — never +a shared deployment. The {doc}`adoption guide ` is the +walkthrough; {doc}`adoption/config_surfaces` is the exact contract. + +Be aware of what this *is* before investing: PyAutoScientist assumes +**Claude Code** (skills and commands installed under `~/.claude`), the +**GitHub CLI**, a trunk-based single-maintainer flow with task worktrees, +and GitHub Actions + PyPI for releases. Those assumptions are the product, +not incidental debt — they are stated plainly in the adoption guide. + +## Reading order + +```{toctree} +:maxdepth: 2 + +concepts/organism +concepts/agents +concepts/workflow +``` + +```{toctree} +:caption: The organs +:maxdepth: 1 + +organs/mind +organs/brain +organs/heart +organs/build +organs/memory +``` + +```{toctree} +:caption: Adopting it +:maxdepth: 1 + +satellites +adoption/guide +adoption/config_surfaces +example +``` diff --git a/docs/organs/brain.md b/docs/organs/brain.md new file mode 100644 index 0000000..e2b32cb --- /dev/null +++ b/docs/organs/brain.md @@ -0,0 +1,37 @@ +# Brain — PyAutoBrain + +**What it owns:** reasoning. The Brain classifies work, plans it, routes it +through the {doc}`conductors and faculties <../concepts/agents>`, and +delegates everything else: state to Mind, health to Heart, execution to +Hands. It deliberately owns no state, no checks, no release mechanics. + +**Repo:** [PyAutoLabs/PyAutoBrain](https://github.com/PyAutoLabs/PyAutoBrain) +· canonical organism page: +[ORGANISM.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/ORGANISM.md) +· autonomy contract: +[AUTONOMY.md](https://github.com/PyAutoLabs/PyAutoBrain/blob/main/AUTONOMY.md) + +## The pieces + +- **`agents/`** — the conductor and faculty directories, each an `AGENTS.md` + role description plus a deterministic entrypoint (`bin/pyauto-brain + ` dispatches to them). +- **`skills/`** — the workflow skill bodies (`start_dev`, `ship_library`, + the verb commands, the shared `WORKFLOW.md`). These are production + prompts, symlinked into the agent harness by `bin/install.sh`; they are + the agents' operating procedure, and this documentation never restates + them. +- **`ORGANISM.md` / `AUTONOMY.md`** — the two canonical doctrine pages the + whole organism links to. +- **`bin/`** — the CLI dispatcher and the cross-organ skill installer. + +Runs from its checkout — no pip install; it resolves the sibling organs' +binaries from `PATH` or the workspace layout. + +## For an adopter + +Fork it. The reasoning, the agent architecture, the skills and the doctrine +pages are the framework — domain facts appear only in small constant tables +inside `agents/` (repo sets for sizing, keyword maps for routing, the +release library tuple), which are declared config surfaces you replace with +your own. See {doc}`../adoption/config_surfaces` for the exact list. diff --git a/docs/organs/build.md b/docs/organs/build.md new file mode 100644 index 0000000..b122922 --- /dev/null +++ b/docs/organs/build.md @@ -0,0 +1,35 @@ +# Hands — PyAutoBuild + +**What it owns:** execution of the release pipeline. Packaging, tagging, +notebook generation from example scripts, workspace validation runs, and +PyPI publication via `release.yml` — nightly, when there is new activity to +ship. + +**Repo:** [PyAutoLabs/PyAutoBuild](https://github.com/PyAutoLabs/PyAutoBuild) + +## The boundary that matters + +The Hands are a **pure executor**: no readiness checks of their own, no +re-deriving of gate decisions. Readiness is gated upstream — the Brain's +release path consults the vitals faculty, which reads Heart, and only a +GREEN verdict reaches the dispatch. Historically Build owned some checking; +that all migrated to Heart, and thin shims remain so old entry points still +work. + +## The pieces + +- **`bin/autobuild`** — the single dispatcher; every operation is a + subcommand with `--help` (`pre_build`, `generate`, `run_all`, + `tag_and_merge`, …). +- **`pre_build.sh`** — the declarative heart of the pipeline: one + `run_workspace ` row per workspace + describes everything the pipeline needs to know about it. +- **`release.yml`** — package to TestPyPI, verify the install, run the + workspace scripts, and on success release to PyPI and tag the workspaces. + +## For an adopter + +Fork it. The pipeline mechanics are the framework; the `run_workspace` +table in `pre_build.sh` and the small maps in `autobuild/*.py` (which +workspaces to run, what to skip) are the declared config surfaces you +rewrite for your own repos — see {doc}`../adoption/config_surfaces`. diff --git a/docs/organs/heart.md b/docs/organs/heart.md new file mode 100644 index 0000000..ce770f4 --- /dev/null +++ b/docs/organs/heart.md @@ -0,0 +1,41 @@ +# Heart — PyAutoHeart + +**What it owns:** the health verdict. Heart continuously watches every repo +— branch state, CI conclusions, open PRs, version skew, script timing, +workspace-validation results — and rolls them into one authoritative +answer: `pyauto-heart readiness` → **GREEN / YELLOW / RED**, a score, and +the reasons. GREEN means it is safe to release. + +**Repo:** [PyAutoLabs/PyAutoHeart](https://github.com/PyAutoLabs/PyAutoHeart) +· live board: + +## The boundary that matters + +Heart is an **observer**. It never writes into other repos and never +triggers a build; the Brain reads the verdict (through its vitals faculty — +the only component allowed to talk to Heart) and decides what to do. RED is +a hard stop at every autonomy level. YELLOW requires an explicit human +acknowledgement to ship past. This split — the gate cannot execute, the +executor cannot gate — is the organism's central safety property. + +## The pieces + +- **Continuous checks** run in a <30s tick (daemon or scheduled): repo + state, CI status, open PRs, worktree drift, script timing, version skew. +- **Deep checks** run on demand or on cloud cron: install verification, the + URL-hygiene sweep, release validation. +- **One renderer, many surfaces:** the same cached snapshot projects to the + terminal board, a one-line shell prompt, GitHub Pages, markdown summaries + and JSON — the surfaces cannot disagree. +- **`config/repos.yaml`** — the polling/gating policy: which repos, which + required workflows, what thresholds, which dirty-file patterns are noise. + +## For an adopter + +Fork it. The check framework, tick budget, dashboard and readiness logic +are the framework; **`config/repos.yaml` is yours** — it is the single +biggest config surface in the organism, and it is checked against your +Mind's body map by `repos_sync.py --check`. A handful of remaining +constant tables (the library tuple in `readiness.py`, the +workspace→library map in `version_skew.py`) are declared surfaces listed in +{doc}`../adoption/config_surfaces`. diff --git a/docs/organs/memory.md b/docs/organs/memory.md new file mode 100644 index 0000000..9e5479d --- /dev/null +++ b/docs/organs/memory.md @@ -0,0 +1,38 @@ +# Memory — PyAutoMemory + +**What it owns:** long-term domain knowledge — *what the science says*. +Cross-linked wikis distilling literature, concepts and methods, backed by +canonical citation metadata, so agents planning domain work reason from +verifiable knowledge instead of vibes. + +**Repo:** [PyAutoLabs/PyAutoMemory](https://github.com/PyAutoLabs/PyAutoMemory) + +## The read contract + +Memory is **pull-only, on demand**. No agent loads it automatically; the +Brain's memory faculty consults it when a task is scientific, returning a +cited digest (pages + snippets) rather than bulk content. Operational +history — what the organism *did* — deliberately lives in the Mind +(`complete.md`, issues), not here: Memory is what the domain says, Mind is +what the organism did. + +## The pieces + +- **Sub-wikis**, each self-contained with the same schema: in the live + instance, strong lensing, black holes, detector calibration, inference + methods, galaxy evolution. +- **`bibliography/`** — canonical BibTeX metadata every wiki claim cites + against; `make validate-literature-citations` keeps claims and metadata + honest together. +- **An index-first layout** — agents reach pages through `index.md` chains, + never hard-coded paths, so the wiki can grow without breaking readers. + +## For an adopter + +You do not fork this repo — the content is the upstream instance's personal +research knowledge. You create your own Memory with the same shape: +sub-wikis per domain, the shared schema, the bibliography layer, the +validation make target. The generic asset is the *structure* (MIT-licensed; +the upstream content itself is CC BY 4.0), and the coupling point to the +rest of the organism is a single keyword map in the Brain's memory faculty +— adopter config like everything else. diff --git a/docs/organs/mind.md b/docs/organs/mind.md new file mode 100644 index 0000000..e842496 --- /dev/null +++ b/docs/organs/mind.md @@ -0,0 +1,36 @@ +# Mind — PyAutoMind + +**What it owns:** intent and workflow state. Every task starts here as a +plain-English markdown prompt; the registry files track what is in flight +(`active.md`), queued (`planned.md`) and done (`complete.md`); and +`repos.yaml` — the **body map** — is the single source of repo identity for +the whole organism. + +**Repo:** [PyAutoLabs/PyAutoMind](https://github.com/PyAutoLabs/PyAutoMind) +· schemas and conventions: +[REFERENCE.md](https://github.com/PyAutoLabs/PyAutoMind/blob/main/REFERENCE.md) + +## The pieces + +- **Prompts** live at `//.md`. The first folder is + the kind of thinking required (`feature/`, `bug/`, `refactor/`, `docs/`, + `research/`, …) — it selects the Brain agent. The second is the target + repo or domain. Prompts are free-form prose; an optional light header + (`Type:` / `Difficulty:` / `Autonomy:` / `Priority:`) gives both humans + and the Brain a glance-level summary. +- **The registry** (`active.md` / `planned.md` / `complete.md`) is the + shared task state — worktree claims, issue links, status, resume notes. + It is what makes the workflow machine-independent. +- **The body map** (`repos.yaml`) declares every repo's GitHub home, + category and role. `scripts/repos_sync.py --write` regenerates the routing + tables other repos display; `--check` fails on any drift between the map, + the organs' config surfaces, and the actual git remotes — including the + {ref}`tenant firewall `. + +## For an adopter + +You do not fork this repo — its content *is* the upstream instance's +backlog and history. You create your own Mind with the same shape: the +registry files, the work-type folders, your own `repos.yaml` describing +your repos, and a copy of `scripts/` (the sync/drift tooling is generic). +The shapes are documented in REFERENCE.md. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..7cd2b1f --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=7 +furo +myst-parser diff --git a/docs/satellites.md b/docs/satellites.md new file mode 100644 index 0000000..14d0dcf --- /dev/null +++ b/docs/satellites.md @@ -0,0 +1,35 @@ +# The category contract + +The organism works *on* satellites — the repositories being developed. The +body map (`PyAutoMind/repos.yaml`) assigns every repo a **category**, and +the category is a contract: it says what the repo is for and what the +organism expects of it. You don't need the live instance's repos; you need +repos that honour the contracts your body map declares. + +| Category | What it is for | What the organism expects of it | +|----------|----------------|--------------------------------| +| `organ` | The five organism repos themselves. | Framework identity — names survive a fork; excluded from the tenant firewall's instance-fact tokens. | +| `library` | A source package you release. | A test suite and CI workflow Heart gates on; a row in the Brain release conductor's library set; a PyPI package the Hands release; a version floor workspaces pin against. | +| `workspace` | Runnable, user-facing examples for one library. | A `run_workspace` row in `pre_build.sh` (repo, package, flags, parent library); a version pin Heart's `version_skew` compares to the installed library; required CI (smoke tests) on `main`; notebook generation from its scripts. | +| `workspace_test` | Regression / smoke / parity scripts — code-heavy, doc-light. | Same `run_workspace` mechanics; scripts runnable headless in the validation pipeline; the home for cross-package and integration checks that don't belong in a library's unit tests. | +| `workspace_developer` | Profiling and experiment scripts. | Not release-gated; polled for repo state only. | +| `howto` | Narrative teaching tutorials. | Version-pinned like a workspace; notebook generation; prose held to a higher bar (judgment-tier writing). | +| `assistant` | A curated knowledge pack that makes any AI assistant an expert on one domain/stack. | Self-contained and public; its own currency checks; never a dumping ground for personal material. | +| `pipeline` | Glue for one external project or survey. | Workspace-like validation where runnable; otherwise polled only. | +| `project` | Analysis/results repos (profiling campaigns, the docs hub). | Polled for state; no release mechanics. | +| `admin` | Personal tooling. | Outside the organism proper; hosts helpers the workflow sources (e.g. the worktree script). | + +Two properties make the contract workable: + +- **Declared, not discovered.** Everything the organism knows about a repo + is in the body map plus the per-organ config surfaces — never inferred + from the repo's contents at runtime. Adding a repo is: add the `repos.yaml` + row, add the config-surface rows its category requires, run + `repos_sync.py --write`, and the drift checks confirm the mirrors agree. +- **Checked, not trusted.** `repos_sync.py --check` verifies the body map + against Heart's polling policy, the Hands' `run_workspace` table, the + label tooling, and every local checkout's actual git remote — so the + contract can't silently rot. + +An adopter's minimal viable body: one `library` + one `workspace`. Every +other category is opt-in as your project grows into it. diff --git a/docs/sphinx_warning_baseline.txt b/docs/sphinx_warning_baseline.txt new file mode 100644 index 0000000..573541a --- /dev/null +++ b/docs/sphinx_warning_baseline.txt @@ -0,0 +1 @@ +0