loremaster-ai/loremaster / skills/loremaster-setup
loremaster-setup
UnverifiedGuided, interactive onboarding that takes a Hermes Agent user from "tap added" to "first project live" — run it on first install of the Loremaster pack, when adding a new project (new channel + new lore vault), or when reconfiguring an existing setup (scripts, Jira, timezone, Obsidian).
Loremaster setup — from "tap added" to "first project live"
Interactive onboarding. You (the agent) drive it; the human decides.
Conduct (invariant)
- One step at a time. Run a step, show the result, confirm it passed, then move on. Never batch steps, never skip a verification.
- Detect, don't decide. Detect current state and report it; every choice (vault path, channel, timezone, skip/do) belongs to the human.
- Every write is proposed first. Show the exact file/diff/command, get an explicit
approval in chat (or via the
request_approvaltool if installed), then apply. This is the pack's approval-gate philosophy — the setup skill is not exempt. - Never echo secrets. No tokens, no
.envcontents, no key files in chat — check existence withgrep -q/test -fonly. - Re-runnable. Every step starts by detecting what is already done and skips it. Steps 6 (Jira), 8 (Obsidian), and 10 (developer-side skills) are optional; offer to skip.
Step 1 — Preflight
Run each check, report a pass/fail table, and fix failures before continuing.
hermes --version # expect: Hermes Agent v0.17.0 or later
hermes gateway status # expect: active (running) — or the user runs it in foreground
git --version # expect: any modern git
graphify --version # expect: graphify 0.8.44
- hermes < v0.17 → stop; ask the user to upgrade (
hermes update) first. - Gateway not running →
hermes gateway start(installed service) orhermes gateway run(foreground). If neither is set up, point tohermes gateway setup. - Chat platform: ask which platform the gateway is connected to. Slack is recommended —
the channel = project binding (Step 5) is Slack-first in this pack version. Confirm the
wiring without touching any secrets:
hermes gateway statusreports the connected platform (expect a connected Slack line). If nothing is connected, walk the user throughhermes gateway setup. - GitHub push auth (the vault pushes need it):
On failure:gh auth status # expect: Logged in to github.com # or, for SSH remotes: ssh -T git@github.com # expect: "successfully authenticated"gh auth login, or add an SSH key / deploy key. Re-verify before Step 4. - graphify missing or wrong version → propose (then run after approval):
The version pin matters — the helper scripts (Step 3) are tested against this exact release; do not install an unpinned latest. Ifuv tool install 'graphifyy==0.8.44'uvis missing, install it first per the official guide at https://docs.astral.sh/uv/getting-started/installation/ (download the installer, let the user review it, then run) — with approval.
Step 2 — Install the remaining skills
Check what is already there, then install only what is missing:
hermes skills tap list # expect: loremaster-ai/loremaster listed
hermes skills tap add loremaster-ai/loremaster # only if missing
hermes skills list --source hub # note which loremaster skills are installed
Install the missing ones (all pack skills except this one):
for s in backlog-proposal backlog-update conflict-detection daily-scrum impact-analysis \
meeting-agenda refine-wiki resolve-conflicts sprint-planning sprint-retro wiki-qa; do
hermes skills install "loremaster-ai/loremaster/skills/$s" --yes
done
- Expected per skill: quarantine → security scan → install at trust level community. The third-party risk prompt is normal — tell the user to expect it.
- GitHub API rate limit errors → set
GITHUB_TOKENorgh auth login, retry. - The first search/browse after
tap addcan come back empty while the hub index warms up — just run it again. - Verify:
hermes skills list --source hubnow shows every pack skill enabled (the 11 above plus this one).
Optional (Slack only, recommended): the approval-buttons plugin that provides the
request_approval tool the skills call before every external write:
hermes plugins install loremaster-ai/loremaster/plugins/loremaster-approval --enable
hermes gateway restart
Note: tested against Hermes Agent v0.17.0 (it imports private internals); if it breaks
after a Hermes upgrade, pin the hermes version. Update later with install --force.
Step 3 — Fetch the helper scripts
The four deterministic helpers are not delivered by skill install (they live at the
repo root scripts/). Fetch them to ~/.hermes/scripts/:
mkdir -p ~/.hermes/scripts
for f in loremaster-graphify-plan.py loremaster-graphify-build.py \
loremaster-derive-wikilinks.py loremaster-poker.py; do
if [ -e ~/.hermes/scripts/"$f" ]; then
echo "exists, skipping: $f" # re-run safe — never overwrite silently
continue
fi
curl -fsSL "https://raw.githubusercontent.com/loremaster-ai/loremaster/main/scripts/$f" \
-o ~/.hermes/scripts/"$f"
done
Verify they are runnable (a usage error is the expected output):
python3 ~/.hermes/scripts/loremaster-graphify-plan.py
# expect: "usage: loremaster-graphify-plan.py <concepts_dir> [--force]"
On curl failure (DNS/proxy/404): report the exact error; do not substitute guessed
alternatives. The loop skips files that already exist; to refresh one, show ls -l,
ask, and delete it before re-running the loop.
Step 4 — Create or wire the lore vault
Ask: new vault, or wire an existing repo? Either way the vault is a git repo shaped:
raw/ # truth — humans write here (PRD.md, decisions/, gtm/, planning/)
wiki/ # derived — machine-written (concepts/*.md + index.md); never hand-edited
conflicts/ # open conflict / underspecified-decision reports
graphify-out/ # graph build products (appear after the first refine)
raw is truth, wiki is derived — one-way: raw/ → wiki/ → knowledge graph →
[[wikilinks]]. Humans never edit the derived layers.
New vault — propose the full file set from references/vault-skeleton.md, get approval, then:
VAULT=~/vaults/<project-name> # basename = project name (Jira mapping in Step 6 keys on it)
mkdir -p "$VAULT"/{raw/decisions,raw/gtm,raw/planning,wiki/concepts,conflicts}
cd "$VAULT" && git init -b main
# write README.md, .gitignore, raw/PRD.md, wiki/index.md per the skeleton, then:
touch "$VAULT"/{raw/decisions,raw/gtm,raw/planning,wiki/concepts,conflicts}/.gitkeep
git add -A && git commit -m "Initialize lore vault skeleton"
Existing repo — verify it has raw/ (or propose moving source docs under raw/),
add the missing skeleton pieces (wiki/, conflicts/, .gitignore entries) with approval.
Remote + push check (auth from Step 1 must hold):
gh repo create <owner>/<project-name>-lore-vault --private --source "$VAULT" --push
# or wire an existing remote:
git remote add origin <url> && git push -u origin main
git push --dry-run origin main && echo push-auth-ok # dry-run proves WRITE access
On auth failure, report it as-is (no workarounds) — fix auth, re-verify, then continue.
Step 5 — Bind channel = project (channel prompt, human-approved)
Slack only; on other platforms skip and note that the vault path must then be given per conversation. This is the pack's isolation invariant: channel = project = vault.
- Ask for the project's Slack channel ID (channel name → right-click → copy link → the
trailing
C0…segment). The agent must already be invited to that channel. - Build the prompt block from references/channel-prompt-template.md, filling in the channel ID, project name, and the vault's absolute path.
- Propose it: show the full block plus the exact insertion plan (append under
slack.channel_prompts; ifslack.allowed_channelsexists, append the channel ID comma-separated). Do not touch any other key. Do not quote other channels' prompts back into chat. Wait for explicit approval — this edits the live agent config. - After approval — backup first, then edit surgically:
Apply the approved block, then validate:CFG="$(hermes config path)" cp "$CFG" "$CFG.bak.$(date +%Y%m%d-%H%M%S)"if python3 -c 'import yaml' 2>/dev/null; then python3 -c "import yaml; yaml.safe_load(open('$CFG'))" && echo YAML-OK || echo YAML-BROKEN else echo NO-PYYAML # no validator on this host — the gateway restart below is the check fiYAML-BROKEN→ restore the backup, report, stop.NO-PYYAML→ proceed, but if the gateway restart in the next step fails to come back up, restore the backup and report. - Tell the user to run
hermes gateway restart, then verify by mentioning the agent in the channel — it should answer as that project's SM/PM and name the vault path.
If DENIED: keep the backup unused, change nothing, and continue to the next step.
Step 6 — Jira (optional — offer to skip)
Ask whether the team uses Jira. If yes:
mkdir -p ~/.hermes/keys
curl -fsSL https://raw.githubusercontent.com/loremaster-ai/loremaster/main/examples/jira.env.example \
-o ~/.hermes/keys/jira.env
curl -fsSL https://raw.githubusercontent.com/loremaster-ai/loremaster/main/examples/jira-projects.tsv.example \
-o ~/.hermes/keys/jira-projects.tsv
chmod 600 ~/.hermes/keys/jira.env ~/.hermes/keys/jira-projects.tsv
- Ask in chat for
JIRA_BASE_URLandJIRA_EMAILand fill them in. - The API token must never pass through chat. Ask the user to edit
~/.hermes/keys/jira.envthemselves on the host and setJIRA_API_TOKEN=(least-scope token — ideally an account that sees only the managed projects), then say "done". Never read the token back, never echo it. - Replace the example rows in
jira-projects.tsvwith one line per vault:<vault-basename><TAB><JIRA_KEY>(propose the exact line, then write). - Verify without exposing anything: load the credentials
(
set -a; . ~/.hermes/keys/jira.env; set +a), then callGET {JIRA_BASE_URL}/rest/api/3/myselfwith HTTP Basic auth (Jira email + API token) via Python urllib, written at run time. Report only the HTTP status code — expect200. The token never goes on a command line, and the response body is never printed.401/403→ token or scope wrong; ask the user to re-issue and retry. Never print the response body.
Step 7 — TEAM_TZ (team timezone)
Skills date-stamp every artifact with TZ="$TEAM_TZ" so filenames and dates match the
team's wall clock, not the host's (often UTC).
timedatectl show -p Timezone --value # linux; macOS: readlink /etc/localtime
Show the detected host timezone and ask the user to confirm the team's IANA timezone
(they may differ — e.g. a cloud host on UTC, a team on America/New_York or
Asia/Tokyo). Then tell the user where to set it (propose the exact lines; append only
with approval):
- Current session (interactive/CLI runs):
export TEAM_TZ="Area/City". If the user wants it permanent, they add that line to their own shell profile themselves — propose the line, don't edit their profile. - Gateway service environment (gateway-spawned sessions): systemd —
systemctl edit hermes-gateway, add[Service]/Environment=TEAM_TZ=Area/City, thensystemctl daemon-reloadandhermes gateway restart; launchd — add it toEnvironmentVariablesin the service plist.
Verify: TZ="$TEAM_TZ" date +%F prints today's date in the team's timezone.
Step 8 — Obsidian (recommended — offer to skip)
The vault is plain markdown, so each teammate can browse it as an Obsidian vault — on their own machine, not the agent host:
- Clone the vault repo, then Obsidian → Open folder as vault.
- Install the community Obsidian Git plugin. Configure pull-only: auto pull on a
short interval (e.g. 2 minutes), auto commit-and-push off — the agent host is the
single writer of the derived layers, and auto-push from teammate machines races it and
leaks half-finished state. Humans edit
raw/only and commit-and-sync manually when they do. - The graph view is the payoff:
wiki/concepts/*.mdcarry frontmatterrelated[[wikilinks]]derived from the graphify graph — Obsidian visualizes the team's lore (clusters, hubs, how a decision ripples). Never hand-editrelatedor[[ ]]; the next derivation overwrites them. To change a link, changeraw/and re-refine. .obsidian/must stay gitignored in the vault (editor state is per-person) — the skeleton's.gitignorealready covers it; verify on existing repos.
Step 9 — Smoke test
Run the whole pipeline once, end to end, in the vault.
- If the user already has a real PRD, use it as
raw/PRD.md. Otherwise propose writing the tiny sample from references/sample-prd.md toraw/PRD.md(two related features, so the graph gets an edge) and commit it. - Run one refinement pass by following the
refine-wikiskill exactly (plan → inline semantic extraction → build → wikilink derivation → commit → push approval). - Verify the artifacts:
ls wiki/index.md graphify-out/graph.json && ls wiki/concepts/ # expect: index + graph.json exist, and one concept page per PRD conceptgraphify-out/graph.jsonshould contain nodes for each concept and at least one edge. Missing graph → re-check Step 1 (graphify 0.8.44) and Step 3 (scripts); empty wiki → re-read refine-wiki's preconditions (e.g. an open conflict holds refinement). - Ask-and-answer one question by following the
wiki-qaskill (graphify query → read only the pointed-to pages → answer withsourcescited), e.g. "what does the PRD say about sharing?" A cited, evidence-only answer = the project is live. - If the sample PRD was used: remind the user to replace it with the real one and re-run refine-wiki — deleted concepts drop out of the graph automatically.
Step 10 — Developer-side skills (optional — offer to skip)
The last mile of an issue happens in each developer's local coding agent (Claude Code,
Cursor, or any agentskills.io client). This repo ships those skills in client-template/
— they install by being committed into the product repo, not per developer.
- Ask for the product repo path (the code repo, not the vault). Skip if the team does not use local coding agents.
- Fetch
client-template/.claude/from this repo (same raw.githubusercontent.com base as Step 3, files underclient-template/.claude/skills/<name>/SKILL.mdfor backlog-kickoff, backlog-complete, backlog-recall, project-onboard) into<product-repo>/.claude/skills/. If.claude/skills/already exists there, show what would be added and never overwrite existing skills without approval. - Propose the commit (show
git status), get approval, commit with message "Add Loremaster developer-side skills" and push. - Tell the team: everyone gets the skills on their next
git pull—backlog-kickoff <issue>to start an issue,backlog-complete <issue>to finish (pre-push conflict check → commit/push → Jira transition).
Wrap-up
Report a final checklist: hermes/graphify versions, skills installed, scripts fetched, vault path + remote, channel bound (or skipped), Jira (or skipped), TEAM_TZ, Obsidian notes, developer-side skills (or skipped), smoke test result. List anything skipped so the user can re-run this skill later — it detects done steps and picks up where it left off.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |