Packages

usage_rules

0.1.6
1.2.6 1.2.5 1.2.4 1.2.3 1.2.2 1.2.1 1.2.0 1.1.0 1.0.3 1.0.2 1.0.1 1.0.0-rc.3 1.0.0-rc.2 1.0.0-rc.1 1.0.0-rc.0 0.1.26 0.1.25 0.1.24 0.1.23 0.1.22 0.1.21 0.1.20 0.1.19 0.1.18 0.1.17 0.1.16 0.1.15 0.1.14 0.1.13 0.1.12 0.1.11 0.1.10 0.1.9 0.1.8 0.1.7 0.1.6 0.1.5 0.1.4 0.1.3 0.1.2 0.1.1 0.1.0

A config-driven dev tool for Elixir projects to manage AGENTS.md files and agent skills from dependencies

HexDocs

Current section

42 Versions

Jump to
Readme
42 Versions
1 Dependency
Dependants
Files
Activity
Hide whitespace

Compare versions

5 files changed
+104 additions
-118 deletions
  @@ -5,6 +5,15 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline
5 5
6 6 <!-- changelog -->
7 7
8 + ## v0.1.6 (2025-06-06)
9 +
10 +
11 +
12 +
13 + ### Improvements:
14 +
15 + * add `--link-to-folder deps` option, and recommend its use
16 +
8 17 ## v0.1.5 (2025-06-06)
  @@ -14,6 +14,8 @@ We don't really know what makes great usage-rules.md files yet. Ash Framework is
14 14
15 15 One quick tip is to have an agent begin the work of writing rules for you, by pointing it at your docs and asking it to write a `usage-rules.md` file in a condensed format that would be useful for agents to work with your tool. Then, aggressively prune and edit it to your taste.
16 16
17 + Make sure that your `usage-rules.md` file is included in your hex package's `files` option, so that it is distributed with your package.
18 +
17 19 ## Key Features
18 20
19 21 1. **Dependency Rules Collection**: Automatically discovers and collects usage rules from dependencies that provide `usage-rules.md` files in their package directory
  @@ -32,7 +34,31 @@ This is particularly useful for projects using frameworks like Ash, Phoenix, or
