@delorenj/pjangler 1.2.17 → 1.2.19

package/templates/hermes-agent/docs/sentinel/providers.md

@@ -1,7 +1,7 @@
 # Provider adapters
 
 This guide is the reference for the ticket-provider abstraction: the contract
-every adapter implements, the two adapters that ship today, and a
+every adapter implements, the three adapters that ship today, and a
 step-by-step process for adding a new provider or verifying an existing one
 against a live board. Read [Architecture](architecture.md) first for how the
 adapter fits into the engine.
@@ -43,8 +43,12 @@ maps each to its back end's concrete state.
 
 ## The adapters that ship today
 
-The repository includes two supported adapters with different verification status.
+The repository includes three adapters with different verification status.
 
+- **Linear** (`providers/linear.sh`) is the reference implementation. It uses
+  the Linear GraphQL API. It's verified live against a real board. Linear's
+  `issue(id:)` field accepts both the UUID and the human identifier (for
+  example, `DEL-42`), so the engine can pass identifiers through.
 - **Plane** (`providers/plane.sh`) uses the Plane REST API with `X-API-Key`
   authentication. A Plane project maps to the board, a cycle maps to the
   milestone, and `state.group` maps to the state type. It's verified live. Note
@@ -60,12 +64,26 @@ The repository includes two supported adapters with different verification statu
 
 Set credentials in the environment and the board binding in `role.yaml`.
 
+<details>
+<summary>Linear</summary>
+
+- Credentials: `LINEAR_API_KEY`.
+- Binding:
+
+  ```yaml
+  ticket_provider:
+    name: linear
+    team: DEL # Linear team key
+    project: "" # optional, scopes milestone and issue queries
+  ```
+
+</details>
+
 <details>
 <summary>Plane</summary>
 
-- Credentials: `PLANE_API_KEY` or workspace-specific
-  `PLANE_<WORKSPACE>_API_KEY` from the shared fleet env. Endpoint:
-  `PLANE_BASE` (default `https://plane.delo.sh`).
+- Credentials: `PLANE_API_KEY`. Endpoint: `PLANE_BASE` (default
+  `https://plane.delo.sh`).
 - Binding:
 
   ```yaml
@@ -96,9 +114,8 @@ Set credentials in the environment and the board binding in `role.yaml`.
 
 To add a fourth provider, for example GitHub Issues or Jira, follow these steps.
 
-1. Create `template/.scripts/providers/<name>.sh`. Start from `plane.sh` if it
-   uses REST with a single API key, or `trello.sh` if it has a board/list/card
-   model.
+1. Create `template/.scripts/providers/<name>.sh`. Start from `linear.sh` if the
+   back end uses GraphQL, or `plane.sh` if it uses REST with a single API key.
 2. Implement every operation in [the contract](#the-contract). Return the exact
    JSON shapes shown in the table. Map your back end's states to the five
    normalized states.
@@ -110,7 +127,8 @@ To add a fourth provider, for example GitHub Issues or Jira, follow these steps.
 5. Extend `template/role.yaml.jinja` with a provider-specific binding block
    under the `{% if ticket_provider == '<name>' %}` branch.
 6. Teach `42-ticket-provider.sh` how to resolve or create the board for your
-   provider, if it differs from the existing `plane` and `trello` cases.
+   provider, if it differs from the existing `linear`, `plane`, and `trello`
+   cases.
 7. Validate and verify with the steps below.
 
 <!-- prettier-ignore -->
@@ -140,7 +158,7 @@ Before you touch a live board, confirm the adapter parses and fails cleanly.
    exit, with no Python traceback:
 
    ```bash
-   ( unset PLANE_API_KEY PLANE_33GOD_API_KEY; sh template/.scripts/providers/plane.sh resolve )
+   ( unset LINEAR_API_KEY; sh template/.scripts/providers/linear.sh resolve )
    ```
 
 ## Verifying an adapter against a live board
@@ -151,15 +169,15 @@ never closes or modifies a ticket, so it's safe to run.
 
 ```bash
 # 1. Load the credential into the environment only (never print it).
-export PLANE_API_KEY="$(grep -E '^(export )?PLANE(_[A-Z0-9_]+)?_API_KEY=' \
-  ~/.hermes/<agent>.env | head -1 | sed -E 's/^(export )?PLANE(_[A-Z0-9_]+)?_API_KEY=//; s/^"//; s/"$//')"
+export LINEAR_API_KEY="$(grep -E '^(export )?LINEAR_API_KEY=' \
+  ~/.hermes/<agent>.env | head -1 | sed -E 's/^(export )?LINEAR_API_KEY=//; s/^"//; s/"$//')"
 
 # 2. Stage a role directory bound to the real board.
 T=$(mktemp -d); RD="$T/agents/hermes/pm"
 mkdir -p "$RD/.scripts/lib" "$RD/.scripts/providers"
 cp template/.scripts/lib/ticket-provider.sh "$RD/.scripts/lib/"
