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

.claude/commands/wake_up.md

@@ -0,0 +1 @@
+../../skills/wake_up/wake_up.md

.claude/commands/workspace.md

@@ -0,0 +1 @@
+../../skills/workspace/workspace.md

.claude/skills/wake_up

@@ -0,0 +1 @@
+../../skills/wake_up

.claude/skills/workspace

@@ -0,0 +1 @@
+../../skills/workspace

.codex/skills/wake-up

@@ -0,0 +1 @@
+../../skills/wake_up

.codex/skills/workspace

@@ -0,0 +1 @@
+../../skills/workspace

AGENTS.md

@@ -123,6 +123,17 @@ humans invoke identically, so behaviour isn't re-derived from prose each time.
   formalises). The first conductor whose normal `--auto` mode is **`safe`**
   (the `refactor` work-type cap in [`AUTONOMY.md`](AUTONOMY.md)). Reuses the
   Feature Agent's core by import.
+- **`agents/conductors/workspace/`** — the *Voice*: the organism's expressive
+  function — how it speaks to practitioners (workspace examples) and teaches
+  first-time learners (the `howto` register). Reasons over workspace + HowTo
+  example authorship and emits a `WorkspaceDecision` — target repo, audience
+  register (`workspace`|`howto`), placement in the target's real `scripts/`
+  tree, the sibling example to mirror, prose tier, format checklist — that the
+  `start_dev → start_workspace → ship_workspace` flow consumes. A `survey`
+  mode inventories/diffs example catalogues (the newborn-workspace bootstrap
+  tool). One agent, two registers; the split trigger for a future HowTo agent
+  is recorded in its AGENTS.md. Decision-only: never edits source, never
+  writes files.
 - **`agents/conductors/profiling/`** — the *proprioceptive function*: the
   organism's sense of its own effort. Heart reads the vitals at rest; this
   agent runs the stress test — it owns the performance-data lifecycle with
@@ -224,6 +235,7 @@ the `/<verb>` slash commands.
 | `feature` | Reason over PyAutoMind feature tasks: select, size, phase, plan for start_dev | `bin/pyauto-brain feature` |
 | `bug` | The immune system: classify a bug/regression/Heart finding, locate the fix, plan the repair | `bin/pyauto-brain bug` |
 | `refactor` | The renewal function: plan behaviour-preserving restructuring — RefactorDecision; default-safe under --auto | `bin/pyauto-brain refactor` |
+| `workspace` | The voice — the organism's expressive function: plan/survey workspace + HowTo example authorship (workspace\|howto registers) — WorkspaceDecision (never writes) | `bin/pyauto-brain workspace` |
 | `profiling` | The proprioceptive function — the organism's sense of its own effort: campaign/ingest/triage plans over the autolens_profiling workspace — ProfilingDecision | `bin/pyauto-brain profiling` |
 | `hygiene` | The maintenance function — the organism's sense of its own upkeep: code-quality debt (dev-loop cost + tidiness), delegating fixes — HygieneDecision | `bin/pyauto-brain hygiene` |
 | `clone` | The Mitosis Agent (v0: decision only): partition the reference assistant, analyze the domain, emit the CloneDecision — never writes | `bin/pyauto-brain clone` |
@@ -262,6 +274,7 @@ the Brain routes it to the right agent; normal usage never says "PyAutoBrain".
 | `/build` | Build Agent → vitals → Heart → PyAutoBuild | real conductor |
 | `/health` | Health Agent loop → vitals → Heart | real conductor |
 | `/refactor` | Refactor Agent → `start_dev [--auto]` (default-safe) | real conductor |
+| `/workspace` | Workspace Agent → WorkspaceDecision → `start_dev` → `start_workspace` | real conductor |
 | `/docs` `/research` | `start_dev` pre-tagged with the work-type | work-type entry* |
 | `/route <text>` | infers the work-type and dispatches to one of the above | NL router |
 | `/wake_up` | sync + clean-slate (local) + gh-API glance (overnight runs, version drift, resume) + `/health`/`/hygiene` → digest; CLI + mobile/codex | composition door |
@@ -271,7 +284,10 @@ the Brain routes it to the right agent; normal usage never says "PyAutoBrain".
 Brain dev-flow with their PyAutoMind work-type fixed (still through the Brain,
 nothing bypassed). A dedicated conductor is added only on demonstrated need,
 never for symmetry — the Refactor Agent earned its promotion via the `ideas.md`
-backlog bullet, the skill's own recorded follow-up, and the autonomy series.
+backlog bullet, the skill's own recorded follow-up, and the autonomy series;
+the Workspace Agent earned its via the recurring post-library example work and
+the `autoreduce_workspace` birth (`/docs` remains the generic docs entry —
+workspace/HowTo *example authorship* specifically routes via `/workspace`).
 Every command routes **through** the Brain; none replaces it.
 
 The command bodies live in `skills/<verb>/<verb>.md`; thin `SKILL.md` wrappers

agents/conductors/workspace/AGENTS.md

