---
name: hermes-profile-router
description: Use when deciding whether work belongs in default Hermes, a bounded subagent, a retained specialist profile, a temporary project worker, a tenant stack, or a wiki; includes profile-usage auditing and safe consolidation.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [hermes, profiles, routing, skills, memory, wiki]
    related_skills: [hermes-agent, llm-wiki]
---

# Hermes Profile Router

## Overview

Use this skill to decide whether work needs a separate Hermes profile at all, which profile should own it when isolation is justified, when to query/update an LLM Wiki, and what belongs in memory versus skills versus wiki pages.

Do **not** preserve a specialist-profile split merely because the profile homes exist. First audit real use from each profile's `state.db`/session timestamps and logs, explicit `hermes --profile ...` launches, cron/script references, credentials, role prompts, and tool differences. Filesystem mtimes alone are weak evidence because inspection commands can touch logs. Distinguish:

- **Permanent personal profile** — normally `default`, Telegram-facing, with Alex's coherent memory, custom plugins, and class-level cross-domain skills.
- **Temporary project worker** — bounded build/review/research profile with a strong role prompt, explicit worktree/board, and lifecycle end; archive after durable handoff.
- **Tenant/customer profile or stack** — retained for real credential, memory, data, channel, or security isolation.

A one-permanent-profile design is preferred when specialist profiles have generic SOUL files, nearly identical tools/credentials, low substantive use, duplicated skills, and unreliable prompt-only routing. In that case specialization should come from skills, project `AGENTS.md`, wikis, and bounded `delegate_task` workers. Keep separate durable profiles only for meaningful credential/security boundaries, distinct messaging identities, tenant-private memory, strongly conflicting authority, or long-running autonomous workflows.

Before consolidation, audit the skill catalog rather than merging every historical skill blindly. Preserve one copy of locally developed skills, archive stale/absorbed entries instead of deleting the only source, split oversized sediment-heavy skills into compact front doors plus `references/`, and record source freshness for volatile API/model/provider procedures. Creation date is evidence but weaker than last source verification, current path/schema checks, successful recent use, and whether another system became authoritative.

Historical specialist map (use only while those profiles remain active):
- `default` — Telegram-facing orchestrator and Hermes operations
- `astro` — astrology, Human Design, BG5, I Ching, tarot, Astro Engine/HD Prism, astro/HD wikis
- `build` — code, debugging, tests, GitHub, PM2/nginx/VPS deployments, `/home/avalon/apps`
- `creative` — media/story/image/video/audio/music and creative production workflows
- `research` — source-backed research, docs/API/vendor/model investigation, papers, LLM Wiki/corpus work, and MLOps as a subdomain
- `ops` — productivity/integrations/automations

Treat `frontend`, `backend`, `qa`, `devops`, and `security` primarily as build roles/skills unless a dedicated project swarm is active. Treat `astral*`, `salmon*`, `caduceus-*`, and similar project-role profiles as temporary execution infrastructure unless a current workflow proves otherwise.

Project swarms are temporary execution structures, not durable global profiles. After a project push, actively audit whether the swarm is still needed; archive durable outcomes into repo docs, skills, wikis, or summaries, then delete stale swarm profiles once the user agrees. Do not let abandoned swarm profiles accumulate just because they were once useful.

## Profile Map

### default — Orchestrator
Use for:
- Alex-facing Telegram coordination
- Hermes configuration, gateway, cron, profiles, skills, routing
- quick cross-domain triage
- delegating/spawning specialist work
- global app/path/port awareness

When a specialist profile is retained and current, prefer it for long domain ingests, deep creative production, large research compounding, or app-specific coding. In a consolidated one-profile setup, keep the work in `default` but load the smallest relevant class-level skills, use project-local context, and delegate bounded parallel subtasks instead of recreating permanent profiles.

### astro / Astral specialist context
Use `astro` for general astrology readings, transit snapshots, chart search, Human Design, BG5, I Ching, tarot, Astro Engine / HD Prism domain work, and astrology/HD wiki queries or source-grounded ingestion.

For sustained Astral Hermes platform work after the June 2026 cleanup, do **not** route to the historical `astral*` project-swarm profiles unless the user explicitly recreates a new swarm. The old `astralpm`, `astralbackend`, `astralfrontend`, `astralops`, `astralqa`, `astralastro`, and `astralreviewer` profile homes were deleted as stale execution scaffolding. Use the canonical durable profiles instead:
- `astro` — astrology / Human Design / reading-source correctness
- `build` — Astral app implementation, tests, repo changes
- `ops` — PM2/nginx/VPS/runtime/tenant deployment operations
- `default` — orchestration, Telegram-facing coordination, cron/profile management

