Add concise PyAutoBrain agent commands

AGENTS.md

@@ -182,6 +182,34 @@ Like the other PyAuto repos, PyAutoBrain runs from its checkout (no pip install)
 it resolves the sibling `pyauto-heart` and `autobuild` binaries from PATH or the
 `~/Code/PyAutoLabs/` checkouts.
 
+## The command surface (Brain implicit)
+
+The `bin/pyauto-brain <agent>` CLI above is the machinery; humans drive it through
+short verb commands installed into `~/.claude/commands/`. The Brain stays
+**implicit** — you type a verb (or plain natural language) and the Brain routes it
+to the right agent; normal usage never says "PyAutoBrain".
+
+> **Users speak in short commands; PyAutoBrain performs the routing.**
+
+| Command | Routes to | Tier |
+|---------|-----------|------|
+| `/feature` | Feature Agent → `start_dev` | real conductor |
+| `/build` | Build Agent → vitals → Heart → PyAutoBuild | real conductor |
+| `/health` | Health Agent loop → vitals → Heart | real conductor |
+| `/bug` `/refactor` `/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 |
+| `/brain <agent>` | raw `bin/pyauto-brain` passthrough | debug door |
+
+\* No dedicated Bug/Refactor/Docs/Research conductor exists yet — those verbs
+route through the Brain dev-flow with their PyAutoMind work-type fixed (still
+through the Brain, nothing bypassed), until each earns promotion to its own
+conductor. Every command routes **through** the Brain; none replaces it.
+
+The command bodies live in `skills/<verb>/<verb>.md` (thin; installed as flat
+commands by `bin/install.sh`); the shared architecture prose is in
+[`skills/COMMANDS.md`](skills/COMMANDS.md). The work-type taxonomy the router and
+work-type entries use is `PyAutoMind/ROUTING.md`.
+
 ## Never rewrite history
 
 NEVER perform these operations on any repo with a remote:

README.md

@@ -99,4 +99,25 @@ that used to live in `admin_jammy/skills/`. Run `bash PyAutoBrain/bin/install.sh
 to (re-)symlink every organ's skills/commands into `~/.claude/`. See
 [`bin/README.md`](bin/README.md).
 
+## The command surface (Brain implicit)
+
+Humans drive the CLI above through short verb commands installed into
+`~/.claude/commands/`. The Brain stays **implicit**: you type a verb (or plain
+natural language) and it routes to the right agent — normal usage never says
+"PyAutoBrain".
+
+> **Users speak in short commands; PyAutoBrain performs the routing.**
+
+- **Real conductors:** `/feature` → Feature Agent, `/build` → Build Agent,
+  `/health` → Health Agent (each → vitals/Heart/Build as needed).
+- **Work-type entries:** `/bug` `/refactor` `/docs` `/research` route through the
+  Brain dev-flow (`start_dev`) with their PyAutoMind work-type fixed — honest
+  interim doors until each earns its own conductor.
+- **Router + debug:** `/route <text>` infers the work-type and dispatches;
+  `/brain <agent>` is the raw passthrough. Every command routes **through** the
+  Brain; none replaces it.
+
+Bodies live in `skills/<verb>/<verb>.md`; shared prose in
+[`skills/COMMANDS.md`](skills/COMMANDS.md).
+
 See [`AGENTS.md`](AGENTS.md) for the full description.

skills/COMMANDS.md