-cp template/.scripts/providers/plane.sh "$RD/.scripts/providers/"
-printf 'repo: demo\nrole: pm\nticket_provider:\n  name: plane\n  workspace: 33god\n  project: <project-uuid>\n' \
+cp template/.scripts/providers/linear.sh "$RD/.scripts/providers/"
+printf 'repo: demo\nrole: pm\nticket_provider:\n  name: linear\n  team: DEL\n' \
   > "$RD/role.yaml"
 
 # 3. Run the read operations.
@@ -181,4 +199,5 @@ verification.
 ## Read next
 
 - [Development guide](development.md): the full edit, validate, and propagate
-  workflow, plus the open roadmap, which includes live-verifying Trello.
+  workflow, plus the open roadmap, which includes live-verifying Plane and
+  Trello.

package/templates/hermes-agent/install-local.sh

@@ -15,11 +15,10 @@
 #
 # Environment overrides (skip the prompts):
 #   HAT_REPO=<name>            project/repo name (default: basename of CWD)
-#   HAT_PROVIDER=plane|trello   (default: plane)
+#   HAT_PROVIDER=linear|plane|trello   (default: plane)
 #   HAT_ROLES="pm"                     roles to install (default: pm)
 #   HAT_DRY_RUN=1              print actions, change nothing
-#   Provider creds: PLANE_API_KEY or PLANE_<WORKSPACE>_API_KEY + PLANE_BASE
-#                   | TRELLO_KEY+TRELLO_TOKEN
+#   Provider creds: LINEAR_API_KEY | PLANE_API_KEY+PLANE_BASE | TRELLO_KEY+TRELLO_TOKEN
 set -eu
 
 say()  { printf '\033[36m%s\033[0m\n' "$*"; }
@@ -101,7 +100,7 @@ TOML
 fi
 
 # --- 4. Provider credentials + board binding ---------------------------------
-ask HAT_PROVIDER "Ticket provider (plane|trello)" "plane"
+ask HAT_PROVIDER "Ticket provider (linear|plane|trello)" "plane"
 PROVIDER="$HAT_PROVIDER"
 ask HAT_REPO "Project/repo name" "$(basename "$PROJECT_DIR" | tr '[:upper:]' '[:lower:]')"
 REPO="$HAT_REPO"
@@ -110,17 +109,13 @@ PM_ENV="$HOME/.hermes/${REPO}-pm.env"
 # These get written into the pm role.yaml binding after render.
 # Pre-seed from optional env knobs so the install can run non-interactively.
 TP_WORKSPACE="${HAT_PLANE_WORKSPACE:-}"; TP_PROJECT="${HAT_PLANE_PROJECT:-}"
-TP_BOARD="${HAT_TRELLO_BOARD:-}"
+TP_TEAM="${HAT_LINEAR_TEAM:-}"; TP_BOARD="${HAT_TRELLO_BOARD:-}"
 case "$PROVIDER" in
   plane)
     ask PLANE_BASE "Plane base URL" "https://app.plane.so"
+    : "${PLANE_API_KEY:?Set PLANE_API_KEY in your environment, then re-run}"
     ask TP_WORKSPACE "Plane workspace slug" ""
     [ -n "$TP_WORKSPACE" ] || die "workspace is required"
-    TP_WORKSPACE_KEY="$(printf '%s' "$TP_WORKSPACE" | tr '[:lower:]' '[:upper:]' | sed 's/[^A-Z0-9]/_/g')"
-    TP_WORKSPACE_KEY="PLANE_${TP_WORKSPACE_KEY}_API_KEY"
-    eval "TP_WORKSPACE_API_KEY=\${$TP_WORKSPACE_KEY:-}"
-    PLANE_API_KEY="${PLANE_API_KEY:-$TP_WORKSPACE_API_KEY}"
-    : "${PLANE_API_KEY:?Set PLANE_API_KEY or $TP_WORKSPACE_KEY in your environment, then re-run}"
     say "   Plane projects in '$TP_WORKSPACE':"
     _pj="$(mktemp)"
     curl -fsS "$PLANE_BASE/api/v1/workspaces/$TP_WORKSPACE/projects/?per_page=100" \
