capture-rule

name	capture-rule
description	Capture a reusable, non-obvious project insight into the rules home where it will auto-inject in future sessions. Use when investigation or implementation surfaces knowledge worth persisting (a gotcha, a convention, the "why" behind a decision), or when the user asks to remember a project learning.
argument-hint	The insight to capture, and which repository it applies to.

Capture Rule

Route durable knowledge to the home where it will auto-inject when next relevant.

Step 1 — Qualify the insight

Capture only knowledge that is reusable and non-obvious from code, git history, or existing instruction files: gotchas, build/tooling quirks, design invariants, conventions, the "why" behind a decision.

Skip (and tell the user why) if it is: a one-off fact for this task only, already documented in the repo, or plainly derivable by reading the code. If it does not qualify, stop here.

Establish the target repository the insight is about. If unclear, infer from the files touched this session and confirm with the user.

Step 2 — Route to a home

Pick exactly one:

Insight is about…	Home
A specific repo's own code/tooling	that repo's .claude/rules/<slug>.md
Target-repo files, but the rule must live in the harness workspace	harness .claude/rules-ex/<slug>.md
The harness's own machinery	harness .claude/rules/<slug>.md (often grow harness-internals.md)
Personal/cross-project preference, feedback, or machine-local fact	auto-memory (MEMORY.md + memory/)

If the home is auto-memory, do not write a rule — tell the user it belongs in memory and stop.

Step 3 — Dedup

Search the chosen directory for an existing rule on the same topic. If one exists, update it instead of creating a new file. One topic = one file.

Step 4 — Write the rule

Use a kebab-case slug. The body below the frontmatter is exactly what gets injected — keep it focused and imperative.

.claude/rules (native, lives in the repo it governs):

• paths: is optional. Omit it to inject on every file touched in that repo; add repo-relative globs to scope it. Matching is permissive (an implicit leading **/ is tried), so src/** also matches nested paths.

---
paths:
  - "src/**/*.ts"
---
<the insight, imperative and focused>

.claude/rules-ex (extended rules, lives in the harness workspace):

• paths: is required (a rule without it is skipped). Globs are workspace-relative — use .. to reach sibling repos. Matching is strict and root-anchored (no implicit **/); use ** for any depth. * also works as the repo-name segment itself, for an insight that applies to any sibling repo rather than one specific one.

---
paths:
  - ../<repo>/plugins/**/*.mjs
---
<the cross-cutting insight>

Cross-repo example (applies to every sibling repo, not just one):

---
paths:
  - ../*/.github/workflows/**
---
<an insight that applies to any repo's GitHub Actions workflows>

If the harness has .claude/rules/rules-ex-authoring.md or harness-internals.md, consult them for the full extended-rules mechanics before writing there.

Step 5 — Wrap up

Report the file path written or updated. Suggest committing it (Conventional Commits: docs: or chore:). No plugin version bump is involved — rules and memory are content, not plugin code.