agents-city 0.3.0-beta.21

package/plugin/domains/research.md

@@ -0,0 +1,32 @@
+---
+id: research
+order: 70
+name: Research & education
+summary: Coordinate questions, evidence, methods, ethics and reusable knowledge.
+parcel: a study, course, corpus or research repository
+source: github|disk
+grows_with: reviewed findings or learning outcomes
+grow_command:
+roles:
+  - research-director  # on by default
+  - researcher  # on by default
+  - methods  # on by default
+  - research-ops
+  - ethics
+  - knowledge
+  - blank
+units:
+  - Studies ; 3fb8a0
+  - Methods ; 4a9ede
+  - Teaching ; e08a3c
+  - Knowledge ; 8f7ae6
+---
+# Research & education
+
+State the question, population, method, evidence quality and limits before the
+conclusion. Preserve null results, competing explanations and provenance. Do not
+upgrade correlation to causation or a preliminary result to settled knowledge.
+
+The chair synthesises; methods and ethics roles remain independent checks. Reuse
+existing evidence when it fits, but do not carry a result into a new context
+without testing whether its assumptions still hold.

package/plugin/domains/sales.md

@@ -0,0 +1,30 @@
+---
+id: sales
+order: 60
+name: Sales & customer success
+summary: Coordinate pipeline, accounts, revenue operations and customer outcomes.
+parcel: an account segment, playbook or revenue repository
+source: github|disk
+grows_with: verified customer outcomes and correctly closed opportunities
+grow_command:
+roles:
+  - revenue-lead  # on by default
+  - account-executive  # on by default
+  - revops  # on by default
+  - customer-success
+  - enablement
+  - blank
+units:
+  - New business ; 3fb8a0
+  - Expansion ; 8f7ae6
+  - Customer success ; 4a9ede
+  - Revenue operations ; e08a3c
+---
+# Sales & customer success
+
+Keep account facts, buyer intent, commitments and forecast judgement separate.
+Never invent a customer statement or turn missing CRM data into a confident
+pipeline claim. A promised feature, price or date must have an accountable owner.
+
+Optimise for durable customer outcomes, not activity counts alone. Surface churn
+risk, handoff gaps, stale stages and conflicting commitments across accounts.

package/plugin/domains/software.md

@@ -0,0 +1,37 @@
+---
+id: software
+order: 10
+name: Software development
+summary: Build, operate and evolve software products and their repositories.
+parcel: a repository or working folder
+source: github|disk
+grows_with: verified changes shipped
+grow_command: git log --since=30.days --oneline | wc -l
+roles:
+  - cpto  # on by default
+  - dev  # on by default
+  - data-engineer  # on by default
+  - devops  # on by default
+  - data  # on by default
+  - product-design
+  - po
+  - llm-engineer
+  - ai-manager
+  - blank
+units:
+  - Platform ; 3fb8a0
+  - Product ; e08a3c
+  - Mobile ; 8f7ae6
+  - Data ; 4a9ede
+---
+# Software development
+
+The city coordinates evidence and decisions across repositories. A support
+agent owns the context of its repo; the seat owns direction and the final call.
+
+Ask for reproducible code, tests, logs and diffs. Treat a green build as evidence
+for the checks it ran, not proof that the product behaves correctly. Changes to
+public interfaces, schemas, security, costs, analytics or shared UI should reach
+the relevant role even when the code itself still compiles.
+
+Repo skills stay in their repos and are invoked by their own runtime.

package/plugin/hooks/activity.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -u
+# Outside a city runtime the whole plugin stays silent (see the guard).
+. "$(dirname "$0")/solo-en-ciudad.sh"
+ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+exec python3 "$ROOT/scripts/hook_activity.py" "${1:-}"