@@ -138,9 +133,15 @@ PY
     rm -f "$_pj"
     ask TP_PROJECT "Plane project UUID to manage" ""
     [ -n "$TP_PROJECT" ] || die "project UUID is required"
-    CRED_LINES="$TP_WORKSPACE_KEY=$PLANE_API_KEY
+    CRED_LINES="PLANE_API_KEY=$PLANE_API_KEY
 PLANE_BASE=$PLANE_BASE"
     ;;
+  linear)
+    : "${LINEAR_API_KEY:?Set LINEAR_API_KEY in your environment, then re-run}"
+    ask TP_TEAM "Linear team key (for example DEL)" ""
+    [ -n "$TP_TEAM" ] || die "team key is required"
+    CRED_LINES="LINEAR_API_KEY=$LINEAR_API_KEY"
+    ;;
   trello)
     : "${TRELLO_KEY:?Set TRELLO_KEY in your environment, then re-run}"
     : "${TRELLO_TOKEN:?Set TRELLO_TOKEN in your environment, then re-run}"
@@ -164,13 +165,12 @@ fi
 export SKIP_TELEGRAM=1 SKIP_EMAIL=1 SKIP_RUNTIME_REPO=1 SKIP_PLANE=1 \
        SKIP_BLOODBANK=1 SKIP_SYSTEMD=1
 ROLES="${HAT_ROLES:-pm}"
-SCRUB_PLANE_KEY="${TP_WORKSPACE_KEY:-PLANE_DEFAULT_API_KEY}"
 for ROLE in $ROLES; do
   say "5. provisioning role: $ROLE"
   DEST="$PROJECT_DIR/agents/hermes/$ROLE"
   # Scrub provider creds from copier's environment so 42-ticket-provider skips
   # board CREATION; we bind to the existing board in step 6 instead.
-  run "env -u PLANE_API_KEY -u '$SCRUB_PLANE_KEY' \
+  run "env -u PLANE_API_KEY -u PLANE_33GOD_API_KEY -u LINEAR_API_KEY \
         -u TRELLO_KEY -u TRELLO_TOKEN \
         copier copy '$TEMPLATE_SRC' '$DEST' --trust --defaults --overwrite \
         --data target_repo='$REPO' --data role='$ROLE' --data ticket_provider='$PROVIDER'"
@@ -180,7 +180,7 @@ done
 PM_ROLE="$PROJECT_DIR/agents/hermes/pm/role.yaml"
 if [ -f "$PM_ROLE" ] && [ "${HAT_DRY_RUN:-0}" != "1" ]; then
   say "6. binding pm to your $PROVIDER board"
-  TP_WORKSPACE="$TP_WORKSPACE" TP_PROJECT="$TP_PROJECT" \
+  TP_WORKSPACE="$TP_WORKSPACE" TP_PROJECT="$TP_PROJECT" TP_TEAM="$TP_TEAM" \
   TP_BOARD="$TP_BOARD" PROVIDER="$PROVIDER" python3 - "$PM_ROLE" <<'PY'
 import os, re, sys, pathlib
 p = pathlib.Path(sys.argv[1]); t = p.read_text()
@@ -190,6 +190,7 @@ def setleaf(text, key, val):
     return new if n else text
 t = setleaf(t, "workspace", os.environ.get("TP_WORKSPACE",""))
 t = setleaf(t, "project",   os.environ.get("TP_PROJECT",""))
+t = setleaf(t, "team",      os.environ.get("TP_TEAM",""))
 t = setleaf(t, "board",     os.environ.get("TP_BOARD",""))
 p.write_text(t)
 print("   bound:", {k:v for k,v in os.environ.items() if k.startswith("TP_") and v})

package/templates/hermes-agent/runtime-scaffold/README.md

@@ -13,7 +13,7 @@ and recoverable on failure.
 | `memories/MEMORY.md` | yes | The condensed mental-model summary loaded each session |
 | `memories/USER.md` | yes | The operator's persona (Jarad DeLorenzo, ...) |
 | `sessions/sessions.db` | yes (LFS) | SQLite store of every conversation |
-| `bloodbank-consumer.py` | yes | NATS subscriber for repo-scoped events |
+| `bloodbank-consumer.py` | yes | NATS subscriber using canonical subjects plus envelope routing data |
 | `decisions/` | yes | Agent-emitted decisions, one file per important call |
 | `.env` | **no** | API keys + Telegram bot token (per-machine secret) |
 | `auth.json` | **no** | Deprecated local OAuth store; fleet auth defaults to `HERMES_OAUTH_FILE=~/.hermes/auth.json` |

