claude-code-hermit: Instructions file for Claude Code

Repository guidelines

Before changing a plugin, read its plugins/<slug>/AGENTS.md. Load only the guides for the work in scope. Local guides add constraints to these repository rules; detailed inventories and procedures belong in READMEs, docs, or skills. Keep AGENTS.md and CLAUDE.md independently readable, with no extra instruction-file hop between harnesses.

Repository and architecture

• Seven independently versioned Claude Code plugins live under plugins/<slug>/, each owning its manifest, code, templates, tests, and changelog. .claude-plugin/marketplace.json is the sole catalog; README.md is the marketplace overview.
• Hermit runs continuously inside Claude Code. Evaluate features for downstream chat operators, not only this repository's development workflow. Do not use this development hermit's session history as evidence of core feature utility. Check Claude Code documentation and the plugin catalog before adding a capability; when one already covers it, link to it instead of reimplementing.
• Domain plugins depend on core. Core discovers siblings generically from metadata; it must not import siblings, hardcode their slugs in logic, or branch on their installation. Siblings use core commands with an appropriate version floor instead of importing core code. Preserve ${CLAUDE_PLUGIN_ROOT}/../*/.claude-plugin/plugin.json discovery.
• Domain plugin skills/, agents/, state-templates/, and docs/ carry core-facing terminology; sweep them when core wording changes.
• Keep required_core_version and requires in .claude-plugin/hermit-meta.json synchronized with plugin.json dependencies. Internal hermit.* extensions belong in hermit-meta.json. Raise min_claude_code_version when relying on newer host behavior; do not add old-host shims.

Authoring contracts

• Model-facing prose: Follow Anthropic's skill authoring guidance. After compaction Claude Code re-attaches only a skill's first 5,000 tokens, so the rules every run needs come first and conditional detail goes in supporting files linked directly from SKILL.md. Evaluate skills on every model intended to use them.
• Keep schemas, permissions, hook protocols, and command interfaces strict; keep operator-authored content flexible and upgrade-safe. Features default on except those requiring credentials/configuration, real per-invocation spend, or destructive actions. Cover new and existing installations.
• Skills state the present inputs, goal, workflow, and result. Keep history in changelogs or code comments and branch-specific detail in referenced sibling files. Use fully namespaced plugin agent references.
• Hook stdout, tool output, and skill-driven reads enter operator context. Use scripts for deterministic work and bounded log/database summaries; do not ask the model to read unbounded state or reproduce calculations. Print verdict-sized digests, and add always-loaded instructions only when their recurring behavioral value justifies the context cost.
• state-templates/CLAUDE-APPEND.md is installed product content, separate from development instructions. Describe behavior there without restating config values such as schedules, channel IDs, identity, or mode flags.
• Core's scripts/domain-hatch.ts and lib/domain-hatch/ own target resolution and state/hatch-options.json. Consumers use domain-hatch preflight, ensure-target, and sync-block; read those contracts before changing routing.
• Before changing plugin storage or routine registration, read the storage contract or routine authoring, respectively.