reliquary/plugins/spire/skills/init/SKILL.md

name, description, disable-model-invocation, allowed-tools

name	description	disable-model-invocation	allowed-tools
init	Initialize Spire for the current project — detect project facts, scaffold .claude/spire/project.md, create adept templates, and handle shared vs. personal install. Human-triggered.	true	Bash(cat:*), Bash(grep:*), Bash(ls:*), Bash(just:*), Bash(git:*), Read, Write, Glob, Grep

Spire — Init

Initialize Spire for the current project. Run this once after installing the Spire plugin, or again after major structural changes. Re-init is safe — it will not clobber hand-edited files.

Seven phases: detect install type, detect project facts, scaffold project.md, scaffold adept templates, gitignore (if personal), optional alias, and commit (if shared).

---

Phase 1 — Detect install type

Determine whether Spire is a shared (project-level) or personal (user-level) install. This governs whether scaffolded files get committed or gitignored.

1. Read .claude/settings.json (if it exists). Search for any string containing spire in the plugins or mcpServers keys — typically "spire@reliquary" or a path containing /spire/.
2. Read .claude/settings.local.json (if it exists). Same search.
3. Classify:

Spire found in	Install type	Action
settings.json	Shared	Files will be committed
settings.local.json only	Personal	Files will be gitignored
Neither file	Ambiguous	Ask the user: "Should the Spire config be shared with the project (committed) or personal (gitignored)?"

Store the result as $INSTALL_TYPE (shared or personal) for later phases.

---

Phase 2 — Detect project facts

Auto-detect as much as possible. Each fact that cannot be detected becomes a placeholder in the scaffolded project.md.

2.1 — Workpad location

Resolve the workpad using the spire:workpad resolution chain (environment variable, just workpad-folder, docs/workpad/, .workpad/). Record the path as $WORKPAD.

2.2 — Pinned agents

