reliquary/docs/workpad/plans/2026-09-17-spire-project-override-init.md

# Plan: Spire project override + spire:init

**Design**: `designs/spire-project-override-and-init.md`
**Date**: 2026-09-17

---

## Commit 1 — `✨ Add spire:project skill and update template hint`

### Task 1.1 — Create `spire:project` skill

**Create** `plugins/spire/skills/project/SKILL.md`

```markdown
---
name: project
description: Loads per-project Spire configuration (override or bundled template).
allowed-tools: Bash(cat:*)
---

!`cat "${CLAUDE_PROJECT_DIR}/.claude/spire/project.md" 2>/dev/null || cat "${CLAUDE_SKILL_DIR}/../igor/references/project.md"`

<!-- If the above block is the blank template, run /spire:init to configure this project. -->
```

**Verify**: Directory `plugins/spire/skills/project/` exists and `SKILL.md` parses as valid skill frontmatter.

### Task 1.2 — Add init hint to bundled template

**Modify** `plugins/spire/skills/igor/references/project.md`

Add at the very top (before the `# Project Knowledge` heading):

```markdown
<!-- This is the blank template. Run /spire:init to generate a project-specific override. -->
```

**Verify**: The hint appears at line 1; existing template content is unchanged below it.

---

## Commit 2 — `🤖 Wire agents to use spire:project`

### Task 2.1 — Update Igor skill to drop `@` import

**Modify** `plugins/spire/skills/igor/SKILL.md` (line 32)

Remove:
```
@references/project.md
```

Replace with:
```
Project-specific knowledge is loaded by the `spire:project` skill at agent startup. If it loaded the blank template (the hint says "run /spire:init"), try reading `.claude/spire/project.md` directly before orienting from scratch.
```

**Verify**: No `@references/project.md` line remains in the file. The replacement text is present near the same location (after the "swappable per-project reference" sentence on line 30).

### Task 2.2 — Add `spire:project` to Igor agent

**Modify** `plugins/spire/agents/igor.md`

Add `spire:project` to the `skills:` list in frontmatter (before `spire:igor`):

```yaml
skills:
  - spire:project
  - spire:igor
  - spire:workpad
```

**Verify**: `spire:project` appears in the skills list. Agent body is untouched.

### Task 2.3 — Rewire Athanor agent

**Modify** `plugins/spire/agents/athanor.md`

1. Add `spire:project` to the `skills:` list in frontmatter (first entry):
   ```yaml
   skills:
     - spire:project
     - spire:workpad
     - spire:implementation
     - superpowers:using-superpowers
     - superpowers:subagent-driven-development
     - superpowers:dispatching-parallel-agents
   ```
2. In the body (line 25), remove:
   ```
   @skills/igor/references/project.md
   ```
   Replace with:
   ```
   Project-specific knowledge is loaded by the `spire:project` skill at agent startup.
   ```

**Verify**: No `@skills/igor/references/project.md` line remains. `spire:project` is in the skills list. The paragraph around line 23 still reads coherently.

---

## Commit 3 — `✨ Add spire:init skill with adept scaffolding`

### Task 3.1 — Create `spire:init` skill

**Create** `plugins/spire/skills/init/SKILL.md`

Frontmatter:
```yaml
---
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
---
```

Body must implement these phases (model the structure on `plugins/tome/skills/init/SKILL.md`):

**Phase 1 — Detect install type**: Read `.claude/settings.json` and `.claude/settings.local.json`. If `spire@reliquary` (or any spire plugin ref) appears in `settings.json` then shared; if in `settings.local.json` or absent from both then personal/ask the user.

**Phase 2 — Detect project facts**: Auto-detect workpad location (via `spire:workpad` resolution), pinned agents from `.claude/agents/*.md`, verification commands from `Justfile`/`Makefile`/`package.json`/`Cargo.toml`, conventions from root `CLAUDE.md`, and tome skill presence.

**Phase 3 — Scaffold `project.md`**: Write `.claude/spire/project.md` using the bundled template structure from `plugins/spire/skills/igor/references/project.md` but filled with detected values. Add `status: generated` in YAML frontmatter. Re-init safe: only overwrite if existing file has `status: generated`, never clobber `status: authored`.

**Phase 4 — Scaffold adept templates**: Create `<workpad>/adepts/` (if missing), `<workpad>/adepts/CLAUDE.md` (directory orientation), and `<workpad>/adepts/_template/CLAUDE.md` (default starting CLAUDE.md for new adepts). Both get `status: generated` frontmatter. Content for these files should be embedded in the skill body as heredoc-style templates (see Task 3.2).

**Phase 5 — Gitignore** (personal install only): Append `spire/` to `.claude/.gitignore`, creating the file if needed.

**Phase 6 — Optional alias**: Offer to create `.claude/skills/assistant/SKILL.md` that invokes `spire:igor` as `/assistant`.

**Phase 7 — Commit** (shared install only): Stage and commit scaffolded files with `🤖 Initialize Spire project config`.

**Verify**: File parses as valid skill frontmatter with `disable-model-invocation: true`. All seven phases are present as instructional sections.

### Task 3.2 — Define adept template content

Embed in the `spire:init` skill body (or as `plugins/spire/skills/init/references/` files) the default content for:

- **`adepts/CLAUDE.md`**: Explains the adepts directory purpose, that each subfolder is one domain, and links to the adept agent definition for conventions.
- **`adepts/_template/CLAUDE.md`**: Starter CLAUDE.md for a new domain folder. Sections: `## Domain`, `## Key files`, `## Conventions`, `## Open questions`. All placeholder.

**Verify**: Both template texts exist and are reachable by the init skill.

---

## Verification (all commits)

1. `grep -r '@references/project.md' plugins/spire/` returns zero hits.
2. `grep -r '@skills/igor/references/project.md' plugins/spire/` returns zero hits.
3. `grep -l 'spire:project' plugins/spire/agents/igor.md plugins/spire/agents/athanor.md` returns both files.
4. `plugins/spire/skills/project/SKILL.md` exists with shell injection line.
5. `plugins/spire/skills/init/SKILL.md` exists with `disable-model-invocation: true`.