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), sosrc/**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.