List .claude/agents/*.md. For each file, read its frontmatter to extract name and description. These become the "Pinned agents" list.

2.3 — Verification commands

Check these files in order for verification commands:

• Justfile: Look for recipes named check, test, lint, build, verify, ci, or similar. Run just --list if available.
• Makefile: Look for targets named check, test, lint, build.
• package.json: Read scripts for test, lint, build, check.
• Cargo.toml: If present, cargo check, cargo test, cargo clippy are likely verification commands.

Sort what you find into gate (cheap, run between blocks: check, lint, typecheck, clippy) and tests (the test suite, run once per phase).

2.4 — Conventions

Read the root CLAUDE.md for project conventions — commit message style, branching strategy, review process, language/framework preferences. Summarize relevant conventions concisely.

2.5 — Tome presence

Check whether the tome plugin is installed:

• Search .claude/settings.json and .claude/settings.local.json for tome references.
• Check for a *-tome:navigate skill or tome@reliquary plugin reference.
• If found, note the tome skill name for the project.md template.

---

Phase 3 — Scaffold project.md

Write .claude/spire/project.md using the detected facts.

3.1 — Re-init safety check

If .claude/spire/project.md already exists:

• Read its YAML frontmatter.
• If status: authored — stop. Tell the user: "project.md has been manually edited (status: authored). Skipping to avoid clobbering your changes. Delete or change status to generated to allow re-scaffolding."
• If status: generated — proceed, overwriting the file.
• If no status field — treat as authored, do not overwrite.

3.2 — Write the file

Create .claude/spire/ directory if needed. Write project.md with this structure:

---
status: generated
generated: <YYYY-MM-DD>
---
# Project Knowledge (per-project — swap this file when adopting Igor)

Project-specific facts for Igor and the athanor. The generic behavior files
stay unchanged across projects; only this file (and any tome/navigation skill
preload) changes.

## This project

- **Tome skill**: <detected tome skill or "none detected — Igor will orient via direct file reads">
- **Workpad**: <detected workpad path with subfolder structure>
- **Adepts**: Domain knowledge agents with persistent folders at `<workpad>/adepts/<domain-slug>/`.
- **Pinned agents** (prefer these over generic tiers):
  <list of detected agents with name and description, or placeholder comment>
- **Domain skills to route to subagents when relevant**: <!-- detect and list, or leave as placeholder -->
- **Conventions**: <summarized conventions from CLAUDE.md, or placeholder comment>

## Build

Read by `spire:implementation`. Unset means the skill's default; `none` means deliberately absent.

- **Gate** (cheap, between blocks): <detected gate commands, or placeholder comment>
- **Tests** (once per phase): <detected test command, or placeholder comment>
- **Checkout**: <!-- one checkout (default) | worktrees -->
- **Branches**: <!-- who commits where; default: the branch the brief names -->
- **Staging**: <!-- explicit paths (default) -->
- **Owner models**: <!-- per block kind; default: Opus 5.5 for complex blocks, Sonnet for mechanical ones -->
- **Brief constraints**: <!-- sensitive areas, e.g. generated files, migrations -->
- **Host rules**: <!-- temp dirs, memory caps -->
- **Build plan**: <!-- user sees it before the run (default) | skip -->

Personal overrides go in `.claude/spire/project.local.md` (gitignored, same headings). They win over this file.

Fill every field that was detected; leave a <!-- placeholder --> comment for fields that were not.

---

Phase 4 — Scaffold adept templates

Create the adept directory structure in the workpad. These files are referenced by the adept agent during genesis (see agents/adept.md).

4.1 — Create the adepts directory

mkdir -p "${WORKPAD}/adepts/_template"

4.2 — Write adepts/CLAUDE.md

If ${WORKPAD}/adepts/CLAUDE.md already exists and contains status: authored in its frontmatter, skip it. Otherwise write:

---
status: generated
---
# Adepts

This directory holds domain knowledge accumulated by adept agents. Each
subfolder is one domain — a subsystem, a library, a cross-cutting concern —
named with a short kebab-case slug.

## Structure

adepts/ CLAUDE.md ← you are here _template/ ← starter template; copied on founding CLAUDE.md handoff.md / CLAUDE.md ← INDEX — frontmatter + tiered reading list. Short. Auto-loaded. handoff.md ← rolling state for the successor. Overwritten, not appended. key-files.md ← solid knowledge docs — as many as the domain needs conventions.md architecture.md gotchas.md ... ← any other doc, provided it is listed in CLAUDE.md journal/ YYYY-MM-DD-HH-genesis.md YYYY-MM-DD-HH-.md

## Conventions

- **One domain per folder.** Overlap → pick the stricter scope. Broad names are gravity wells.
- **CLAUDE.md is an index, not a document.** Frontmatter + tiered reading list + open questions. Under ~60 lines. It is auto-loaded whenever anything in the folder is read — keep it cheap.
- **Every file in the domain root is listed in CLAUDE.md.** Unlisted files do not exist.
- **handoff.md is overwritten, never appended.** Write it early, refresh it after anything significant. `verified-at` is the commit the solid docs were last checked against.
- **journal/ is append-only.** One file per topic or session, `YYYY-MM-DD-HH-<topic>.md`. Recency and session counts are derived from these names — keep the prefix exact.
- **Solid knowledge goes in docs; experiences go in the journal.** Branch observations stay in the journal (and handoff.md's "In flight") until the code is on main.
- **Don't hoard.** Findings that belong in the project's docs or a workpad report go there; link from here.
- **Metadata is derived.** Never hand-maintain counts, dates, or an index file. Declare `domain`, `summary`, `covers`, `related`, `status` once in frontmatter; the roster does the rest.

4.3 — Write adepts/_template/CLAUDE.md

If ${WORKPAD}/adepts/_template/CLAUDE.md already exists and contains status: authored, skip it. Otherwise write:

---
status: generated
domain: <Domain Name>
summary: <One-line summary of what this domain covers.>
covers:
  - <path/to/main/source/>
  - <path/to/tests/>
related: []
status: active
---
# <Domain Name>

<!-- Replace this heading and fill the frontmatter during genesis orientation.
     This file is the index — keep it under ~60 lines. It is auto-loaded by
     the harness whenever any file in this folder is read. -->

<!-- One paragraph: scope, boundaries, what is and is not this domain. -->

## Must-read

Every genesis, before answering anything. Keep this list to three or four entries.

- `handoff.md` — where the previous adept left things. Always first.
- `key-files.md` — the files that matter, what each does, where the seams are.
<!-- - `conventions.md` — rules here that differ from the project-wide ones. -->

## Good-to-read-if

<!-- State the condition for each entry. -->

<!-- - `architecture.md` — if asked how the pieces fit, or where a new thing should go. -->
<!-- - `gotchas.md` — if asked why something behaves oddly. -->
- `journal/` — if `handoff.md` points at a specific entry, or a question touches a dead end noted there. Do not read the whole journal.

## Open questions

Carried forward by predecessors. Try to resolve one before adding one.

<!-- - "Why does FooService bypass the standard auth middleware?" (since YYYY-MM-DD) -->

4.4 — Write adepts/_template/handoff.md

If ${WORKPAD}/adepts/_template/handoff.md already exists and contains status: authored, skip it. Otherwise write:

---
status: generated
updated: <YYYY-MM-DD-HH>
session: <path to current session journal entry>
branch: <current branch or worktree>
verified-at: <commit SHA when solid docs were last checked against code>
---
# Handoff — <Domain Name>

## State
<!-- Where things stand. What is documented and verified, what is not. -->

## In flight (experiences, not solid)
<!-- Branch observations, unmerged work. These stay here until the code is on main. -->

## Open threads
<!-- Unfinished investigations, pending questions, next steps. -->

## Successor: read first
1. This file.
2. `key-files.md` — most likely to have drifted.
<!-- 3. `journal/<entry>.md` if a specific branch is still open. -->

## Drift check
    git log --oneline <verified-at>..HEAD -- '<path1>' '<path2>'

---

Phase 5 — Gitignore (personal install only)

If $INSTALL_TYPE is personal:

1. Read .claude/.gitignore (create it if it does not exist).
2. Check whether it already contains a line matching spire/.
3. If not present, append spire/ on its own line.

If $INSTALL_TYPE is shared, append spire/project.local.md to .claude/.gitignore instead (if not already present), so personal overrides stay out of the repo.

---

Phase 6 — Optional alias

Offer the user an optional convenience alias:

"Would you like to create /assistant as an alias for /spire:igor? This creates .claude/skills/assistant/SKILL.md so you can invoke Igor as just /assistant."

If the user accepts:

1. Create .claude/skills/assistant/ directory if needed.
2. Write .claude/skills/assistant/SKILL.md:

---
name: assistant
description: Start an Igor session — alias for spire:igor.
user-invocable: true
---

Invoke the `spire:igor` skill. Pass through any arguments:

/spire:igor $ARGUMENTS

If the user declines or doesn't respond, skip.

---

Phase 7 — Commit (shared install only)

If $INSTALL_TYPE is shared:

1. Stage all files created or modified by this init run:
   • .claude/spire/project.md
   • ${WORKPAD}/adepts/CLAUDE.md
   • ${WORKPAD}/adepts/_template/CLAUDE.md
   • ${WORKPAD}/adepts/_template/handoff.md
   • .claude/skills/assistant/SKILL.md (if created in Phase 6)
2. Commit with message: 🤖 Initialize Spire project config

If $INSTALL_TYPE is personal, do not commit — the files are gitignored.

---

Summary

After all phases, report to the user:

• Install type detected (shared / personal)
• What was scaffolded (list files created or updated)
• What was skipped (files with status: authored, phases that didn't apply)
• Next steps: "Edit .claude/spire/project.md to fill in any remaining placeholders, then change status from generated to authored to lock it against future re-inits. Personal settings go in .claude/spire/project.local.md."