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, "Write the email announcing next week's meeting":

This is an illustration, not a run result: which items come up, and how, varies with the model and the person. A decision the AI makes alone is not wrong for that; what differs is whether it passed through you.

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), deficit recognition (/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

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

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.

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. 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.

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.

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

{
  "name": "epistemic-protocols",
  "description": "A domain-free metalanguage of structured types and morphisms that moves the cognitive load of human-AI collaboration from recall to recognition: unknowns are elicited into utterance and answered or recognized where they bind, before local misalignment hardens into system-wide rework.",
  "owner": {
    "name": "jongwony"
  },
  "plugins": [
    {
      "name": "katalepsis",
      "source": "./katalepsis",
      "description": "Check that something in play — code, a document, a result — is actually understood, step by step — /grasp (κατάληψις: a grasping firmly)"
    },
    {
      "name": "aitesis",
      "source": "./aitesis",
      "description": "Collect what the AI can reach on its own, hand back the rest as the user's unknown — /inquire (αἴτησις: a requesting)"
    },
    {
      "name": "analogia",
      "source": "./analogia",
      "description": "Check what an analogy, framework, or earlier design carried to a case actually supports — /ground (ἀναλογία: a proportion)"
    },
    {
      "name": "periagoge",
      "source": "./periagoge",
      "description": "Align concrete cases first, then name what they share — /induce (περιαγωγή: turning-around)"
    },
    {
      "name": "euporia",
      "source": "./euporia",
      "description": "Find the decisions a rough intent turns on, traced from your own material and the domain's usual decisions — /elicit (εὐπορία: way through)"
    },
    {
      "name": "merismos",
      "source": "./merismos",
      "description": "Apportion an autonomous goal into coarse execution units and derive each unit's completion conditions — /apportion (μερισμός: an apportionment)"
    },
    {
      "name": "epharmoge",
      "source": "./epharmoge",
      "description": "Check that a result fits everywhere it lands — misfits and omissions on one sheet — /contextualize (ἐφαρμογή: an application)"
    },
    {
      "name": "horismos",
      "source": "./horismos",
      "description": "See what a task needs decided, then choose what to keep or entrust — /bound (ὁρισμός: a bounding)"
    },
    {
      "name": "epistemic-cooperative",
      "source": "./epistemic-cooperative",
      "description": "Utility skills layered on top of the core protocols; each utility skill's own SKILL.md carries its contract."
    },
    {
      "name": "anamnesis",
      "source": "./anamnesis",
      "description": "Resolve vague recall into recognized context — one session, or a line of work, topic, or settled concept across several — /recollect (ἀνάμνησις: recollection)"
    },
    {
      "name": "hyphegesis",
      "source": "./hyphegesis",
      "description": "Settle how work with several lines of thinking runs before starting it — /conduct (ὑφήγησις: a leading-the-way)"
    },
    {
      "name": "proplasma",
      "source": "./proplasma",
      "description": "Compare throwaway probes of candidate directions before committing to one — /preview (πρόπλασμα: a preliminary clay model)"
    },
    {
      "name": "hypotyposis",
      "source": "./hypotyposis",
      "description": "Discover a form by marking what does not fit on concrete sketches until one is recognized — /sketch (ὑποτύπωσις: an outline, a first sketch)"
    },
    {
      "name": "heuresis",
      "source": "./heuresis",
      "description": "Widen an empty or prematurely narrowed field of ideas before choosing — /ideate (εὕρεσις: finding/invention)"
    },
    {
      "name": "route",
      "source": "./route",
      "description": "Route the accumulated session context to the core protocol whose deficit it shows — /route (per-prompt hook directive)"
    }
  ]
}