Skip to content

loremaster-ai/loremaster / skills/loremaster-setup

loremaster-setup

Verified

Guided, 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).

FileKindSize
SKILL.mdskill md16.0 KB
references/channel-prompt-template.mdmarkdown1.8 KB
references/sample-prd.mdmarkdown710 B
references/vault-skeleton.mdmarkdown2.2 KB
---
name: loremaster-setup
description: >
  Guided, 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).
version: 0.2.0
author: Loremaster
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [setup, onboarding, install, vault, config, scrum, PM]
    related_skills: [refine-wiki, wiki-qa]
---

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

```bash
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) or `hermes gateway run`
  (foreground). If neither is set up, point to `hermes 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 status` reports the connected
  platform (expect a connected Slack line). If nothing is connected, walk the user through
  `hermes gateway setup`.
- **GitHub push auth** (the vault pushes need it):
  ```bash
  gh auth status            # expect: Logged in to github.com
  # or, for SSH remotes:
  ssh -T git@github.com     # expect: "successfully authenticated"
  ```
  On failure: `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):
  ```bash
  uv tool install 'graphifyy==0.8.44'
  ```
  The version pin matters — the helper scripts (Step 3) are tested against this exact
  release; do not install an unpinned latest. If `uv` is 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:

```bash
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):

```bash
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_TOKEN` or `gh auth login`, retry.
- The **first** search/browse after `tap add` can come back empty while the hub index
  warms up — just run it again.
- Verify: `hermes skills list --source hub` now 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:

```bash
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/`:

```bash
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):

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

```bash
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):

```bash
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**.

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.
2. 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.
3. **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.
4. 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.
5. 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:

```bash
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:
  `<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 call
  `GET {JIRA_BASE_URL}/rest/api/3/myself` with HTTP Basic auth (Jira email + API token)
  via Python urllib, written at run time. Report **only the HTTP status code** — expect
  `200`. 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).

```bash
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`,
  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](https://obsidian.md) 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.
3. 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.
4. `.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.
2. Run one refinement pass **by following the `refine-wiki` skill exactly** (plan →
   inline semantic extraction → build → wikilink derivation → commit → push approval).
3. 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).
4. 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.
5. 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.
2. Fetch `client-template/.claude/` from this repo (same raw.githubusercontent.com base
   as Step 3, files under `client-template/.claude/skills/<name>/SKILL.md` for
   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.
3. Propose the commit (show `git status`), get approval, commit with message
   "Add Loremaster developer-side skills" and push.
4. 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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall