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

---
name: init
description: >
  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.
disable-model-invocation: true
allowed-tools: 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.

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

```markdown
---
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>
- **Verification commands**: <detected commands, 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>
```

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

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

```markdown
---
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
  <domain-slug>/
    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-<topic>.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:

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

```markdown
---
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**, skip this phase entirely.

---

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

```markdown
---
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."