package/templates/hermes-agent/runtime-scaffold/bloodbank-consumer.py

@@ -3,14 +3,16 @@
 Bloodbank consumer for hermes agent {{agent_id}}.
 
 Subscribes to:
-    bloodbank.evt.v1.repo.{{repo}}.>
-    bloodbank.cmd.v1.agent.{{agent_id}}.>
+    bloodbank.evt.v1.repo.>
+    bloodbank.cmd.v1.agent.>
 
-This scaffold is a transitional receiver: it proves NATS subscription and keeps
-a durable audit copy at $HERMES_HOME/bloodbank-inbox/<timestamp>.json. It is
-not the final command path. Bloodbank command subjects should become a Hermes
-gateway/transport so each consumed event enters the same turn queue as Telegram
-or web input, with backpressure handled by the queue instead of by a file drain.
+The Bloodbank subject identifies the fixed domain/entity/action route. Repo and
+agent identifiers stay in envelope data, so this consumer filters repo events
+by ``data.repo`` and agent commands by ``data.target_agent_id``.
+
+For each event/command received, writes it to the agent's notification queue at
+$HERMES_HOME/bloodbank-inbox/<timestamp>.json so the gateway can ingest it on
+the next tick. Reconnects on broker churn; idempotent across restarts.
 
 Generated by hermes-agent-template/runtime-scaffold/bloodbank-consumer.py and
 rendered with role-specific values at provision time. Re-render by re-running
@@ -49,8 +51,8 @@ PRODUCER = f"hermes-agent:{AGENT_ID}"
 SOURCE   = f"hermes://agent/{AGENT_ID}"
 
 SUBJECTS = [
-    f"bloodbank.evt.v1.repo.{REPO}.>",
-    f"bloodbank.cmd.v1.agent.{AGENT_ID}.>",
+    "bloodbank.evt.v1.repo.>",
+    "bloodbank.cmd.v1.agent.>",
 ]
 
 KIND_MARKERS = {"event": "evt", "command": "cmd", "reply": "rpy"}
@@ -62,8 +64,8 @@ def _now():
 
 def _subject_and_domain(ce_type, kind):
     parts = ce_type.split(".")
-    if len(parts) != 5 or parts[0] != "bloodbank" or not parts[1].startswith("v"):
-        raise ValueError(f"type {ce_type!r} must match bloodbank.vN.<domain>.<entity>.<action>")
+    if len(parts) != 5 or parts[0] != "bloodbank" or parts[1] != "v1":
+        raise ValueError(f"type {ce_type!r} must match bloodbank.v1.<domain>.<entity>.<action>")
     if kind not in KIND_MARKERS:
         raise ValueError(f"unknown envelope kind {kind!r}")
     _vendor, version, domain, entity, action = parts
@@ -95,6 +97,33 @@ def build_envelope(ce_type, data, *, kind="event", correlationid=None, causation
     return env
 
 
+def _is_for_consumer(subject, payload):
+    """Route canonical subjects using identifiers carried in envelope data."""
+    if not isinstance(payload, dict):
+        return False
+    parts = subject.split(".")
+    if len(parts) != 6 or parts[0] != "bloodbank" or parts[2] != "v1":
+        return False
+
+    _vendor, kind, version, domain, entity, action = parts
+    if kind not in KIND_MARKERS.values():
+        return False
+    if KIND_MARKERS.get(payload.get("kind")) != kind:
+        return False
+    if payload.get("subject") != subject:
+        return False
+    if payload.get("type") != f"bloodbank.{version}.{domain}.{entity}.{action}":
+        return False
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        return False
+    if kind == "evt" and domain == "repo":
+        return data.get("repo") == REPO
+    if kind == "cmd" and domain == "agent":
+        return data.get("target_agent_id") == AGENT_ID
+    return False
+
+
 async def main():
     nc = await nats.connect(NATS_URL, name=f"hermes-{AGENT_ID}")
     stop = asyncio.Event()
@@ -103,7 +132,10 @@ async def main():
         try:
             payload = json.loads(msg.data.decode())
         except Exception:
-            payload = {"_raw": msg.data.decode(errors="replace")}
+            sys.stderr.write(f"[bloodbank-consumer:{AGENT_ID}] skipped unroutable payload on {msg.subject}\n")
+            return
+        if not _is_for_consumer(msg.subject, payload):
+            return
         entry = {
             "received_at": _now(),
             "subject": msg.subject,
@@ -125,7 +157,7 @@ async def main():
         "bloodbank.v1.agent.online.changed",
         {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "online"},
     )
-    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(online).encode())
+    await nc.publish(online["subject"], json.dumps(online).encode())
 
     def _shutdown(*_):
         stop.set()
