Epistemic Protocols

한국어

When AI collaboration goes off-track, you redo everything. These protocols bring the decisions that set the direction to you early — often at the plan level, before a wrong one hardens into code or other downstream work — and leave each one yours to settle. Fix the direction before the implementation compounds it.

Why

As models improve, a well-written prompt goes a long way: if it already states everything that matters, working with or without a protocol can lead to nearly the same result. Writing that prompt is the hard part. It means recalling every unknown at once and anticipating the cases the work will meet at runtime, alone, before the first reply. What the prompt missed surfaces later, and the later it surfaces the more it costs: a wrong direction corrected at the plan level can cost one conversation turn, while one found after release to a live service costs rework that grows with everything built on it. The protocols make the AI a thinking partner at those decision points. It asks, and you answer with what the question brings to mind; it presents candidates, and you recognize which one fits. Many of the items that end up deciding the work are ones you could not have listed at the start.

For example, the same request handed to three sub-agents — once in one line, once with /elicit first (click for the video):

_{Companies, reasons and numbers in the clip are illustrative, not a run result.}

Or when you set out to do something — here, preparing next week's churn meeting — /inquire first gathers what the work rests on from every source it can reach, then hands back in one pass what it confirmed, what conflicts, what it could not reach, and what only you decide (click for the video):

_{Meetings, sources and numbers in the clip are illustrative, not a run result.}

Where the protocols help

Use the protocols to catch a wrong direction while planning, before it shapes later work. The same structured checkpoints also help when you hand work to an autonomous run, check a result against your actual situation, recall an earlier discussion, or make sure you understand something before building on it.

Quick Start

Claude Code

Install every protocol, together with the route and epistemic-cooperative plugins:

curl -fsSL https://raw.githubusercontent.com/jongwony/epistemic-protocols/main/scripts/install.sh | bash

route lets the agent invoke a suitable protocol from the conversation context, and find relevant collaboration principles when needed, so you do not have to know which protocol fits. It is still experimental: its wording and hook set can change between releases. epistemic-cooperative adds guided learning (/onboard), recognizing what is stuck from grounded candidates (/probe), and contributor tools. To leave either one out, run claude plugin disable <name>@epistemic-protocols after installing; without route, every protocol stays installed and callable by its own command.

You can also invoke a protocol yourself at the decision point you are at — for example /inquire before handing work to the AI, or /bound when you cannot yet see what a task needs you to decide.

/onboard gives a quick recommendation from your recent sessions and can continue into guided learning with scenarios, trials, and quizzes.

Codex

This repository is also a Codex plugin marketplace. To add it from GitHub:

curl -fsSL https://raw.githubusercontent.com/jongwony/epistemic-protocols/main/scripts/install-codex.sh | bash

For local development from a checkout:

codex plugin marketplace add /path/to/epistemic-protocols

The Codex marketplace keeps the same plugin boundaries as Claude Code: each protocol is its own plugin, and epistemic-cooperative carries the utility skills. The marketplace lives at .agents/plugins/marketplace.json; each plugin keeps its Codex manifest beside its Claude manifest at <plugin>/.codex-plugin/plugin.json.

A protocol's checkpoint presents its decisions and what each answer changes; it does not by itself suspend execution, so on a non-interactive run such as codex exec the decisions can arrive after the work has started.

Other agent tools

Protocol skill sources live in each plugin directory under <plugin>/skills/<name>/SKILL.md. The repository does not ship a pre-materialized .agents/skills/ symlink view because Codex marketplace discovery can scan both plugin manifests and Agent Skills symlinks, producing duplicate skill entries.

Hosts that need an Agent Skills-style view should materialize it outside the Codex marketplace checkout or use host-specific packaging. Runtime tool grounding still varies by tool, so protocol behavior in non-Claude-Code hosts is provisional pending accumulated cross-host use evidence.

Protocols

