jvanheerikhuize · Jul 25, 2026 · Jul 25, 2026 · Jul 25, 2026 · Jul 25, 2026 · Jul 25, 2026
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,14 +1,93 @@
 # Roadmap
 
-## Current Focus
-- Refine existing 25 personas based on usage feedback
-- Compress persona prompts to SemantiCode variants for API efficiency
-
-## Next Quarter
-- Add "prompt recipes" combining multiple roles for compound use cases (e.g., "security reviewer + documentation writer")
-- Document best practices for prompt engineering with roles
-
-## Future / Backlog
-- Auto-generate role variants (e.g., formal vs. casual tone)
-- Create a community submission process for new personas
-- Build a role composition DSL for defining complex agent behaviors
+Why the library exists is in [PURPOSE.md](PURPOSE.md). The full v2 target
+architecture is in [docs/REBUILD_PLAN.md](docs/REBUILD_PLAN.md). This file
+tracks the order work happens in, and why.
+
+Status as of 2026-07-25: **23 roles across 6 categories.** Phases 0 and 1 of
+the rebuild plan have shipped — each role is a single `role.md`, `index.yaml`
+and `dist/prompts/` are generated by `tools/build.py`, and CI gates stale
+artifacts. The previous version of this file promoted SemantiCode variants as
+the current focus; those are archived under `archive/semanticode/`.
+
+## What the rebuild fixed, and the one gap it left
+
+Before the migration, role metadata lived in three hand-maintained places:
+`index.yaml`, the `> **Version:**` line in `prompt.md`, and the same line in
+`README.md`. Nothing enforced agreement and 12 roles disagreed with themselves.
+
+Generating `index.yaml` and `dist/` from `role.md` frontmatter ended that for
+two of the three copies — they are derived, and CI fails on stale artifacts.
+
+**The per-role `README.md` is still hand-written**, per REBUILD_PLAN §3.1. That
+leaves exactly one unguarded copy of every role's version and category, and it
+is already drifting. The migration read its versions from the stale
+`index.yaml` rather than from the prompts, which silently reverted nine roles
+from 1.1 back to 1.0 and `spray` from 2.0 to 1.0 — while `spray`'s README and
+its own `<MASTER_PROMPT version="2.0">` body kept saying 2.0.
+
+The reason nothing caught it: every check in `validate-index.sh` is
+*existence*-shaped ("the referenced file is present"). None was
+*agreement*-shaped ("these files say the same thing"), and a hand-written copy
+going stale is only ever caught by the second kind.
+
+## Now — Close the drift class
+
+1. **Restore the lost versions.** Nine roles to 1.1, `spray` to 2.0, sourced
+   from the pre-migration prompt bodies (`73d2285` bumped 19 prompts to 1.1;
+   `24525e9` bumped spray to 2.0). Done.
+2. **Add an agreement check.** `validate-index.sh` now verifies each role
+   `README.md` against its `role.md` frontmatter on version and category. It
+   fails on `main` today with exactly the `spray` case — that is the point.
+   Done.
+3. **Finish the module rename.** `catalog.yaml` still declared
+   `name: agent-roledefinitions-submodule` after the repository URL had already
+   moved to `Agent-Roles`. Resolves open decision #2 in the rebuild plan. Done.
+4. **Generate the README metadata header.** The durable fix, and a deliberate
+   divergence from REBUILD_PLAN §3.1: the README is the only participant left
+   in the drift, so leaving it hand-written preserves the problem the rebuild
+   set out to remove. Generate the `> **Version:** … | **Category:** …` block
+   from frontmatter, hand-write the prose below it, and the check above
+   becomes redundant. **Not yet done** — the check is the interim guard.
+
+## Next — REBUILD_PLAN Phase 2
+
+Prompt modernization (§3.2) and config templating (§3.4). Order matters:
+
+- One category per PR: engineering → utility → productivity → education →
+  entertainment → **health last**.
+- Config templating (§3.4) lands *before* any health rewrite, so
+  `{{crisis_block}}` is injected from `config/crisis-resources.yaml` and the
+  build fails closed rather than silently dropping a safety block.
+- `test-roles.sh` currently emits four warnings about crisis numbers hardcoded
+  outside `config/` (psy, frank, vita, agora). Templating turns those warnings
+  into the thing it removes.
+
+Before this starts, push the `v1.x` final tag REBUILD_PLAN Phase 1 calls for —
+it is still outstanding, and pinned submodule consumers need it to exist
+before the layout moves further.
+
+## Later — Phases 3 and 4
+
+Per REBUILD_PLAN §4, unchanged in substance. Two opinions carried forward:
+
+- **Prefer two build targets to six.** `system-prompt` (the paste-and-play
+  promise in PURPOSE.md) and the generated manifest (keeps `resolve.sh` and
+  submodule consumers alive). REBUILD_PLAN §3.1 and §3.6 specify six plus an
+  MCP server; §5 itself warns about scope creep. Add a target when a real
+  consumer asks for one.
+- **Behavioural evals (§3.5) come before the health-role rewrites**, not after.
+  Their crisis-detection promises should be tested promises.
+
+## Known risks
+
+- **Don't lose the voice.** The personas' character is the product; rewrites
+  are repackaging. Carried from REBUILD_PLAN §5.
+- **Health roles are load-bearing.** They target vulnerable users. No health
+  prompt-body change merges without a passing crisis-detection eval.
+- **Existing consumers.** The generated root `index.yaml` + `resolve.sh` +
+  tag-pinning contract is what keeps submodule consumers working; changes to
+  it are breaking changes regardless of how the source is stored.
+- **Hand-written copies of generated data are the recurring failure mode
+  here.** It has now happened twice. Each time something becomes derived,
+  either generate every copy of it or add an agreement check in the same PR.
diff --git a/catalog.yaml b/catalog.yaml
@@ -8,8 +8,8 @@
 # =============================================================================
 
 module:
-  name: agent-roledefinitions-submodule
-  version: "2.0.0-alpha.1"
+  name: Agent-Roles
+  version: "2.0.0-alpha.2"
   description: >
     A library of structured LLM agent system prompts. Each role is a single
     self-contained role.md (metadata frontmatter + prompt body). The build

diff --git a/index.yaml b/index.yaml
@@ -1,14 +1,14 @@
 # =============================================================================
-# Module Index — agent-roledefinitions-submodule
+# Module Index — Agent-Roles
 # =============================================================================
 # GENERATED FILE — do not edit by hand.
 # Source of truth: roles/<category>/<slug>/role.md + catalog.yaml.
 # Regenerate with: python3 tools/build.py
 # =============================================================================
 
 module:
-  name: agent-roledefinitions-submodule
-  version: "2.0.0-alpha.1"
+  name: Agent-Roles
+  version: "2.0.0-alpha.2"
   description: >
     A library of structured LLM agent system prompts. Each role is a single self-
     contained role.md (metadata frontmatter + prompt body). The build tool compiles
@@ -28,7 +28,7 @@ roles:
     name: "D.I.C.E. — Detective Investigation and Case Engine"
     slug: dice
     category: entertainment
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -140,7 +140,7 @@ roles:
     name: "H.E.I.S.T. — High-stakes Extraction and Infiltration Strategy Tactician"
     slug: heist
     category: entertainment
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -297,7 +297,7 @@ roles:
     name: "C.R.A. — Code Review Analyst"
     slug: cra
     category: engineering
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -445,7 +445,7 @@ roles:
     name: "Q.A.V.E. — Quality Assurance and Verification Engineer"
     slug: qave
     category: engineering
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -604,7 +604,7 @@ roles:
     name: "F.R.A.N.K. — Forthright Relationship Analyst Navigating Knots"
     slug: frank
     category: health
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -737,7 +737,7 @@ roles:
     name: "P.S.Y. — Trauma-Specialised Psychologist"
     slug: psy
     category: health
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -868,7 +868,7 @@ roles:
     name: "A.G.O.R.A. — Autonomous Guide for Open-minded Reasoning and Asking"
     slug: agora
     category: education
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -1087,7 +1087,7 @@ roles:
     name: "S.P.R.A.Y. — Stencil Processor and Rapid Assembly Yielder"
     slug: spray
     category: utility
-    version: "1.0"
+    version: "2.0"
     status: stable
 
     files:
@@ -1142,7 +1142,7 @@ roles:
     name: "A.G.L. — Authoritative Governance Lead"
     slug: agl
     category: productivity
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:
@@ -1189,7 +1189,7 @@ roles:
     name: "P.R.I.M.E. — Product Requirements and Intent Management Executive"
     slug: prime
     category: productivity
-    version: "1.0"
+    version: "1.1"
     status: stable
 
     files:

diff --git a/resolve.sh b/resolve.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# resolve.sh -- Lightweight role resolver for agent-roledefinitions-submodule
+# resolve.sh -- Lightweight role resolver for Agent-Roles
 # Parses index.yaml using native bash/awk. Zero external dependencies.
 # Usage: ./resolve.sh --list | --id <id> | --category <cat> | --tag <tag> | ...
 

diff --git a/roles/education/agora/README.md b/roles/education/agora/README.md
@@ -1,6 +1,6 @@
 # A.G.O.R.A. — Autonomous Guide for Open-minded Reasoning and Asking
 
-> **Version:** 1.0 | **Category:** Education
+> **Version:** 1.1 | **Category:** Education
 
 ---
 

diff --git a/roles/education/agora/role.md b/roles/education/agora/role.md
@@ -2,7 +2,7 @@
 id: agora
 name: "A.G.O.R.A. — Autonomous Guide for Open-minded Reasoning and Asking"
 category: education
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A philosophical inquiry companion for curious people of all ages and backgrounds.

diff --git a/roles/engineering/cra/README.md b/roles/engineering/cra/README.md
@@ -1,6 +1,6 @@
 # C.R.A. — Code Review Analyst
 
-> **Version:** 1.0 | **Category:** Engineering
+> **Version:** 1.1 | **Category:** Engineering
 
 ---
 

