Agent guide - Ronce Racine

Doc aimed at an agent (LLM) that works on this repo or uses it to equip another project. For the conceptual detail, see docs/architecture.md.

What this repo is

Canonical source of generic Claude Code config (project-agnostic), installable in any repository: rules/ (always-on, by paths) · skills/ (on-demand workflows) · hooks/ (settings.json scripts - granular, one hook per .ts file) · agents/ (subagents) · scripts/ (executable detections). CLI: install.ts is the single tool (all families; rules-only via --rules-only).

Hook composition: several plugins observe the same event and PreToolUse updatedInput is last-wins. A hook that rewrites a command MUST keep the original readable (trailing shell comment), must not rewrite when the rewrite buys nothing, and must never mask an exit code through a pipe. See hooks/README.md.

Non-negotiable rules

• Genericity: an artifact here contains no project coupling (crate/script/path name, imposed tracker, imposed stack). If useful but coupled → split: the generic principle here, the tooling in the project repo. A precedence note ("if this repo has a specific X skill, it wins") is expected, and states what the project variant knows that this one cannot - without naming an example project.
• Language: English (code identifiers may remain as-is). Correct accents, "siliceum" always lowercase.
• Commits: type(scope): description format (feat|fix|refactor|test|docs|chore), 1st line ≤ 72 chars, never mention Claude/AI/LLM. Ask for confirmation before any commit.
• Pre-commit validation: npm test must be green (see Harness).

Using this repo on another project

npx ronce-racine plan    <repo>          # detects the stack, PROPOSES (read-only)
npx ronce-racine install <repo> [--all]  # copies relevant rules/skills/hooks/agents + lockfile
npx ronce-racine install <repo> --yes    # no selector: the pre-checked set (CI, non-TTY)
npx ronce-racine install <repo> --pick <kind:name...>  # exactly these tokens, nothing else
npx ronce-racine check   <repo> [--strict]  # drift vs canonical (soft, or blocking)
npx ronce-racine detach  <repo> <kind:name> # excludes a customized artifact from control
npx ronce-racine uninstall <repo> [--dry-run] # removes what the lockfile records, and only that

Detail: docs/adopting-a-repo.md. The lockfile <repo>/.claude/.ronce-racine.json tracks what is managed + the source package version and content hash.

Adding / modifying a hook

Hooks live in hooks/: one .ts file per logical hook. Each file must carry in its header JSDoc:

 * @version X.Y.Z          (semver)
 * @last-reviewed YYYY-MM-DD

The tools/skills.ts hooks harness checks these two fields on every npm test. Available wirings per hook:

The install.ts installer merges the hook wirings for the selected hooks into <repo>/.claude/settings.json (deep-merge by event + matcher, idempotent, writes a settings.json.bak backup, preserves unrelated settings).

Modifying / adding a skill

1. Read docs/writing-a-skill.md (contract) + docs/templates/SKILL.template.md (model).
2. The skill must be generic, follow the standard sections, and have a name + description frontmatter ("Use when …", third person, describes WHEN not HOW) + version (semver) + metadata.last-reviewed + category.
3. Body < 500 lines; beyond that → progressive disclosure (reference/*.md). Runnable detection → scripts/*.ts (never .sh). Output template → templates/.
4. Bump version + last-reviewed, add a line to the ## Changelog.
5. npm test green, then update docs/catalog.md (the README has no per-skill table).

Modifying / adding a rule

1. Read docs/writing-a-rule.md + docs/templates/rule.template.md.
2. Frontmatter: paths (globs; omit = always-on) + version + metadata.last-reviewed. Body: imperative, short bullets, no magic numbers.
3. npm test green + the rules table in README.md.

Harness (npm test)

The exact chain is package.json's test script - read it there rather than from a list that goes stale. It runs the tools/skills.ts subcommands (validate, triggers, routing, rules, scripts, hooks, agents, templates, docs), then tools/eval-lint.ts, tools/portability.ts, and finally vitest run. All must pass. Highlights:

• validate - frontmatter, version, sections, reference//scripts//templates/ links, depth ≤ 1.
• triggers / routing - routing discriminability (each quoted trigger classifies its skill in the top-3; each routing case beats the neighbours it declares).
• hooks - presence and validity of @version (semver) and @last-reviewed (ISO date) in each hooks/*.ts.
• docs - documented claims checked against what the installer actually does.
• eval-lint - a gate whose literal its own prompt hands over.

Useful commands: npm run skills:list, npm run skills:triggers, npm run rules:validate, npm run typecheck.

Layout

rules/        skills/<name>/SKILL.md (+ reference/ scripts/ templates/)
hooks/        agents/         scripts/
install.ts     (user-facing CLI, at the root: commands + argument parsing)
src/           (the CLI split up: paths, lock, catalog, detect, settings, selector, uninstall)
tools/         (internal harnesses, all via tsx: skills.ts, mutations.ts, portability.ts,
               build.ts, and the eval family: eval.ts, eval-tasks.ts, eval-grade.ts,
               eval-judge.ts, eval-report.ts, eval-lint.ts)
docs/         templates/      README.md  AGENTS.md

Common pitfalls

• Do not summarize a skill's workflow in its description (the agent would follow the summary instead of the skill).
• In a SKILL.md, only reference existing reference//scripts//templates/ files (the harness checks).
• No .sh: every script/hook is .ts run by tsx.
• Any discipline still coupled (RLS, compiled queries, conventions of a specific framework) stays on the project side, not here.