docs: reference-assistant audit — README/AGENTS cleanup + mode-model assessment

[Jammy2211]

Overview

Audit and improve autolens_assistant as the reference implementation of a PyAuto domain assistant, ahead of it becoming the template future assistants (autofit/autogalaxy/autoarray) are cloned from. Phase 1 of 2: the audit report plus README/AGENTS.md cleanup and the interaction-mode assessment; skill-stub completion is deferred to a second PR.

Plan

1. Audit the six areas in the prompt — README onboarding, AGENTS.md, skills index, wiki split, project lifecycle, template-readiness — and write the audit report into the draft-PR body.
2. Assess the interaction-mode model, with the working hypothesis that Assistant and Agent merge into one adaptive Assistant mode (conversational by default, autonomous when asked) while Teacher stays distinct; implement the reworded model if the audit supports it.
3. Apply small, reviewable README + AGENTS.md cleanups from the audit findings — no rewrite.
4. Add maturity labels (mature / stub) to skills/README.md index entries; fill nothing.
5. Tighten the assistant-repo vs science-project vs PyAutoLens-source boundary wording where unclear.
6. Leave template-readiness notes: what is PyAutoLens-specific vs generic assistant infrastructure.
7. Validate and open a draft PR; merge stays human.

Detailed implementation plan

Affected Repositories

• autolens_assistant (primary, only)

Branch Survey

Repository	Current Branch	Dirty?
./autolens_assistant	main	clean (one stray untracked james.bib, untouched)

Suggested branch: feature/autolens-assistant-audit

Implementation Steps

1. Mode merge (the one design change): rework AGENTS.md "Modes" (~lines 89–103) and README.md "Modes" (~lines 61–71) into a two-mode model: Teacher (learn) and Assistant (do — adapts planning depth, conversation and autonomy to the request; defaults conversational; runs autonomously with checkpoints when the user asks). Merge modes/agent.md into modes/assistant.md as an "autonomy dial" section; keep .mode: agent accepted as a back-compat alias so nothing breaks. Rework README example prompt 3's header ("Agent Mode" → autonomy-requested Assistant phrasing). Grep all other "agent mode" references (skills/_style.md, wiki/, llms.txt, modes/maintainer.md) and reconcile.
2. README: onboarding order already good; fix small clarity issues found in audit (e.g. typo "preparaton"; mode-section rewrite above); confirm the three example prompts remain the right three.
3. AGENTS.md: structure sound at 199 lines; audit for contradictions across session-start / safety invariants / maintainer mode / source-of-truth resolution; wording-level fixes only, plus the Modes rewrite.
4. skills/README.md: annotate the index (~19 entries already carry pending markers) with an explicit maturity legend (mature / stub); write no stub content.
5. Template notes: short assistant-as-template note (likely wiki/project/ or a README maintainer pointer) mapping generic infrastructure (modes, skills framework, wiki split, project lifecycle, API gate) vs PyAutoLens-specific content (al_* skills, literature wiki, bundled datasets).
6. Audit report in the draft-PR body: what was inspected / changed / deliberately not changed / follow-up work.

Validation

• python autoassistant/audit_skill_apis.py --check-version; any Makefile check targets; markdown-link sweep over edited files; internal-consistency pass.
• Commit per checkpoint with explicit staging (never git add -A); draft PR opened via gh api if needed.

Deliberately not changing

• Safety invariants, skill names, wiki scientific content, output//sources/ machinery, skill stubs (phase 2).

Key Files

• AGENTS.md — canonical instructions; Modes section rewrite + consistency fixes
• README.md — Modes section, example prompt 3, small clarity fixes
• modes/assistant.md, modes/agent.md — merge into adaptive assistant mode
• skills/README.md — maturity legend + labels

Original Prompt

Click to expand starting prompt

Goal: audit and improve autolens_assistant as the reference implementation of a
PyAuto domain assistant.

Scope for the first pass: the audit report plus README/AGENTS.md cleanup
only. Skill-stub completion and larger structural changes are deferred to a
second PR.

Context

autolens_assistant is intended to be an AI assistant for PyAutoLens science. It
combines:

• repository-level agent instructions;
• Teacher / Assistant / Agent interaction modes;
• procedural skills;
• core, literature and project wiki material;
• science-project scaffolding;
• safety rules for real data, source editing, API drift, generated scripts and
  git history.

Review the repository deeply and improve it where useful, but keep the scope
controlled. The aim is not a rewrite. The aim is to make autolens_assistant
clearer, more robust, more internally consistent, and easier to use as the
canonical pattern for future PyAuto assistants.

Important design constraints

• Treat AGENTS.md as the canonical agent-agnostic source of truth.
• Do not create parallel duplicated instruction files that will drift.
• Teacher mode is definitely important — preserve it. The Assistant / Agent
  split is up for assessment (see "Interaction modes" below); do not treat the
  three-mode model as fixed.