package/plugin/hooks/digging.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# PreToolUse / Edit|Write|MultiEdit — leave a note saying where the digging is.
+#
+# This hook does not publish on the bus. It writes a note on disk and the seat
+# reports it. Repo runtimes receive chaired assignments through their adapter,
+# but never get road credentials or authority to address peers directly.
+#
+# It runs before every edit, so the fast path has to be cheap: one check of the
+# remote and a one-line file.
+set -uo pipefail
+# Outside a city runtime the whole plugin stays silent (see the guard).
+. "$(dirname "$0")/solo-en-ciudad.sh"
+nada() { printf '{}\n'; exit 0; }
+
+# One resolver for settings and for "does this repo belong to the city".
+# It used to be a hardcoded organisation name, which meant this hook did nothing
+# at all for anybody who was not that one company.
+. "${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/scripts/city-env.sh"
+REPO="$(repo_de_la_ciudad)" || nada
+
+CITY_SCOPE="$(printf '%s' "${CITY_ADDRESS:-city}" | tr -c 'A-Za-z0-9_.@-' '-')"
+DIR="$CITY_DIR/digging/$CITY_SCOPE"
+mkdir -p "$DIR" 2>/dev/null || nada
+
+# The parcel comes from the file being touched, matched against parcels.yml in
+# the data repo. Without that, the house is the whole repo.
+ENTRADA="$(cat)"
+FICHERO="$(sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' <<<"$ENTRADA" | head -1)"
+RAIZ="$(git rev-parse --show-toplevel 2>/dev/null || echo '')"
+REL="${FICHERO#$RAIZ/}"
+
+PARCELA="$REPO"
+EQUIPO="${AGENTS_CITY_DATA:-$HOME/agents-city-data}"
+if [ -n "$REL" ] && [ -f "$EQUIPO/parcelas.yml" ]; then
+  EN_REPO=0
+  while IFS= read -r linea; do
+    case "$linea" in
+      "  $REPO:") EN_REPO=1; continue ;;
+      "  "[a-zA-Z0-9_.-]*":") EN_REPO=0; continue ;;
+    esac
+    [ "$EN_REPO" -eq 1 ] || continue
+    case "$linea" in *"- ruta:"*) ;; *) continue ;; esac
+    RUTA="$(sed -n 's/.*- ruta:[[:space:]]*"\([^"]*\)".*/\1/p' <<<"$linea")"
+    [ -z "$RUTA" ] && { PARCELA="$REPO"; break; }   # empty path = the whole repo
+    # shellcheck disable=SC2254
+    case "$REL" in $RUTA) PARCELA="$REPO:$RUTA"; break ;; esac
+  done < "$EQUIPO/parcelas.yml"
+fi
+
+# El agente no es la persona, y tampoco es el repo: es ESTA ventana. Una persona
+# tiene la del puesto y una por repo, y si trabaja con worktrees, una por
+# worktree — mismo repo, ramas distintas, agentes distintos. Se distinguen por
+# el directorio del worktree y la rama, que es lo que de verdad los separa.
+DIRTRAB="$(basename "$RAIZ")"
+RAMA="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')"
+PRINCIPAL="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+[ -z "$PRINCIPAL" ] && PRINCIPAL=main
+
+AGENTE="$DIRTRAB"
+if [ -n "$RAMA" ] && [ "$RAMA" != "$PRINCIPAL" ] && [ "$RAMA" != "HEAD" ]; then
+  AGENTE="$DIRTRAB@$RAMA"
+fi
+
+# Un fichero por agente, no por repo: dos worktrees del mismo repo son dos.
+SEGURO="$(printf '%s' "$AGENTE" | tr -c 'A-Za-z0-9_.@-' '-')"
+printf '{"repo":"%s","parcela":"%s","agente":"%s","rama":"%s","ts":%s}\n' \
+  "$REPO" "$PARCELA" "$AGENTE" "$RAMA" "$(date +%s)" > "$DIR/$SEGURO.json"
+nada

package/plugin/hooks/growth.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Stop — report how much each parcel has grown, once a day.
+#
+# The city's cron can count merged pull requests on its own. It cannot run a
+# command inside somebody's folders, and in a marketing, legal or finance city
+# that is exactly what growth is: pieces published, matters filed, periods
+# closed. So it has to be reported from where the folders are, and if that means
+# somebody remembering to run a script, the map stops growing in week two.
+#
+# Once every twenty hours, not on every turn: these are real commands in real
+# folders — a find, a wc, sometimes a query — and the number they return does not
+# change by the minute. Detached and silent, like the spend report.
+set -uo pipefail
+# Outside a city runtime the whole plugin stays silent (see the guard).
+. "$(dirname "$0")/solo-en-ciudad.sh"
+nada() { printf '{}\n'; exit 0; }
+
+RAIZ="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+. "$RAIZ/scripts/city-env.sh"
+
+[ -n "${AGENTS_CITY_URL:-}" ] || nada
+[ -n "${CITY_BUS_TOKEN:-}" ] || nada
+[ -n "${AGENTS_CITY_DATA:-}" ] || nada
+[ -d "${AGENTS_CITY_DATA:-}" ] || nada
+command -v python3 >/dev/null 2>&1 || nada
+
+MARCA="$CITY_DIR/growth-last"
+mkdir -p "$CITY_DIR" 2>/dev/null || nada
+AHORA="$(date +%s)"
+if [ -f "$MARCA" ]; then
+  ANTES="$(cat "$MARCA" 2>/dev/null || echo 0)"
+  case "$ANTES" in ''|*[!0-9]*) ANTES=0 ;; esac
+  [ $((AHORA - ANTES)) -lt 72000 ] && nada
+fi
+printf '%s' "$AHORA" > "$MARCA"
+
+( AGENTS_CITY_URL="$AGENTS_CITY_URL" CITY_BUS_TOKEN="$CITY_BUS_TOKEN" \
+  AGENTS_CITY_DATA="$AGENTS_CITY_DATA" \
+  python3 "$RAIZ/scripts/report.py" --push --quiet \
+  >/dev/null 2>&1 & ) >/dev/null 2>&1
+
+nada

