diff --git a/docs/workpad/plans/2026-09-17-spire-project-override-init.md b/docs/workpad/plans/2026-09-17-spire-project-override-init.md new file mode 100644 index 0000000..795f5b5 --- /dev/null +++ b/docs/workpad/plans/2026-09-17-spire-project-override-init.md @@ -0,0 +1,156 @@ +# 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`.