diff --git a/roles/engineering/cra/role.md b/roles/engineering/cra/role.md
@@ -2,7 +2,7 @@
 id: cra
 name: "C.R.A. — Code Review Analyst"
 category: engineering
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A structured code review agent grounded in security (OWASP, CWE), correctness,

diff --git a/roles/engineering/qave/README.md b/roles/engineering/qave/README.md
@@ -1,6 +1,6 @@
 # Q.A.V.E. — Quality Assurance and Verification Engineer
 
-> **Version:** 1.0 | **Category:** Engineering
+> **Version:** 1.1 | **Category:** Engineering
 
 ---
 

diff --git a/roles/engineering/qave/role.md b/roles/engineering/qave/role.md
@@ -2,7 +2,7 @@
 id: qave
 name: "Q.A.V.E. — Quality Assurance and Verification Engineer"
 category: engineering
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A structured QA engineering agent for software development teams and risk officers.

diff --git a/roles/entertainment/dice/README.md b/roles/entertainment/dice/README.md
@@ -1,6 +1,6 @@
 # D.I.C.E. — Detective Investigation and Case Engine
 
-> **Version:** 1.0 | **Category:** Entertainment
+> **Version:** 1.1 | **Category:** Entertainment
 
 ---
 

diff --git a/roles/entertainment/dice/role.md b/roles/entertainment/dice/role.md
@@ -2,7 +2,7 @@
 id: dice
 name: "D.I.C.E. — Detective Investigation and Case Engine"
 category: entertainment
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A stateful murder mystery game master. Generates a unique, self-consistent case at

diff --git a/roles/entertainment/heist/README.md b/roles/entertainment/heist/README.md
@@ -1,6 +1,6 @@
 # H.E.I.S.T. — High-stakes Extraction and Infiltration Strategy Tactician
 
-> **Version:** 1.0 | **Category:** Entertainment
+> **Version:** 1.1 | **Category:** Entertainment
 
 ---
 

diff --git a/roles/entertainment/heist/role.md b/roles/entertainment/heist/role.md
@@ -2,7 +2,7 @@
 id: heist
 name: "H.E.I.S.T. — High-stakes Extraction and Infiltration Strategy Tactician"
 category: entertainment
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A cinematic heist game master. Generates a self-contained job at session start —

diff --git a/roles/health/frank/README.md b/roles/health/frank/README.md
@@ -1,6 +1,6 @@
 # F.R.A.N.K. — Forthright Relationship Analyst Navigating Knots
 
-> **Version:** 1.0 | **Category:** Health
+> **Version:** 1.1 | **Category:** Health
 
 ---
 

diff --git a/roles/health/frank/role.md b/roles/health/frank/role.md
@@ -2,7 +2,7 @@
 id: frank
 name: "F.R.A.N.K. — Forthright Relationship Analyst Navigating Knots"
 category: health
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A relationship psychoeducation and self-reflection agent grounded in attachment

diff --git a/roles/health/psy/README.md b/roles/health/psy/README.md
@@ -1,6 +1,6 @@
 # P.S.Y. — Trauma-Specialised Psychologist
 
-> **Version:** 1.0 | **Category:** Health
+> **Version:** 1.1 | **Category:** Health
 
 ---
 

diff --git a/roles/health/psy/role.md b/roles/health/psy/role.md
@@ -2,7 +2,7 @@
 id: psy
 name: "P.S.Y. — Trauma-Specialised Psychologist"
 category: health
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A trauma-informed psychoeducation and emotional support companion grounded in the

diff --git a/roles/productivity/agl/README.md b/roles/productivity/agl/README.md
@@ -1,6 +1,6 @@
 # A.G.L. — Authoritative Governance Lead
 
-> **Version:** 1.0 | **Category:** Productivity
+> **Version:** 1.1 | **Category:** Productivity
 
 ---
 

diff --git a/roles/productivity/agl/role.md b/roles/productivity/agl/role.md
@@ -2,7 +2,7 @@
 id: agl
 name: "A.G.L. — Authoritative Governance Lead"
 category: productivity
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A stateless, single-purpose EU AI Act tier classifier. Given any AI component

diff --git a/roles/productivity/prime/README.md b/roles/productivity/prime/README.md
@@ -1,6 +1,6 @@
 # P.R.I.M.E. — Product Requirements and Intent Management Executive
 
-> **Version:** 1.0 | **Category:** Productivity
+> **Version:** 1.1 | **Category:** Productivity
 
 ---
 

diff --git a/roles/productivity/prime/role.md b/roles/productivity/prime/role.md
@@ -2,7 +2,7 @@
 id: prime
 name: "P.R.I.M.E. — Product Requirements and Intent Management Executive"
 category: productivity
-version: "1.0"
+version: "1.1"
 status: stable
 description: >
   A stateless Product Owner role for agentic pipelines and development teams. Given a

diff --git a/roles/utility/spray/role.md b/roles/utility/spray/role.md
@@ -2,7 +2,7 @@
 id: spray
 name: "S.P.R.A.Y. — Stencil Processor and Rapid Assembly Yielder"
 category: utility
-version: "1.0"
+version: "2.0"
 status: stable
 description: >
   A professional stencil conversion tool for graffiti artists and makers. Accepts an