Historical `astral*` references may still appear in old roadmap docs, Kanban logs, or session transcripts; treat those as historical records, not active routing targets.

Wiki placement:
- Human Design: `~/wiki-human-design` when present
- astrology research/source wiki: `~/astro-sources-wiki` when present
- tenant-private Astral KB: app/runtime controlled, often via `ASTRAL_KB_ROOT`; do not substitute old Obsidian vault scaffolds for tenant KBs

### build
Use for:
- coding, debugging, tests, GitHub PRs/issues, deployments
- app work under `/home/avalon/apps`
- VPS app conventions, PM2/nginx, health checks

Knowledge placement:
- project-specific context belongs in repo `AGENTS.md`, local docs, or app-local skills
- cross-app stable architecture can be summarized into an LLM Wiki page if useful

### creative
Use for:
- Hermes Creative, image generation, video generation, story pipeline, music/audio, comics, infographics
- Venice image/video/audio tasks
- Civitai/SDCPP workflows
- social creative asset drafting

Knowledge placement:
- style systems, brand constraints, and reusable production workflows belong in skills or creative wiki pages
- raw source assets belong in vault/S3, not memory

### research
Use for:
- source-backed research, vendor/API/model/docs investigation, papers, literature review, blog/release monitoring, market/category research, and durable research reports
- LLM Wiki/corpus work: source-backed ingestion, synthesis, provenance repair, and knowledge compounding
- MLOps/model-engineering as a subdomain: HF, vLLM, llama.cpp, GGUF, fine-tuning, evals, GPU/serverless, and model-serving research

Wiki placement:
- primary home for general LLM Wiki workflows
- use `~/wiki` or the relevant vault discovered by SCHEMA/index/log orientation

### ops
Use for:
- email, Google Workspace, Notion, Airtable, Linear, maps, social console operations, smart-home, integrations
- scheduled cron reporting and operational automations

Security:
- credentials should be scoped carefully; do not expose productivity credentials to unrelated profiles.

## LLM Wiki Placement Rule

LLM Wiki is the durable knowledge layer, not a replacement for memory or skills.

- Memory: compact stable facts needed every turn.
- Skills: procedures and workflows.
- LLM Wiki: source-backed knowledge, research syntheses, architecture notes, decisions, domain corpora, and long-running knowledge projects.
- Profiles: scoped runtime homes with selected tools/skills/memory.

Use or update a wiki when:
- the user asks about a wiki, knowledge base, notes, corpus, or source-backed research
- the answer would be painful to re-derive later
- a domain corpus is growing over time
- there are raw sources, PDFs, recordings, transcripts, or web captures to preserve
- a project needs a durable decision/architecture record

Do not write trivial chat facts to the wiki. Propose reviewable writes for personal/tenant memory-like content.

## Routing Procedure

1. Classify the request by domain, side effects, authority, credentials, and required durable context.
2. Decide whether profile isolation is actually needed. Use `default` plus relevant skills for ordinary personal work; use `delegate_task` for bounded context isolation; launch/create a profile only for a verified durable boundary or autonomous workflow.
3. If a retained specialist clearly owns the work, launch it explicitly with a self-contained prompt and bounded output contract. Do not describe this as automatic routing.
4. If the request is cross-domain, default orchestrates. Use the smallest useful fan-out and synthesize once; avoid maintaining dormant profiles solely for occasional fan-out.
5. If source-backed knowledge is involved, orient to the relevant wiki first: `SCHEMA.md`, `index.md`, recent `log.md`, then targeted search.
6. If coding in an app repo, use workdir/project context before global memory.
7. For business/project effects that have moved into a governed product such as Caduceus, prefer that product's gate/source-of-truth skill over legacy sibling-app operator skills; preserve legacy skills only for verified rollback/migration gaps until cutover.
8. After completion, save stable facts to memory, procedures to class-level skills, source-backed syntheses to wiki, and project-specific detail to repo docs or `references/`.

See `references/profile-fanout-content-pipeline.md` for a historical profile-orchestration pattern; do not treat it as evidence that permanent specialists are still warranted.

## Project Swarm Lifecycle

When project-specific profiles such as `astral*`, `salmon*`, or another `<project><role>` swarm appear, treat them as disposable execution infrastructure unless there is an explicit ongoing mandate.