package/plugin/hooks/hooks.json

@@ -0,0 +1,106 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/notice-on-pr.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/digging.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/activity.sh\" SessionStart",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/notice-pending.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/activity.sh\" UserPromptSubmit",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/activity.sh\" Stop",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/notice-on-stop.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/tokens.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/growth.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/activity.sh\" SessionEnd",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/hooks/notice-on-pr.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# PreToolUse / Bash — when a PR is opened, hand the question to the agent.
+#
+# The hook matcher cannot filter Bash by the content of the command, so the filter
+# is here and it comes first: if the command does not open a PR, leave. This runs
+# before EVERY shell command, so the fast path has to be cheap.
+#
+# Like the rest of the notice hooks, this judges nothing: it only spots the
+# moment. Which property the change touches, and who it hurts, is the agent's
+# call.
+set -uo pipefail
+# Outside a city runtime the whole plugin stays silent (see the guard).
+. "$(dirname "$0")/solo-en-ciudad.sh"
+
+nada() { printf '{}\n'; exit 0; }
+
+ENTRADA="$(cat)"
+grep -qE 'gh[[:space:]]+pr[[:space:]]+create' <<<"$ENTRADA" || nada
+
+# One resolver for settings and for "does this repo belong to the city".
+# It used to be a hardcoded organisation name, which meant this hook did nothing
+# at all for anybody who was not that one company.
+. "${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/scripts/city-env.sh"
+REPO="$(repo_de_la_ciudad)" || nada
+
+python3 - "$REPO" "${CITY_SEAT_NAME:-seat}" <<'PY'
+import json, sys
+repo, seat = sys.argv[1:3]
+msg = f"""You are opening a PR in {repo}. As soon as it exists, judge whether what it carries touches a domain owned by a connected city, before moving on to anything else: this is the best moment there is, because after the merge it is decided and the destination seat can only ask for a rewrite.
+
+Follow /city:notice: compare the PR's diff against the "What reaches you" section of each roles/<role>.md, and work out who owns each property from the cards and the unit map.
+
+Two things about this window: it has no roads — repo windows deliberately do not get them — so hand the written notice to the city seat named "{seat}" and let it send. And if there is nothing to send, do not send anything and do not comment on it: silence is the right answer most of the time."""
+print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": msg}}))
+PY

