Skip to content

Commit 060b0fc

Browse files
Jammy2211claude
authored and
Jammy2211
committed
feat(commands): add concise PyAutoBrain agent commands
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/<verb>/<verb>.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 <noreply@anthropic.com>
1 parent 91ebb13 commit 060b0fc

12 files changed

Lines changed: 277 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,34 @@ Like the other PyAuto repos, PyAutoBrain runs from its checkout (no pip install)
182182
it resolves the sibling `pyauto-heart` and `autobuild` binaries from PATH or the
183183
`~/Code/PyAutoLabs/` checkouts.
184184

185+
## The command surface (Brain implicit)
186+
187+
The `bin/pyauto-brain <agent>` CLI above is the machinery; humans drive it through
188+
short verb commands installed into `~/.claude/commands/`. The Brain stays
189+
**implicit** — you type a verb (or plain natural language) and the Brain routes it
190+
to the right agent; normal usage never says "PyAutoBrain".
191+
192+
> **Users speak in short commands; PyAutoBrain performs the routing.**
193+
194+
| Command | Routes to | Tier |
195+
|---------|-----------|------|
196+
| `/feature` | Feature Agent → `start_dev` | real conductor |
197+
| `/build` | Build Agent → vitals → Heart → PyAutoBuild | real conductor |
198+
| `/health` | Health Agent loop → vitals → Heart | real conductor |
199+
| `/bug` `/refactor` `/docs` `/research` | `start_dev` pre-tagged with the work-type | work-type entry* |
200+
| `/route <text>` | infers the work-type and dispatches to one of the above | NL router |
201+
| `/brain <agent>` | raw `bin/pyauto-brain` passthrough | debug door |
202+
203+
\* No dedicated Bug/Refactor/Docs/Research conductor exists yet — those verbs
204+
route through the Brain dev-flow with their PyAutoMind work-type fixed (still
205+
through the Brain, nothing bypassed), until each earns promotion to its own
206+
conductor. Every command routes **through** the Brain; none replaces it.
207+
208+
The command bodies live in `skills/<verb>/<verb>.md` (thin; installed as flat
209+
commands by `bin/install.sh`); the shared architecture prose is in
210+
[`skills/COMMANDS.md`](skills/COMMANDS.md). The work-type taxonomy the router and
211+
work-type entries use is `PyAutoMind/ROUTING.md`.
212+
185213
## Never rewrite history
186214

