Skip to content

Latest commit

 

History

History
88 lines (74 loc) · 4.45 KB

CLAUDE.md

File metadata and controls

88 lines (74 loc) · 4.45 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository ships

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.

Commands

  • make validate — runs validate-version, validate-translations, validate-plugin, validate-skills, check-diff.
  • make test — smoke-tests scripts/install-local.sh with stubbed harness CLIs and --dry-run, asserting on the snapshot it builds. No harness is touched.
  • make validate-plugin and make validate-skills shell out to scripts outside this repo under $HOME/.codex/skills/.system/. They fail without Codex installed; override with PLUGIN_CREATOR_ROOT / SKILL_CREATOR_ROOT.
  • After changing skills/ or hooks/: run make validate, then make install-local and 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 (via npx, needs network) plus shellcheck on scripts/*.sh. Kept out of make validate so validation stays offline; CI runs both.
  • make remove-local uninstalls from every harness.

Versioning invariants

  • VERSION and four manifests must be byte-identical: .codex-plugin/plugin.json, .github/plugin/plugin.json, .claude-plugin/plugin.json, gemini-extension.json. scripts/check-version.js fails CI when they drift. This is the most common way to break the build.
  • VERSION never carries a leading v; 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 main requires a version bump, docs-only changes included.
  • The bump is its own commit: chore(release): bump version to X.Y.Z.
  • .github/workflows/release.yml tags and publishes on push to main. It fails on purpose when vX.Y.Z already points at another commit — bump again rather than moving a released tag.

Hooks

  • hooks/hooks.json (Codex/Claude/Gemini) and hooks/copilot-hooks.json both run hooks/semver-context.js on SessionStart and SubagentStart.
  • Hook commands must be POSIX sh, not bash. Bash-only substitutions have broken hooks under /bin/sh twice.
  • hooks/hooks.json must reference CODEX_PLUGIN_ROOT in both command and commandWindows for both events; hooks/copilot-hooks.json must reference PLUGIN_ROOT in both bash and powershell. check-version.js enforces both files.
  • .codex-plugin/plugin.json must not declare a hooks key; Codex auto-detects hooks/hooks.json and the validator rejects the duplicate.
  • Plugin-root resolution cascades CODEX_PLUGIN_ROOT → CLAUDE_PLUGIN_ROOT → ${extensionPath}; Copilot uses PLUGIN_ROOT. Windows paths are normalized with tr '\\' '/'.

Style

  • 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.jsonc because badge rows and long links legitimately exceed 80 — the wrap is a convention, not a linted rule. MD024 and MD051 are relaxed for the per-harness repeated headings and the emoji anchors.
  • .shellcheckrc disables SC1007; CDPATH= cd -- is intentional.
  • All repository content, commit messages and PR descriptions are in English.

Git workflow

  • Branches: codex → PR → dev → PR → main. dev is the working branch.
  • Conventional Commits, English, scoped (hooks, scripts, codex, ci, docs, semver, release).
  • The four translations in docs/README.*.md must be updated alongside the canonical README.md. scripts/check-translations.js compares the structural skeleton (heading levels, fenced code blocks, images) — it does not check the prose, so a stale translation with intact structure still passes.