package/plugin/hooks/notice-on-stop.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Stop — at the end of a turn where something changed, hand the question to the
+# agent.
+#
+# This hook does NOT decide whether to send a notice. It cannot: whether a change
+# breaks somebody else's property is a judgement, and no pattern is going to get
+# it right. All the code decides is whether there is new material nobody has
+# judged yet — that part is deterministic and cheap. The judgement belongs to the
+# agent, which has the diff and the roles in front of it.
+set -uo pipefail
+# Outside a city runtime the whole plugin stays silent (see the guard).
+. "$(dirname "$0")/solo-en-ciudad.sh"
+
+# Silent exit. It returns {} rather than nothing: with empty output, Claude Code
+# logs a "Hook output does not start with {" and a spurious error.
+nada() { printf '{}\n'; exit 0; }
+
+ENTRADA="$(cat)"
+
+# stop_hook_active arrives true when this hook already forced a continuation.
+# Without this exit, infinite loop.
+if grep -q '"stop_hook_active"[[:space:]]*:[[:space:]]*true' <<<"$ENTRADA"; then
+  nada
+fi
+
+# One resolver for settings and for "does this repo belong to the city".
+# It used to be a hardcoded organisation name, which meant this hook did nothing
+# at all for anybody who was not that one company.
+. "${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/scripts/city-env.sh"
+REPO="$(repo_de_la_ciudad)" || nada
+
+HEAD_SHA="$(git rev-parse HEAD 2>/dev/null || true)"
+[ -z "$HEAD_SHA" ] && nada
+
+# The fingerprint includes the CONTENT of the change, not just which files are
+# touched: `git status --porcelain` returns the same thing the first time you edit
+# a file and the fifth, so the second change — which may be the dangerous one —
+# would never be judged.
+SUCIO="$( { git status --porcelain 2>/dev/null
+            git diff HEAD 2>/dev/null
+            # Y el contenido de los ficheros nuevos, que no salen en el diff.
+            # Acotado a 200: esto corre al final de cada turno y no puede costar.
+            git ls-files --others --exclude-standard 2>/dev/null | head -200 \
+              | tr '\n' '\0' | xargs -0 shasum -a 256 2>/dev/null
+          } | shasum -a 256 | cut -d' ' -f1)"
+HUELLA="$HEAD_SHA:$SUCIO"
+
+CITY_SCOPE="$(printf '%s' "${CITY_ADDRESS:-city}" | tr -c 'A-Za-z0-9_.@-' '-')"
+DIR="$CITY_DIR/notices-judged/$CITY_SCOPE"
+mkdir -p "$DIR" 2>/dev/null || nada
+MARCA="$DIR/$REPO"
+
+# This exact state has already been asked about.
+if [ -f "$MARCA" ] && [ "$(cat "$MARCA")" = "$HUELLA" ]; then
+  nada
+fi
+
+# First time in this repo: take note and do not interrupt. Otherwise the first
+# session in any repo would open with a question nobody asked for.
+if [ ! -f "$MARCA" ]; then
+  printf '%s\n' "$HUELLA" > "$MARCA"
+  nada
+fi
+
+printf '%s\n' "$HUELLA" > "$MARCA"
+
+python3 - "$REPO" "${CITY_SEAT_NAME:-seat}" <<'PY'
+import json, sys
+repo, seat = sys.argv[1:3]
+razon = f"""Before you finish: you changed things in {repo}, and nobody has judged yet whether they touch another role's property.
+
+Judge it yourself — you have the diff in front of you, and no pattern can decide this. Compare what you changed against the "What reaches you" section of each roles/<role>.md, and against the unit map to work out whose it is when a property has more than one owner.
+
+Almost always the right answer is that there is nothing to send. If so, say it in one line and finish.
+
+If there is something: write it the way /city:notice says — [property] first, evidence with file and line, why it reaches them, what to look at, and that it does not block — and hand it to the city seat named "{seat}", which is the one with the roads. This window does not have them, on purpose.
+
+When in doubt, do not send one — except for anything about measurement (analytics, tags, pixels, consent, URLs, schemas, events): there, when in doubt, send it. It is the one property where arriving late cannot be fixed afterwards."""
+print(json.dumps({"decision": "block", "reason": razon}))
+PY

