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

Next-Generation Plugin Design Spec

Replaces g4b_ai. Target location: reliquary/plugins/<name>/.

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 a mage tower. Igor runs the lab, adepts study their domains, the tome holds accumulated knowledge, the forge produces artifacts, Pinky asks the unhinged questions that crack the problem, and Zathras maintains the tower itself. The user is the wizard. The tower travels with them -- it deploys into any project, officially or as a shadow, and adapts to what it finds. The arcane register is deliberate: Igor (Pratchett's clan of brilliant assistants), adepts (skill through practice), 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 forge.	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)
Forge	Dispatching orchestrator. Receives a brief, decomposes it, fans out subagents by tier, synthesizes results. The "oven" for multi-part implementation jobs.	Built	.claude/agents/dispatching-orchestrator.md (warpspace)	agents/forge.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	Markdown-embedded SVG rendering rules and renderer compatibility.	Built	skills/markdown-embedded-svg/ (g4b_ai)	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 --> Forge (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 forge executes multi-part work. Pinky brainstorms with the user (Igor hands off the conversation). Zathras maintains the tower.

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
Forge agent	Built	warpspace .claude/agents/dispatching-orchestrator.md	agents/forge.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	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. The Naming Pitch

The system is a wizard's tower that travels with its owner. Igor runs the daily operations -- greets the user, delegates tasks, keeps the journal, knows when to call in a specialist. Adepts study their domains and accumulate institutional knowledge that outlives any single session. The tome holds the accumulated wisdom -- navigable, curable, correct-on-contact. The forge turns plans into artifacts through coordinated labor. Pinky sits in the corner asking questions that sound naive but consistently identify the real flaw. Zathras maintains the tower itself, because every system that doesn't maintain itself rots.

The plugin name is not any single role -- it is the name for the whole tower. The register is arcane, intimate, and slightly old-fashioned. It should feel like a place where real work happens, not a product name. The current placeholder (g4b_ai) carries no meaning and should be replaced.

Candidates from the brainstorm

Name	Register	Why it fits
Sanctum	The private workspace	Clean, universally understood. "The sanctum's adepts."
Grimoire	A book of practiced, working magic	Not just knowledge but working knowledge. Implies the system does things.
Athanor	Alchemist's slow furnace	Patient background transformation. Obscure but beautiful.
Spire	The tower itself	Minimal, vertical, implies reach.
Studiolo	Renaissance private study	Intimate, cultured, where real thinking happens.
Arcanum	Secret knowledge / its container	"The arcanum's adepts." Natural possessive.
Vademecum	"Go with me" -- a portable handbook	Fits the portable plugin idea perfectly.
Orrery	Mechanical model of celestial bodies	Fits the space-game origin. A working model of complexity.
Collegium	Medieval scholarly community	Adepts study there. Community over hierarchy.