Protocol	Command	When to use	Once it has run
Aitesis	/inquire	A task rests on missing context or unchecked assumptions, and you need to see what remains unknown	You can recognize what was settled and from where, what rests on weak or unreached ground, and what only you decide
Euporia	/elicit	You know roughly what you want but can't yet say which decisions it turns on — the clues can sit in your words, your own material (codebase, rules, past sessions), or the decisions the domain usually turns on	You can say "this is my intent, aligned enough" — each recorded value stands on your own words, and what you left open is carried
Heuresis	/ideate	You have no candidates yet, the ones you have narrowed too early, or the field is thin — widen it before choosing any, or pick up a field you widened before	You can look over one map of your idea field — each frame and the branches dug under it, every candidate with where it came from, what stays unexplored, and what you set out of scope or aside — and take that field forward, with nothing in it chosen or ranked; choosing among it is a separate act
Proplasma	/preview	You're about to commit to one of several directions, but you can't judge them from their descriptions — you'd have to see them first	You can say what each direction means for your purpose, whether that rests on a probe you saw, a description, your own account, or evidence, and which one you take
Hypotyposis	/sketch	You have to make something and can't say what it should be, but you'd recognize it on sight	You can point at a version as you met it and say "this is the form, for this purpose", and see where it and the passed-over versions are
Analogia	/ground	You're carrying a framework, an analogy, or an earlier design over to a case, or checking an abstraction against its own cases, and it isn't clear what that comparison actually supports	You can say what carries each conclusion, what was checked and found, what would break it, and whether it holds, is blocked, or remains undetermined
Periagoge	/induce	Several concrete cases seem to share something no one has named yet, or that a name in use no longer says — pin down what they have in common	You can name what your cases share, say which cases it takes in and which it leaves out, and recognize it as serving your goal
Merismos	/apportion	You're about to hand one goal to an autonomous run — cut it into units that each fit one stretch of the run and carry their own conditions for when they are done	You can call the plan yours — units with their checks, accepted gaps, and held judgments; what needed you before the run is settled, and the rest comes back to you once at the end
Epharmoge	/contextualize	A result — this session's or another's — may be correct but not fit your actual situation, or leave out something you asked for	You can see each misfit found, settled or withdrawn by your words, your grant, or evidence, with the fixes carried out and reread until nothing remains open
Horismos	/bound	You cannot yet see what needs deciding in a task, or which decisions to keep or entrust	You can see each decision, what rests on it, its cost if wrong, what settled it, and what remains open and who settles it
Anamnesis	/recollect	You vaguely remember something was discussed before but cannot name it — one session, or a line of work, topic, or concept spread across several	You recognize the past you were reaching for — a conversation, or a line of work, topic, or settled concept across several — in a story whose every sentence rests on a record you can reopen, knowing it took place, not that it still holds
Katalepsis	/grasp	Something in front of you — code, a document, a result — needs to be actually understood: you can't follow it yet, or you nod along and aren't sure	You can say your understanding serves your purpose, on a map built with you and checked against the material, knowing what would settle the checks still pending
Hyphegesis	/conduct	The work takes several lines of thinking, and it isn't obvious what order they run in, which can run apart, how their results combine, when to stop, or where each result goes — settle how it runs before starting	You can say how the lines order, combine, stop, and where their results go, recognize what you entrusted and kept, and call the method yours

The protocols are not a fixed sequence or grouping: reach for the one whose deficit you are in, and combine them as the situation calls for.

Utilities

For utility plugin installation in Claude Code, see Quick Start.

Epistemic Cooperative

Skills that act at their own decision points — around the protocols, on the work itself, and on the prose that steers the agent.

