This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
A portable Semantic Versioning 2.0.0 rule pack for five agent harnesses (Codex, Claude Code, Gemini CLI, GitHub Copilot CLI, OpenCode/Cursor). The product is Markdown and JSON, not a library. There is no build and no test suite.
AGENTS.md is the single source of the rule text: hooks/semver-context.js
injects it as session context, gemini-extension.json declares it as the
context file, and OpenCode/Cursor users copy it directly. Editing it changes
behavior in every harness at once.
make validate— runsvalidate-version,validate-translations,validate-plugin,validate-skills,check-diff.make test— smoke-testsscripts/install-local.shwith stubbed harness CLIs and--dry-run, asserting on the snapshot it builds. No harness is touched.make validate-pluginandmake validate-skillsshell out to scripts outside this repo under$HOME/.codex/skills/.system/. They fail without Codex installed; override withPLUGIN_CREATOR_ROOT/SKILL_CREATOR_ROOT.- After changing
skills/orhooks/: runmake validate, thenmake install-localand open a fresh session in the target harness to confirm the context injection actually landed. Static validation alone does not prove a hook works. make lint—markdownlint-cli2(vianpx, needs network) plusshellcheckonscripts/*.sh. Kept out ofmake validateso validation stays offline; CI runs both.make remove-localuninstalls from every harness.
VERSIONand four manifests must be byte-identical:.codex-plugin/plugin.json,.github/plugin/plugin.json,.claude-plugin/plugin.json,gemini-extension.json.scripts/check-version.jsfails CI when they drift. This is the most common way to break the build.VERSIONnever carries a leadingv; git tags do (v0.2.6).- Pre-1.0 policy for this repo, also stated in
README.md: a breaking change to a published contract (hook event/command shape, skill name or frontmatter, manifest keys, dropping a harness) bumps MINOR; everything else bumps PATCH. - Every merge into
mainrequires a version bump, docs-only changes included. - The bump is its own commit:
chore(release): bump version to X.Y.Z. .github/workflows/release.ymltags and publishes on push tomain. It fails on purpose whenvX.Y.Zalready points at another commit — bump again rather than moving a released tag.
hooks/hooks.json(Codex/Claude/Gemini) andhooks/copilot-hooks.jsonboth runhooks/semver-context.jsonSessionStartandSubagentStart.- Hook commands must be POSIX sh, not bash. Bash-only substitutions have
broken hooks under
/bin/shtwice. hooks/hooks.jsonmust referenceCODEX_PLUGIN_ROOTin bothcommandandcommandWindowsfor both events;hooks/copilot-hooks.jsonmust referencePLUGIN_ROOTin bothbashandpowershell.check-version.jsenforces both files..codex-plugin/plugin.jsonmust not declare ahookskey; Codex auto-detectshooks/hooks.jsonand the validator rejects the duplicate.- Plugin-root resolution cascades
CODEX_PLUGIN_ROOT→CLAUDE_PLUGIN_ROOT→${extensionPath}; Copilot usesPLUGIN_ROOT. Windows paths are normalized withtr '\\' '/'.
- Markdown is hard-wrapped at ~80 columns (
AGENTS.md,README.md,skills/**/SKILL.md). Keep it that way. - JSON: 2-space indent, trailing newline.
MD013(line length) is off in.markdownlint-cli2.jsoncbecause badge rows and long links legitimately exceed 80 — the wrap is a convention, not a linted rule.MD024andMD051are relaxed for the per-harness repeated headings and the emoji anchors..shellcheckrcdisablesSC1007;CDPATH= cd --is intentional.- All repository content, commit messages and PR descriptions are in English.
- Branches:
codex→ PR →dev→ PR →main.devis the working branch. - Conventional Commits, English, scoped (
hooks,scripts,codex,ci,docs,semver,release). - The four translations in
docs/README.*.mdmust be updated alongside the canonicalREADME.md.scripts/check-translations.jscompares the structural skeleton (heading levels, fenced code blocks, images) — it does not check the prose, so a stale translation with intact structure still passes.