@@ -138,7 +170,7 @@ async def main():
         "bloodbank.v1.agent.online.changed",
         {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "offline"},
     )
-    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(offline).encode())
+    await nc.publish(offline["subject"], json.dumps(offline).encode())
     await nc.drain()
 
 

package/templates/hermes-agent/runtime-scaffold/memories/MEMORY.md

@@ -7,8 +7,8 @@ short and high-signal — anything that should ALWAYS be in context.
 
 You are **{{display_name}}**, the `{{role}}` agent for the `{{repo}}` repo.
 Your scope is the repo at the project root. You communicate via Telegram
-(`@{{repo}}_{{role}}_bot`) and Bloodbank events on the
-`bloodbank.evt.v1.repo.{{repo}}.*` lane.
+(`@{{repo}}_{{role}}_bot`) and canonical Bloodbank repo events on
+`bloodbank.evt.v1.repo.>`, filtered by `data.repo = {{repo}}`.
 
 ## Operator
 

package/templates/hermes-agent/scripts/fleet-sync.sh

@@ -42,11 +42,7 @@ for p in sys.argv[2].split("."):
         cur = cur[p]
     else:
         print(sys.argv[3], end=""); sys.exit(0)
-if isinstance(cur, list):
-    cur = " ".join(str(x) for x in cur)
-else:
-    cur = str(cur)
-print(os.path.expanduser(cur), end="")
+print(os.path.expanduser(str(cur)), end="")
 PYEOF
   return 0
 }
@@ -60,7 +56,6 @@ REGISTRY_FILE="${HERMES_FLEET_REGISTRY_FILE:-$(cfg fleet.registry_file "$HOME/.h
 PROFILES_DIR="${HERMES_FLEET_HOME:-$HOME/.hermes}/profiles"
 VOXXY_PLUGIN_DIR="${VOXXY_PLUGIN_DIR:-$(cfg fleet.voxxy_plugin_dir "$HOME/code/voxxy/plugins/tts/voxxy")}"
 VOX_URL_VALUE="${VOX_URL:-$(cfg fleet.vox_url 'https://vox.delo.sh')}"
-PM_EXTERNAL_SKILL_DIRS="${PM_EXTERNAL_SKILL_DIRS:-$(cfg fleet.pm_external_skill_dirs "$HOME/code/skillex/skill-sets/global/.system $HOME/code/skillex/packs/bmad/6.10.2")}"
 
 APPLY=0
 RESTART=1
@@ -141,42 +136,6 @@ path.write_text("\n".join(lines) + "\n")
 PYEOF
 }
 
