Epistemic Protocols

한국어

When AI collaboration goes off-track, you redo everything. These protocols catch misalignment early — often at the plan level, before it hardens into code or other downstream work. Fix the direction before the implementation compounds it.

Why

Correcting a wrong direction at the plan level can cost one conversation turn. Once it hardens into code, rollout steps, or downstream explanations, it can cost hours of rework. These protocols insert structured checkpoints at decision points — intent, goal, context, perspective, execution, applicability, recall, and comprehension — so you and AI can surface, judge, and adapt misalignment before it compounds.

Mission and Machinery

Stated Mission — the public hook: catch wrong directions early, especially at the plan level. This is the clearest entry story and how most users reach for the protocols.

Realized Machinery — the actual coverage: structured checkpoints span planning, analysis, decision, execution, verification, recall, and comprehension. Protocols such as Merismos (goal apportionment into conditioned execution units), Epharmoge (post-execution applicability), Anamnesis (session recall), and Katalepsis (comprehension verification) extend beyond plan-level alone.

The two layers serve different audiences: the README carries the narrow public contract; SKILL.md and CLAUDE.md describe the full machinery. See docs/mission-bridge.md for the governance rules that keep these layers aligned.

Quick Start

Claude Code

Install every protocol:

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

Then invoke a protocol at the decision point you are at — for example /inquire before handing work to the AI, or /bound before a refactor that crosses several domains.

The two utility plugins are opt-in, so the one-liner leaves them out. epistemic-cooperative adds learning and deficit recognition (/onboard, /probe) plus contributor tooling; route carries the session hooks — a per-prompt routing directive, at session start the installed-protocol deficit table with the premise index beneath it, and again at the tool calls the matcher can see are a premise document's moment — an instruction surface changing, work handed to an agent — that document's entry. Add either on its own:

claude plugin install epistemic-cooperative@epistemic-protocols
claude plugin install route@epistemic-protocols

With epistemic-cooperative installed, /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.

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
Aitesis	/inquire	AI charges ahead without asking what it needs to know
Euporia	/elicit	You have intent but the decision coordinates are implicit — reverse-trace them from the externalized substrate (codebase, rules, past sessions) until intent crystallizes
Heuresis	/ideate	The candidate field for a decision is empty or has prematurely converged — widen it into a diverse set before any selection, not after
Proplasma	/preview	Right before committing to a direction — the candidates read fine but you'd have to see them to judge; contrast cheap discard-committed probes first
Hypotyposis	/sketch	A form has to be made and you cannot say what it should be, but you'd know it on sight — sketch it, mark what does not fit, revise the kept version, and finish on the one you recognize
Prothesis	/frame	Need to settle which lens to look through before the analysis starts — one lens or several
Analogia	/ground	AI's advice sounds right in theory but unclear in your context
Periagoge	/induce	One or more concrete cases accumulating into an unnamed essence — crystallize the emerging abstraction
Merismos	/apportion	About to hand a goal to an autonomous run — cut it into units that each fit one interval and close each unit first — on its own done-condition where one compiles, on your recorded acceptance where none does, or on a reservation where a judgment rather than a check settles it
Epharmoge	/contextualize	AI's output is correct but doesn't fit your situation
Elenchus	/sublate	About to externalize a working context that may have decayed — vet it dialectically first
Horismos	/bound	An epistemic boundary is undefined — direction/priority, scope, type/concept, or who decides (ownership)
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
Katalepsis	/grasp	Code, a paper, or a big change you need to actually understand — you can't follow it yet, or you nod along and aren't sure. Verify your understanding is genuine before you approve or build on it
Hyphegesis	/conduct	Multiple cognitive moves whose order, independence, reconciliation, stopping (termination), and routing aren't obvious — conduct how the whole session's work runs before starting

Concern clusters: Planning (/inquire, /elicit, /ideate, /preview, /sketch) · Analysis (/frame, /ground, /induce) · Execution (/apportion) · Verification (/contextualize, /sublate) · Cross-cutting (/bound, /recollect, /grasp, /conduct)

Utilities

Two plugins sit beside the protocols. Both are opt-in for the Claude Code one-liner:

claude plugin install epistemic-cooperative@epistemic-protocols
claude plugin install route@epistemic-protocols

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 one recommendation from your recent sessions, then optionally learn by scenario, trial, and quiz
/probe	Something feels off but you cannot name which deficit it is — several hypotheses, routed by your recognition
Shaping the work
/triage	A pile of GitHub issues needs to become focused work units, each fused with the project's northstar and handed to a session by pointer
/forge	You need a prompt or a standing skill recipe grounded in a vendor reference (a model prompt guide, the Codex Goals spec), not one written from memory
/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
Reviewing a change
/review-loop	Drive a change through review until every finding is verified against the codebase and disposed of, re-reviewing each round
Auditing instruction prose
/place	An instruction file keeps growing — route each clause to where it belongs (a load tier, the ledger, or deletion)
/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
Steering the project
/realign	The project guide's direction line no longer matches where the work is going — fuse the inscribed line, outside signals, and your present understanding
Delegating to Codex
/goal-research	A factual research question you want scoped and externally verified in a background Codex session, with the full trace returned

Route

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. When the accumulated context shows a deficit exactly one installed core protocol resolves, the agent invokes that protocol, nudges when several fit, and stays silent when none does. The invoked protocol's own first gate keeps your judgment where it was.

Design

Each protocol targets a specific decision point where human-AI collaboration can drift. Public docs lead with the plan-level hook because it is the clearest entry story; contributor docs explain the broader machinery spanning planning, execution, verification, recall, and comprehension. For the bridge between those layers, see docs/mission-bridge.md. For architecture details and design philosophy, see CLAUDE.md.

For Contributors

New to the repo? Start with ONBOARDING.md. The intended usage: paste it into a fresh Claude Code session — the file carries an embedded instruction block that turns Claude into an onboarding buddy. Claude checks your environment against the setup checklist, routes you to the protocol that best matches your current stance, walks you through the core docs in order, and surfaces the contribution workflow and conventions.

Entry-point routing happens up front, so you can experience the protocols while onboarding onto them:

• First encounter, no prior context → /onboard (epistemic-cooperative) for a quick recommendation plus scenario/trial/quiz walkthrough
• Want comprehension of the project itself verified → /grasp (katalepsis) over CLAUDE.md or a specific SKILL.md
• Already have a personal Claude Code workflow and want this project mapped onto it → /ground (analogia), with your existing usage as the concrete domain
• Need a fast when-to-use-which reference → the protocol table above, or the route plugin's session-start table

For the architecture and principles behind the protocols themselves, read CLAUDE.md and the axiom files under .claude/rules/.

Greek Codex

Protocol	Greek	Meaning
Prothesis	πρόθεσις	Setting forth
Katalepsis	κατάληψις	Grasping, comprehension
Horismos	ὁρισμός	A bounding
Aitesis	αἴτησις	Request, inquiry
Analogia	ἀναλογία	Proportion
Periagoge	περιαγωγή	Turning-around
Euporia	εὐπορία	Way through, resourcefulness
Merismos	μερισμός	Apportionment
Epharmoge	ἐφαρμογή	Application, fitting
Elenchus	ἔλεγχος	Cross-examination, refutation
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