• Preserve the safety invariants, especially:
  • inspect real data before fitting;
  • never write into output/ or sources/;
  • keep wiki/core/ read-only except through the update workflow;
  • do not edit PyAuto source code in normal user sessions;
  • never rewrite git history.
• Keep the assistant practical and user-facing. It should help a scientist get
  work done, not become an over-engineered meta-framework.
• Prefer small, reviewable improvements over broad rewrites.
• Do not break existing skill names or expected workflows.

Audit areas

Interaction modes (explicit design question)

Assess whether Assistant mode and Agent mode should remain distinct. The
working hypothesis: merge them into a single Assistant mode that adapts
its planning depth, amount of conversation and autonomy to the user's request
— defaulting to more conversational, and only running autonomously when the
user asks for it. Teacher mode stays as a distinct mode. If the audit
supports the merge, propose the reworded mode model (README + AGENTS.md) as
part of this PR; if there is a strong reason to keep the split, say why.

Onboarding and README

• Is the README clear for a new user?
• Is the distinction between the assistant repo and a separate science project
  clear?
• Are the examples still the right three examples?
• Are Teacher / Assistant / Agent modes explained in a way a user will
  understand?

Agent instructions

• Is AGENTS.md concise enough for coding agents while still complete?
• Are the session-start steps sensible?
• Are the safety invariants clear and non-contradictory?
• Are maintainer mode, user profile, mode selection and source-of-truth
  resolution well defined?
• Are there any instructions likely to confuse Claude Code, Codex, Gemini,
  OpenCode or Copilot?

Skills

• Audit skills/README.md and the individual skills.
• Identify which skills are mature, which are stubs, and which are missing.
• Improve the most important high-leverage skill documentation first.
• Do not try to fill every pending stub in one PR.
• If you choose a stub to complete, pick one with clear value and limited
  scope. (First pass: identify and label only — completion is a second PR.)

Wiki

• Check whether the wiki/core/, wiki/literature/ and wiki/project/ split is
  explained clearly.
• Check whether wiki references from skills are discoverable and not stale.
• Do not rewrite large scientific content unless necessary.
• Flag places where the wiki is missing obvious assistant-critical concepts.

Project lifecycle

• Review start-new-project and related project workflow material.
• Check whether the assistant clearly separates:
  • the assistant's own skills/wiki/tooling;
  • a user's science project data/scripts/results/journal;
  • PyAutoLens source code.
• Improve wording or structure if this boundary is unclear.

Assistant-as-template

• While reviewing, think ahead: this repo may become the template for future
  assistants such as autofit_assistant, autogalaxy_assistant, or
  autoarray_assistant.
• Identify which parts are genuinely PyAutoLens-specific and which are generic
  assistant infrastructure.
• Do not prematurely generalise the codebase, but leave clear notes about what
  would need abstraction later.

Deliverables

• A short audit report in the PR body covering: what was inspected; what was
  changed; what was deliberately not changed; the most important follow-up
  work.
• A focused PR that improves the repo. First-pass candidates:
  • clearer README onboarding;
  • cleaner mode explanation;
  • improved AGENTS.md structure;
  • better skill index / maturity labels;
  • clearer documentation of the assistant repo vs science project boundary;
  • notes preparing the repo to serve as a future assistant template.
• Deferred to a second PR: upgrading a high-value skill stub from TODO
  scaffold to usable recipe.

The Clone Agent / Mitosis Agent design (a future PyAutoBrain agent that
generates new assistants modelled on autolens_assistant) is filed as a
separate prompt under PyAutoBrain — do not implement it here.

Validation

• Run any available tests or lint/check scripts in the repo.
• Check markdown links where practical.
• Check that any edited instructions remain internally consistent.
• If there is a line-count or skill-format guard, run it.
• Do not push directly to main. Create a branch named something like
  feature/autolens-assistant-audit and open a draft PR with a clear summary.

[Jammy2211]

Draft PR is up: #34.

The audit ran across README, AGENTS.md, all four mode files, the skills index/style guide, the wiki split and the project-lifecycle boundary. Headline outcome: Assistant and Agent modes are merged into one adaptive Assistant mode (conversational by default, phased + checkpointed when you ask for autonomy), with Teacher kept distinct and agent accepted everywhere as a legacy alias — nothing breaks. Maintainer notes now map the generic-template vs PyAutoLens-specific seam for the future assistant-cloning workflow.

Validation: citation metadata valid, API symbol audit 0 broken (110 symbols), links clean. The --check-version failure is the pre-existing stack skew Heart already tracks, not from this PR.

Full audit report (inspected / changed / deliberately-not-changed / follow-ups) is in the PR body. Phase 2 — upgrading one skill stub to a full recipe — stays a separate PR.

[Jammy2211]

Update: the agent mode name is now removed entirely — no legacy alias. modes/agent.md is deleted and the mode vocabulary is exactly teacher | assistant; autonomy is something you ask assistant mode for, not a mode name (commit 41b4d74).

Validation re-run after the change: citations valid, symbol audit 0 broken, no dangling modes/agent.md links. PR #34 is updated and marked ready for review — merge is yours.