-pm_skill_dirs_status() {  # pm_skill_dirs_status <config-path>
-  python3 - "$1" "$PM_EXTERNAL_SKILL_DIRS" <<'PYEOF'
-import pathlib
-import sys
-
-import yaml
-
-path = pathlib.Path(sys.argv[1])
-desired = [entry for entry in sys.argv[2].split() if entry]
-if not path.exists():
-    print('missing')
-    raise SystemExit(0)
-data = yaml.safe_load(path.read_text()) or {}
-skills = data.get('skills') or {}
-current = list(skills.get('external_dirs') or [])
-print('ok' if current == desired else 'mismatch')
-PYEOF
-}
-
-set_pm_skill_dirs() {  # set_pm_skill_dirs <config-path>
-  python3 - "$1" "$PM_EXTERNAL_SKILL_DIRS" <<'PYEOF'
-import pathlib
-import sys
-
-import yaml
-
-path = pathlib.Path(sys.argv[1])
-desired = [entry for entry in sys.argv[2].split() if entry]
-data = yaml.safe_load(path.read_text()) or {}
-skills = data.get('skills') or {}
-skills['external_dirs'] = desired
-data['skills'] = skills
-path.write_text(yaml.safe_dump(data, sort_keys=False))
-PYEOF
-}
-
 wanted_agent() {
   [[ ${#ONLY_AGENTS[@]} -eq 0 ]] && return 0
   local a
@@ -279,28 +238,6 @@ while IFS=$'\t' read -r agent_id role_dir profile_name gateway_unit consumer_uni
   # 5. PM fleet voice contract: runtime plugin symlink + Voxxy config + VOX_URL.
   role_name="$(basename "$role_dir")"
   if [[ "$role_name" == "pm" && -d "$runtime" ]]; then
-    runtime_config="$runtime/config.yaml"
-    if [[ -n "$PM_EXTERNAL_SKILL_DIRS" ]]; then
-      skill_dir_status="$(pm_skill_dirs_status "$runtime_config")"
-      case "$skill_dir_status" in
-        ok) ;;
-        missing)
-          note "$agent_id" DRIFT "runtime config missing: $runtime_config"
-          DRIFT=$((DRIFT + 1))
-          ;;
-        *)
-          if [[ $APPLY -eq 1 ]]; then
-            set_pm_skill_dirs "$runtime_config"
-            note "$agent_id" FIXED "PM runtime skills.external_dirs synchronized"
-            changed=1; FIXED=$((FIXED + 1))
-          else
-            note "$agent_id" DRIFT "PM runtime skills.external_dirs differ from fleet contract"
-            DRIFT=$((DRIFT + 1))
-          fi
-          ;;
-      esac
-    fi
-
     plugin_link="$runtime/plugins/tts/voxxy"
     if [[ -d "$VOXXY_PLUGIN_DIR" ]]; then
       if [[ -L "$plugin_link" ]]; then

package/templates/hermes-agent/template/.gitignore.jinja

@@ -4,5 +4,3 @@
 # We just ignore the provisioning log so it doesn't end up in the project repo.
 .scripts/.provision.log
 .scripts/.last-run
-runtime/
-

package/templates/hermes-agent/template/.runtime-scaffold/README.md

@@ -13,7 +13,7 @@ and recoverable on failure.
 | `memories/MEMORY.md` | yes | The condensed mental-model summary loaded each session |
 | `memories/USER.md` | yes | The operator's persona (Jarad DeLorenzo, ...) |
 | `sessions/sessions.db` | yes (LFS) | SQLite store of every conversation |
-| `bloodbank-consumer.py` | yes | NATS subscriber for repo-scoped events |
+| `bloodbank-consumer.py` | yes | NATS subscriber using canonical subjects plus envelope routing data |
 | `decisions/` | yes | Agent-emitted decisions, one file per important call |
 | `.env` | **no** | API keys + Telegram bot token (per-machine secret) |
 | `auth.json` | **no** | Deprecated local OAuth store; fleet auth defaults to `HERMES_OAUTH_FILE=~/.hermes/auth.json` |

package/templates/hermes-agent/template/.runtime-scaffold/bloodbank-consumer.py

@@ -3,8 +3,12 @@
 Bloodbank consumer for hermes agent {{agent_id}}.
 
 Subscribes to:
-    bloodbank.evt.v1.repo.{{repo}}.>
-    bloodbank.cmd.v1.agent.{{agent_id}}.>
+    bloodbank.evt.v1.repo.>
+    bloodbank.cmd.v1.agent.>
+
+The Bloodbank subject identifies the fixed domain/entity/action route. Repo and
+agent identifiers stay in envelope data, so this consumer filters repo events
+by ``data.repo`` and agent commands by ``data.target_agent_id``.
 
 For each event/command received, writes it to the agent's notification queue at
 $HERMES_HOME/bloodbank-inbox/<timestamp>.json so the gateway can ingest it on
@@ -47,8 +51,8 @@ PRODUCER = f"hermes-agent:{AGENT_ID}"
 SOURCE   = f"hermes://agent/{AGENT_ID}"
 
 SUBJECTS = [
-    f"bloodbank.evt.v1.repo.{REPO}.>",
-    f"bloodbank.cmd.v1.agent.{AGENT_ID}.>",
+    "bloodbank.evt.v1.repo.>",
+    "bloodbank.cmd.v1.agent.>",
 ]
 
 KIND_MARKERS = {"event": "evt", "command": "cmd", "reply": "rpy"}
@@ -60,8 +64,8 @@ def _now():
 
 def _subject_and_domain(ce_type, kind):
     parts = ce_type.split(".")
-    if len(parts) != 5 or parts[0] != "bloodbank" or not parts[1].startswith("v"):
-        raise ValueError(f"type {ce_type!r} must match bloodbank.vN.<domain>.<entity>.<action>")
+    if len(parts) != 5 or parts[0] != "bloodbank" or parts[1] != "v1":
+        raise ValueError(f"type {ce_type!r} must match bloodbank.v1.<domain>.<entity>.<action>")
     if kind not in KIND_MARKERS:
         raise ValueError(f"unknown envelope kind {kind!r}")
     _vendor, version, domain, entity, action = parts
@@ -93,6 +97,33 @@ def build_envelope(ce_type, data, *, kind="event", correlationid=None, causation
     return env
 
 
+def _is_for_consumer(subject, payload):
+    """Route canonical subjects using identifiers carried in envelope data."""
+    if not isinstance(payload, dict):
+        return False
+    parts = subject.split(".")
+    if len(parts) != 6 or parts[0] != "bloodbank" or parts[2] != "v1":
+        return False
+
+    _vendor, kind, version, domain, entity, action = parts
+    if kind not in KIND_MARKERS.values():
+        return False
+    if KIND_MARKERS.get(payload.get("kind")) != kind:
+        return False
+    if payload.get("subject") != subject:
+        return False
+    if payload.get("type") != f"bloodbank.{version}.{domain}.{entity}.{action}":
+        return False
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        return False
+    if kind == "evt" and domain == "repo":
+        return data.get("repo") == REPO
+    if kind == "cmd" and domain == "agent":
+        return data.get("target_agent_id") == AGENT_ID
+    return False
+
+
 async def main():
     nc = await nats.connect(NATS_URL, name=f"hermes-{AGENT_ID}")
     stop = asyncio.Event()
@@ -101,7 +132,10 @@ async def main():
         try:
             payload = json.loads(msg.data.decode())
         except Exception:
-            payload = {"_raw": msg.data.decode(errors="replace")}
+            sys.stderr.write(f"[bloodbank-consumer:{AGENT_ID}] skipped unroutable payload on {msg.subject}\n")
+            return
+        if not _is_for_consumer(msg.subject, payload):
+            return
         entry = {
             "received_at": _now(),
             "subject": msg.subject,
@@ -123,7 +157,7 @@ async def main():
         "bloodbank.v1.agent.online.changed",
         {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "online"},
     )
-    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(online).encode())
+    await nc.publish(online["subject"], json.dumps(online).encode())
 
     def _shutdown(*_):
         stop.set()
@@ -136,7 +170,7 @@ async def main():
         "bloodbank.v1.agent.online.changed",
         {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "offline"},
     )
