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. 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/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/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 | ... 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 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"