Restructure PyAutoMind prompts by work type

AGENTS.md

@@ -23,10 +23,16 @@ For the full workflow narrative, conventions, and registry schemas, read
 
 ## Layout (operational)
 
-- **Prompts** — `<category>/<name>.md` (free-form markdown, one task per file).
-  Categories: `autoarray/`, `autofit/`, `autogalaxy/`, `autolens/`, `autobuild/`,
-  `cluster/`, `weak/`, `workspaces/`, `autolens_workspace_developer/`,
-  `autoprompt/`, `z_vault/`.
+- **Prompts** — `<work-type>/<target>/<name>.md` (free-form markdown, one task
+  per file). The **first** folder is the *kind of work*; the **second** is the
+  *target repo or domain*. Work-types: `feature/`, `bug/`, `refactor/`, `docs/`,
+  `test/`, `release/`, `maintenance/`, `research/`, `experiment/` (plus `triage/`
+  for prompts whose classification is still unclear). PyAutoBrain routes by the
+  first folder — see [README.md](README.md) "Prompt taxonomy" and `ROUTING.md`.
+  Lifecycle/meta folders are **not** work-types and keep their own names:
+  `issued/` (routed prompts), `z_features/` (multi-task epic trackers),
+  `z_vault/` (deferred), `shelved/`, and `autoprompt/` (prompts about this repo's
+  own infrastructure).
 - **Registry** — root-level markdown files: `active.md`, `complete.md`,
   `planned.md`, `parked.md`, `queue.md`, `priority.md`, `ideas.md`. Mutate
   these only via the skills in `skills/` so commit messages stay consistent.
@@ -52,13 +58,19 @@ For the full workflow narrative, conventions, and registry schemas, read
 
 ## When you are asked to add a new prompt
 
-Write the file under the appropriate category. Don't touch `active.md` or
-`issued/` directly — those are managed by `/start_dev` / `/create_issue`.
+Write the file under `<work-type>/<target>/<name>.md` — pick the work-type from
+the list above (use `triage/` if genuinely unsure) and the target repo/domain as
+the second folder, e.g. `feature/autolens/potential_corrections.md` or
+`bug/autoarray/mask_edge_case.md`. Don't touch `active.md` or `issued/` directly
+— those are managed by `/start_dev` / `/create_issue`.
 
 ## When you are asked to start work on an existing prompt
 
-Use `/start_dev <category>/<name>.md`. It will route to `/start_library` or
-`/start_workspace` based on the repos referenced in the prompt body.
+Use `/start_dev <work-type>/<target>/<name>.md` (older `<target>/<name>.md` paths
+from before the taxonomy migration still work too). It will route to
+`/start_library` or `/start_workspace` based on the repos referenced in the
+prompt body — routing keys off the `@RepoName` references in the content, not the
+folder.
 
 ## When in doubt
 

README.md

@@ -141,7 +141,7 @@ fine — write naturally, the AI fills in the rest.
   idea               ── you write it in ideas.md
     │
     ▼
-  draft prompt       ── you write a markdown file under <category>/<name>.md
+  draft prompt       ── you write a markdown file under <work-type>/<target>/<name>.md
     │
     ▼
   /start_dev         ── reads the prompt, audits the code, drafts an issue,
@@ -192,27 +192,35 @@ PyAutoMind/
 ├── priority.md              ← hand-curated priority hints
 ├── queue.md                 ← processing queue for /register_and_iterate
 │