-    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(offline).encode())
+    await nc.publish(offline["subject"], json.dumps(offline).encode())
     await nc.drain()
 
 

package/templates/hermes-agent/template/.runtime-scaffold/memories/MEMORY.md

@@ -7,8 +7,8 @@ short and high-signal — anything that should ALWAYS be in context.
 
 You are **{{display_name}}**, the `{{role}}` agent for the `{{repo}}` repo.
 Your scope is the repo at the project root. You communicate via Telegram
-(`@{{repo}}_{{role}}_bot`) and Bloodbank events on the
-`bloodbank.evt.v1.repo.{{repo}}.*` lane.
+(`@{{repo}}_{{role}}_bot`) and canonical Bloodbank repo events on
+`bloodbank.evt.v1.repo.>`, filtered by `data.repo = {{repo}}`.
 
 ## Operator
 

package/templates/hermes-agent/template/.scripts/01-config.sh

@@ -26,7 +26,6 @@ hermes_repo = "~/.hermes/hermes-agent"
 fleet_env = "~/.hermes/fleet.env"
 registry_file = "~/.hermes/agents-registry.yaml"
 canonical_skills_dir = "/home/delorenj/.agents/skills"
-pm_external_skill_dirs = ["~/code/skillex/skill-sets/global/.system", "~/code/skillex/packs/bmad/6.10.2"]
 
 [github]
 runtime_repo_owner = "delorenj"

package/templates/hermes-agent/template/.scripts/05-fleet-env.sh

@@ -47,15 +47,6 @@ PYEOF
 
 upsert_fleet_env HERMES_FLEET_OAUTH_FILE "$HERMES_OAUTH_FILE"
 upsert_fleet_env HERMES_FLEET_CODEX_HOME "$CODEX_HOME"
-
-PLANE_WORKSPACE_KEY="$(plane_workspace_key "$PLANE_WORKSPACE")"
-PLANE_WORKSPACE_VALUE="${!PLANE_WORKSPACE_KEY:-}"
-if [[ -z "$PLANE_WORKSPACE_VALUE" && -n "${PLANE_API_KEY:-}" ]]; then
-  PLANE_WORKSPACE_VALUE="$PLANE_API_KEY"
-fi
-if [[ -n "$PLANE_WORKSPACE_VALUE" ]]; then
-  upsert_fleet_env "$PLANE_WORKSPACE_KEY" "$PLANE_WORKSPACE_VALUE"
-fi
 chmod 600 "$FLEET_ENV"
 
 mark_done 05-fleet-env

package/templates/hermes-agent/template/.scripts/10-hermes-profile.sh