package/plugin/hooks/notice-pending.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# SessionStart — catches what the other two triggers could not see.
+#
+# A PR opened from GitHub's web UI, or commits that arrived through a pull, never
+# pass through a command in this session. So when the repo window opens, look for
+# commits nobody has reviewed since the last pass.
+#
+# The FIRST time in a repo it says nothing and only leaves the mark. Otherwise
+# the first session in a repo with two years of history sets off an avalanche.
+set -uo pipefail
+# Outside a city runtime the whole plugin stays silent (see the guard).
+. "$(dirname "$0")/solo-en-ciudad.sh"
+
+nada() { printf '{}\n'; exit 0; }
+
+# One resolver for settings and for "does this repo belong to the city".
+# It used to be a hardcoded organisation name, which meant this hook did nothing
+# at all for anybody who was not that one company.
+. "${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/scripts/city-env.sh"
+REPO="$(repo_de_la_ciudad)" || nada
+
+CITY_SCOPE="$(printf '%s' "${CITY_ADDRESS:-city}" | tr -c 'A-Za-z0-9_.@-' '-')"
+DIR="$CITY_DIR/notices-seen/$CITY_SCOPE"
+mkdir -p "$DIR" 2>/dev/null || nada
+MARCA="$DIR/$REPO"
+HEAD_SHA="$(git rev-parse HEAD 2>/dev/null || true)"
+[ -z "$HEAD_SHA" ] && nada
+
+if [ ! -f "$MARCA" ]; then
+  printf '%s\n' "$HEAD_SHA" > "$MARCA"
+  nada
+fi
+
+VISTO="$(cat "$MARCA")"
+[ "$VISTO" = "$HEAD_SHA" ] && nada
+if ! git cat-file -e "$VISTO" 2>/dev/null; then
+  printf '%s\n' "$HEAD_SHA" > "$MARCA"
+  nada
+fi
+
+# First-parent and no merges: in a repo with many merges, counting everything
+# gives absurd figures — 85 commits for five real ones.
+N="$(git rev-list --count --first-parent --no-merges "$VISTO..HEAD" 2>/dev/null || echo 0)"
+[ "$N" -eq 0 ] && nada
+
+python3 - "$REPO" "$VISTO" "$N" "$MARCA" "$HEAD_SHA" "${CITY_SEAT_NAME:-seat}" <<'PY'
+import json, sys
+repo, visto, n, marca, head, seat = sys.argv[1:7]
+msg = f"""In {repo} there are {n} commit(s) nobody has reviewed since {visto[:8]}.
+
+Before starting on whatever this session brings, judge whether any of them touch another role's property: look at {visto[:8]}..HEAD and follow /city:notice. No pattern can decide this; it has to be read.
+
+If something does, write the notice and hand it to the city seat named "{seat}", which is the one with the roads. If nothing does, do not send anything and do not comment on it.
+
+When you are done, bring the mark up to date so the pass is not repeated:
+  echo {head} > {marca}"""
+print(json.dumps({"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": msg}}))
+PY

package/plugin/hooks/solo-en-ciudad.sh

@@ -0,0 +1,23 @@
+# shellcheck shell=bash
+# Sourced first by every hook: the plugin's conscience runs only inside a city.
+#
+# Installing the plugin must not enrol every Claude conversation on the machine.
+# A city runtime always carries its actor identity in the environment —
+# CITY_BUS_ACTOR, set by city-session.sh for the seat and every repo window — and
+# a plain session carries none, so that is the gate. Outside a city every hook
+# answers `{}` and leaves: no passes, no digging notes, no judgements, no counters.
+#
+# Somebody who WANTS the old machine-wide conscience sets CITY_HOOKS=everywhere,
+# in the environment or in $CITY_DIR/.env. It is an explicit choice, never the
+# default: second-order effects should be opted into, not discovered.
+_CITY_DIR="${CITY_DIR:-$HOME/.claude/channels/city-bus}"
+_ambito="${CITY_HOOKS:-}"
+if [ -z "$_ambito" ] && [ -f "$_CITY_DIR/.env" ]; then
+  _ambito="$(sed -n 's/^CITY_HOOKS=//p' "$_CITY_DIR/.env" | head -1)"
+  _ambito="${_ambito%\"}"; _ambito="${_ambito#\"}"
+fi
+if [ "$_ambito" != "everywhere" ] && [ -z "${CITY_BUS_ACTOR:-}" ]; then
+  # `{}` rather than nothing: empty hook output logs a spurious error upstream.
+  printf '{}\n'
+  exit 0
+fi