-├── autoarray/               ← prompts targeting PyAutoArray
-├── autofit/                 ← prompts targeting PyAutoFit
-├── autogalaxy/              ← prompts targeting PyAutoGalaxy
-├── autolens/                ← prompts targeting PyAutoLens
-├── autolens_workspace_developer/   ← prompts targeting the dev workspace
-│
-├── autobuild/                   ← prompts targeting build/release infrastructure (PyAutoBuild)
-├── workspaces/              ← prompts targeting any *_workspace repo
-│
-├── cluster/                 ← cluster-lensing prompt series (numbered)
-├── weak/                    ← weak-lensing prompt series (numbered)
+│   PROMPTS — organised by WORK TYPE (first folder), then TARGET (second folder).
+│   See "Prompt taxonomy" below and ROUTING.md.
+├── feature/                 ← new user-facing or scientific capabilities
+│   ├── autoarray/  autofit/  autogalaxy/  autolens/  autolens_assistant/  …
+│   ├── workspaces/          ← any *_workspace repo
+│   ├── pyautobrain/         ← prompts that implement PyAutoBrain agents
+│   ├── jax_substructure/  weak/  cluster/   ← numbered topic series (kept together)
+├── bug/                     ← incorrect behaviour, crashes, regressions
+│   ├── autofit/  autogalaxy/  autolens/  autoarray/  priors/  …
+├── refactor/                ← internal restructuring, no intended behaviour change
+├── docs/                    ← documentation, tutorials, notebooks, examples
+├── test/                    ← test coverage, smoke tests, validation scripts
+├── release/                 ← packaging, versions, deployment, release readiness
+├── maintenance/             ← dependency updates, hygiene, cleanup, small tech debt
+├── research/                ← exploratory scientific / algorithmic investigation
+├── experiment/              ← prototypes, spikes, proof-of-concept work
+├── triage/                  ← classification still unclear; needs manual review
 │
+│   LIFECYCLE / META — not work-types; keep their own names.
 ├── issued/                  ← prompts that have been routed via /start_dev
 │   └── autolens_workspace_developer/   ← per-target subdirs preserved
 │
 ├── z_features/              ← multi-task epic trackers (one tracker → many sub-prompts)
 │   └── complete/            ← archived trackers (all sub-prompts shipped)
 │
 ├── z_vault/                 ← deferred prompts (z_ prefix sorts last in listings)
+├── shelved/                 ← shelved prompts
 │
-├── autoprompt/              ← prompts about THIS repo's own infrastructure
+├── autoprompt/              ← prompts about THIS repo's own infrastructure (meta)
 │
 ├── scripts/
 │   ├── status.sh            ← prompt inventory helper
@@ -243,17 +251,78 @@ replaces the previous `admin_jammy/software/admin_sync.sh` which operated on
 
 ---
 
+## Prompt taxonomy
+
+PyAutoMind organises **intent by the kind of thinking required; PyAutoBrain uses
+that structure to choose the right reasoning agent.**
+
+Prompts live at `<work-type>/<target>/<name>.md`:
+
+- The **first folder** answers *what kind of thinking or agent is needed?* — the
+  work type.
+- The **second folder** answers *what domain or repository is affected?* — the
+  target repo (`autoarray`, `autofit`, `autogalaxy`, `autolens`,
+  `autolens_assistant`, `pyautobrain`, …), a workspace bucket (`workspaces`), or
+  a topic series (`jax_substructure`, `weak`, `cluster`, `priors`).
+
+### Work types → PyAutoBrain agents
+
+| Folder | Holds | Future PyAutoBrain agent |
+|--------|-------|--------------------------|
+| `feature/` | new user-facing or scientific capabilities | feature planner |
+| `bug/` | incorrect behaviour, crashes, regressions | debugger |
+| `refactor/` | internal restructuring, no intended behaviour change | refactor architect |
+| `docs/` | documentation, tutorials, notebooks, examples | documentation agent |
+| `test/` | test coverage, smoke tests, validation scripts | test engineer |
+| `release/` | packaging, versions, deployment, release readiness | release engineer |
+| `maintenance/` | dependency updates, hygiene, cleanup, small tech debt | hygiene agent |
+| `research/` | exploratory scientific / algorithmic investigation | research analyst |
+| `experiment/` | prototypes, spikes, proof-of-concept work | prototype agent |
+
+`triage/` holds prompts whose classification is still unclear — file there with a
+short note and re-home once the work type is obvious. The full mapping (and the
+note that the agents themselves live in PyAutoBrain, not here) is in
+[`ROUTING.md`](ROUTING.md).
+
+### Good prompt paths
+
+```
+feature/autolens/potential_corrections.md
+bug/autoarray/mask_edge_case.md
+refactor/autofit/result_object_cleanup.md
+docs/workspaces/pixelization_tutorial.md
+research/autofit/sbi_design.md
+experiment/autoarray/jax_sparse_mapping.md
+```
+
+### Not work-types
+
+`issued/`, `z_features/`, `z_vault/`, `shelved/` are **workflow lifecycle**
+folders, and `autoprompt/` holds **meta** prompts about this repo's own
+infrastructure. They keep their own names and are not routed by work type.
+
+### Migration note
+
+The repository previously used the target repo as the first folder
+(`autoarray/foo.md`). Those prompts have moved to `<work-type>/autoarray/foo.md`.
+Routing always keyed off the `@RepoName` references in a prompt's body, not its
+folder, so the skills accept both old and new paths during the transition — but
+new prompts should use the work-type layout.
+
+---
+
 ## Conventions
 
 ### Naming
 
 - Prompt filenames are lowercase `kebab_or_snake_case.md`.
 - Numbered series use a leading number: `0_docs.md`, `1_simulator.md`. Skipping a