@@ -0,0 +1,65 @@
+# PyAutoBrain command surface — shared reference
+
+The short verb commands (`/feature`, `/build`, `/health`, `/bug`, `/refactor`,
+`/docs`, `/research`, `/route`, `/brain`) are a thin, human-friendly **veneer**
+over the PyAutoBrain router (`bin/pyauto-brain`). This file is the shared context
+every command file points at, so each command body stays a few lines long.
+
+> **Users speak in short commands; PyAutoBrain performs the routing.**
+
+## The Brain is implicit
+
+You don't tell a brain to "activate the visual cortex" — you *look*, and it
+routes. Same here: a user types a short verb (or plain natural language) and the
+Brain routes it to the right specialist agent. **Normal usage never says
+"PyAutoBrain".** The only explicit-Brain surface is `/brain`, the debug door.
+
+## Never bypass the Brain
+
+Every command routes **through** PyAutoBrain — either its CLI (`bin/pyauto-brain
+<agent>`) or the `start_dev` workflow entry point, which itself routes reasoning
+through the Brain Feature Agent. A command is a *shortcut into* the Brain, never a
+*replacement for* it. No command file re-implements classification, planning, the
+readiness gate, or execution — those belong to the organs.
+
+## The three command tiers
+
+**1. Real conductors** — route straight to an existing agent in
+`agents/conductors/` (`AGENTS.md` is authoritative):
+
+| Command | Agent | Chain |
+|---------|-------|-------|
+| `/feature` | Feature Agent | `bin/pyauto-brain feature` → `start_dev` → `ship_*` |
+| `/build` | Build Agent | `bin/pyauto-brain build` → vitals faculty → Heart → PyAutoBuild |
+| `/health` | Health Agent | `bin/pyauto-brain health` loop → vitals faculty → Heart → GREEN |
+
+**2. Work-type entries** — no dedicated conductor exists **yet**, so these route
+through the Brain dev-flow with their PyAutoMind work-type fixed. Still through
+the Brain (via `start_dev` → Feature Agent), so nothing is bypassed:
+
+| Command | PyAutoMind work-type | Promotion follow-up |
+|---------|----------------------|---------------------|
+| `/bug` | `bug/` | dedicated Bug conductor |
+| `/refactor` | `refactor/` | dedicated Refactor conductor |
+| `/docs` | `docs/` | dedicated Documentation conductor |
+| `/research` | `research/` | dedicated Research conductor |
+
+These are honest interim doors — they do **not** pretend an agent exists that
+doesn't. The taxonomy they tag is `PyAutoMind/ROUTING.md`.
+
+**3. Router + debug door:**
+
+- **`/route <free text>`** — the natural-language door (the "look at this" path):
+  infer the work-type from the request and dispatch to the matching command
+  above. This is the primary interface; the verbs are typed shortcuts into it.
+- **`/brain <agent> [args]`** — explicit, un-veneered passthrough to
+  `bin/pyauto-brain` for debugging. Free-text `/brain` defers to `/route`.
+
+## How these are installed
+
+Each command is a directory `skills/<verb>/` containing only `<verb>.md` (no
+`SKILL.md`). `bin/install.sh` turns that into a flat `~/.claude/commands/<verb>.md`
+symlink — a typed slash command, not an auto-triggered skill. This file
+(`COMMANDS.md`) sits at the `skills/` root, so the installer's directory scan
+skips it: it is reference-only. Keep command bodies short and this file the single
+place architecture prose lives (guarded by `bin/check_skill_line_counts.sh`).

skills/brain/brain.md

@@ -0,0 +1,15 @@
+# /brain — low-level PyAutoBrain passthrough (debug)
+
+Explicit, un-veneered access to the router, for debugging and direct agent
+invocation. Normal usage should prefer the verb commands (`/feature`, `/build`,
+`/health`, …) and `/route`; this is the mechanic's door.
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+- `/brain <agent> [args...]` where `agent ∈ {feature, build, release, health,
+  vitals}` → run `bin/pyauto-brain <agent> [args...]` and report the output
+  verbatim.
+- `/brain help [agent]` → run `bin/pyauto-brain help [agent]`.
+- `/brain <free text>` with no known agent → defer to **`/route`**.

skills/bug/bug.md

@@ -0,0 +1,14 @@
+# /bug — fix a regression, failing test, or wrong behaviour
+
+A **work-type entry** into the Brain dev-flow. No dedicated Bug conductor exists
+yet, so this routes through the Feature Agent's classifier with the PyAutoMind
+work-type fixed to `bug/`. (Follow-up: promote to a dedicated Bug conductor.)
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+Treat the request as PyAutoMind work-type **`bug/`**. If no prompt path exists,
+first create one under `PyAutoMind/bug/<target>/<name>.md` (original request
+verbatim), then run **`/start_dev`** on it. `start_dev` routes reasoning through
+the Brain — nothing bypasses it. Taxonomy: `PyAutoMind/ROUTING.md`.

skills/build/build.md

