g4borg
937759b530
Design spec for the g4b_ai replacement plugin — component inventory, deployment model, architecture, and existence map. Fable naming review evaluates candidates and recommends "Keep" as the plugin name.
150 lines
12 KiB
Markdown
150 lines
12 KiB
Markdown
# 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. |
|