@@ -110,29 +110,10 @@ CANONICAL_SKILLS_DIR="${CANONICAL_SKILLS_DIR:-$(config_get fleet.canonical_skill
 CANONICAL_PM_SKILL_SRC="$CANONICAL_SKILLS_DIR/subagent-driven-development"
 LOCAL_PM_SKILL_DST="$PROFILE_HOME/skills/software-development/subagent-driven-development"
 
-if [[ "$ROLE" == "pm" ]]; then
-  PM_EXTERNAL_SKILL_DIRS="${PM_EXTERNAL_SKILL_DIRS:-$(config_get fleet.pm_external_skill_dirs "$HOME/code/skillex/skill-sets/global/.system $HOME/code/skillex/packs/bmad/6.10.2")}" 
-  read -r -a RESOLVED_PM_EXTERNAL_SKILL_DIRS <<< "$PM_EXTERNAL_SKILL_DIRS"
-  if [[ ${#RESOLVED_PM_EXTERNAL_SKILL_DIRS[@]} -gt 0 ]]; then
-    log "    setting PM skills.external_dirs = ${RESOLVED_PM_EXTERNAL_SKILL_DIRS[*]}"
-    python3 - "$PROFILE_HOME/config.yaml" "${RESOLVED_PM_EXTERNAL_SKILL_DIRS[@]}" <<'PYEOF'
-import pathlib
-import sys
-
-import yaml
-
-path = pathlib.Path(sys.argv[1])
-external_dirs = sys.argv[2:]
-data = yaml.safe_load(path.read_text()) or {}
-skills = data.get("skills") or {}
-skills["external_dirs"] = external_dirs
-data["skills"] = skills
-path.write_text(yaml.safe_dump(data, sort_keys=False))
-PYEOF
-  fi
-fi
-
 if [[ -d "$CANONICAL_SKILLS_DIR" ]]; then
+  log "    setting skills.external_dirs[0] = $CANONICAL_SKILLS_DIR"
+  env HERMES_HOME="$PROFILE_HOME" "$HERMES_BIN" config set skills.external_dirs.0 "$CANONICAL_SKILLS_DIR"
+
   # Ensure key PM/local-ops skills are symlinked into runtime/profile skills root.
   # This preserves canonical ownership and keeps updates instant across agents.
   read -r -a SYMLINKED_RUNTIME_SKILLS <<< "${SYMLINKED_RUNTIME_SKILLS:-$(config_get fleet.symlinked_runtime_skills 'delonet-conventions delonet-dotenv hermes-pm-template-maintenance hindsight subagent-driven-development')}"

package/templates/hermes-agent/template/.scripts/20-runtime-repo.sh

@@ -144,28 +144,6 @@ log "    profile symlink $PROFILE_HOME -> $RUNTIME_LOCAL"
 # Apply the one genuine per-repo config delta directly to the runtime config.
 env HERMES_HOME="$RUNTIME_LOCAL" "$HERMES_BIN" config set terminal.cwd "$PROJECT_PATH" >/dev/null 2>&1 || true
 
-if [[ "$ROLE" == "pm" ]]; then
-  PM_EXTERNAL_SKILL_DIRS="${PM_EXTERNAL_SKILL_DIRS:-$(config_get fleet.pm_external_skill_dirs "$HOME/code/skillex/skill-sets/global/.system $HOME/code/skillex/packs/bmad/6.10.2")}"
-  read -r -a RESOLVED_PM_EXTERNAL_SKILL_DIRS <<< "$PM_EXTERNAL_SKILL_DIRS"
-  if [[ ${#RESOLVED_PM_EXTERNAL_SKILL_DIRS[@]} -gt 0 ]]; then
-    python3 - "$RUNTIME_LOCAL/config.yaml" "${RESOLVED_PM_EXTERNAL_SKILL_DIRS[@]}" <<'PYEOF'
-import pathlib
-import sys
-
-import yaml
-
-path = pathlib.Path(sys.argv[1])
-external_dirs = sys.argv[2:]
-data = yaml.safe_load(path.read_text()) or {}
-skills = data.get("skills") or {}
-skills["external_dirs"] = external_dirs
-data["skills"] = skills
-path.write_text(yaml.safe_dump(data, sort_keys=False))
-PYEOF
-    log "    set PM runtime skills.external_dirs -> ${RESOLVED_PM_EXTERNAL_SKILL_DIRS[*]}"
-  fi
-fi
-
 if [[ "$ROLE" == "pm" ]]; then
   VOXXY_PLUGIN_DIR="${VOXXY_PLUGIN_DIR:-$(config_get fleet.voxxy_plugin_dir "$HOME/code/voxxy/plugins/tts/voxxy")}"
   if [[ -d "$VOXXY_PLUGIN_DIR" ]]; then