reliquary/docs/workpad/designs/2026-09-14-plugin-design-spec.md

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 — "put it in the oven" is the colloquial shorthand.	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 — "put it in the oven"
Pinky	Brainstorm catalyst	Warner Bros.	The fool whose instincts are right
Zathras	Self-maintenance	Babylon 5	The tireless machine-tender