Command	When to use
Finding the protocol
/onboard	You want to find which protocols fit your work, or practise using them — whether new here or back after new protocols arrived or your workflow changed — get a recommendation from your recent sessions, or learn by scenario, trial, and quiz
/probe	Something feels off and you cannot name what is stuck — you can then say what it is: a shown candidate, your own words, or none shown, having seen what each rests on and what rules it out
Shaping the work
/reduced-space-test	A claim about behavior, performance, transfer, or value that reasoning alone cannot settle, where evidence from a stand-in for the real setting would — test it in a bounded space and carry the untested remainder forward explicitly
/gate-check	Options for a reversible decision are about to be put to you and may not be genuinely different choices, or an answer to an earlier set settled nothing — an independent advisor checks whether the options form a real choice, and the grounds it cites are verified before the set reaches you
Auditing instruction prose
/white-bear	Prose that names something the agent should not reach for — a forbidden act, a retired path, a rejected alternative — find the mentions that keep that wrong target in view without earning their place
/zero-shot	Prose that anchors on examples where a principle would generalize — find and name those spots

Route

Experimental. The hook set and the injected wording can change between releases — see route/README.md before depending on either.

Context-driven protocol routing. A session-start hook places the two protocols to reach for first — /inquire before gathering context, /elicit where the intent is unclear (the plugin's purpose.md) — the installed-protocol table with each protocol's declared description, and the premise index at the head of context, once per context epoch; the agent in the main conversation judges in the turn itself, at the prompt and mid-turn; a delegated agent, a fork included, invokes no protocol. With it, you meet the deficit your conversation shows as the core protocol that resolves it, without recalling which protocols exist: the agent brings in /inquire or /elicit where the purpose names them and reads any other gap against the protocols' declared descriptions, and the invoked protocol's own gates hold your judgment. Route has no command of its own: where you already know the protocol you want, type that protocol's command.

What the checks cover

Different mechanisms check different things, and it helps to know where each one stops.

• Lean proofs — a protocol's contract is also written as a Lean model inside its SKILL.md. Lean checks that the properties stated about that model hold, under the assumptions the model declares; the judgments the model leaves open are among those assumptions, not things it proves. A protocol's lean/EpistemicProtocols/<Protocol>/Theorems.lean holds what is stated and proved about its model.
• Runtime evidence — the contributor skill /realize runs a protocol in a real session and collects evidence that the steps it declares actually happen, through automatic checks plus a review of the transcript.
• Static checks — /verify checks the files' structure: required sections, consistent names and references, matching versions.

None of these measures what happens downstream of a protocol, such as whether it reduces rework, and that is deliberate: how much a protocol helps depends on what each person does not yet know, and on the model, which keeps improving. What a run can show is which decisions entered the conversation because the AI asked or presented them rather than because they were written up front. The contributor skill /outcome runs the same request with and without a protocol and lists those decisions with the passages they came from.

For Contributors

Start with ONBOARDING.md. Paste the full file into a fresh Claude Code session to use Claude as an onboarding buddy for environment setup, core docs, and the contribution workflow.

For architecture, read CLAUDE.md. For the underlying collaboration principles, explore premise/.

When editing the project's public description, follow the guidance in Mission Bridge.

Greek Codex

Protocol	Greek	Meaning
Katalepsis	κατάληψις	Grasping, comprehension
Horismos	ὁρισμός	A bounding
Aitesis	αἴτησις	Request, inquiry
Analogia	ἀναλογία	Proportion
Periagoge	περιαγωγή	Turning-around
Euporia	εὐπορία	Way through, resourcefulness
Merismos	μερισμός	Apportionment
Epharmoge	ἐφαρμογή	Application, fitting
Anamnesis	ἀνάμνησις	Recollection
Hyphegesis	ὑφήγησις	Leading the way, guiding from ahead
Proplasma	πρόπλασμα	Preliminary model, first mold
Hypotyposis	ὑποτύπωσις	Outline, first sketch
Heuresis	εὕρεσις	Finding, discovery

Acknowledgments

• @yolohyo — Comment-lifecycle UX design contribution for comment-review (the skill has since moved to cc-plugin as a protocol-free substrate plugin)
• @zzsza — Quiz-based participatory UX design contribution for Onboard

License

MIT