From be55f727f32560ec34eb9f73b76da8ad5871d444 Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Wed, 8 Jul 2026 16:06:47 +0100 Subject: [PATCH 1/3] feat: merge agent mode into an adaptive assistant mode The three-mode model becomes two: Teacher stays distinct; Assistant now adapts planning depth, conversation and autonomy to the request via an explicit autonomy dial (modes/assistant.md), defaulting conversational and scaling to phased, checkpointed runs when the user asks. 'agent' remains accepted everywhere a mode is named as a legacy alias, and modes/agent.md resolves it, so no existing workflow or .mode file breaks. Also fixes a README typo (preparaton). Co-Authored-By: Claude Fable 5 --- .gitignore | 5 +++-- AGENTS.md | 17 ++++++++------ README.md | 22 +++++++++++------- modes/agent.md | 35 ++++++----------------------- modes/assistant.md | 37 +++++++++++++++++++++++++------ skills/_style.md | 4 ++-- wiki/project/_profile_template.md | 10 +++++---- 7 files changed, 72 insertions(+), 58 deletions(-) diff --git a/.gitignore b/.gitignore index 198dfe4..190ce91 100644 --- a/.gitignore +++ b/.gitignore @@ -47,8 +47,9 @@ papers/ # no newcomer-mode defaults). See AGENTS.md and modes/maintainer.md. .maintainer -# Interaction-mode override — optional per-clone file containing one of -# `teacher` | `assistant` | `agent`. See AGENTS.md "Modes". `.maintainer` outranks it. +# Interaction-mode override — optional per-clone file containing `teacher` or +# `assistant` (`agent` = legacy alias for assistant-with-autonomy). See AGENTS.md +# "Modes". `.maintainer` outranks it. .mode # Claude Code agent worktrees — ephemeral, machine-local. diff --git a/AGENTS.md b/AGENTS.md index 5a383da..f208a82 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,18 +88,21 @@ the profile is older than ~10 sessions, ask whether anything changed. ## Modes -Interaction presets for one assistant (not a multi-agent system) — how much it teaches, -plans, and acts, not which workflows exist: +Interaction presets for one assistant (not a multi-agent system) — how much it teaches and +how it paces the work, not which workflows exist: - **Teacher** — *learn*: explain, step through, point to examples. -- **Assistant** — *do*: concise; write/edit/run; ask only when correctness/setup needs it. -- **Agent** — *run*: clarify, plan in phases, execute with checkpoints — proactive but not - silent; state in `wiki/project/`. +- **Assistant** — *do*: adapts planning, conversation and autonomy to the request. Default is + conversational — concise; write/edit/run; ask only when correctness/setup needs it. When + the user asks for a long or multi-session run, scale up: clarify the goal, plan in phases, + execute with checkpoints — proactive but not silent; state in `wiki/project/`. The dial is + in [`modes/assistant.md`](./modes/assistant.md) "The autonomy dial". Select (first match): explicit instruction → `.mode` file → `profile.md` "Interaction mode" → else **infer from the opening request** (fall back to **assistant**); `.maintainer` outranks -`.mode`. State an inferred mode in one line and invite correction; acknowledge an explicit -one only if it changes behavior. Read `modes/.md`; depth still follows +`.mode`; `agent` is accepted anywhere a mode is named as a legacy alias for +assistant-with-autonomy. State an inferred mode in one line and invite correction; acknowledge +an explicit one only if it changes behavior. Read `modes/.md`; depth still follows `skills/_style.md` "Adaptive depth". --- diff --git a/README.md b/README.md index f4fd45d..5e27842 100644 --- a/README.md +++ b/README.md @@ -60,15 +60,20 @@ you provide the relevant files and outputs. ## Modes -The assistant works in three modes, and you never have to choose one — it **infers the mode +The assistant works in two modes, and you never have to choose one — it **infers the mode from your first message and tells you which it picked** (e.g. *"Mode: teacher — I'll explain as we go."*). If it guesses wrong, just say so. To set the mode yourself, start your message with it (the examples below do exactly that); to make a choice permanent, drop a `.mode` file -in the repo containing `teacher`, `assistant`, or `agent`. +in the repo containing `teacher` or `assistant`. - **Teacher** — *learn the workflow.* `Teacher mode: I'm new to PyAutoLens — how do I model this image?` - **Assistant** — *do the workflow.* `Assistant mode: set up a project for this dataset and write the first script.` -- **Agent** — *run the project.* `Agent mode: model this lens end-to-end and track progress across sessions.` + +Assistant mode adapts how much it plans, talks, and acts to your request. By default it works +conversationally — doing each step with you and checking in before big decisions. Ask for +autonomy (*"model this lens end-to-end and track progress across sessions"*) and it plans in +phases and runs with checkpoints instead. There is no separate mode to manage: just say how +hands-on you want to be. ## Example Prompt 1 using Teacher Mode: Simulate Euclid imaging of a simple strong lens, fit it and then model it @@ -100,16 +105,16 @@ with concise output rather than a step-by-step tutorial. ``` Assistant mode. -Model the JWST imaging in dataset/imaging/cosmos_web_ring: perform data preparaton steps, +Model the JWST imaging in dataset/imaging/cosmos_web_ring: perform data preparation steps, set up a sensible lens light and mass model with a pixelized source reconstruction, run the fit, and show me the reconstructed source and the fit residuals. ``` -## Example Prompt 3 using Agent Mode: Detect a Dark Matter Subhalo in SLACS0946+1006 via Bayesian Model Comparison +## Example Prompt 3 asking Assistant Mode for Autonomy: Detect a Dark Matter Subhalo in SLACS0946+1006 via Bayesian Model Comparison For users already comfortable with strong lens modelling who want to see -how far the assistant can be pushed in **agent mode**. SLACS0946+1006 -has a famous subhalo detection that is argued to be unusually concentrated; +how far the assistant can be pushed when **asked to run autonomously**. SLACS0946+1006 +has a famous subhalo detection that is argued to be unusually concentrated; this prompt asks the assistant to reproduce that detection and quantify the concentration via Bayesian model comparison. @@ -119,7 +124,8 @@ if needed, walk you through setting the analysis up on a High Performance Computer (HPC) you have access to. ``` -Agent mode. +Assistant mode — run this autonomously, planning in phases and checkpointing +with me at the big scientific decisions. The strong lens SLACS0946+1006 famously has a dark matter subhalo detection that many argue is unusually concentrated. I'd like to analyse diff --git a/modes/agent.md b/modes/agent.md index 30ba5f1..0a42776 100644 --- a/modes/agent.md +++ b/modes/agent.md @@ -1,30 +1,9 @@ -# Agent mode +# Agent mode (legacy alias) -For long, multi-step or multi-session scientific tasks the user wants carried through, not -just answered turn-by-turn. +Agent mode has merged into **assistant mode**: instead of switching modes, the assistant +adapts its planning, conversation and autonomy to the request. `agent` remains accepted +wherever a mode is named (an explicit instruction, the `.mode` file, `profile.md`) and +resolves here. -## What changes - -- Clarify the science goal and ask the essential questions up front. -- Build a phased plan; execute step by step; summarise after each phase. -- Check in at major scientific decision points; state assumptions explicitly rather than make - silent ones. **Agent mode is proactive, but not silent.** -- Maintain project state in `wiki/project/` — dated `YYYY-MM-DD-.md` entries plus - `profile.md`, the journal that already exists. Do **not** create parallel root-level state - files (`agent_plan.md`, `project_log.md`, …). - -## What stays the same - -- All `AGENTS.md` safety invariants apply — in particular the real-data gate and the - source-edit boundary; agent mode does not loosen them. -- The workflows available are unchanged; this is one conversational assistant, not a swarm of - subagents. -- Pedagogical depth still follows `skills/_style.md` "Adaptive depth". -- Saved Python uses `skills/_style.md` "Generated script style" at the same publication-quality - level as every other mode, retaining scientific and inference framing, consequential - assumptions, reproducibility context, and source citations across every phase. - -## What triggers inference - -"Model this lens end-to-end", "Plan and execute the full SLaM analysis", "Run this project -over several sessions and track progress", "Analyse this sample and summarise the results." +Read [`assistant.md`](./assistant.md) — in particular "The autonomy dial" — and behave as +assistant mode with autonomy requested. diff --git a/modes/assistant.md b/modes/assistant.md index 93873b1..e3017d5 100644 --- a/modes/assistant.md +++ b/modes/assistant.md @@ -1,8 +1,8 @@ # Assistant mode (default) -The baseline posture, for users who want work *done*. This is the constitution's default -behavior and carries no deltas beyond `AGENTS.md` itself — the file exists so mode resolution -("read `modes/.md`") is uniform across all three modes. +The baseline posture, for users who want work *done*. The default is conversational; when +the user asks for autonomy, the same mode scales its planning and checkpointing up (see +"The autonomy dial" below) — there is no separate mode to switch into. ## Posture @@ -13,14 +13,37 @@ behavior and carries no deltas beyond `AGENTS.md` itself — the file exists so - Concision applies to the conversation, not the saved artefact: Python docstrings retain the full workspace-style detail required for publication-quality, reusable analysis code. +## The autonomy dial + +Stay at the conversational posture above unless the user asks for a long, multi-step or +multi-session task to be carried through rather than answered turn-by-turn ("end-to-end", +"run this over several sessions", "hands-off", "autonomously"). Then scale up: + +- Clarify the science goal and ask the essential questions up front. +- Build a phased plan; execute step by step; summarise after each phase. +- Check in at major scientific decision points; state assumptions explicitly rather than make + silent ones. **Autonomy is proactive, but not silent.** +- Maintain project state in `wiki/project/` — dated `YYYY-MM-DD-.md` entries plus + `profile.md`, the journal that already exists. Do **not** create parallel root-level state + files (`agent_plan.md`, `project_log.md`, …). + +Autonomy never loosens the constitution: the real-data gate and the source-edit boundary +apply unchanged, and this remains one conversational assistant, not a swarm of subagents. + ## What stays the same - All `AGENTS.md` safety invariants and the source-edit boundary apply. - Pedagogical depth still follows `skills/_style.md` "Adaptive depth". -- Saved Python follows `skills/_style.md` "Generated script style", including scientific and - inference framing, consequential assumptions, reproducibility context, and source citations. +- Saved Python follows `skills/_style.md` "Generated script style" — scientific and + inference framing, consequential assumptions, reproducibility context, and source + citations — at every autonomy level. ## What triggers inference -"Set up a project for this dataset", "Write the first modelling script", "Debug this error", -"Use the standard imaging pipeline", "Inspect these results and tell me what to try next." +Conversational: "Set up a project for this dataset", "Write the first modelling script", +"Debug this error", "Use the standard imaging pipeline", "Inspect these results and tell me +what to try next." + +Autonomy: "Model this lens end-to-end", "Plan and execute the full SLaM analysis", "Run this +project over several sessions and track progress", "Analyse this sample and summarise the +results." diff --git a/skills/_style.md b/skills/_style.md index 605939b..24a1961 100644 --- a/skills/_style.md +++ b/skills/_style.md @@ -74,8 +74,8 @@ markdown cell and the code between blocks becomes a code cell. Two rules. -The level of detail in a saved script is **mode-invariant**. Teacher, assistant, and agent -modes may change the pacing and depth of the surrounding conversation, but they must not +The level of detail in a saved script is **mode-invariant**. Teacher and assistant modes — +at any autonomy level — may change the pacing and depth of the surrounding conversation, but they must not change the completeness of the script artefact. Write docstrings as if the script may become part of the open-source repository accompanying a paper: preserve the scientific motivation, what is inferred and how, consequential assumptions and configuration choices, enough context diff --git a/wiki/project/_profile_template.md b/wiki/project/_profile_template.md index c4b75e3..a6eba71 100644 --- a/wiki/project/_profile_template.md +++ b/wiki/project/_profile_template.md @@ -38,12 +38,14 @@ _unrecorded_ ## Interaction mode -Durable preference for how the assistant should interact: `teacher` (learn the workflow), -`assistant` (do the workflow), or `agent` (run the project). Leave unrecorded to let the -assistant infer the mode from each opening request. See `AGENTS.md` "Modes". Examples: +Durable preference for how the assistant should interact: `teacher` (learn the workflow) or +`assistant` (do the workflow — note a preferred autonomy level in prose if it's durable). +`agent` is still understood as a legacy alias for assistant-with-autonomy. Leave unrecorded +to let the assistant infer the mode from each opening request. See `AGENTS.md` "Modes". +Examples: - "teacher — workshop attendee, wants the science explained." -- "agent — running a multi-session subhalo project." +- "assistant — prefers autonomous multi-session runs (subhalo project)." _unrecorded_ From 8f6b0b215218542b6a80801cff96f861a9f82b0b Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Wed, 8 Jul 2026 16:06:47 +0100 Subject: [PATCH 2/3] docs: template-boundary notes for maintainers + skills-index maturity legend MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit maintainer.md gains an assistant-as-template section mapping generic assistant infrastructure vs PyAutoLens-specific content — the seam a future assistant-cloning workflow cuts along (no premature generalisation). skills/README.md states the complete-unless-(stub) convention up front. Co-Authored-By: Claude Fable 5 --- modes/maintainer.md | 25 +++++++++++++++++++++++++ skills/README.md | 4 ++++ 2 files changed, 29 insertions(+) diff --git a/modes/maintainer.md b/modes/maintainer.md index 44cc429..3cd52c5 100644 --- a/modes/maintainer.md +++ b/modes/maintainer.md @@ -54,6 +54,31 @@ Ordering matters at release: PyAutoBuild regenerates + commits the API baseline calling this workflow, so `--check-version` compares the new stack against an already-updated baseline. When you change the rules, edit them here only; never copy a rule into PyAutoBuild. +## Assistant-as-template: generic vs PyAutoLens-specific + +This repo is the reference implementation future PyAuto domain assistants (e.g. +`autofit_assistant`, `autogalaxy_assistant`) will be modelled on. When maintaining it, keep +this boundary in mind — it is the seam a future cloning workflow will cut along. Do not +generalise anything pre-emptively; just avoid entangling the two sides. + +**Generic assistant infrastructure** (clones to any domain assistant near-verbatim): +`AGENTS.md`'s skeleton (session start, safety invariants, three-layer model, mode +selection, source-of-truth resolution, commit cadence), the Teacher/Assistant mode model +and `modes/` machinery (`.mode`, `.maintainer` sentinels), the skills framework +(`_style.md`, `_bootstrap_skill.md`, the README index conventions), the +`core`/`literature`/`project` wiki split and its read-only/update rules, the science-project +lifecycle (`start-new-project`, `contribute-upstream`), `sources.yaml` + the source +registry pattern, the API gate (`autoassistant/audit_skill_apis.py` + wiki-currency +workflow), and the profile template. + +**PyAutoLens-specific content** (regenerated per domain, never copied blind): every +`al_*` skill body, `wiki/core/` reference pages, the entire `wiki/literature/` sub-wiki, +bundled `dataset/` examples, the README's science framing and three example prompts, the +standard-imports convention, and `hpc/` templates tuned to lensing runtimes. + +**Mixed** (structure generic, values domain-specific): `llms.txt` read-order, +`config/`, the maintainer smoke tests below. + ## Chat-surface compatibility smoke test Run these checks after documentation changes are available on the public GitHub repository. Do diff --git a/skills/README.md b/skills/README.md index 74bfc29..fc5abfc 100644 --- a/skills/README.md +++ b/skills/README.md @@ -24,6 +24,10 @@ configured) via symlinks; the canonical files live here. ## Index +Every skill below is a **complete recipe** unless marked `(stub)` — the stubs are gathered +under "Pending — stubbed" at the end, with a queue of catalogued-but-unstubbed topics after +them. + ### Meta - [`_style.md`](./_style.md) — writing guide every skill is authored against. Read first From 41b4d74633362822a19b1e597045898eb7eed70f Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Wed, 8 Jul 2026 16:13:23 +0100 Subject: [PATCH 3/3] =?UTF-8?q?feat!:=20remove=20the=20agent=20mode=20name?= =?UTF-8?q?=20entirely=20=E2=80=94=20no=20legacy=20alias?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit modes/agent.md is deleted and every alias mention removed (AGENTS.md mode selection, .gitignore .mode comment, profile template). The mode model is exactly two names: teacher and assistant; autonomy is a request within assistant mode, not a mode name. A '.mode' file or profile entry saying 'agent' is now simply unrecognised. Co-Authored-By: Claude Fable 5 --- .gitignore | 3 +-- AGENTS.md | 5 ++--- modes/agent.md | 9 --------- wiki/project/_profile_template.md | 5 ++--- 4 files changed, 5 insertions(+), 17 deletions(-) delete mode 100644 modes/agent.md diff --git a/.gitignore b/.gitignore index 190ce91..f3a0699 100644 --- a/.gitignore +++ b/.gitignore @@ -48,8 +48,7 @@ papers/ .maintainer # Interaction-mode override — optional per-clone file containing `teacher` or -# `assistant` (`agent` = legacy alias for assistant-with-autonomy). See AGENTS.md -# "Modes". `.maintainer` outranks it. +# `assistant`. See AGENTS.md "Modes". `.maintainer` outranks it. .mode # Claude Code agent worktrees — ephemeral, machine-local. diff --git a/AGENTS.md b/AGENTS.md index f208a82..dc6038a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,9 +100,8 @@ how it paces the work, not which workflows exist: Select (first match): explicit instruction → `.mode` file → `profile.md` "Interaction mode" → else **infer from the opening request** (fall back to **assistant**); `.maintainer` outranks -`.mode`; `agent` is accepted anywhere a mode is named as a legacy alias for -assistant-with-autonomy. State an inferred mode in one line and invite correction; acknowledge -an explicit one only if it changes behavior. Read `modes/.md`; depth still follows +`.mode`. State an inferred mode in one line and invite correction; acknowledge an explicit +one only if it changes behavior. Read `modes/.md`; depth still follows `skills/_style.md` "Adaptive depth". --- diff --git a/modes/agent.md b/modes/agent.md deleted file mode 100644 index 0a42776..0000000 --- a/modes/agent.md +++ /dev/null @@ -1,9 +0,0 @@ -# Agent mode (legacy alias) - -Agent mode has merged into **assistant mode**: instead of switching modes, the assistant -adapts its planning, conversation and autonomy to the request. `agent` remains accepted -wherever a mode is named (an explicit instruction, the `.mode` file, `profile.md`) and -resolves here. - -Read [`assistant.md`](./assistant.md) — in particular "The autonomy dial" — and behave as -assistant mode with autonomy requested. diff --git a/wiki/project/_profile_template.md b/wiki/project/_profile_template.md index a6eba71..d0515f5 100644 --- a/wiki/project/_profile_template.md +++ b/wiki/project/_profile_template.md @@ -40,9 +40,8 @@ _unrecorded_ Durable preference for how the assistant should interact: `teacher` (learn the workflow) or `assistant` (do the workflow — note a preferred autonomy level in prose if it's durable). -`agent` is still understood as a legacy alias for assistant-with-autonomy. Leave unrecorded -to let the assistant infer the mode from each opening request. See `AGENTS.md` "Modes". -Examples: +Leave unrecorded to let the assistant infer the mode from each opening request. See +`AGENTS.md` "Modes". Examples: - "teacher — workshop attendee, wants the science explained." - "assistant — prefers autonomous multi-session runs (subhalo project)."