1. Inventory before cleanup: `hermes profile list`, `hermes profile show <name>`, profile sizes, session counts, gateway state, cron references, and router/skill references. Sanitize any `.env`, auth, token, key, password, or connection-string content.
2. Classify each swarm:
   - active: recent work, running jobs, or a project the user is actively pushing
   - paused: worth keeping briefly, but not part of global routing
   - stale: project not active, gateways stopped, no current cron/workflow dependency
3. Preserve durable knowledge outside the swarm before deletion: repo docs, LLM Wiki pages, skills, final handoff summaries, or targeted backups. Avoid carrying huge session stores forward unless the user explicitly wants them.
4. Prefer targeted backups for cleanup under disk pressure: config/SOUL/skills and other small durable files; exclude volatile `sessions`, `logs`, `audio_cache`, `tmp`, and `cache` unless session history is specifically required.
5. Delete stale swarm profiles after user approval, then verify `hermes profile list` and remove or pause matching cron jobs/scripts if they are no longer desired.
6. When asked whether cleanup affected a live deployment pipeline, verify the live service directly rather than reasoning from profile state alone: app health endpoint, PM2/systemd process status, app directory/repo presence, cron references, and search for deleted profile names in active repo/config paths. Historical docs are allowed to mention deleted profiles.
7. Explain profile bloat as profile-home state, not app ownership: large deleted profiles usually accumulated sessions, state databases, logs, caches, skills snapshots, or task artifacts. Do not imply the deployment pipeline lived inside a stale profile unless active scripts/configs prove it.

## Common Pitfalls

- Do not clone every skill/memory into every profile and call it a split; that only duplicates the monolith.
- Do not create one profile per app unless the app has sustained high-volume work.
- Do not keep project swarms indefinitely after the project push ends; archive durable output and clean up stale role profiles.
- Do not tell Alex all durable profiles should be continuously running. In this install, `default` is the always-on Telegram/gateway profile; `astro`, `build`, `creative`, `ops`, and `research` are normally dormant isolated homes unless launched manually, by cron, or as a distinct service. Running all profiles as gateways risks duplicate responses, resource waste, and credential confusion.
- Do not hide critical routing knowledge from default; default must know when specialists exist.
- Do not let LLM Wiki become unreviewed memory spam.
- Do not update raw wiki sources; raw files are immutable.

## Auditing Whether Profiles Are Actually Used

Do not infer real routing from `hermes profile list`, installed skills, profile-home mtimes, or the existence of `hermes-profile-router`. Those prove configuration, not execution. In this architecture, the router is an instructional skill: Telegram enters the always-on `default` profile, and a specialist runs only when `default`, a script, cron, Kanban dispatcher, or operator explicitly launches `hermes --profile <name> ...`. Describe this as **on-demand explicit routing**, not automatic profile switching, unless a deterministic launcher is verified.

Audit usage from execution evidence:

1. Run `hermes profile list` to establish configured profiles and live gateways.
2. Check running processes for persistent specialist gateways or active `hermes --profile ...` workers. A stopped gateway does not mean a profile is unusable; it may be launched per task.
3. Inspect each profile's own `state.db`, grouping `messages` by `session_id` and ordering by the actual maximum `messages.timestamp`. Use session source, message count, and a sanitized first user prompt to distinguish smoke probes (`Reply with exactly: ok`) from substantive work.
4. Treat profile-home and `agent.log` mtimes cautiously: commands such as `hermes --profile <name> tools list` can initialize a profile and touch logs without creating a real agent session. Prefer state-database timestamps and message records.
5. Search the default profile's message/tool history and scripts for explicit launches such as `hermes --profile research chat -q ...`. Correlate the invocation with a new session in the specialist's state database.
6. Inspect cron jobs, Kanban dispatchers, watchdog scripts, and service definitions for deterministic profile launches. Note whether those jobs are active or paused now; historical success does not imply current automation.
7. Report separately:
   - configured and available;
   - substantively used recently;
   - used only for smoke tests;
   - currently running;
   - deterministically routed by automation;
   - optionally routed by agent judgment.
8. When evaluating routing quality, look for domain requests handled entirely by `default` despite an appropriate specialist. One successful fan-out proves the mechanism works, not that routing is consistent.

For a compact SQLite inspection recipe and interpretation notes, see `references/profile-usage-audit.md`.

## Verification Checklist

- [ ] Request routed to the smallest sufficient profile.
- [ ] Relevant wiki was oriented before query/ingest.
- [ ] App-specific facts stayed in project context where possible.
- [ ] Memory updates are stable and compact.
- [ ] New reusable procedures became skills, not memory.
- [ ] Claims that routing is active are backed by specialist session records or explicit launcher evidence, not configuration alone.