Skip to content

ONBOARDING.md

Latest commit

 

History

History
154 lines (124 loc) · 12.9 KB

ONBOARDING.md

File metadata and controls

154 lines (124 loc) · 12.9 KB
Raw

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 /epistemic-cooperative:triage ████░░░░░░░░░░░░░░░░ 4x route incoming findings to a protocol /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

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/AGENTS.md — what the portable premise collection is and what each document covers; start here (~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
  • /prothesis:frame — assemble analytical lenses (category theory, type theory, operational semantics) for protocol-level changes
  • /analogia:ground — validate abstract-concrete mappings
  • /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
  • /task-workflow:ship — one-shot commit + push + PR + task registration. Optional convenience; lives in the external jongwony/ClaudePanel.spoon plugin, not this repo. Plain git push + gh pr create also works.

Contribution Workflow

  1. Scope — read the premise document(s) for the area you're touching (premise/AGENTS.md routes by concern), plus .claude/rules/project-profile.md and .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; /prothesis:frame for protocol-level changes that warrant multi-lens scrutiny
  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 — /task-workflow:ship for the one-shot flow if you have that external plugin installed, or fall back to plain git push -u origin <branch> + gh pr create; PR body language is Korean (hook-enforced)
  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
  • 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/AGENTS.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