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

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, and the optional advisory channel is unvalidated — see route/README.md before depending on either.

Context-driven protocol routing. A session-start hook places the installed-protocol deficit table and the premise index at the head of context, once per context epoch; a per-prompt hook places a short directive beside each prompt. With it, you meet the deficit your conversation shows as the core protocol that resolves it, and see why it was brought in, without recalling which protocols exist: the agent shows its reading and invokes one protocol whose fit is plain, chosen by how the fits raised now compose with each other and with the work in hand, saying how the other fits follow it or stand beside it; otherwise it points at each fit, one line each, or stays silent; another protocol's gate that holds your judgment stays yours while that happens.

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.

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