From 060b0fcb90752f93af543718d9123d0cf4909521 Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Tue, 7 Jul 2026 19:54:40 +0100 Subject: [PATCH] feat(commands): add concise PyAutoBrain agent commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a thin, human-friendly command veneer over the existing bin/pyauto-brain router so the Brain stays implicit — users type short verbs (or plain natural language) and the Brain routes to the right specialist agent. Users speak in short commands; PyAutoBrain performs the routing. Command tiers (skills//.md; auto-installed as flat commands): - Real conductors: /feature, /build, /health -> existing agents. - Work-type entries: /bug, /refactor, /docs, /research -> start_dev pre-tagged with the PyAutoMind work-type (still through the Brain; no fictional agents). - Router + debug: /route infers the work-type and dispatches; /brain is the raw pyauto-brain passthrough. Shared architecture prose factored into skills/COMMANDS.md (reference-only, not installed) so command bodies stay short and pass check_skill_line_counts.sh. No install.sh change needed — skills/ is already a scanned root. Docs added to AGENTS.md and README.md. Follow-ups (not this PR): promote bug/refactor/docs/research to dedicated conductors; reconcile /health with /health_check and /pyauto-status. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 28 ++++++++++++++++ README.md | 21 ++++++++++++ skills/COMMANDS.md | 65 +++++++++++++++++++++++++++++++++++++ skills/brain/brain.md | 15 +++++++++ skills/bug/bug.md | 14 ++++++++ skills/build/build.md | 18 ++++++++++ skills/docs/docs.md | 16 +++++++++ skills/feature/feature.md | 19 +++++++++++ skills/health/health.md | 18 ++++++++++ skills/refactor/refactor.md | 16 +++++++++ skills/research/research.md | 17 ++++++++++ skills/route/route.md | 30 +++++++++++++++++ 12 files changed, 277 insertions(+) create mode 100644 skills/COMMANDS.md create mode 100644 skills/brain/brain.md create mode 100644 skills/bug/bug.md create mode 100644 skills/build/build.md create mode 100644 skills/docs/docs.md create mode 100644 skills/feature/feature.md create mode 100644 skills/health/health.md create mode 100644 skills/refactor/refactor.md create mode 100644 skills/research/research.md create mode 100644 skills/route/route.md diff --git a/AGENTS.md b/AGENTS.md index 85e8978..0572c1a 100644 --- a/AGENTS.md +++ b/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 ` 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 ` | infers the work-type and dispatches to one of the above | NL router | +| `/brain ` | 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//.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: diff --git a/README.md b/README.md index ae2c213..3dcf8db 100644 --- a/README.md +++ b/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 ` infers the work-type and dispatches; + `/brain ` is the raw passthrough. Every command routes **through** the + Brain; none replaces it. + +Bodies live in `skills//.md`; shared prose in +[`skills/COMMANDS.md`](skills/COMMANDS.md). + See [`AGENTS.md`](AGENTS.md) for the full description. diff --git a/skills/COMMANDS.md b/skills/COMMANDS.md new file mode 100644 index 0000000..cf40f6a --- /dev/null +++ b/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 +`) 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 `** — 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 [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//` containing only `.md` (no +`SKILL.md`). `bin/install.sh` turns that into a flat `~/.claude/commands/.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`). diff --git a/skills/brain/brain.md b/skills/brain/brain.md new file mode 100644 index 0000000..73690dd --- /dev/null +++ b/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 [args...]` where `agent ∈ {feature, build, release, health, + vitals}` → run `bin/pyauto-brain [args...]` and report the output + verbatim. +- `/brain help [agent]` → run `bin/pyauto-brain help [agent]`. +- `/brain ` with no known agent → defer to **`/route`**. diff --git a/skills/bug/bug.md b/skills/bug/bug.md new file mode 100644 index 0000000..b97efee --- /dev/null +++ b/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//.md` (original request +verbatim), then run **`/start_dev`** on it. `start_dev` routes reasoning through +the Brain — nothing bypasses it. Taxonomy: `PyAutoMind/ROUTING.md`. diff --git a/skills/build/build.md b/skills/build/build.md new file mode 100644 index 0000000..f67c62c --- /dev/null +++ b/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). diff --git a/skills/docs/docs.md b/skills/docs/docs.md new file mode 100644 index 0000000..73e2973 --- /dev/null +++ b/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//.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`. diff --git a/skills/feature/feature.md b/skills/feature/feature.md new file mode 100644 index 0000000..02cc5da --- /dev/null +++ b/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 `. + 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. diff --git a/skills/health/health.md b/skills/health/health.md new file mode 100644 index 0000000..7797afe --- /dev/null +++ b/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. diff --git a/skills/refactor/refactor.md b/skills/refactor/refactor.md new file mode 100644 index 0000000..0e8ce97 --- /dev/null +++ b/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//.md` (original +request verbatim), then run **`/start_dev`** on it. `start_dev` routes through the +Brain. Taxonomy: `PyAutoMind/ROUTING.md`. diff --git a/skills/research/research.md b/skills/research/research.md new file mode 100644 index 0000000..47c6391 --- /dev/null +++ b/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//.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`. diff --git a/skills/route/route.md b/skills/route/route.md new file mode 100644 index 0000000..3e7e6bc --- /dev/null +++ b/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.