From e5366c8628efd229f29611c7f28b264552690813 Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Fri, 10 Jul 2026 14:38:58 +0100 Subject: [PATCH 1/2] docs: human-led natural-language tone sweep (PyAutoBrain#81) Reword organism framing to the human-led voice settled on the org front page: you lead in plain English, agents plan/build/test/release, you make every judgment call. Tone only - no boundary changes. Co-Authored-By: Claude Fable 5 --- ORGANISM.md | 4 ++++ README.md | 7 ++++--- docs/concepts/workflow.md | 5 +++-- docs/index.md | 14 ++++++++------ 4 files changed, 19 insertions(+), 11 deletions(-) diff --git a/ORGANISM.md b/ORGANISM.md index 9391c5f..fffa8c6 100644 --- a/ORGANISM.md +++ b/ORGANISM.md @@ -4,6 +4,10 @@ The **one canonical page** for the organs, their boundaries, and the call chain. Every other repo links here instead of restating this — if you are editing organism prose anywhere else, stop and edit this file. +The organism is an agentic AI ecosystem for **human-led, natural-language +software development**: you describe what you want in plain English, the +organs plan, build, test and release it, and you make every judgment call. + ## The organs | Organ | Repo | Role and boundary | diff --git a/README.md b/README.md index 55fdf4a..7536560 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ gets done: it classifies incoming tasks, plans them, and routes them to specialist agents, delegating execution to the other organs. It holds no state, runs no health checks, and never releases anything itself. -The organism is described once in [ORGANISM.md](ORGANISM.md). The short -version: +The organism — an agentic AI ecosystem for human-led, natural-language +software development — is described once in [ORGANISM.md](ORGANISM.md). The +short version: | Organ | Repo | Job | |-------|------|-----| @@ -31,5 +32,5 @@ 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). The full -organism documentation — including how to fork and run your own — is at +organism documentation — including how to fork it and lead your own — is at (source: `docs/`). diff --git a/docs/concepts/workflow.md b/docs/concepts/workflow.md index 2f549a3..8409b6e 100644 --- a/docs/concepts/workflow.md +++ b/docs/concepts/workflow.md @@ -7,8 +7,9 @@ idea → prompt file → issue → worktree → PR(s) → merge → (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. +1. **Intent is written down first.** A task starts as a markdown file you + write 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: diff --git a/docs/index.md b/docs/index.md index bae8dc5..c886bc7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,20 +1,22 @@ # 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. +**AI-agent development organism** for human-led, natural-language software +development: a set of five git repositories — Mind, Brain, Heart, Hands, +Memory — through which you lead a multi-repo project in plain English. You +describe what you want; AI agents plan, implement, test, gate and release +it; you make every judgment call. 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 +can **fork it and lead 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**. +- Every piece of work starts as a plain-English markdown file you write 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. From cd0fda68f2a9ce0af6468e36d7a2289625f5a8a6 Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Fri, 10 Jul 2026 14:45:21 +0100 Subject: [PATCH 2/2] docs: trim human-led emphasis to the agentic-AI framing contexts only Organ READMEs state role/abstraction; the human-led voice stays where the text explicitly pitches the agentic-AI system (ORGANISM.md definition, PyAutoScientist docs landing page). Co-Authored-By: Claude Fable 5 --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7536560..55fdf4a 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,8 @@ gets done: it classifies incoming tasks, plans them, and routes them to specialist agents, delegating execution to the other organs. It holds no state, runs no health checks, and never releases anything itself. -The organism — an agentic AI ecosystem for human-led, natural-language -software development — is described once in [ORGANISM.md](ORGANISM.md). The -short version: +The organism is described once in [ORGANISM.md](ORGANISM.md). The short +version: | Organ | Repo | Job | |-------|------|-----| @@ -32,5 +31,5 @@ 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). The full -organism documentation — including how to fork it and lead your own — is at +organism documentation — including how to fork and run your own — is at (source: `docs/`).