@@ -0,0 +1,108 @@
+# Workspace agent
+
+> **Tier: conductor** — a front-door agent you *drive*. The *Voice* — the
+> organism's expressive function: how it speaks to its users. Workspace
+> examples are how it addresses practitioners; the `howto` register is how it
+> teaches first-time learners (undergrads, new PhD students). It reasons over
+> example-authorship intent and emits a `WorkspaceDecision` the
+> `start_dev → start_workspace → ship_workspace` flow consumes — it never
+> edits source and, in v0, never writes anything at all.
+
+Grown from demonstrated need, not symmetry: workspace-example authorship is a
+recurring follow-up to every library extension, and `autoreduce_workspace` /
+`autoreduce_workspace_test` are being born and must mirror the established
+workspaces. Founding prompt and one-agent-vs-two assessment: PyAutoMind
+`active/workspace_examples_agent.md` (issue PyAutoBrain#116).
+
+## One agent, two registers
+
+The examples surface has one format and two audiences:
+
+- **`workspace`** — reference examples for practitioners (`*_workspace`
+  repos): standalone, task-oriented, reachable from a search with no prior
+  reading assumed.
+- **`howto`** — narrative teaching for first-time learners (`HowTo*` repos):
+  cumulative chapters, terms defined at first use, physical intuition before
+  API.
+
+Everything else — the contents+docstring script format, markdown/notebook
+generation, the `start_workspace → ship_workspace` pipeline, API grounding
+against the installed stack, the assistant-training role — is shared, which is
+why this is one agent and not two.
+
+**Split trigger** (recorded so the future decision is cheap): promote the
+`howto` register to its own agent only when it develops a decision surface the
+workspace register cannot share — curriculum/chapter-continuity planning,
+exercise design, or learner-feedback state. Until then it is a register, not
+an organism function.
+
+## Modes
+
+Both modes are read-only; the agent writes nothing (the Clone Agent's v0
+boundary).
+
+- **plan** (default) — `pyauto-brain workspace "<raw text>"` or
+  `pyauto-brain workspace <PyAutoMind prompt path>`: classifies the intent and
+  emits the `WorkspaceDecision` — library family, target repo, register,
+  placement (ranked against the target's *real* `scripts/` tree; the repo's
+  own folders always win), the sibling example to mirror, the prose tier
+  (WORKFLOW.md tutorial-prose split), the format checklist, and the routing
+  (`start_dev` → `start_workspace`). A newborn target with no `scripts/` tree
+  anchors its structure on `autolens_workspace` — the bootstrap case.
+- **survey** — `pyauto-brain workspace survey <repo> [--against <sibling>]`:
+  inventories a workspace repo's example catalogue (packages + script counts);
+  `--against` diffs the structure against a sibling — missing/extra packages
+  and per-package counts. This is the `autoreduce_workspace` bootstrap tool:
+  `survey autoreduce_workspace --against autolens_workspace` is its birth
+  checklist.
+
+`--json` gives the machine-readable decision/survey for both.
+
+## Format grounding (pointers, never a restated spec)
+
+The canonical format lives where it is executed, and the decision points at it
+rather than duplicating it:
+
+- the **sibling example script** the decision names — structure is copied from
+  a living example, never invented;
+- **PyAutoBuild's notebook generation** — every top-level docstring becomes a
+  markdown cell, which is what makes the docstring format load-bearing;
+- **`skills/WORKFLOW.md` tutorial-prose split** — example/howto prose is
+  judgment-tier (the docstrings are the product); `*_workspace_test` scripts
+  are execution-tier;
+- the workspace rules that recur in review: docs are minimal not maximal
+  (flag/value + one-line note, no ported runnable blocks); new library
+  `output.yaml` keys are mirrored into workspace configs; every API symbol is
+  grounded against the installed stack (the PyAuto API gate enforces this).
+
+## Consult graph
+
+Like every conductor it consults faculties, never other conductors: the
+**memory faculty** when tutorial prose needs scientific or prior-art context
+(`pyauto-brain memory "<topic>"`). It has no business with Heart — example
+authorship is dev work, gated at ship time like any other change.
+
+## Boundary
+
+- **Decides and routes; never authors.** The writing happens in the dev flow
+  the decision points into; prose stays judgment-tier per WORKFLOW.md.
+- **Never writes files, never mutates a repo** (v0). If an `--apply` ever
+  arrives it will scaffold *placement* (empty package dirs mirroring a
+  sibling), not prose.
+- **Conductor, not faculty, deliberately:** it is a front door a human drives
+  to *start* example work (the Feature Agent's shape), not an opinion another
+  conductor consults. If a ship-time "does this script meet the format?"
+  opinion is later needed, that is a separate read-only faculty, not this
+  agent grown teeth.
+
+## Running
+
+```
+bin/pyauto-brain workspace "interferometer example for autoreduce_workspace"
+bin/pyauto-brain workspace "new HowToLens chapter on mass profiles"
+bin/pyauto-brain workspace draft/docs/workspaces/<prompt>.md
+bin/pyauto-brain workspace survey autoreduce_workspace --against autolens_workspace
+```
+
+Repos resolve under `PYAUTO_ROOT` (default `~/Code/PyAutoLabs`). Exit codes:
+0 decision · 4 inputs unresolvable · 5 bad usage.