feat: Workspace Agent — conductor for workspace + HowTo example authorship

[Jammy2211]

Overview

Workspace-example authorship is becoming a routine follow-up to library work, and autoreduce_workspace / autoreduce_workspace_test are about to be born. This task adds the Workspace Agent — a new PyAutoBrain conductor (the Voice — the organism's expressive function) that reasons over workspace + HowTo example authorship and routes it into the dev flow. One agent covers both surfaces via two audience registers (workspace for practitioners, howto for first-time learners); the split trigger for a future dedicated HowTo agent is recorded in its AGENTS.md.

Plan

• Add conductor agents/conductors/workspace/ (AGENTS.md + thin workspace.sh + stdlib-only _workspace.py), decision-only v0: emits a WorkspaceDecision, never writes.
• Modes: default plan (raw text or Mind prompt path → target repo, register, placement, sibling example, prose tier, format checklist, next action) and survey (workspace survey <repo> [--against <sibling>] — read-only catalogue inventory + structural diff; the autoreduce_workspace bootstrap tool).
• Wire the verb: bin/pyauto-brain maps + CONDUCTOR_ORDER, regenerate the command-surface tables via bin/install.sh --write-agents-surface, add skills/workspace/ wrapper + body, skills/COMMANDS.md row, PyAutoBrain AGENTS.md conductor bullet + /docs footnote amendment.
• Hermetic contract tests tests/test_workspace_conductor.py mirroring the hygiene conductor's.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary, only)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoBrain	main	clean

Suggested branch: feature/workspace-agent
Worktree: ~/Code/PyAutoLabs-wt/workspace-agent/

Design decisions (from the approved plan)

• One agent, two registers (workspace | howto): ~90% of the machinery is shared (contents+docstring format, notebook generation, start_workspace→ship_workspace pipeline, assistant-training role). Doctrine: "new agents on demonstrated need, never for symmetry".
• Conductor, not faculty: a front door the human drives that decides-and-routes example work into the dev flow (the Feature Agent's shape). Like the Clone Agent, v0 is decision-only and writes nothing.
• Organism analogy (first line of its description): the Voice — how the organism speaks to practitioners (workspace examples) and teaches first-time learners (the howto register).
• Split trigger recorded in AGENTS.md: promote HowTo to its own agent only if it grows an unshareable decision surface (curriculum/chapter-continuity planning, exercise design, learner-feedback state).
• Format-spec grounding is pointers, never a restated spec: workspace repos' scripts, PyAutoBuild notebook generation, WORKFLOW.md tutorial-prose split, the "docs minimal not maximal" rule.

Implementation Steps

1. agents/conductors/workspace/AGENTS.md — Tier line + Voice analogy first; demonstrated need; the two registers + split trigger; modes; WorkspaceDecision fields; format-spec grounding pointers; consult graph (memory faculty optionally; never Heart); "never edits source, never writes" v0 boundary; founding prompt reference.
2. agents/conductors/workspace/workspace.sh — ~20-line entrypoint (clone.sh pattern): usage header, source ../../_common.sh, exec python3 "$HERE/_workspace.py" "$@".
3. agents/conductors/workspace/_workspace.py — stdlib-only, read-only. Plan mode: classify register (HowTo* target or teaching keywords ⇒ howto), resolve target workspace repo, suggest placement anchored on the core-API structure (imaging/interferometer/point_source/guides), find nearest sibling example dir (read-only scan), emit prose tier (judgment per WORKFLOW.md), compact format checklist, next action (start_dev → start_workspace). Survey mode: inventory a workspace repo's example catalogue; --against diffs structure vs a sibling. Repos resolve under PYAUTO_ROOT (default ~/Code/PyAutoLabs) so tests are hermetic. --json for both modes.
4. bin/pyauto-brain — AGENT_SCRIPT[workspace], AGENT_DESC[workspace] ("The voice — the organism's expressive function: plan/survey workspace + HowTo example authorship (workspace|howto registers) — WorkspaceDecision (never writes)"), CONDUCTOR_ORDER insert after refactor, header comment.
5. bash bin/install.sh --write-agents-surface (regenerates the AGENTS.md verb tables from AGENT_DESC) and bash bin/install.sh (installs the /workspace skill symlinks).
6. PyAutoBrain/AGENTS.md hand parts — Workspace Agent bullet under "### Conductors"; /workspace row in the command-routing table; amend the /docs footnote.
7. skills/workspace/SKILL.md + skills/workspace/workspace.md — command body (required by tests/test_skill_install.py).
8. skills/COMMANDS.md — /workspace routing row.
9. tests/test_workspace_conductor.py — hermetic contract tests: complete --json WorkspaceDecision structure; register classification both ways; survey + --against on a fabricated temp tree; unknown mode exits non-zero; tree unchanged after runs (never writes).

Key Files

• agents/conductors/workspace/{AGENTS.md,workspace.sh,_workspace.py} — the new conductor
• bin/pyauto-brain, bin/install.sh (run, not edited) — verb wiring + generated surface
• skills/workspace/{SKILL.md,workspace.md}, skills/COMMANDS.md — command surface
• AGENTS.md — conductor bullet, routing row, /docs footnote
• tests/test_workspace_conductor.py — contract tests

Verification

• pytest tests/ in the worktree (new tests + test_skill_install.py green).
• bash bin/install.sh --check — no surface drift.
• Manual drives: plan mode on workspace-flavoured and HowTo-flavoured text; survey autolens_workspace; pyauto-brain help workspace shows the Voice first line.

Original Prompt

Click to expand starting prompt

Workspace Examples Agent — one Brain agent for workspace + HowTo example authorship

Type: feature
Target: PyAutoBrain
Repos:

• PyAutoBrain
  Difficulty: medium
  Autonomy: supervised
  Priority: normal
  Status: formalised

Intent (original request, condensed)

PyAutoReduce will soon gain autoreduce_workspace / autoreduce_workspace_test,
mirroring the design, functionality and purpose of the existing workspaces
(autolens_workspace, autogalaxy_workspace). Workspace conventions: scripts follow
a specific contents + Python-docstring format used to generate their markdown and
Jupyter-notebook docs; they are the user-facing docs giving end-to-end scientific
examples for most high-level tasks; and they are the core scientific context that
trains the domain assistants (e.g. autolens_assistant). Working workspace examples
is becoming a common task in development workflows after source-library
extensions, so @PyAutoBrain needs a dedicated agent for it. Assess whether the
same agent can also cover the HowTo repos (HowToFit/HowToGalaxy/HowToLens — same
structure/format, but written at a lower level for first-time learners such as
undergrads and new PhD students), or whether a separate HowTo agent is needed.

Assessment: one agent, two registers (decided at intake, revisit at start_dev)

One agent covering both, with an explicit workspace vs howto audience
register, is the right shape:

• ~90% of the machinery is identical: the contents+docstring format spec, the
  markdown/notebook generation conventions, the start_workspace → ship_workspace
  pipeline, API grounding against the installed stack, and the
  assistant-training role. Two agents would duplicate the format spec — a drift
  hazard the workspace's single-source-of-truth rule exists to prevent.
• PyAutoBrain doctrine agrees: "new agents are added on demonstrated need,
  never for symmetry"; there is no demonstrated HowTo-specific need yet, only a
  register difference. WORKFLOW.md already treats HowTo repos as workspace repos
  in the same pipeline, and its tutorial-prose split already places howto*
  prose in the judgment tier alongside workspace tutorials.
• Modes are the established pattern for one conductor with variant behaviour
  (build: build/deploy/release; profiling: campaign/ingest/triage).
• Split trigger (record in the agent's AGENTS.md): promote HowTo to its own
  agent only when it develops a decision surface the workspace register cannot
  share — e.g. curriculum/chapter-continuity planning, exercise design, or
  learner-feedback state. Until then it is a register, not an organism function.

Design questions for start_dev

1. Conductor vs faculty. The authoring itself is dev work the existing
   start_dev → start_workspace → ship_workspace flow already executes; what is
   missing is specialist reasoning (where an example belongs, format/register
   checklists, coverage gaps after a library change). That is a read-only
   opinion → the Brain's tier rule suggests a faculty (an ExamplesSurface
   consulted by the /docs work-type entry and ship_workspace), not a new
   conductor. A conductor is only justified if it must decide-and-dispatch
   (e.g. select the next coverage gap and route it into start_dev, like the
   Feature Agent). Decide the tier explicitly before wiring.
2. What the decision object contains: target repo + package placement,
   format checklist, audience register, phasing, downstream-notebook impact.
3. How the format spec is grounded — point at the canonical spec/generator in
   the workspace repos / PyAutoBuild rather than restating it in prose.
4. autoreduce_workspace bootstrap: the new agent/faculty should serve the
   autoreduce workspace's creation as its first demonstrated-need case.

Deliverables

• The one-vs-two assessment recorded (this file, refined if start_dev disagrees).
• The new Brain agent (conductor or faculty per question 1) under
  PyAutoBrain/agents/, with AGENTS.md, deterministic entrypoint, and the
  workspace/howto register distinction documented.
• Command-surface wiring only if a conductor: verb + skill body; a faculty
  stays consult-only behind /docs.

[Jammy2211]

PR open: #118 — implemented per the plan (conductor + wiring + all conductor-describing surfaces updated: AGENTS.md tables/bullet, COMMANDS.md, route/brain skill bodies, docs/concepts/agents.md, PyAutoMind/ROUTING.md, project-discovery symlinks). 69/69 tests green incl. 10 new hermetic contract tests; manual drives verified both registers, the autoreduce newborn fallback, and the survey diff. Heart RED at ship time was unrelated to this branch (parallel-session PyAutoLens dirt + stale 07-09 validation pointer) — shipped to PR-open on user acknowledgement; merge stays human.

[Jammy2211]

Shipped: PR #118 merged to main. The Workspace Agent (the Voice) is live — pyauto-brain workspace / /workspace, plan + survey modes, workspace|howto registers. First use case queued: workspace survey autoreduce_workspace --against autolens_workspace when the autoreduce workspace is born.