epistemic-protocols

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 — and your own material (codebase, rules, past sessions) and the domain's usual decisions hold the clues	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, or the field narrowed too early — widen it before choosing any	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	New here — get a recommendation from your recent sessions, then optionally 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 that a stand-in behaves like the real target — test it in a bounded space and carry the untested remainder forward explicitly
/gate-check	An option set is about to be presented to you — an independent advisor rules it genuine, collapsed, or malformed, and its cited grounds are verified first
Auditing instruction prose
/white-bear	Prose that tells the agent what not to do — find prohibition framing and negated anchoring that keep the wrong target in view
/zero-shot	Prose that anchors on examples where a principle would generalize — find and name those spots

Route