# 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"` ``` **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 ``` **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 `/adepts/` (if missing), `/adepts/CLAUDE.md` (directory orientation), and `/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`.