From 30141ee3485b097ce283f566fcedada8d86f9a90 Mon Sep 17 00:00:00 2001 From: Jerry van Heerikhuize Date: Sat, 25 Jul 2026 08:27:36 +0200 Subject: [PATCH 1/4] fix(roles): restore versions lost in the v2 migration The v2 migration sourced role.md frontmatter versions from the stale index.yaml rather than from the prompt bodies, silently reverting nine roles from 1.1 to 1.0 and spray from 2.0 to 1.0. Authoritative values come from history, not inference: 73d2285 bumped 19 prompt.md files to 1.1 while touching neither index.yaml nor any README, and 24525e9 bumped spray to 2.0 in prompt.md + README.md only. The prompt files record the real content changes; the bump commits forgot the rest. spray was consumer-visible: its README and its body said 2.0 while resolve.sh --id spray reported 1.0. No prompt bodies changed. Co-Authored-By: Claude Opus 5 --- index.yaml | 26 +++++++++++++------------- roles/education/agora/README.md | 2 +- roles/education/agora/role.md | 2 +- roles/engineering/cra/README.md | 2 +- roles/engineering/cra/role.md | 2 +- roles/engineering/qave/README.md | 2 +- roles/engineering/qave/role.md | 2 +- roles/entertainment/dice/README.md | 2 +- roles/entertainment/dice/role.md | 2 +- roles/entertainment/heist/README.md | 2 +- roles/entertainment/heist/role.md | 2 +- roles/health/frank/README.md | 2 +- roles/health/frank/role.md | 2 +- roles/health/psy/README.md | 2 +- roles/health/psy/role.md | 2 +- roles/productivity/agl/README.md | 2 +- roles/productivity/agl/role.md | 2 +- roles/productivity/prime/README.md | 2 +- roles/productivity/prime/role.md | 2 +- roles/utility/spray/role.md | 2 +- 20 files changed, 32 insertions(+), 32 deletions(-) diff --git a/index.yaml b/index.yaml index 8339b76..713f56d 100644 --- a/index.yaml +++ b/index.yaml @@ -1,5 +1,5 @@ # ============================================================================= -# Module Index — agent-roledefinitions-submodule +# Module Index — Agent-Roles # ============================================================================= # GENERATED FILE — do not edit by hand. # Source of truth: roles///role.md + catalog.yaml. @@ -7,8 +7,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 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/roles/education/agora/README.md b/roles/education/agora/README.md index 46f95b4..21a6647 100644 --- 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 index 93b3f1c..f2c3d15 100644 --- 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 index 8b17848..d36bcda 100644 --- 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 index 4a12e5a..ddf2379 100644 --- 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 index 65ad7cb..6d349cd 100644 --- 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 index 2f3c6d6..1f6e348 100644 --- 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 index 632b3c1..a7e8429 100644 --- 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 index 45da4f5..3e807bf 100644 --- 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 index 89ec8f9..f9ca453 100644 --- 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 index 28f2681..1adc92e 100644 --- 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 index b28208b..f6781c1 100644 --- 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 index ec16b08..e847f34 100644 --- 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 index a380541..f756456 100644 --- 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 index 414dbfe..bf3660c 100644 --- 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 index 57c1d38..f24781b 100644 --- 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 index c359733..96f0b93 100644 --- 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 index 9593654..74a97f1 100644 --- 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 index 7886136..6b54d4d 100644 --- 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 index 4dce21c..c91b6e2 100644 --- 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 From 25bab4e81ffbb5dae234f380d53c664bbfff0768 Mon Sep 17 00:00:00 2001 From: Jerry van Heerikhuize Date: Sat, 25 Jul 2026 08:27:36 +0200 Subject: [PATCH 2/4] feat(validate): check role README agrees with role.md frontmatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every existing check in validate-index.sh is existence-shaped ("the referenced file is present"). None was agreement-shaped, which is the only kind that catches a hand-written copy going stale — and that is exactly how the version regression shipped. index.yaml and dist/ are generated and CI gates them with a git-diff check, so the per-role README is the one unguarded copy of version and category left. This check fails on main today with precisely the spray case. Interim guard: it becomes redundant once the README metadata header is generated too (see ROADMAP.md). Co-Authored-By: Claude Opus 5 --- scripts/validate-index.sh | 44 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/scripts/validate-index.sh b/scripts/validate-index.sh index 87b6598..0813c12 100755 --- a/scripts/validate-index.sh +++ b/scripts/validate-index.sh @@ -6,7 +6,8 @@ # 1. Every role directory on disk has an index.yaml entry. # 2. Every index.yaml entry points at files that exist. # 3. The README role-count badge matches the actual count. -# 4. (--check-crisis) config/crisis-resources.yaml entries are verified within +# 4. Each role README agrees with its role.md frontmatter on version/category. +# 5. (--check-crisis) config/crisis-resources.yaml entries are verified within # the last 12 months. set -euo pipefail @@ -106,7 +107,46 @@ if [[ -f "$README" ]]; then fi # --------------------------------------------------------------------------- -# 4. Crisis resources freshness (opt-in) +# 4. Role README agrees with role.md frontmatter +# --------------------------------------------------------------------------- +# index.yaml and dist/ are generated from role.md, and CI gates that with a +# git-diff check -- so those three can never disagree. The per-role README is +# still hand-written, which leaves exactly one unguarded copy of the version +# and category. That gap is not hypothetical: the v2 migration took its +# versions from the stale index.yaml, and spray shipped on main with a README +# and prompt body saying 2.0 against frontmatter saying 1.0. +# +# Every other check in this file is existence-shaped ("the referenced file is +# present"). This one is agreement-shaped, which is the only kind that catches +# a hand-written copy going stale. It becomes redundant the day the README +# header is generated too (see ROADMAP.md). +echo "==> README metadata agreement" +while IFS= read -r role_md; do + dir="$(dirname "$role_md")" + readme="$dir/README.md" + slug="$(basename "$dir")" + [[ -f "$readme" ]] || continue + + # Frontmatter is the source of truth; read only the leading --- block. + fm_version=$(awk '/^---$/{n++; next} n==1 && /^version:/ {gsub(/^version: *"?/,""); gsub(/".*/,""); print; exit}' "$role_md") + fm_category=$(awk '/^---$/{n++; next} n==1 && /^category:/ {gsub(/^category: *"?/,""); gsub(/".*/,""); print; exit}' "$role_md") + + header=$(grep -m1 '\*\*Version:\*\*' "$readme" || true) + [[ -n "$header" ]] || continue + + rd_version=$(sed -nE 's/.*\*\*Version:\*\* *([0-9]+(\.[0-9]+)*).*/\1/p' <<<"$header") + rd_category=$(sed -nE 's/.*\*\*Category:\*\* *([A-Za-z-]+).*/\1/p' <<<"$header") + + if [[ -n "$rd_version" && "$rd_version" != "$fm_version" ]]; then + fail "$slug: README says version $rd_version, role.md frontmatter says $fm_version" + fi + if [[ -n "$rd_category" && "${rd_category,,}" != "${fm_category,,}" ]]; then + fail "$slug: README says category '$rd_category', role.md frontmatter says '$fm_category'" + fi +done < <(find "$ROLES_DIR" -mindepth 3 -maxdepth 3 -name role.md | sort) + +# --------------------------------------------------------------------------- +# 5. Crisis resources freshness (opt-in) # --------------------------------------------------------------------------- if $CHECK_CRISIS; then echo "==> Crisis resources freshness" From c5c905ea4dae9a7e89228a0788904b4b78960b74 Mon Sep 17 00:00:00 2001 From: Jerry van Heerikhuize Date: Sat, 25 Jul 2026 08:27:36 +0200 Subject: [PATCH 3/4] fix(catalog): rename module to Agent-Roles and bump to 2.0.0-alpha.2 catalog.yaml still declared name: agent-roledefinitions-submodule after the repository URL had already moved to Agent-Roles. Resolves open decision #2 in docs/REBUILD_PLAN.md. REBUILD_PLAN keeps the old name where it quotes it historically. PATCH-equivalent prerelease bump per VERSIONING.md ("metadata corrections"). Co-Authored-By: Claude Opus 5 --- catalog.yaml | 4 ++-- resolve.sh | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/catalog.yaml b/catalog.yaml index a22729d..d27be0b 100644 --- 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/resolve.sh b/resolve.sh index 603d058..3293438 100755 --- 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 | --category | --tag | ... From ae4a6ed68809eaf2da4d618c3e16683a004dc6bd Mon Sep 17 00:00:00 2001 From: Jerry van Heerikhuize Date: Sat, 25 Jul 2026 08:27:36 +0200 Subject: [PATCH 4/4] docs(roadmap): rewrite around the v2 rebuild sequence The old roadmap promoted SemantiCode variants as the current focus; the rebuild archived them under archive/semanticode/. Replaces it with what shipped, the one gap Phase 1 left, and the ordering for Phases 2-4. Co-Authored-By: Claude Opus 5 --- ROADMAP.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 91 insertions(+), 12 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 34efbce..5455653 100644 --- 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 `` 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.