Essay 7.2 — The Plugin Kit, Part 2 of 9.

Essay 7.1 framed the plugin as a cell — a system of cognitive organs that read each other, write to each other, and depend on each other through declared channels. Every organ carries the same three properties: who reads it, who writes it, what it depends on. This sub-essay opens the universal-skeleton organs every plugin in the prototype must have and names those properties at each step.

CLAUDE.md — The Plugin’s Brain Surface

What it is. A markdown file at the root of every plugin directory — the plugin’s primary memory surface, declaring what the plugin owns, what its hooks fire on, what its size limits are, what its current version is. Every plugin carries one — there is no exception. The file is the agent’s primary read at session start and at every moment the plugin becomes relevant to the work. ⓘ

Who reads it. The LLM, mostly. Claude Code reads CLAUDE.md files into the agent’s working memory at session start. When a plugin is unlocked for editing, the unlock ceremony auto-injects the plugin’s CLAUDE.md (along with docs/evolution.md) so the editor inherits the plugin’s reasoning before changing anything. Other plugins reading this plugin’s CLAUDE.md happens rarely and almost always for one-line cross-references, not deep parsing. ⓘ

Who writes it. The CONDENSE phase. By design, CLAUDE.md edits route through CONDENSE because that is the only phase whose guard permits writes to the brain layer. The operator can also touch CLAUDE.md directly via gmode for existing-plugin work — a deliberate escape hatch for fixes outside the cycle ceremony. ⓘ

What it depends on. Almost nothing inside the plugin. CLAUDE.md is the surface; other organs depend on it, not the reverse. The single exception is the four phase-section markers at the bottom (---Ob---, ---Pl---, ---Ex---, ---Ve---) which the section-boundary guard reads to decide where each phase may write. ⓘ

The new-plugin lens. When you guide your seed agent to create a new plugin, the first artifact the seed authors is CLAUDE.md. The seed declares the plugin’s single concern, names the hooks it will register, lists its size limits, and stamps version v0.1.0. Every other organ inside the plugin will reference choices made here. If CLAUDE.md does not name the concern clearly, the rest of the plugin drifts. New-user guidance: tell your seed to write CLAUDE.md FIRST, then the hooks, then everything else. ⓘ

hooks/ — The Reflexes

What it is. A directory of small shell scripts that fire on Claude Code events: UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionStart, SubagentStart. Hooks are how the plugin reaches the agent’s cognitive process from outside the LLM. They are pure shell, executing in milliseconds, returning exit codes that decide whether the call proceeds. ⓘ

Who reads them. Claude Code itself, at event time. The agent never reads its own hooks during reasoning — the hooks are invisible to the LLM unless one of them emits a voice into the context. ⓘ

Who writes them. The [PLUGIN-LOCK] ceremony. Plugin code is not edited the way ordinary files are — every change passes through a deliberate unlock cycle, runs the plugin’s test suite at the lock boundary, and reverts to a captured git checkpoint on test failure. ⓘ

What they depend on. A small set of sibling organs: scripts/ (when a hook needs to invoke the plugin’s own CLI for state mutation), hooks/voice.xml (for every message the hook emits to the agent’s context), data.json (for state, but only read-mediated through the plugin’s own scripts — never directly), and a shared helper at .claude/plugins/lib/voice-helper/ (the get_voice substitution function). ⓘ

A plugin "cell" showing the universal skeleton inside the cell wall, conditional cognitive organs in a secondary tier, and the brain-root wiring file labeled outside the cell
Image 7.2. Universal skeleton (solid border) plus conditional organs (dashed). The wiring file lives at brain root, outside the cell.

The new-plugin lens. When you guide your seed to create a plugin, the seed decides which Claude Code events the plugin needs to fire on, and authors one hook per event. A plugin with no hooks is dead — every active plugin has at least one. The seed also adds the hook registration to the brain-root settings.local.json (covered in Essay 7.7); without registration, the file is just a shell script on disk that nothing invokes. A research lab could install a [PROTOCOL-CHECK] plugin whose hooks/ fires on every [IRB-RELEVANT] question; scripts/ exposes protocol.sh validate for downstream auditors. Same skeleton, same edit-gate; different concern. ⓘ

scripts/ — The Verbs

What it is. A directory of internal CLI scripts the plugin publishes for the agent (or another plugin) to call. phase.sh advance. observe.sh set-multiplier. safe-lock.sh. drift-check.sh. Scripts are how the plugin lets the agent or other plugins talk to it through a stable interface. ⓘ

Who reads them. The agent, when it invokes a command. Other plugins, when they query this plugin’s state via its published read-only commands. The hooks of this plugin, when they need to mutate data.json (the only path to mutation is the plugin’s own scripts). ⓘ

Who writes them. Same [PLUGIN-LOCK] ceremony as hooks. Scripts and hooks share the same edit gate because both are code. ⓘ

What they depend on. data.json (the script either reads it or atomically mutates it via the read-under-flock + jq-transform + temp-validate + atomic-mv protocol). voice.xml (for messages to whoever called the script). config.conf (for operator-tunable thresholds). The lib/voice-helper/ shared helper. ⓘ

The Distributed Job Extension pattern. Other plugins reach into this plugin only through these scripts — never through the raw data.json. The plugin’s public read-only commands (job.sh focused, phase.sh current) are the entire cross-plugin contract. Direct cat data.json from outside the owning plugin is forbidden discipline. New-user guidance: when you guide your seed to write a plugin that wants to know about another plugin’s state, tell the seed to call the other plugin’s *.sh command, not to peek at its files. The seed’s own knowledge layer reinforces this — every plugin’s knowledge dir names its public-API commands explicitly so future cycles can find them. ⓘ

The minimum-viable plugin shape. Not every plugin needs scripts/. question_discipline ships none — it is a pure-gate plugin that does not publish CLI verbs. A plugin without scripts/ is announcing: I do not expose verbs; I only enforce. The absence is itself information. ⓘ

The skeleton organs share one edit gate. CLAUDE.md is the brain surface; hooks are the reflexes; scripts are the verbs. The universal-skeleton organs every plugin in the prototype must have ship together — and every edit to any of them passes through the same PLUGIN-LOCK ceremony. The gate is friction — gmode bypasses it deliberately, and coverage gaps in the plugin’s own tests let bad edits through. ⓘ The next sub-essay opens the organ that almost every plugin doubles — voice.xml, once for the LLM and once for the operator.

Essay 7.2 — The Plugin Kit, Part 2 of 9.

Previous: Essay 7.1 — Plugin Kit Foundation — cell-as-system frame and the mini-series roadmap. Next: Essay 7.3 — The Dual Voice Architecture — two voice.xml files, one for the LLM and one for the operator.