# Loremaster Setup

> >

- **Type:** Skill
- **Install:** `agentstack add skill-loremaster-ai-loremaster-loremaster-setup`
- **Verified:** Pending review
- **Seller:** [loremaster-ai](https://agentstack.voostack.com/s/loremaster-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [loremaster-ai](https://github.com/loremaster-ai)
- **Source:** https://github.com/loremaster-ai/loremaster/tree/main/skills/loremaster-setup

## Install

```sh
agentstack add skill-loremaster-ai-loremaster-loremaster-setup
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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  [--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):

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

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

- **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](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//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.
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
   ` 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](https://github.com/loremaster-ai)
- **Source:** [loremaster-ai/loremaster](https://github.com/loremaster-ai/loremaster)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-loremaster-ai-loremaster-loremaster-setup
- Seller: https://agentstack.voostack.com/s/loremaster-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.