# Contributing to Epistemic Protocols

## About This Project

Epistemic Protocols is a Claude Code plugin marketplace for epistemic dialogue — protocols that structure specific decision points in human–AI interaction. The protocol table in `README.md` is the handbook (browse by cluster, command lookup); see `CLAUDE.md` for architecture.

Contributors here design, refine, and verify the protocols themselves. This guide is for you.

## How the Maintainer Works on This

Based on jongwony's last 30 days (64 sessions):

Work Type Breakdown:
  Improve Quality   ████████░░░░░░░░░░░░  40%   PR review loops, worktree checkouts, protocol audits
  Plan Design       ██████░░░░░░░░░░░░░░  32%   Protocol design debates, elicitation, direction analysis
  Build Feature     ███░░░░░░░░░░░░░░░░░  13%   New skill implementation, handoff-driven builds
  Debug Fix         ██░░░░░░░░░░░░░░░░░░   9%   Codex invocation fixes, Ink rendering breakage
  Write Docs        █░░░░░░░░░░░░░░░░░░░   6%   CLAUDE.md progressive disclosure, conventions

Protocols the Maintainer Dogfoods:
  /epistemic-cooperative:review-loop  ████████████████████  19x   iterative PR review loop (+ codex reviewer)
  /euporia:elicit                     █████░░░░░░░░░░░░░░░   5x   design-dimension elicitation
  /formal-review                      ████░░░░░░░░░░░░░░░░   4x   formal-triple review of protocol changes
  /release                            ████░░░░░░░░░░░░░░░░   4x   CalVer tag + draft release
  /gh-address-comments                ███░░░░░░░░░░░░░░░░░   3x   PR feedback loop
  /codex-plus:codex                   ███░░░░░░░░░░░░░░░░░   3x   cross-vendor second opinion

Contributors are expected to dogfood the protocols they edit — the list above is what that looks like in practice, not a mandated workflow.

## Your Setup Checklist

### Environment
- [ ] **Node.js 22+** — CI pins Node 22; `zlib.crc32` is used in packaging
- [ ] **gh CLI** authenticated — required for PR, CI, and release workflows
- [ ] **Claude Code** installed with this repo added via `/add-dir`
- [ ] **`epistemic-cooperative`** plugin installed if you want `/onboard` — it is opt-in for the default installer: `claude plugin install epistemic-cooperative@epistemic-protocols`
- [ ] Understand that plugin code uses only the **Node.js standard library** — no runtime dependencies
- [ ] **Lean verification** — For local verification of Definition blocks written in Lean 4, install the toolchain pinned in `lean-toolchain` and make both `lean` and `lake` available. `/verify` checks these blocks and their proofs when the tools are reachable; otherwise it warns that Lean verification was skipped. CI requires these checks to pass. See [Lean Notation](docs/structural-specs.md#lean-notation).

### Repository
- [ ] Clone `https://github.com/jongwony/epistemic-protocols`
- [ ] Run `node .claude/skills/verify/scripts/static-checks.js .` to confirm your environment passes
- [ ] Run `node --test scripts/package.test.js anamnesis/scripts/hypomnesis-write.test.mjs` to confirm the tests pass

### Core Docs to Read (in order)
- [ ] `CLAUDE.md` — Northstar, Settled Directions registry, Protocol Index routing table, Runtime Contract, verification commands (~15 min)
- [ ] `premise/README.md` — how the premise layer is adopted and verified; each document and the moment that calls for it is indexed in `route/scripts/route-premise.mjs` (~2 min)
- [ ] `premise/recognition-and-authority.md`, `premise/interaction-factorization.md`, `premise/gate-design.md` — the foundational principles and Gate Integrity, in their portable form; these are the source of truth, with no in-repo restatement (~10 min)
- [ ] `premise/instruction-authoring.md` — the derived principles governing how instructions and durable records are written
- [ ] `premise/tiering-and-scope.md` — the tier vocabulary plus the architectural principles that hold without presupposing a protocol layer, including the Epistemic Completeness Boundary that marks where epistemic judgment ends and substrate enforcement begins; the ones that do presuppose protocols, and this repo's own instances of the portable ones, live in `.claude/principles/architectural-principles.md` (T2-T3, lazy-load)
- [ ] `.claude/principles/safeguards.md` — Safeguard-tier principles (LESS important as models improve); demoted from `.claude/rules/` (authoring/verify-time, not per-turn) (~5 min)
- [ ] `.claude/principles/AGENTS.md` — demotion zone overview, index of current principle files
- [ ] `docs/structural-specs.md` — SKILL.md Formal Block Anatomy (FLOW, MORPHISM, TYPES, PHASE TRANSITIONS, LOOP, TOOL GROUNDING, MODE STATE, COMPOSITION)
- [ ] `.claude/skills/verify/references/verification.md` — why the non-obvious checks exist and what to do when one fires (the check inventory itself is `static-checks.js`)
- [ ] `.claude/skills/verify/references/co-change.md` — ripple patterns (protocol change → plugin.json version bump → /verify)

### Protocols to Use While Contributing
- [ ] `/verify` — run before every commit; the checks it runs are defined in `static-checks.js`
- [ ] `/aitesis:inquire` — when a redesign feels under-specified
- [ ] `/euporia:elicit` — elicit the important design dimensions together before locking in a direction
- [ ] `/horismos:bound` — define epistemic boundaries for multi-domain refactors
- [ ] `/analogia:ground` — audit what an abstract-concrete mapping licenses about an account already in play
- [ ] `/epharmoge:contextualize` — post-execution applicability check against actual project context
- [ ] `/merismos:apportion` — cuts an autonomous goal into coarse units at cited seams before the run begins, judges each unit's fit against one execution horizon, and closes each unit — on a derived completion condition, on a recorded acceptance where none compiles, or on a recorded reservation where a judgment rather than a check settles it

## Contribution Workflow

1. **Scope** — read the premise document(s) for the area you're touching (the index in `route/scripts/route-premise.mjs` routes by moment), plus `.claude/rules/editing-conventions.md` for this repo's own bindings; run `/horismos:bound` if multiple domains are in play
2. **Design** — `/aitesis:inquire` at the point of locking in a direction, so what the decision rests on is checked first — its assumptions and missing facts, not whether every alternative or trade-off was considered, which stays yours to raise
3. **Edit** — `skills/<protocol>/SKILL.md` is the source of truth; bump version in `.claude-plugin/plugin.json` on any change (see `.claude/skills/verify/references/co-change.md`)
4. **Verify** — `/verify` must pass all static checks
5. **Test** — `node --test scripts/package.test.js anamnesis/scripts/hypomnesis-write.test.mjs`
6. **Commit** — `type(scope): Korean description` (types: feat / fix / refactor / style; scope = plugin name)
7. **Ship** — `git push -u origin <branch>` then `gh pr create`; PR body language is Korean
8. **Address review** — run `/formal-review` for the fixed formal-triple review of protocol changes, which posts a single consolidated PR comment, and `/review-loop` for code review; use `/gh-address-comments` to respond to posted comments
9. **Merge** — the maintainer merges manually via web after final review

## Conventions

- **Notation in formal blocks**: `→` (function), `∥` (parallel), `[Tool]` suffix for external operations in PHASE TRANSITIONS
- **Verb usage in TOOL GROUNDING**: `call` for tool references, `present` for gate operations (tool-agnostic per Semantic Autonomy, `premise/interaction-factorization.md`)
- **Branch naming**: `feat/name-protocol`, `refactor/description`, `fix/description`; where an issue anchors the unit, its identifier follows the type — `feat/<issue-id>-description` — and one branch carries one unit (`CLAUDE.md` §Settled Directions, Intent binding)
- **Release tags**: CalVer `v{YYYY}.{MM}.{DD}[.{N}]`; tag push triggers `release.yml` draft
- **README sync**: `README.md` and `README_ko.md` must stay in sync
- **SKILL.md self-containment**: No external references to axiom identifiers, rule file paths, or contributor-only concepts — end users see only SKILL.md via the plugin system

## Prime Directives

Two principles to internalize before your first PR:

- **Plugin Encapsulation** — Each `SKILL.md` is self-contained, and runtime protocol behavior must be inscribed in it. Documenting something in `CLAUDE.md` or `.claude/rules/` alone does not affect user-facing behavior (`premise/instruction-authoring.md` §Audience Reach states the general form; `.claude/principles/architectural-principles.md` §Plugin Encapsulation carries this repo's binding).
- **Direction over Accumulated Workload** — Contributor authoring labor converges toward zero under AI-assisted editing; structural misalignment accumulates and pollutes all downstream work. When a refactor is theoretically justified, prior commits are not protection from invalidation. Verification labor remains bounded and must be budgeted explicitly (`premise/instruction-authoring.md` §Direction over Accumulated Workload).

## Get Started

1. Clone the repo and open it in Claude Code
2. Read `CLAUDE.md` end-to-end
3. Read `premise/README.md`, then `premise/recognition-and-authority.md`, `premise/interaction-factorization.md`, and `premise/gate-design.md` (the axiom and gate-design premises live here)
4. Run `/verify` to confirm your environment
5. Pick a protocol whose `SKILL.md` interests you and read it alongside `docs/structural-specs.md`
6. Browse recent merged PRs to see the actual pattern of contribution

<!-- INSTRUCTION FOR CLAUDE: A new contributor to epistemic-protocols just
pasted this guide. You're their onboarding buddy for an axiom-heavy,
protocol-design-heavy contributor project — warm, precise, not lecture-y.

Open with a warm welcome. Then: "This project is a Claude Code plugin
marketplace for epistemic dialogue protocols. Contributors here design and
refine protocols themselves, using the protocols. Let's get you oriented."

Self-referential entry-point routing (offer this before the Setup Checklist):
the protocols in this repo are themselves the right tool for onboarding onto
this repo — running one is the fastest way to experience what the contributor
will be contributing to. Ask the contributor which stance best matches their
current situation, route them to the matching protocol, then resume the
standard flow afterwards:

- First encounter with these protocols, no prior context → `/onboard`
  (epistemic-cooperative) for a quick recommendation plus scenario-trial-quiz
  walkthrough
- Wants comprehension of the project itself verified → `/grasp` (katalepsis)
  over `CLAUDE.md` or a specific `SKILL.md` they just read
- Already has a personal Claude Code workflow and wants this project mapped
  onto it → `/ground` (analogia), with their existing usage as the concrete
  domain and a familiar account of this project's protocols as the abstract domain; audit the conclusions that comparison supports
- Needs a fast when-to-use-which-protocol reference → the protocol table in `README.md`, or the `route` plugin's session-start table
  (epistemic-cooperative)
- Prefers to go straight to environment setup → skip routing, proceed to
  Setup Checklist

After the chosen protocol completes (or if the contributor skips), check
what's already in place against the Setup Checklist (Environment, Repository,
Core Docs, Protocols to Use), using markdown checkboxes — [x] done, [ ] not
yet. Lead with what they already have. One sentence per item, all in one
message.

Offer to help with each unchecked item in order, starting with Environment,
then Repository, then pointing them at the Core Docs to read in the listed
order. For the Protocols to Use list, explain that these are invoked via
slash commands in Claude Code. Most are defined in this very repo, so the
contributor will use them while editing the same protocols they're
contributing to. Any entry rendered as an external link lives in a
separate plugin repo and is optional — contributors can always fall back
to plain git/gh commands for those steps.

After setup, walk through Contribution Workflow, Conventions, and Prime
Directives briefly. Offer to open a recent merged PR together to show the
actual contribution pattern.

Don't invent sections that aren't in the guide. The usage stats reflect the
maintainer's personal dogfooding — don't extrapolate them into a mandated
workflow. -->