-  number (e.g. `weak/2_*.md` not present) is fine — it usually means a step was
-  consolidated or deferred.
-- Category dirs match the target repo name (lowercased, no `Py` prefix):
-  `autoarray/`, `autofit/`, `autogalaxy/`, `autolens/`. Workspace prompts go
-  under `workspaces/` regardless of which workspace.
+  number (e.g. `feature/weak/2_*.md` not present) is fine — it usually means a
+  step was consolidated or deferred.
+- **First folder = work type** (`feature/`, `bug/`, …); **second folder = target**
+  repo or domain (lowercased, no `Py` prefix): `feature/autoarray/`,
+  `bug/autofit/`, `refactor/autogalaxy/`. Workspace prompts go under
+  `<work-type>/workspaces/` regardless of which workspace. See "Prompt taxonomy".
 
 ### Prompt file format
 
@@ -265,6 +334,24 @@ Free-form markdown. Strong conventions:
 - One prompt = one task = one PR (ideally). If a prompt outlines several
   loosely-related changes, split before issuing.
 - No frontmatter required. Title in the first line is helpful but optional.
+- **Optional metadata header.** A prompt may carry a light, human-writable header
+  near the top so both people and PyAutoBrain can see its type/target at a glance.
+  This is a convention, not a schema — never required, no YAML frontmatter:
+
+  ```markdown
+  # Short task title
+
+  Type: feature
+  Target: PyAutoLens
+  Repos:
+  - PyAutoLens
+  - autolens_workspace
+
+  Status: draft
+  ```
+
+  When present, `Type:` should match the work-type folder. The goal is light
+  structure, not bureaucracy — prompts stay free-form prose.
 
 ### `active.md` schema
 

ROUTING.md

@@ -0,0 +1,54 @@
+# Routing — prompt taxonomy → PyAutoBrain agents
+
+PyAutoMind stores **intent**. PyAutoBrain reasons over that intent and routes it
+to the right specialist agent. This file defines the contract between the two:
+the first folder of every prompt path declares the *kind of work*, and PyAutoBrain
+maps that to a reasoning agent.
+
+> PyAutoMind organises intent by the kind of thinking required; PyAutoBrain uses
+> that structure to choose the right reasoning agent.
+
+## The map
+
+Prompts live at `<work-type>/<target>/<name>.md`. The **work-type** (first folder)
+determines the agent; the **target** (second folder) tells the agent which repo or
+domain is affected.
+
+| Work-type folder | Intent | PyAutoBrain agent |
+|------------------|--------|-------------------|
+| `feature/`       | new user-facing or scientific capabilities | feature planner |
+| `bug/`           | incorrect behaviour, crashes, regressions | debugger |
+| `refactor/`      | internal restructuring, no intended behaviour change | refactor architect |
+| `docs/`          | documentation, tutorials, notebooks, examples | documentation agent |
+| `test/`          | test coverage, smoke tests, validation scripts | test engineer |
+| `release/`       | packaging, versions, deployment, release readiness | release engineer |
+| `maintenance/`   | dependency updates, hygiene, cleanup, small technical debt | hygiene agent |
+| `research/`      | exploratory scientific / algorithmic investigation before implementation | research analyst |
+| `experiment/`    | prototypes, spikes, proof-of-concept work | prototype agent |
+| `triage/`        | classification still unclear | (human triages, then re-homes) |
+
+## Targets (second folder)
+
+The second folder names the affected repo or domain, e.g. `autoarray`, `autofit`,
+`autogalaxy`, `autolens`, `autolens_assistant`, `autolens_profiling`,
+`autolens_workspace_developer`, `autobuild`, `pyautobrain`; the workspace bucket
+`workspaces`; or a topic series kept together as a unit (`jax_substructure`,
+`weak`, `cluster`, `priors`).
+
+Within the libraries, work classifies as **library** vs **workspace** for the
+`/start_library` ↔ `/start_workspace` split — but that is decided from the
+`@RepoName` references in the prompt body, *not* from the folder. The folder is
+for human + agent legibility and PyAutoBrain routing.
+
+## Scope of this file
+
+This repository **only defines the taxonomy and the metadata/documentation** that
+PyAutoBrain consumes. The agents themselves are **not** implemented here — they
+live in PyAutoBrain (currently the PyAutoAgent repo). Prompts that *implement*
+those agents are ordinary `feature/pyautobrain/*.md` prompts.
+
+## Not routed by work type
+
+`issued/`, `z_features/`, `z_vault/`, `shelved/` are workflow-lifecycle folders;
+`autoprompt/` holds meta prompts about this repo's own infrastructure. None of
+these are work-type folders and PyAutoBrain does not route them.

priors/z_features.md → bug/priors/z_features.md

@@ -8,7 +8,7 @@ across Prior subclasses"), we audited every prior and message in PyAutoFit
 for similar latent math bugs.
 
 Full audit lives at:
-`PyAutoPrompt/autofit/priors_and_messages_math_audit.md`
+`PyAutoMind/research/autofit/priors_and_messages_math_audit.md`
 
 This folder breaks that audit into a logical, dependency-ordered sequence
 of standalone GitHub issues. The intent is to land them one by one so
@@ -38,7 +38,7 @@ review before any code change.
 When ready to action one of these issues, run:
 
 ```
-/create_issue priors/<file>.md
+/create_issue bug/priors/<file>.md
 ```
 
 That files the issue. The agent should NOT call `/start_dev` against

planned.md

@@ -24,7 +24,7 @@
     source_plane.py in the same dir — they share the seed dataset.
 
 ## nfw-truncated-potential-accuracy
-- prompt: PyAutoMind/autogalaxy/nfw_truncated_potential_accuracy.md
+- prompt: PyAutoMind/bug/autogalaxy/nfw_truncated_potential_accuracy.md
 - status: planned
 - filed: 2026-06-05
 - classification: library (accuracy bug)
@@ -40,7 +40,7 @@
   - PyAutoGalaxy
 
 ## piemass-potential
-- prompt: PyAutoMind/autogalaxy/piemass_potential.md
+- prompt: PyAutoMind/feature/autogalaxy/piemass_potential.md
 - status: planned
 - filed: 2026-06-05
 - classification: library (missing feature)

scripts/status.sh