@@ -0,0 +1,18 @@
+# /build — build & release execution (via the Brain Build Agent)
+
+Route execution work through PyAutoBrain's **Build Agent**: it consults the
+read-only vitals faculty (→ Heart) and, only on a healthy verdict, delegates the
+building to PyAutoBuild. It decides *whether / what* to build; it does not build.
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+- Run `bin/pyauto-brain build` to coordinate a build. Add `--dry-run` to reason
+  and plan only (emit the `BuildDecision`), or use `bin/pyauto-brain release` for
+  the release path.
+- Surface the vitals verdict: **GREEN** → proceed; **YELLOW** → proceed only with
+  explicit user acknowledgement; **RED** → stop and report.
+
+The Brain decides and PyAutoBuild executes — never re-derive the readiness gate
+here (that is Heart's, read via the vitals faculty).

skills/docs/docs.md

@@ -0,0 +1,16 @@
+# /docs — documentation, examples, notebooks, tutorials
+
+A **work-type entry** into the Brain dev-flow. No dedicated Documentation
+conductor exists yet, so this routes through the Feature Agent's classifier with
+the PyAutoMind work-type fixed to `docs/`. (Follow-up: promote to a dedicated
+Documentation conductor.)
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+Treat the request as PyAutoMind work-type **`docs/`** — documentation, examples,
+notebooks, or tutorial prose. If no prompt path exists, create one under
+`PyAutoMind/docs/<target>/<name>.md` (original request verbatim), then run
+**`/start_dev`** on it. `start_dev` routes through the Brain, and the tutorial
+Opus/Sonnet split in `../WORKFLOW.md` applies. Taxonomy: `PyAutoMind/ROUTING.md`.

skills/feature/feature.md

@@ -0,0 +1,19 @@
+# /feature — grow the organism (via the Brain Feature Agent)
+
+Route a feature request through PyAutoBrain's **Feature Agent** — the growth
+function — then hand its decision to the dev workflow. You never name the Brain;
+this command is the door.
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+1. If a PyAutoMind task path is given, run `bin/pyauto-brain feature <path>`.
+   With no path, run `bin/pyauto-brain feature` to select and plan the next
+   feature task from PyAutoMind.
+2. Take the emitted `FeatureDecision` (classification, sizing, phasing, memory
+   context) and continue with **`/start_dev`** on the chosen task — that carries
+   the branch survey, issue creation, and registration.
+
+The Feature Agent **reasons; it never edits source.** Implementation happens only
+when `start_dev` / `ship_*` execute the plan. Do not bypass the Brain.

skills/health/health.md

@@ -0,0 +1,18 @@
+# /health — get the organism to green (via the Brain Health Agent)
+
+Route health and readiness through PyAutoBrain's **Health conductor** — the
+organism's clinician. It runs the loop with you: assess (via the read-only vitals
+faculty → Heart) → triage → dispatch a validation leg → re-judge, until Heart
+reports GREEN.
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+- Run `bin/pyauto-brain health` and drive the loop conversationally with the user.
+- Use the faster sweeps as **legs** of the loop, not replacements: `/health_check`
+  (quick green-light sweep) and `/pyauto-status` (dashboard read).
+- Adopt Heart's verdict **verbatim** via the vitals faculty; never re-derive it.
+
+This is the human front door for "let's get the organism healthy"; the individual
+sweeps sit beneath it.

skills/refactor/refactor.md

@@ -0,0 +1,16 @@
+# /refactor — internal restructuring, no behaviour change
+
+A **work-type entry** into the Brain dev-flow. No dedicated Refactor conductor
+exists yet, so this routes through the Feature Agent's classifier with the
+PyAutoMind work-type fixed to `refactor/`. (Follow-up: promote to a dedicated
+Refactor conductor.)
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+Treat the request as PyAutoMind work-type **`refactor/`** — architecture cleanup
+or internal restructuring with **no intended behaviour change**. If no prompt path
+exists, create one under `PyAutoMind/refactor/<target>/<name>.md` (original
+request verbatim), then run **`/start_dev`** on it. `start_dev` routes through the
+Brain. Taxonomy: `PyAutoMind/ROUTING.md`.

skills/research/research.md

@@ -0,0 +1,17 @@
+# /research — investigation, design notes, scientific background
+
+A **work-type entry** into the Brain dev-flow. No dedicated Research conductor
+exists yet, so this routes through the Feature Agent's classifier with the
+PyAutoMind work-type fixed to `research/`. (Follow-up: promote to a dedicated
+Research conductor.)
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Do
+
+Treat the request as PyAutoMind work-type **`research/`** — exploratory
+investigation, design notes, or scientific background *before* implementation. If
+no prompt path exists, create one under `PyAutoMind/research/<target>/<name>.md`
+(original request verbatim). Research typically produces notes/decisions rather
+than a PR; consult **PyAutoMemory** for prior art and record findings back to
+Mind. Escalate to `/feature` once scoped. Taxonomy: `PyAutoMind/ROUTING.md`.

skills/route/route.md

@@ -0,0 +1,30 @@
+# /route — say what you want; the Brain routes it
+
+The natural-language door — the "look at this" path. The user describes what they
+want in plain words and never names an agent; you infer the work-type and dispatch
+to the matching command. This is the primary interface; the verb commands are just
+typed shortcuts into the same routing.
+
+Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
+
+## Classify → dispatch
+
+Infer the work-type from the request using the taxonomy in
+`PyAutoMind/ROUTING.md`, then behave as the matching command:
+
+| The request is about… | Route to |
+|-----------------------|----------|
+| a new capability, or "what should I work on next" | `/feature` |
+| building, shipping, releasing, publishing | `/build` |
+| failing tests, readiness, "is it safe / green?" | `/health` |
+| a regression, crash, or wrong output | `/bug` |
+| restructuring with no behaviour change | `/refactor` |
+| documentation, examples, notebooks, tutorials | `/docs` |
+| investigation, design, or scientific background | `/research` |
+
+Examples: *"Fix failing tests"* → `/bug` (or `/health` if it's a readiness sweep);
+*"Implement issue #417"* → `/feature`; *"Publish PyAutoLens"* → `/build`.
+
+If genuinely ambiguous, state your inferred route and the runner-up, then proceed
+with the most likely one — only ask when it is a true 50/50. Never route around
+the Brain.