A demonstration repository for the research-clab Claude Code plugin.
Multi-agent research orchestration applied to a deliberately playful question: Can mathematical constants and geometric principles produce objectively better pies?
Four AI researchers -- each modeled after a real scientist with an authentic intellectual methodology -- investigate the intersection of mathematics and pie, governed by strict epistemic rules, pre-registered hypotheses, and constraint-based reasoning.
| Capability | How It's Used |
|---|---|
| Multi-agent teams | 7 agents (3 infrastructure + 4 domain specialists) coordinated via blast-first spawn protocol |
| Persona-based reasoning | Each specialist embodies a real scientist's methodology, not just their knowledge |
| Epistemic discipline | Pre-registered gates, constraint maps, source authority hierarchy, permanent verdicts |
| Session-based workflow | Workshop rounds with structured markdown handoffs between sequential teams |
| Persistent memory | Cross-session agent memory, constraint maps, knowledge index |
| 12 slash commands | Team orchestration, synthesis generation, knowledge querying, agent creation |
| 57 reference papers | 4 domain corpora grounding every claim in cited sources |
Session 0 ran as a 2-round workshop producing a master synthesis. The central finding:
- Pi is structurally necessary in circular pie geometry -- it's the constant of the circle, not a design lever
- Phi (1.618) is absent from every well-posed circular/cylindrical optimization across 28 surveyed papers -- preliminary negative from all 4 specialists
- The decisive question: does the quality-vs-geometry curve have a sharp peak at a mathematical constant, or a broad plateau where constants merely fall in a "good enough" zone?
Output: 6 geometric theorems, 2 pre-registered hypotheses, 10 proposed computations, 10 constraints, and a 3-session investigation plan.
pi-v-pie/
├── .claude/ # Claude Code infrastructure
│ ├── agents/ # 7 agent definitions (*.md)
│ ├── agent-memory/ # Per-agent persistent memory
│ ├── skills/ # 12 slash command definitions
│ ├── rules/ # 6 behavioral rules (auto-loaded)
│ └── settings.json # Plugin configuration
├── researchers/ # Reference corpora
│ ├── Coxeter/ # 14 papers — geometric optimization
│ ├── Herve-This/ # 14 papers — molecular gastronomy
│ ├── Myhrvold/ # 15 papers — computational gastronomy
│ └── Vi-Hart/ # 14 papers — recreational mathematics
├── sessions/ # All session outputs, chronological
│ ├── session-00/ # Initial domain assessment (complete)
│ ├── session-plan/ # Prompts, plans, agendas
│ ├── framework/ # Cross-session methodology docs
│ └── templates/ # 9 session format templates (A-I)
├── tools/ # Knowledge index infrastructure
│ ├── knowledge-index.json # Canonical knowledge graph
│ └── knowledge-schema.yaml # 8 entity types with schemas
├── artifacts/ # Source materials (PDFs, primary docs)
├── CLAUDE.md # Project constitution
└── agents.md # Agent & skill registry
These agents do NOT do domain analysis. They orchestrate, index, and fetch.
| Agent | File | Model | Role |
|---|---|---|---|
| coordinator | coordinator.md |
Sonnet | Orchestrates teams, writes minutes, maintains constraint map. Skill teammate operations (reader/assembler/analyzer). |
| librarian | librarian.md |
Sonnet | Sole writer of knowledge-index.json. Indexes, queries, serves knowledge graph. Reports what files say -- never evaluates. |
| scout | scout.md |
Haiku | Fast paper fetcher. Populates researchers/ folders. One reference at a time, 150-400 lines each. Does not interpret. |
Each uses Opus, reads their full research corpus at engagement start, and maintains persistent memory.
| File | herve-this-molecular-skeptic.md |
| Archetype | Skeptic |
| Corpus | researchers/Herve-This/ (14 papers) |
| Methodology | Note-by-note empiricism. Every claim gets: what was measured? what was the control? how many replicates? what's the uncertainty? Pre-registers predictions before tasting. |
| Core directives | Empirical evaluation of mathematical claims. Physical chemistry decomposition (starch gelatinization, Maillard kinetics, fat crystallization, heat transfer). Adversarial skepticism protocol. Sensory evaluation rigor (ISO standards, triangle tests, hedonic scaling). |
| Unique authority | Only agent who assigns confidence or probability. |
| File | myhrvold-computational-gastronomer.md |
| Archetype | Calculator |
| Corpus | researchers/Myhrvold/ (15 papers) |
| Methodology | Stop debating, run it. Every dispute becomes a computable question with a numerical answer. |
| Core directives | Thermal modeling (FEM, CFD, conduction/convection/radiation). Geometric optimization (surface/volume, heat distribution). Recipe parametrics (scaling laws, sensitivity analysis). Dimensional analysis on everything. |
| Output rule | Lead with computation result. All quantities with units. Parametric functions, never point solutions. |
| File | coxeter-geometric-optimizer.md |
| Archetype | Workhorse |
| Corpus | researchers/Coxeter/ (14 papers) |
| Methodology | Construction over assertion. Show every step. If you can't construct it, it doesn't exist. |
| Core directives | Pie geometry fundamentals (solid of revolution, crust-to-filling ratio, isoperimetric analysis). Symmetry classification (symmetry groups, wallpaper groups, tessellations). Optimization problems (max volume/surface, fair division, venting placement). Mathematical constant analysis (where pi appears necessarily vs. artificially; whether phi emerges from any natural optimization). |
| Output rule | Step-by-step construction. LaTeX for all expressions. Dimensional consistency at every step. |
| File | vi-hart-recreational-dreamer.md |
| Archetype | Dreamer |
| Corpus | researchers/Vi-Hart/ (14 papers) |
| Methodology | Pattern recognition across domains. Making abstract math tangible. Playful investigation leading to genuine insight. |
| Core directives | Hidden mathematical structures (topology of crusts, knot theory of braided edges, fractal dimension, graph theory of lattice patterns). Cross-domain bridges (music, biology, textiles, architecture). "What if" engine (propose counterintuitive alternatives). Mathematical aesthetics. |
| Output rule | Lead with the surprising connection. Every analogy must have a testable implication. Distinguish "interesting pattern" from "load-bearing structure." |
All skills require explicit /skill-name invocation.
| Skill | Usage | Description |
|---|---|---|
/clab-team |
/clab-team <prompt.md> --mode workshop |
Launch a coordinated multi-agent research team from a session prompt. Blast-first spawn, task assignment, hands-off execution. Modes: compute, workshop, panel. |
/clab-synthesis |
/clab-synthesis <docs...> --agent skeptic --type master |
Generate synthesis documents. Solo (one agent) or team (2-3 agents deliberating). Types: solo, team, master (sub-session rollup), fusion (synthesis of syntheses). |
/clab-plan |
/clab-plan <topic> --session N |
Generate session plans and prompts. Context assembly, planner agent, user checkpoint, prompter agent. |
/team-blast |
/team-blast --list |
Direct-write broadcast to all team agent inboxes. Resolves name-to-type mapping. Bypasses SendMessage routing for reliable delivery. |
| Skill | Usage | Description |
|---|---|---|
/weave |
/weave --search "phi" |
Query and maintain the knowledge index. --update rebuilds, --show <type> lists entities, --trace follows references, --db-sync rebuilds SQLite. |
/new-researcher |
/new-researcher "Vi Hart" --archetype dreamer |
Create a new researcher agent with web-fetched papers, agent definition, and librarian indexing. |
/new-research-project |
/new-research-project "domain" |
Scaffold a complete multi-agent research collaboration from scratch. |
/indexing |
/indexing researchers/Coxeter/ |
Build structured index for a researcher folder. |
| Skill | Usage | Description |
|---|---|---|
/shortterm |
/shortterm skeptic |
Collapse and optimize agent memory files. Deduplicate, compress, archive to docs. |
/redact |
/redact "session-05" --dry-run |
Remove all agent-memory references to a session, mechanism, or identifier. |
/clab-review |
/clab-review <session-file> --agents skeptic,calculator |
Multi-agent collaborative document review with fan-out and synthesis. |
/document-prep |
/document-prep --template handoff |
Format-aware document toolkit for templates, notation, and style checking. |
Rules in .claude/rules/ auto-load at session start. Path-scoped rules load only in matching directories.
| Rule | Scope | Key Provisions |
|---|---|---|
| team-lead-behavior | Always | Don't over-manage. Blast-first spawn is non-negotiable. One team at a time. Never self-initiate shutdown. |
| teammate-behavior | Always | Inbox first, always. Max 3 files before checking inbox. Message by NAME, never by type. One writer per output. |
| epistemic-discipline | Always | Pre-register gates before computation. Negative results are constraints, not failures. Only Skeptic assigns confidence. No filler confidence language. |
| output-standards | Always | Action items use 7-component format. Handoffs use 7-section structure. Mark all unvalidated claims as PRELIMINARY. Gate verdicts are permanent. |
| gate-verdicts | sessions/** |
Pre-registration protocol. Verdict format. Permanence -- once recorded, a verdict cannot be changed. |
| session-handoffs | sessions/** |
Session naming conventions. Mandatory handoff documents. Never renumber sessions. |
When sources conflict, higher authority wins:
- Skeptic verdicts (highest)
- Synthesis files
- Gate verdict results
- Session minutes
- Raw computation output (lowest)
The project's institutional memory lives at tools/knowledge-index.json.
8 entity types: findings, ruled_out, decisions, assessment_trajectory, sessions, data_provenance, open_threads, research_corpus
Query interface: /weave --show findings, /weave --trace "phi", /weave --search "heat transfer"
SQLite accelerator: tools/knowledge.db with FTS5 full-text search, rebuilt via /weave --db-sync
Only the librarian agent writes the index. All other agents read it.
| Format | Template | Use When |
|---|---|---|
| A | First Contact Review | Opening investigation of new material |
| B | Adversarial Debate | Stress-testing claims between opposing agents |
| C | Collaborative Deep-Dive | Focused investigation with 2-4 agents |
| D | Workshop | Multi-round deliberation with structured handoffs |
| E | Investigation Arc | Multi-phase gated investigation |
| F | Decisive Computation | Single-objective computation sprint |
| G | Mass Parallel Assessment | 8-17 agents reviewing in parallel |
| H | Decision Gate | Binary yes/no routing decision |
| I | Formalization | Status consolidation and documentation |
Templates live in sessions/templates/. The format selection guide is at sessions/session-plan/format-selection-guide.md.
# 1. Create or use a session prompt
/clab-plan "investigate golden ratio in pie crust thickness" --session 1
# 2. Launch the team
/clab-team sessions/session-plan/session-1-prompt.md --mode compute
# 3. Agents spawn, receive roster, get assignments, work autonomously
# Team lead goes hands-off until agents report results
# 4. After session, rebuild knowledge index
/weave --update
# Fetches papers, writes agent definition, indexes corpus
/new-researcher "Ada Lovelace" --archetype calculator --papers 14
Every team launch follows this sequence -- no exceptions:
- Spawn all agents with minimal prompts ("wait for instructions")
- Wait for ALL agents to confirm ready
- Blast roster to all inboxes (
/team-blast --list) - Then send real work assignments via SendMessage
- Hands off -- team lead routes results, does not do agent work
This repository is powered by research-clab, a Claude Code plugin that provides:
- Team orchestration: TeamCreate, TeamDelete, SendMessage, blast-first workflow
- Task management: TaskCreate, TaskUpdate, TaskList, TaskGet with dependency tracking
- Agent spawning: Spawn specialized agents as teammates with isolated context
- Infrastructure agents: coordinator, librarian, scout as built-in subagent types
- Knowledge tooling: Schema-driven knowledge index with SQLite acceleration
The plugin turns Claude Code from a single-agent tool into a coordinated research laboratory.
This is a demonstration repository. The research question is intentionally playful; the orchestration infrastructure is production-grade.