harness-anchor: Instructions file for Claude Code

harness-anchor — Contributor & AI Collaborator Guidelines

If You Are an AI Agent Editing This Plugin

Stop. Read this before doing anything.

harness-anchor is behaviour-shaping infrastructure — its skills and hooks govern how OTHER agents behave in OTHER repositories. Edits here have outsized impact. A poorly tuned SKILL.md description will fail to trigger in real sessions; a too-fat SessionStart injection wastes context budget on every conversation; an over-eager PostToolUse hook blocks productive work.

Your job is to protect the user from your own enthusiasm. Do not:

1. Add features that aren't in the maintainer's approved plan (kept locally under ~/.claude/plans/)
2. Rewrite skill descriptions to "comply with Anthropic best practices" without evals proving improvement
3. Add MCP server dependencies — this plugin is zero-dependency by design (bash + git)
4. Add block behavior to hooks — the entire design is warn-only (see plan §"决策")
5. Bundle changes to unrelated layers in one commit

Design Invariants (do not break)

1. Warn-only hooks. No PostToolUse / Stop / UserPromptSubmit hook may produce JSON with "permissionDecision": "deny" or "stopReason". PostToolUse / UserPromptSubmit / SessionStart surface additionalContext for self-correction; the Stop event has no additionalContext channel, so its reminder uses systemMessage (still non-blocking — never decision: "block"). PreCompact likewise reaches only the user (a marker file + systemMessage) — the agent gets no turn before compaction runs, so the actionable pre-compaction warning lives in the PostToolUse watermark stages.
2. SessionStart token budget ≤ 3000 tokens. Roughly 12000 chars of injected content. Hard-truncate with a pointer to the on-disk file. The meta-skill body is injected slimmed (frontmatter stripped; conditional regions dropped when their gate doesn't match — cpp-only by project type, os-<name> by HA_OS platform) — headroom belongs to the project-specific TOC/handoff, not to a fatter generic body.
3. Subagents are single-level. Every subagent prompt must end with: "Do not invoke other subagents from this one."
4. State files are git-tracked by default. .harness-anchor/ (error log dir) is the only gitignored runtime path.
5. C/C++ components stay dormant in non-C/C++ projects — through two different gates, and only one of them is cpp-detect.sh. That script is the mechanical gate: it sets the banner's project type, decides whether the meta-skill's cpp-only regions are injected at all, and makes /cpp-init (exit 3) and /sanitize refuse outright. It does not gate skill loading — skills are selected by description matching, and nothing consults cpp-detect.sh at the moment one loads. So the gate on the skills is their own frontmatter: every skills/cpp-* description must scope itself to C/C++ within its first 80 characters, the window invariant #6 says carries the load. That string is the only thing between a clang-tidy skill and a Python repo. Enforced by validate-anchor [3-4/12].