hermitd: Instructions file for Claude Code

hermitd (monorepo)

This repo is a multi-plugin Claude Code marketplace. Seven plugins ship from plugins/<slug>/, each with its own CLAUDE.md, CHANGELOG.md, and tests/. .claude-plugin/marketplace.json is the only marketplace; the root README is the canonical hermit pitch.

Always launch Claude Code from this repo's root. A plugin dir's own .claude-plugin/ would load the plugin under test as the project plugin.

Conventions

• 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.
• Repository-wide tests: use bun run test from the root with Bun 1.4 or newer. It handles plugin working directories, bounded parallelism, and shared root tests. For narrower changes, run the documented suite inside the plugin dir (bun test for core, HA, and Feed; bash tests/run-all.sh for Dev, Fitness, Forge, and Scribe).
• Independent versioning, tag <slug>--v<X.Y.Z>. Domain plugins declare core compat as required_core_version: ">=X.Y.Z" in .claude-plugin/hermit-meta.json, mirrored by requires there and dependencies in plugin.json; required_core_version is what doctor-check.ts reads. Update all three together. All hermit-internal manifest extensions (hermit.*) live in hermit-meta.json.
• CC-version-gated work bumps the floor, never shims around it. When a change depends on Claude Code behavior introduced at a version, raise that plugin's min_claude_code_version in hermit-meta.json; no feature detection or fallback paths for older CC.
• Dependency direction is one-way: domain plugins depend on core; core never imports a sibling, hardcodes a sibling slug in logic, or branches on one being installed. It discovers siblings generically (name-contains-hermit) and consumes only what they declare in hermit-meta.json. Siblings can't import core either: shared logic ships as a hermitd-run verb behind a required_core_version floor.
• Reuse native Claude Code features before building. Check the docs (https://code.claude.com/docs) and plugin catalog for a feature that already covers a capability; on overlap, link to it instead of reimplementing.
• Ship mechanism, not policy (all plugins): contracts stay strict, content stays loose. An installed hermit belongs to its operator, so give skills data + goal + voice and let the model compose, and anything operator-editable must survive hermit-evolve. Contract list, extension points, and how skill text is written: plugins/hermitd/CLAUDE.md § Authorship layers.
• Ship standard: default-on, research preview. Default off only for features needing an operator credential/config, real per-invocation spend, or that are destructive.
• Agent references in skill text use the full namespaced form (<plugin>:<agent-name>). The harness namespaces bare names at load, so a bare name in skill text fails with "Agent type not found".
• Domain plugins carry core-facing wording in skills/, agents/, state-templates/, and docs/; when core terminology changes, sweep all of them.
• Token discipline (all plugins): hook stdout, skill-driven Reads, helper-script output, and native tool results all land in the operator's context, and every tool call re-reads that context from cache, so cache traffic dominates an always-on hermit's spend. Print verdict-sized digests; front unbounded surfaces (JSONL logs, DBs) with a script that returns a bounded summary. Always-loaded files (this one, plugin CLAUDE.mds, CLAUDE-APPEND blocks) are paid every session and re-seeded into every subagent, so a new bullet has to change behavior often enough to earn its place. Pattern and examples: plugins/hermitd/CLAUDE.md § Development.