@@ -26,13 +26,29 @@ bold() { printf "\033[1m%s\033[0m\n" "$1"; }
 dim()  { printf "\033[2m%s\033[0m\n" "$1"; }
 
 # ---------- Counts per category ----------
+#
+# Prompts are now organised by WORK TYPE at the first folder level
+# (feature/, bug/, refactor/, …) with the target repo/domain as the second
+# level. Lifecycle/meta folders (issued/, z_features/, z_vault/, shelved/,
+# autoprompt/, triage/) keep their own names. See README "Prompt taxonomy".
+
+WORK_TYPES=(feature bug refactor docs test release maintenance research experiment)
+LIFECYCLE_DIRS=(triage issued z_features z_vault shelved autoprompt)
 
-bold "== Prompt inventory =="
+bold "== Prompt inventory (by work type) =="
 printf "%-35s %s\n" "category" "count"
 printf "%-35s %s\n" "----------------------------------" "-----"
 
-for dir in autoarray autofit autogalaxy autolens autolens_workspace_developer \
-           autobuild cluster weak workspaces autoprompt z_vault issued; do
+for dir in "${WORK_TYPES[@]}"; do
+  if [ -d "$ROOT/$dir" ]; then
+    count=$(find "$ROOT/$dir" -type f -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    printf "%-35s %s\n" "$dir/" "$count"
+  fi
+done
+
+echo ""
+bold "== Lifecycle / meta =="
+for dir in "${LIFECYCLE_DIRS[@]}"; do
   if [ -d "$ROOT/$dir" ]; then
     count=$(find "$ROOT/$dir" -type f -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
     printf "%-35s %s\n" "$dir/" "$count"
@@ -95,8 +111,7 @@ fi
 
 if [ "${1:-}" = "--full" ]; then
   bold "== Full prompt list =="
-  for dir in autoarray autofit autogalaxy autolens autolens_workspace_developer \
-             autobuild cluster weak workspaces autoprompt z_vault issued; do
+  for dir in "${WORK_TYPES[@]}" "${LIFECYCLE_DIRS[@]}"; do
     [ -d "$ROOT/$dir" ] || continue
     files=$(find "$ROOT/$dir" -type f -name "*.md" 2>/dev/null | sort)
     [ -z "$files" ] && continue

skills/create_issue/SKILL.md

@@ -12,10 +12,12 @@ Convert a prompt file into a tracked GitHub issue with a human-readable plan and
 /create-issue <prompt-file-path>
 ```
 
-The path is relative to `PyAutoMind/`. Examples:
-- `/create-issue autofit/logging.md`
-- `/create-issue autoarray/psf_oversampling.md`
-- `/create-issue autolens/dark_matter_sight_lines.md`
+The path is relative to `PyAutoMind/`. Prompts live under `<work-type>/<target>/`
+(see README "Prompt taxonomy"); pre-migration `<target>/<name>.md` paths still
+resolve. Examples:
+- `/create-issue bug/autofit/factor_graph_3_14_instance_iteration.md`
+- `/create-issue feature/autoarray/oversampling.md`
+- `/create-issue bug/priors/01_log_gaussian_with_limits_crash.md`
 
 ## Steps
 

skills/register_and_iterate/register_and_iterate.md

@@ -12,7 +12,10 @@ gates.
 /register_and_iterate --queue          # reads PyAutoMind/queue.md
 ```
 
-Prompts are paths relative to `PyAutoMind/` (e.g. `autolens/fit_imaging_pytree_rectangular.md`).
+Prompts are paths relative to `PyAutoMind/`, now organised by work type
+(e.g. `feature/autolens/fit_imaging_pytree_rectangular.md`; see README "Prompt
+taxonomy"). Pre-migration `<target>/<name>.md` paths still resolve, which is why
+the historical `# DONE` queue entries below keep their old `autolens/…` form.
 
 ## Autonomy Contract