From 59dc2015902afc42c63dbd496c15a4e636fcdad5 Mon Sep 17 00:00:00 2001
From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com>
Date: Wed, 18 Feb 2026 05:35:53 -0500
Subject: [PATCH 1/2] docs: add @ file linking and .claude/rules/ guidance to
 plugin development docs

- Add File Linking & Memory Organization section explaining @ import syntax
- Document .claude/rules/ for always-active rules with path-specific frontmatter support
- Clarify that markdown links are inert; @ syntax is the correct way to link files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 AGENTS.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 373c328..b92bb03 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -150,6 +150,37 @@ Choose the implementation language based on complexity:
 
 **Key principle**: Simplicity beats sophistication. Use the simplest tool that solves the problem correctly.
 
+## File Linking & Memory Organization
+
+### `@` File Imports
+
+When linking to other files in CLAUDE.md or any rules file, **always use `@path/to/file` syntax** — never markdown links `[text](path)`. The `@` syntax is the official Claude Code import: it actually loads the file's content into context. Markdown links are inert text.
+
+```md
+# ✅ Correct — imports the file's content
+See @docs/setup.md for environment setup.
+
+# ❌ Wrong — just a text reference, nothing is loaded
+See [Setup](docs/setup.md) for environment setup.
+```
+
+### `.claude/rules/` for Always-Active Rules
+
+Place rules that should always be loaded into `.claude/rules/` — Claude Code auto-loads all `.md` files there with the same priority as CLAUDE.md. No `@` import needed.
+
+Rules files support YAML frontmatter to scope them to specific file patterns:
+
+```md
+---
+paths:
+  - "hooks/**/*.py"
+---
+# Hook Script Rules
+- All hooks must exit 0 (allow) or 2 (block)
+```
+
+Rules without `paths` frontmatter apply unconditionally. Use `.claude/rules/` over `@` imports when rules should always be active, not just when a specific file is referenced. Symlinks in `.claude/rules/` are supported — use them to share rules across repos.
+
 ## CI/CD
 
 ### Workflows

From 28e81de15387a2bc2779ba6f0465c84943309b00 Mon Sep 17 00:00:00 2001
From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com>
Date: Wed, 18 Feb 2026 15:03:50 -0500
Subject: [PATCH 2/2] fix: wrap long lines and generalize CLAUDE.md references

- Break lines 157, 169, 182 to stay under MD013 line_length limit
- Replace "CLAUDE.md" with "plugin documentation" for consistency
  since these docs live in AGENTS.md

Co-Authored-By: Claude <noreply@anthropic.com>
---
 AGENTS.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b92bb03..89910a7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -154,7 +154,10 @@ Choose the implementation language based on complexity:
 
 ### `@` File Imports
 
-When linking to other files in CLAUDE.md or any rules file, **always use `@path/to/file` syntax** — never markdown links `[text](path)`. The `@` syntax is the official Claude Code import: it actually loads the file's content into context. Markdown links are inert text.
+When linking to other files in plugin documentation or any rules file,
+**always use `@path/to/file` syntax** — never markdown links `[text](path)`.
+The `@` syntax is the official Claude Code import: it actually loads the
+file's content into context. Markdown links are inert text.
 
 ```md
 # ✅ Correct — imports the file's content
@@ -166,7 +169,9 @@ See [Setup](docs/setup.md) for environment setup.
 
 ### `.claude/rules/` for Always-Active Rules
 
-Place rules that should always be loaded into `.claude/rules/` — Claude Code auto-loads all `.md` files there with the same priority as CLAUDE.md. No `@` import needed.
+Place rules that should always be loaded into `.claude/rules/` — Claude Code
+auto-loads all `.md` files there with the same priority as the project's primary
+documentation. No `@` import needed.
 
 Rules files support YAML frontmatter to scope them to specific file patterns:
 
@@ -179,7 +184,10 @@ paths:
 - All hooks must exit 0 (allow) or 2 (block)
 ```
 
-Rules without `paths` frontmatter apply unconditionally. Use `.claude/rules/` over `@` imports when rules should always be active, not just when a specific file is referenced. Symlinks in `.claude/rules/` are supported — use them to share rules across repos.
+Rules without `paths` frontmatter apply unconditionally. Use `.claude/rules/`
+over `@` imports when rules should always be active, not just when a specific
+file is referenced. Symlinks in `.claude/rules/` are supported — use them to
+share rules across repos.
 
 ## CI/CD