package/plugin/hooks/tokens.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Stop — report what this machine has spent on tokens, at most twice an hour.
+#
+# The counter on the map is global: everybody's spend, one number, no ranking.
+# For that number to mean anything it has to arrive on its own — a reporter you
+# have to remember to run is a reporter that runs once, the day it is written,
+# and then the map quietly starts lying about the cost of the whole thing.
+#
+# What leaves the machine: a day, a model name, and four counts. Never a prompt,
+# never a file name, never a project path. The reporter reads the transcripts
+# Claude Code already writes; nothing new is recorded to make this work.
+#
+# Three rules, because this runs at the end of every turn:
+#   - Throttled. Twice an hour is plenty for a number shown per day.
+#   - Detached. The turn does not wait for a network call.
+#   - Silent. A spend report is not worth a word in somebody's terminal, and it
+#     is certainly not worth an error there.
+set -uo pipefail
+# Outside a city runtime the whole plugin stays silent (see the guard).
+. "$(dirname "$0")/solo-en-ciudad.sh"
+nada() { printf '{}\n'; exit 0; }
+
+RAIZ="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+. "$RAIZ/scripts/city-env.sh"
+
+# Nothing to report to, or nothing to report with: this seat is not on a map.
+[ -n "${AGENTS_CITY_URL:-}" ] || nada
+[ -n "${CITY_BUS_TOKEN:-}" ] || nada
+command -v python3 >/dev/null 2>&1 || nada
+
+MARCA="$CITY_DIR/tokens-last"
+mkdir -p "$CITY_DIR" 2>/dev/null || nada
+AHORA="$(date +%s)"
+if [ -f "$MARCA" ]; then
+  ANTES="$(cat "$MARCA" 2>/dev/null || echo 0)"
+  case "$ANTES" in ''|*[!0-9]*) ANTES=0 ;; esac
+  [ $((AHORA - ANTES)) -lt 1800 ] && nada
+fi
+printf '%s' "$AHORA" > "$MARCA"
+
+# Detached, output discarded. Whatever happens out there is not this turn's
+# problem; the next run picks up whatever this one failed to send.
+( AGENTS_CITY_URL="$AGENTS_CITY_URL" CITY_BUS_TOKEN="$CITY_BUS_TOKEN" \
+  python3 "$RAIZ/scripts/tokens.py" --push --quiet --days 30 \
+  >/dev/null 2>&1 & ) >/dev/null 2>&1
+
+nada

package/plugin/roles/examples/account-executive.md

@@ -0,0 +1,25 @@
+---
+role: account-executive
+trade: Master builder
+cross_cutting: false
+---
+
+## Domain
+
+The opportunities and accounts you carry: buyer context, objections, decisions
+and commitments made.
+
+## What you ask others
+
+- Whether a proposed promise is approved and deliverable.
+- Which customer evidence is current and directly observed.
+- Who owns the next dependency outside the account.
+
+## What reaches you
+
+A product, price, delivery or policy change affecting one of your opportunities.
+
+## What you can answer
+
+What the customer actually said, what remains inferred and why the opportunity is
+in its current state.

package/plugin/roles/examples/ai-manager.md

@@ -0,0 +1,34 @@
+---
+role: ai-manager
+trade: Works inspector
+cross_cutting: true
+---
+
+## Domain
+
+The portfolio of AI initiatives: what is being built, where it overlaps, what
+actually gets adopted, and what the whole thing costs.
+
+In the city you are the **works inspector**. You walk every site: what is being
+built twice, what got built and nobody uses, and what the total costs.
+
+## What you ask others
+
+- What is being automated with AI in each repo, and in what state.
+- Overlaps: two teams solving the same thing separately.
+- What was built and nobody uses.
+- Aggregate cost, and which initiative it comes from.
+- What it would take for something working in one place to serve another.
+
+## What reaches you
+
+- A new AI initiative in a repo.
+- Something starting to be built that already exists solved elsewhere.
+
+The rest of your domain — adoption, aggregate cost, overlaps — does not show up
+in a commit: that comes out in rounds, not in notices.
+
+## What you can answer
+
+What already exists in the house before they build something new, and who they
+should talk to.

package/plugin/roles/examples/associate.md

@@ -0,0 +1,24 @@
+---
+role: associate
+trade: Master builder
+cross_cutting: false
+---
+
+## Domain
+
+The matters you carry. You know their history, what was argued, what was conceded, and what is deliberately not in writing.
+
+## What you ask others
+
+- Whether a change to a shared template affects your matters.
+- Who else is acting for the same client.
+- Whether a precedent for this already exists in the firm.
+
+## What reaches you
+
+- A shared template or clause library changing.
+- A deadline moving on a matter you carry.
+
+## What you can answer
+
+The state of your matters, what is deliberate, and what risk you have taken on knowingly. With the file open, not from memory.