187215
NEVER perform these operations on any repo with a remote:

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,4 +99,25 @@ that used to live in `admin_jammy/skills/`. Run `bash PyAutoBrain/bin/install.sh
9999
to (re-)symlink every organ's skills/commands into `~/.claude/`. See
100100
[`bin/README.md`](bin/README.md).
101101

102+
## The command surface (Brain implicit)
103+
104+
Humans drive the CLI above through short verb commands installed into
105+
`~/.claude/commands/`. The Brain stays **implicit**: you type a verb (or plain
106+
natural language) and it routes to the right agent — normal usage never says
107+
"PyAutoBrain".
108+
109+
> **Users speak in short commands; PyAutoBrain performs the routing.**
110+
111+
- **Real conductors:** `/feature` → Feature Agent, `/build` → Build Agent,
112+
`/health` → Health Agent (each → vitals/Heart/Build as needed).
113+
- **Work-type entries:** `/bug` `/refactor` `/docs` `/research` route through the
114+
Brain dev-flow (`start_dev`) with their PyAutoMind work-type fixed — honest
115+
interim doors until each earns its own conductor.
116+
- **Router + debug:** `/route <text>` infers the work-type and dispatches;
117+
`/brain <agent>` is the raw passthrough. Every command routes **through** the
118+
Brain; none replaces it.
119+
120+
Bodies live in `skills/<verb>/<verb>.md`; shared prose in
121+
[`skills/COMMANDS.md`](skills/COMMANDS.md).
122+
102123
See [`AGENTS.md`](AGENTS.md) for the full description.

‎skills/COMMANDS.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# PyAutoBrain command surface — shared reference
2+
3+
The short verb commands (`/feature`, `/build`, `/health`, `/bug`, `/refactor`,
4+
`/docs`, `/research`, `/route`, `/brain`) are a thin, human-friendly **veneer**
5+
over the PyAutoBrain router (`bin/pyauto-brain`). This file is the shared context
6+
every command file points at, so each command body stays a few lines long.
7+
8+
> **Users speak in short commands; PyAutoBrain performs the routing.**
9+
10+
## The Brain is implicit
11+
12+
You don't tell a brain to "activate the visual cortex" — you *look*, and it
13+
routes. Same here: a user types a short verb (or plain natural language) and the
14+
Brain routes it to the right specialist agent. **Normal usage never says
15+
"PyAutoBrain".** The only explicit-Brain surface is `/brain`, the debug door.
16+
17+
## Never bypass the Brain
18+
19+
Every command routes **through** PyAutoBrain — either its CLI (`bin/pyauto-brain
20+
<agent>`) or the `start_dev` workflow entry point, which itself routes reasoning
21+
through the Brain Feature Agent. A command is a *shortcut into* the Brain, never a
22+
*replacement for* it. No command file re-implements classification, planning, the
23+
readiness gate, or execution — those belong to the organs.
24+
25+
## The three command tiers
26+
27+
**1. Real conductors** — route straight to an existing agent in
28+
`agents/conductors/` (`AGENTS.md` is authoritative):
29+
30+
| Command | Agent | Chain |
31+
|---------|-------|-------|
32+
| `/feature` | Feature Agent | `bin/pyauto-brain feature` → `start_dev` → `ship_*` |
33+
| `/build` | Build Agent | `bin/pyauto-brain build` → vitals faculty → Heart → PyAutoBuild |
34+
| `/health` | Health Agent | `bin/pyauto-brain health` loop → vitals faculty → Heart → GREEN |
35+
36+
**2. Work-type entries** — no dedicated conductor exists **yet**, so these route
37+
through the Brain dev-flow with their PyAutoMind work-type fixed. Still through
38+
the Brain (via `start_dev` → Feature Agent), so nothing is bypassed:
39+
40+
| Command | PyAutoMind work-type | Promotion follow-up |
41+
|---------|----------------------|---------------------|
42+
| `/bug` | `bug/` | dedicated Bug conductor |
43+
| `/refactor` | `refactor/` | dedicated Refactor conductor |
44+
| `/docs` | `docs/` | dedicated Documentation conductor |
45+
| `/research` | `research/` | dedicated Research conductor |
46+
47+
These are honest interim doors — they do **not** pretend an agent exists that
48+
doesn't. The taxonomy they tag is `PyAutoMind/ROUTING.md`.
49+
50+
**3. Router + debug door:**
51+
52+
- **`/route <free text>`** — the natural-language door (the "look at this" path):
53+
infer the work-type from the request and dispatch to the matching command
54+
above. This is the primary interface; the verbs are typed shortcuts into it.
55+
- **`/brain <agent> [args]`** — explicit, un-veneered passthrough to
56+
`bin/pyauto-brain` for debugging. Free-text `/brain` defers to `/route`.
57+
58+
## How these are installed
59+
60+
Each command is a directory `skills/<verb>/` containing only `<verb>.md` (no
61+
`SKILL.md`). `bin/install.sh` turns that into a flat `~/.claude/commands/<verb>.md`
62+
symlink — a typed slash command, not an auto-triggered skill. This file
63+
(`COMMANDS.md`) sits at the `skills/` root, so the installer's directory scan
64+
skips it: it is reference-only. Keep command bodies short and this file the single
65+
place architecture prose lives (guarded by `bin/check_skill_line_counts.sh`).

‎skills/brain/brain.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# /brain — low-level PyAutoBrain passthrough (debug)
2+
3+
Explicit, un-veneered access to the router, for debugging and direct agent
4+
invocation. Normal usage should prefer the verb commands (`/feature`, `/build`,
5+
`/health`, …) and `/route`; this is the mechanic's door.
6+
7+
Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
8+
9+
## Do
10+
11+
- `/brain <agent> [args...]` where `agent ∈ {feature, build, release, health,
12+
vitals}` → run `bin/pyauto-brain <agent> [args...]` and report the output
13+
verbatim.
14+
- `/brain help [agent]` → run `bin/pyauto-brain help [agent]`.
15+
- `/brain <free text>` with no known agent → defer to **`/route`**.

‎skills/bug/bug.md‎

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

‎skills/build/build.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# /build — build & release execution (via the Brain Build Agent)
2+
3+
Route execution work through PyAutoBrain's **Build Agent**: it consults the
4+
read-only vitals faculty (→ Heart) and, only on a healthy verdict, delegates the
5+
building to PyAutoBuild. It decides *whether / what* to build; it does not build.
6+
7+
Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
8+
9+
## Do
10+
11+
- Run `bin/pyauto-brain build` to coordinate a build. Add `--dry-run` to reason
12+
and plan only (emit the `BuildDecision`), or use `bin/pyauto-brain release` for
13+
the release path.
14+
- Surface the vitals verdict: **GREEN** → proceed; **YELLOW** → proceed only with
15+
explicit user acknowledgement; **RED** → stop and report.
16+
17+
The Brain decides and PyAutoBuild executes — never re-derive the readiness gate
18+
here (that is Heart's, read via the vitals faculty).

‎skills/docs/docs.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# /docs — documentation, examples, notebooks, tutorials
2+
3+
A **work-type entry** into the Brain dev-flow. No dedicated Documentation
4+
conductor exists yet, so this routes through the Feature Agent's classifier with
5+
the PyAutoMind work-type fixed to `docs/`. (Follow-up: promote to a dedicated
6+
Documentation conductor.)
7+
8+
Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
9+
10+
## Do
11+
12+
Treat the request as PyAutoMind work-type **`docs/`** — documentation, examples,
13+
notebooks, or tutorial prose. If no prompt path exists, create one under
14+
`PyAutoMind/docs/<target>/<name>.md` (original request verbatim), then run
15+
**`/start_dev`** on it. `start_dev` routes through the Brain, and the tutorial
16+
Opus/Sonnet split in `../WORKFLOW.md` applies. Taxonomy: `PyAutoMind/ROUTING.md`.

‎skills/feature/feature.md‎

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

‎skills/health/health.md‎

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

‎skills/refactor/refactor.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# /refactor — internal restructuring, no behaviour change
2+
3+
A **work-type entry** into the Brain dev-flow. No dedicated Refactor conductor
4+
exists yet, so this routes through the Feature Agent's classifier with the
5+
PyAutoMind work-type fixed to `refactor/`. (Follow-up: promote to a dedicated
6+
Refactor conductor.)
7+
8+
Shared routing context: `PyAutoBrain/skills/COMMANDS.md`.
9+
10+
## Do
11+
12+
Treat the request as PyAutoMind work-type **`refactor/`** — architecture cleanup
13+
or internal restructuring with **no intended behaviour change**. If no prompt path
14+
exists, create one under `PyAutoMind/refactor/<target>/<name>.md` (original
15+
request verbatim), then run **`/start_dev`** on it. `start_dev` routes through the
16+
Brain. Taxonomy: `PyAutoMind/ROUTING.md`.

0 commit comments

Comments
 (0)