Loremaster Setup

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_approval tool if installed), then apply. This is the pack's approval-gate philosophy — the setup skill is not exempt.

• Never echo secrets. No tokens, no .env contents, no key files in chat — check

existence with grep -q/test -f only.

• 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 [--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](references/vault-skeleton.md), get approval, then:

```bash
VAULT=~/vaults/    # 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 /-lore-vault --private --source "$VAULT" --push
# or wire an existing remote:
git remote add origin  && 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.

1. 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.

1. Build the prompt block from

[references/channel-prompt-template.md](references/channel-prompt-template.md), filling in the channel ID, project name, and the vault's absolute path.

1. Propose it: show the full block plus the exact insertion plan (append under

slack.channel_prompts; if slack.allowed_channels exists, 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.

1. After approval — backup first, then edit surgically:

``bash CFG="$(hermes config path)" cp "$CFG" "$CFG.bak.$(date +%Y%m%d-%H%M%S)" ` Apply the approved block, then validate: `bash 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 fi ` YAML-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.

1. 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_URL and JIRA_EMAIL and fill them in.
• The API token must never pass through chat. Ask the user to edit

~/.hermes/keys/jira.env themselves on the host and set JIRA_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.tsv with one line per vault:

`` (propose the exact line, then write).

• Verify without exposing anything:

``bash set -a; . ~/.hermes/keys/jira.env; set +a curl -fsS -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_BASE_URL/rest/api/3/myself" \ -o /dev/null -w '%{http_code}\n' # expect: 200 ` 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):

• Shell profile (interactive/CLI runs): export TEAM_TZ="Area/City" in ~/.bashrc

or ~/.zshrc.

• Gateway service environment (gateway-spawned sessions): systemd —

systemctl edit hermes-gateway, add [Service] / Environment=TEAM_TZ=Area/City, then systemctl daemon-reload and hermes gateway restart; launchd — add it to EnvironmentVariables in 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:

1. Clone the vault repo, then Obsidian → Open folder as vault.
2. 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.

1. The graph view is the payoff: wiki/concepts/*.md carry frontmatter related

[[wikilinks]] derived from the graphify graph — Obsidian visualizes the team's lore (clusters, hubs, how a decision ripples). Never hand-edit related or [[ ]]; the next derivation overwrites them. To change a link, change raw/ and re-refine.

1. .obsidian/ must stay gitignored in the vault (editor state is per-person) — the

skeleton's .gitignore already covers it; verify on existing repos.

Step 9 — Smoke test

Run the whole pipeline once, end to end, in the vault.

1. 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](references/sample-prd.md) to raw/PRD.md (two related features, so the graph gets an edge) and commit it.

1. Run one refinement pass by following the refine-wiki skill exactly (plan →

inline semantic extraction → build → wikilink derivation → commit → push approval).

1. Verify the artifacts:

``bash ls wiki/index.md graphify-out/graph.json && ls wiki/concepts/ # expect: index + graph.json exist, and one concept page per PRD concept ` graphify-out/graph.json` should 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).

1. Ask-and-answer one question by following the wiki-qa skill (graphify query →

read only the pointed-to pages → answer with sources cited), e.g. "what does the PRD say about sharing?" A cited, evidence-only answer = the project is live.

1. 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.

1. Ask for the product repo path (the code repo, not the vault). Skip if the team does

not use local coding agents.

1. Fetch client-template/.claude/ from this repo (same raw.githubusercontent.com base

as Step 3, files under client-template/.claude/skills//SKILL.md for backlog-kickoff, backlog-complete, backlog-recall, project-onboard) into /.claude/skills/. If .claude/skills/ already exists there, show what would be added and never overwrite existing skills without approval.

1. Propose the commit (show git status), get approval, commit with message

"Add Loremaster developer-side skills" and push.

1. Tell the team: everyone gets the skills on their next git pull — `backlog-kickoff

to start an issue, backlog-complete ` 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: loremaster-ai
• Source: loremaster-ai/loremaster
• License: MIT

Install and usage instructions live in the source repository linked above.