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

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

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

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

   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:

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