# Spire — Plugin Design Spec

Replaces `g4b_ai`. Target location: `reliquary/plugins/spire/`.

## 1. Identity

This plugin is a coherent agent orchestration system -- a wizard's private workshop where knowledge accumulates, work gets dispatched, and the system maintains itself. It is not a bag of utilities; it is a coordinated set of roles that compose into a working practice for agent-driven development.

The trope is an **alchemist's spire** — where the arcane and the practical overlap. Igor runs the lab, adepts study their domains, the tome holds accumulated knowledge, the athanor transforms plans into artifacts, Pinky asks the unhinged questions that crack the problem, and Zathras maintains the spire itself. The user is the alchemist. The spire is raised wherever they land — it deploys into any project, officially or as a shadow, and adapts to what it finds. The register bridges pulp-lab characters (Igor, Pinky, Zathras) with arcane practice (adept, tome, athanor): alchemy is where both traditions meet. Igor (Pratchett's clan — generational knowledge, comes pre-equipped), adepts (skill through practice, not innate authority), tome (institutional memory), Pinky (the "fool" whose instincts are right), Zathras (Babylon 5's tireless machine-tender).

This plugin replaces `g4b_ai` (v0.2.0), which is a flat collection of five skills and three agents with no coordination layer. Everything in `g4b_ai` either graduates into this plugin or is absorbed by a component.

## 2. Components

| Component | Role | Status | Current location | Target location |
|-----------|------|--------|------------------|-----------------|
| **Igor** | Session coordinator. Talks to the user, delegates work, keeps a journal, spawns adepts, routes to the athanor. | Built | `.claude/skills/assistant/` + `.claude/agents/assistant.md` (warpspace) | `skills/igor/` + `agents/igor.md` |
| **Adept** | Domain-scoped knowledge agent. Orients on a domain, accumulates journals and CLAUDE.md, answers consultations, dies with the session but leaves knowledge behind. | Built | `.claude/agents/adept.md` (warpspace) | `agents/adept.md` |
| **Tome** | Knowledge layer. Navigate (orient before work), curate (six methods for growing the wiki), check (validate health), handoff (post-work impact), init (bootstrap). Project-overlay pattern: generic `tome` + project-specific `<project>-tome` mutation. | Built | `.claude/skills/tome/` (warpspace, standalone) | `skills/tome/` (absorbed into plugin) |
| **Athanor** | Dispatching orchestrator. Receives a brief, decomposes it, fans out subagents by tier, synthesizes results. The alchemist's slow furnace — plans go into the Athanor and implementations come out. | Built | `.claude/agents/dispatching-orchestrator.md` (warpspace) | `agents/athanor.md` |
| **Workpad** | Document placement. Resolves where reports, plans, goals, journals go. Steers other skills to a single location. | Built | `skills/workpad/` (g4b_ai) | `skills/workpad/` |
| **Research-tree** | Multi-topic research as a phased dependency tree. | Built | `skills/research-tree/` (g4b_ai) | `skills/research-tree/` |
| **Research** | Research governance. Agent spawning rules, web fetch budgets, tier selection. | Built | `skills/research/` (g4b_ai) | `skills/research/` |
| **Implementation** | Implementation orchestration. Sequencing, delegation, bug approach, verification. | Built | `skills/implementation-orchestration/` (g4b_ai) | `skills/implementation/` |
| **SVG** | SVG diagram management — where to place generated SVGs relative to markdown files, how to reference them, directory conventions. Not inline embedding. | Built | `skills/markdown-embedded-svg/` (g4b_ai, name misleading) | `skills/svg/` |
| **Pinky** | Brainstorm catalyst. Opus-tier, philosophical, asks sideways questions that crack problems open. Writes proactively. Invites the next thought. | Designed | Brainstorm doc only | `agents/pinky.md` + `skills/pinky/` |
| **Zathras** | Self-maintenance agent. Maintains the plugin's own skills, templates, conventions. Can deploy a project-level Zathras. Knows all installation methods and environment detection. | Designed | Brainstorm doc only | `agents/zathras.md` + `skills/zathras/` |

### Agents absorbed from g4b_ai

| Agent | Disposition |
|-------|------------|
| `researcher` | Kept as `agents/researcher.md` -- leaf research agent, Opus, no sub-agents, 5-page web cap |
| `search` | Kept as `agents/search.md` -- read-only Sonnet lookup agent |
| `scout` | Kept as `agents/scout.md` -- Haiku quick-fact agent |

## 3. Deployment Model

### Official vs Shadow

| Mode | Mechanism | Visibility |
|------|-----------|------------|
| **Official** | Plugin enabled in project `.claude/settings.json` `enabledPlugins` | All contributors see it |
| **Shadow** | Plugin enabled in `.claude/settings.local.json` `enabledPlugins` | User-only, invisible to project |

Shadow mode is not degraded mode. The plugin works fully in both -- the difference is who sees the configuration.

### The project.md seam

Igor's behavior has two layers: **generic** (session lifecycle, delegation tiers, adept spawning, accretion rules) and **project-specific** (pinned agents, verification commands, workpad location, tome mutation name, domain skills). The seam is a single swappable file: `skills/igor/references/project.md`. When the plugin lands in a new project, this file is the only thing that needs authoring.

### Project-local mutation

The plugin deploys a **project-local overlay** for project-specific knowledge. This follows the tome pattern:

- Generic plugin provides: `skills/tome/` (navigate, curate, check, handoff, init)
- Project creates: `.claude/skills/<project>-tome/` (navigate override, folder guide, platform notes, curation rules)

The overlay is created by `tome:init` during bootstrap. The same pattern applies to Igor: the plugin carries the generic skill; the project carries `skills/igor/references/project.md` and optionally a project-specific agent roster.

### Bootstrap sequence

When the plugin arrives in a new project:

1. **Detect permission level** -- is there a `.claude/`? Can we write to it? Is the repo owned?
2. **Run `tome:init`** -- scaffolds wiki, builds the project-specific tome mutation, detects curation methods
3. **Author `project.md`** -- pinned agents, workpad location, verification commands, domain skills
4. **Resolve persistent storage** -- project workpad if official; `~/.claude/plugins/data/<plugin>/projects/<slug>/` if shadow
5. **Ready** -- Igor can now coordinate, adepts can orient, tome can navigate

Steps 1-4 are Zathras's job. In the absence of Zathras (not yet built), the user or Igor does them manually.

## 4. Architecture

### Role relationships

```
User
  |
Igor (coordinator)
  |--- spawns ---> Adepts (domain knowledge, long-lived within session)
  |--- dispatches --> Athanor (multi-part implementation/research jobs)
  |                     |--- fans out --> researcher / search / scout / implementer agents
  |--- invokes ------> Pinky (brainstorm sessions)
  |--- invokes ------> Zathras (self-maintenance, bootstrap)
  |
  '--- uses skills --> Workpad (file placement)
                       Research-tree (phased research structure)
                       Research (agent governance)
                       Implementation (sequencing, verification)
                       Tome:navigate (orientation before work)
                       SVG (diagram rendering rules)
```

Igor is the only component that talks directly to the user. Adepts advise Igor. The athanor executes multi-part work — you load it, close the door, and wait. Pinky brainstorms with the user (Igor hands off the conversation). Zathras maintains the spire.

### Project-independent vs project-specific

| Layer | Content |
|-------|---------|
| **Plugin (portable)** | All skills, all agent definitions, all references except `project.md`, tome generic skills, workpad resolution logic |
| **Project overlay** | `project.md`, `<project>-tome/` mutation (folder guide, platform notes, curation rules, navigate override), adept domain folders, project wiki |

### Knowledge flow

Adepts produce **ephemeral knowledge** (journals, session observations). Tome curates it into **permanent knowledge** (wiki docs, glossary). The accretion model: corrections accumulate as dated sections during sessions; compression into shorter forms is a separate curator operation done from the outside.

Two knowledge tiers in adepts: **solid** (verified from main, goes into CLAUDE.md) and **experiences** (branch observations, journal only). Branch awareness prevents solidifying speculative code as fact.

## 5. Existence Map

| Component | Status | Current home | Plugin target |
|-----------|--------|-------------|---------------|
| Igor skill | **Built** | warpspace `.claude/skills/assistant/` | `skills/igor/` |
| Igor agent | **Built** | warpspace `.claude/agents/assistant.md` | `agents/igor.md` |
| Igor project.md | **Built** | warpspace `.claude/skills/assistant/references/project.md` | `skills/igor/references/project.md` (template) |
| Adept agent | **Built** | warpspace `.claude/agents/adept.md` | `agents/adept.md` |
| Athanor agent | **Built** | warpspace `.claude/agents/dispatching-orchestrator.md` | `agents/athanor.md` |
| Tome (all skills) | **Built** | warpspace `.claude/skills/tome/` | `skills/tome/` |
| Workpad skill | **Built** | g4b_ai `skills/workpad/` | `skills/workpad/` |
| Research-tree skill | **Built** | g4b_ai `skills/research-tree/` | `skills/research-tree/` |
| Research skill | **Built** | g4b_ai `skills/research/` | `skills/research/` |
| Implementation skill | **Built** | g4b_ai `skills/implementation-orchestration/` | `skills/implementation/` |
| SVG skill | **Built** (needs rename/scope update) | g4b_ai `skills/markdown-embedded-svg/` | `skills/svg/` |
| researcher agent | **Built** | g4b_ai `agents/researcher.md` | `agents/researcher.md` |
| search agent | **Built** | g4b_ai `agents/search.md` | `agents/search.md` |
| scout agent | **Built** | g4b_ai `agents/scout.md` | `agents/scout.md` |
| Pinky agent+skill | **Designed** | brainstorm doc only | `agents/pinky.md` + `skills/pinky/` |
| Zathras agent+skill | **Designed** | brainstorm doc only | `agents/zathras.md` + `skills/zathras/` |

## 6. Name: Spire

**Decided 2026-09-14.** The plugin is **Spire** — the alchemist's tower itself. One syllable, works for both alchemy and magic, implies verticality and reach. `spire:igor`, `spire:tome`, `spire:pinky` all read cleanly as skill namespaces. "The spire's adepts" is natural.

The spire is raised wherever the alchemist lands. It's not a product — it's the room you work in.

### Component naming (final)

| Name | Role | Register | Origin |
|------|------|----------|--------|
| **Spire** | The whole system | Arcane/alchemical | The tower |
| **Igor** | Session coordinator | Pratchett | The clan of brilliant assistants |
| **Adept** | Domain knowledge agent | Alchemical | Skill through practice, not innate authority |
| **Tome** | Knowledge layer | Medieval | Institutional memory |
| **Athanor** | Dispatching orchestrator | Alchemical | The slow furnace — plans go into the Athanor |
| **Pinky** | Brainstorm catalyst | Warner Bros. | The fool whose instincts are right |
| **Zathras** | Self-maintenance | Babylon 5 | The tireless machine-tender |