32 34
33 35 ## Usage
34 36
35 - The main task `Mix.Tasks.UsageRules.Sync` provides several modes of operation:
37 + The main task `mix usage_rules.sync` provides several modes of operation:
38 +
39 + ### Standard usage (recommended)
40 +
41 + There are two standard ways to use usage_rules. The first, is to copy usage rules into your project. This allows customization and visibility into the rules. The second is to use the rules files directly from the deps in your `deps/` folder. In both cases, your rules file is modified to link to the usage rules files, as a breadcrumb to the agent.
42 +
43 + #### Copying into your project
44 +
45 + This will create a folder called `rules`, with a file per package that has a `usage-rules.md` file. Then it will link
46 + to those from you rules file.
47 +
48 + ```sh
49 + mix usage_rules.sync CLAUDE.md --all --link-to-folder docs
50 + ```
51 +
52 + #### Using deps folder
53 +
54 + This will add a section in your rules file for each of your top level dependencies that have a `usage-rules.md`. It is
55 + simply a breadcrumb to tell the agent that it should look
56 + in `deps/<package-name>/usage-rules.md` when working with
57 + that package. This will not overwrite your existing rules, but will append to it, and future calls will synchronize those contents.
58 +
59 + ```sh
60 + mix usage_rules.sync CLAUDE.md --all --link-to-folder deps
61 + ```
36 62
37 63 ### Combine specific packages
38 64 ```sh
  @@ -41,7 +67,7 @@ mix usage_rules.sync rules.md ash phoenix
41 67
42 68 ### Gather all dependencies with usage rules
43 69 ```sh
44 - mix usage_rules.sync rules.md --all
70 + mix usage_rules.sync CLAUDE.md --all
45 71 ```
46 72
47 73 ### List available packages with usage rules
  @@ -51,120 +77,57 @@ mix usage_rules.sync --list
51 77
52 78 ### Check status against a file
53 79 ```sh
54 - mix usage_rules.sync rules.md --list
80 + mix usage_rules.sync CLAUDE.md --list
55 81 ```
56 82
57 83 ### Remove packages from a file
58 84 ```sh
59 - mix usage_rules.sync rules.md ash --remove
85 + mix usage_rules.sync CLAUDE.md ash --remove
60 86 ```
61 87
62 88 ### Use folder links for better organization
63 89 ```sh
64 - mix usage_rules.sync rules.md ash phoenix --link-to-folder rules
90 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder rules
65 91 ```
66 92
67 93 ### Use @-style folder links
68 94 ```sh
69 - mix usage_rules.sync rules.md ash phoenix --link-to-folder rules --link-style at
95 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder rules --link-style at
96 + ```
97 +
98 + ### Link directly to deps files
99 + ```sh
100 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder deps
70 101 ```
71 102
72 103 ### Gather all dependencies with folder links
73 104 ```sh
74 - mix usage_rules.sync rules.md --all --link-to-folder docs
105 + mix usage_rules.sync CLAUDE.md --all --link-to-folder docs
75 106 ```
76 107
77 108 ## Advanced Features
78 109
79 110 ### Folder Links (`--link-to-folder`)
80 111
81 - The `--link-to-folder` option provides enhanced organization for managing large sets of usage rules. This feature is particularly valuable when working with Claude AI or other systems that benefit from modular file organization.
112 + Organizes usage rules into separate files for better management of large rule sets.
82 113
83 - **What it does:**
84 - - Creates individual `.md` files for each package in the specified folder
85 - - Generates a main file with markdown links (`[package usage rules](folder/package.md)`) by default
86 - - Can optionally use @-style links (`@folder/package.md`) with `--link-style at`
87 - - Maintains the same section markers for easy updates and status tracking
88 - - Works with all other options (`--all`, `--list`, `--remove`)
114 + **Options:**
115 + - `--link-style markdown` (default): `[ash usage rules](docs/ash.md)`
116 + - `--link-style at`: `@docs/ash.md` (optimized for Claude AI)
117 + - `--link-to-folder deps`: Links directly to `deps/package/usage-rules.md` (no file copying)
89 118
90 - **Link Style Options:**
91 - - `--link-style markdown` (default): Creates standard markdown links like `[ash usage rules](docs/ash.md)`
92 - - `--link-style at`: Creates @-style links like `@docs/ash.md`
93 -
94 - **Key Benefits:**
95 -
96 - **🤖 Claude AI Integration**
97 - - With `--link-style at`, Claude can efficiently reference specific package rules using the `@folder/file.md` syntax
98 - - Avoids hitting Claude's context limits when working with large rule sets
99 - - Allows Claude to selectively load only relevant rules for the current task
100 - - Enables better conversation flow by referencing specific documentation files
101 -
102 - **📁 Better Organization**
103 - - Large rule sets become easier to navigate and maintain
104 - - Individual files can be edited independently
105 - - Cleaner Git diffs when rules change
106 - - Modular structure scales well with project growth
107 - - Standard markdown links work well with any markdown viewer or documentation system
108 -
109 - **Example workflows:**
119 + **Examples:**
110 120 ```sh
111 - # Create organized rule files with markdown links (default)
112 - mix usage_rules.sync rules.md ash phoenix --link-to-folder docs
121 + # Create individual files with markdown links
122 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder docs
113 123
114 - # Create organized rule files with @-style links
115 - mix usage_rules.sync rules.md ash phoenix --link-to-folder docs --link-style at
124 + # Use @-style links for Claude AI
125 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder docs --link-style at
116 126
117 - # Gather all dependencies with folder organization
118 - mix usage_rules.sync rules.md --all --link-to-folder docs
127 + # Link directly to deps without copying
128 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder deps
119 129 ```
120 130
121 - **File structure created:**
122 - ```
123 - docs/
124 - ├── ash.md # Full Ash usage rules content
125 - └── phoenix.md # Full Phoenix usage rules content
126 - rules.md # Main file with links
127 - ```
128 -
129 - **Main file (`rules.md`) contains (markdown style - default):**
130 - ```markdown
131 - <-- usage-rules-start -->
132 - <-- ash-start -->
133 - ## ash usage
134 - [ash usage rules](docs/ash.md)
135 - <-- ash-end -->
136 - <-- phoenix-start -->
137 - ## phoenix usage
138 - [phoenix usage rules](docs/phoenix.md)
139 - <-- phoenix-end -->
140 - <-- usage-rules-end -->
141 - ```
142 -
143 - **Or with @-style links (`--link-style at`):**
144 - ```markdown
145 - <-- usage-rules-start -->
146 - <-- ash-start -->
147 - ## ash usage
148 - @docs/ash.md
149 - <-- ash-end -->
150 - <-- phoenix-start -->
151 - ## phoenix usage
152 - @docs/phoenix.md
153 - <-- phoenix-end -->
154 - <-- usage-rules-end -->
155 - ```
156 -
157 - **Individual files (`docs/ash.md`) contain:**
158 - ```markdown
159 - # Ash Framework Usage Rules
160 -
161 - Use `list_generators` to list available generators when available...
162 - [Full usage rules content here]
163 - ```
164 -
165 - **Working with Claude:**
166 - When using `--link-style at`, Claude can intelligently load specific package rules by following the `@docs/package.md` links, making your conversations more focused and efficient. The default markdown links work well with standard documentation systems and any markdown viewer.
167 -
168 131 ## Installation
169 132
170 133 ### With Igniter
  @@ -6,7 +6,7 @@
6 6 {<<"GitHub">>,<<"https://github.com/ash-project/usage_rules">>},
7 7 {<<"Website">>,<<"https://ash-hq.org">>}]}.
8 8 {<<"name">>,<<"usage_rules">>}.
9 - {<<"version">>,<<"0.1.5">>}.
9 + {<<"version">>,<<"0.1.6">>}.
10 10 {<<"description">>,
11 11 <<"A dev tool for Elixir projects to gather LLM usage rules from dependencies">>}.
12 12 {<<"elixir">>,<<"~> 1.18">>}.
  @@ -8,7 +8,7 @@ defmodule Mix.Tasks.UsageRules.Sync.Docs do
8 8
9 9 @spec example() :: String.t()
10 10 def example do
11 - "mix usage_rules.sync rules.md ash ash_postgres phoenix"
11 + "mix usage_rules.sync CLAUDE.md --all --link-to-folder deps"
12 12 end
13 13
14 14 @spec long_doc() :: String.t()
  @@ -33,7 +33,7 @@ defmodule Mix.Tasks.UsageRules.Sync.Docs do
33 33
34 34 Gather all dependencies with usage rules:
35 35 ```sh
36 - mix usage_rules.sync rules.md --all
36 + mix usage_rules.sync CLAUDE.md --all
37 37 ```
38 38
39 39 List all dependencies with usage rules:
  @@ -43,37 +43,42 @@ defmodule Mix.Tasks.UsageRules.Sync.Docs do
43 43
44 44 Check status of dependencies against a specific file:
45 45 ```sh
46 - mix usage_rules.sync rules.md --list
46 + mix usage_rules.sync CLAUDE.md --list
47 47 ```
48 48
49 49 Remove specific packages from a file:
50 50 ```sh
51 - mix usage_rules.sync rules.md ash phoenix --remove
51 + mix usage_rules.sync CLAUDE.md ash phoenix --remove
52 52 ```
53 53
54 54 Save usage rules to individual files in a folder with markdown links:
55 55 ```sh
56 - mix usage_rules.sync rules.md ash phoenix --link-to-folder rules
56 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder rules
57 57 ```
58 58
59 59 Save usage rules with @-style links:
60 60 ```sh
61 - mix usage_rules.sync rules.md ash phoenix --link-to-folder rules --link-style at
61 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder rules --link-style at
62 + ```
63 +
64 + Link directly to deps files without copying:
65 + ```sh
66 + mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder deps
62 67 ```
63 68
64 69 Combine all dependencies with folder links:
65 70 ```sh
66 - mix usage_rules.sync rules.md --all --link-to-folder docs
71 + mix usage_rules.sync CLAUDE.md --all --link-to-folder docs
67 72 ```
68 73
69 74 Check status of packages using folder links:
70 75 ```sh
71 - mix usage_rules.sync rules.md --list --link-to-folder rules
76 + mix usage_rules.sync CLAUDE.md --list --link-to-folder rules
72 77 ```
73 78
74 79 Remove packages and their folder files:
75 80 ```sh
76 - mix usage_rules.sync rules.md ash phoenix --remove --link-to-folder rules
81 + mix usage_rules.sync CLAUDE.md ash phoenix --remove --link-to-folder rules
77 82 ```
78 83 """
79 84 end
  @@ -234,6 +239,9 @@ if Code.ensure_loaded?(Igniter) do
234 239 defp add_usage_error(igniter) do
235 240 Igniter.add_issue(igniter, """
236 241 Usage:
242 + mix usage_rules.sync CLAUDE.md --all --link-to-folder deps
243 + Standard usage: gather all dependencies and link directly to deps files
244 +
237 245 mix usage_rules.sync <file> <packages...>
238 246 Combine specific packages' usage rules into the target file
239 247
  @@ -476,36 +484,42 @@ if Code.ensure_loaded?(Igniter) do
476 484 folder_name,
477 485 link_style
478 486 ) do
479 - # First, create individual files for each package in the folder
487 + # Create individual files for each package in the folder (unless folder is "deps")
480 488 igniter =
481 - Enum.reduce(packages, igniter, fn {name, path}, acc ->
482 - usage_rules_path = Path.join(path, "usage-rules.md")
489 + if folder_name == "deps" do
490 + igniter
491 + else
492 + Enum.reduce(packages, igniter, fn {name, path}, acc ->
493 + usage_rules_path = Path.join(path, "usage-rules.md")
483 494
484 - content =
485 - case Rewrite.source(acc.rewrite, usage_rules_path) do
486 - {:ok, source} -> Rewrite.Source.get(source, :content)
487 - {:error, _} -> File.read!(usage_rules_path)
488 - end
495 + content =
496 + case Rewrite.source(acc.rewrite, usage_rules_path) do
497 + {:ok, source} -> Rewrite.Source.get(source, :content)
498 + {:error, _} -> File.read!(usage_rules_path)
499 + end
489 500
490 - package_file_path = Path.join(folder_name, "#{name}.md")
501 + package_file_path = Path.join(folder_name, "#{name}.md")
491 502
492 - Igniter.create_or_update_file(
493 - acc,
494 - package_file_path,
495 - content,
496 - fn source ->
497 - Rewrite.Source.update(source, :content, content)
498 - end
499 - )
500 - end)
503 + Igniter.create_or_update_file(
504 + acc,
505 + package_file_path,
506 + content,
507 + fn source ->
508 + Rewrite.Source.update(source, :content, content)
509 + end
510 + )
511 + end)
512 + end
501 513
502 514 # Then, create the main file with links
503 515 package_contents =
504 516 packages
505 517 |> Enum.map(fn {name, _path} ->
506 518 link_content =
507 - case link_style do
508 - "at" -> "@#{folder_name}/#{name}.md"
519 + case {link_style, folder_name} do
520 + {"at", "deps"} -> "@deps/#{name}/usage-rules.md"
521 + {"at", _} -> "@#{folder_name}/#{name}.md"
522 + {_, "deps"} -> "[#{name} usage rules](deps/#{name}/usage-rules.md)"
509 523 _ -> "[#{name} usage rules](#{folder_name}/#{name}.md)"
510 524 end
  @@ -1,7 +1,7 @@
1 1 defmodule UsageRules.MixProject do
2 2 use Mix.Project
3 3
4 - @version "0.1.5"
4 + @version "0.1.6"
5 5 @description """
6 6 A dev tool for Elixir projects to gather LLM usage rules from dependencies
7 7 """