adamantite 0.44.0 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/README.md +413 -122
  2. package/dist/index.js +638 -57
  3. package/dist/oxlint.js +1 -0
  4. package/dist/presets/analyze.js +1 -0
  5. package/dist/presets/lint/{react-doctor.d.ts → architecture.d.ts} +1 -1
  6. package/dist/presets/lint/architecture.js +8 -0
  7. package/dist/presets/lint/core.js +0 -1
  8. package/dist/presets/lint/effect.js +26 -1
  9. package/dist/presets/lint/jest.d.ts +13 -0
  10. package/dist/presets/lint/jest.js +88 -68
  11. package/dist/presets/lint/plugin/glob.d.ts +7 -0
  12. package/dist/presets/lint/plugin/glob.js +48 -0
  13. package/dist/presets/lint/plugin/imports.d.ts +4 -0
  14. package/dist/presets/lint/plugin/imports.js +4 -1
  15. package/dist/presets/lint/plugin/index.d.ts +3 -0
  16. package/dist/presets/lint/plugin/index.js +14 -8
  17. package/dist/presets/lint/plugin/options.d.ts +5 -5
  18. package/dist/presets/lint/plugin/options.js +19 -7
  19. package/dist/presets/lint/plugin/resolver.d.ts +8 -0
  20. package/dist/presets/lint/plugin/resolver.js +79 -0
  21. package/dist/presets/lint/plugin/rules/import-owners.d.ts +67 -0
  22. package/dist/presets/lint/plugin/rules/import-owners.js +310 -0
  23. package/dist/presets/lint/plugin/rules/layers.d.ts +136 -0
  24. package/dist/presets/lint/plugin/rules/layers.js +479 -0
  25. package/dist/presets/lint/plugin/rules/no-query-data-in-state.js +1 -1
  26. package/dist/presets/lint/plugin/rules/no-react-state-hooks.d.ts +0 -5
  27. package/dist/presets/lint/plugin/rules/no-react-state-hooks.js +3 -47
  28. package/dist/presets/lint/plugin/rules/query-from-loader.js +2 -2
  29. package/dist/presets/lint/plugin/rules/require-suppression-reason.d.ts +5 -0
  30. package/dist/presets/lint/plugin/rules/require-suppression-reason.js +32 -0
  31. package/dist/presets/lint/react-strict.js +22 -2
  32. package/dist/presets/lint/strict.js +35 -2
  33. package/dist/presets/lint/{antislop.d.ts → tailwind.d.ts} +1 -1
  34. package/dist/presets/lint/{shadcn.js → tailwind.js} +1 -1
  35. package/dist/presets/lint/vendor/antislop/license.md +26 -1
  36. package/dist/presets/lint/vendor/antislop/plugin.d.mts +3 -0
  37. package/dist/presets/lint/vendor/antislop/plugin.mjs +940 -31
  38. package/dist/presets/lint/vendor/antislop-effect/license.md +27 -0
  39. package/dist/presets/lint/vendor/antislop-effect/plugin.d.mts +17 -0
  40. package/dist/presets/lint/vendor/antislop-effect/plugin.mjs +579 -0
  41. package/dist/presets/lint/vitest.d.ts +13 -0
  42. package/dist/presets/lint/vitest.js +111 -91
  43. package/dist/presets/{lint → rules}/custom.d.ts +3 -20
  44. package/dist/presets/{lint → rules}/custom.js +50 -46
  45. package/dist/presets/rules/folder.d.ts +34 -0
  46. package/dist/presets/rules/folder.js +52 -0
  47. package/dist/presets/rules/index.d.ts +2 -9
  48. package/dist/presets/rules/index.js +1 -29
  49. package/dist/presets/rules/load.d.ts +8 -0
  50. package/dist/presets/rules/load.js +29 -0
  51. package/dist/presets/rules/plugin.d.ts +3 -0
  52. package/dist/presets/rules/plugin.js +1 -0
  53. package/dist/presets/rules/testing.d.ts +2 -0
  54. package/dist/presets/rules/testing.js +14 -0
  55. package/dist/presets/tsconfig.json +3 -0
  56. package/dist/runtime-CVZPDpfE.js +11 -0
  57. package/package.json +79 -18
  58. package/skills/adamantite/SKILL.md +112 -200
  59. package/skills/adamantite/references/custom-rules.md +120 -0
  60. package/skills/adamantite/references/lint-rules.md +158 -0
  61. package/skills/adamantite/references/setup.md +64 -0
  62. package/dist/presets/lint/antislop.js +0 -28
  63. package/dist/presets/lint/react-doctor.js +0 -20
  64. package/dist/presets/lint/shadcn.d.ts +0 -5
package/README.md CHANGED
@@ -34,11 +34,14 @@ and Sherif so humans and coding agents can use the same project workflow.
34
34
  through an interactive or non-interactive initializer.
35
35
  - **Setup maintenance**: Assess managed integrations with `doctor`, update managed
36
36
  dependencies, and give humans or agents repair instructions.
37
- - **Custom rules**: Write project-specific Oxlint rules in `.adamantite/rules/`, one rule
37
+ - **Custom rules**: Write project-specific Oxlint rules in `.adamantite/lint/`, one rule
38
38
  for each file, and enable all of them with one line.
39
+ - **Hardening**: Have a coding agent turn the coding standards that your code already
40
+ follows into custom rules, and into instructions for the ones that no rule can check.
39
41
  - **Workspace checks**: Find unused code with Knip and dependency inconsistencies with
40
42
  Sherif.
41
- - **Agent guidance**: Add a managed Adamantite section to `AGENTS.md`.
43
+ - **Agent guidance**: Add a managed Adamantite section to `AGENTS.md`, and add the
44
+ Adamantite skill for your coding agents.
42
45
 
43
46
  ## Quick start
44
47
 
@@ -49,7 +52,7 @@ npx adamantite init
49
52
  ```
50
53
 
51
54
  The interactive setup lets you choose package scripts, presets, TypeScript, editors, CI,
52
- and agent guidance. After setup, use the scripts written to `package.json`:
55
+ and coding agent setup with the [Adamantite skill](#agent-skill). After setup, use the scripts written to `package.json`:
53
56
 
54
57
  ```sh
55
58
  bun run check
@@ -89,14 +92,19 @@ Available setup values:
89
92
 
90
93
  - Scripts: `check`, `fix`, and `analyze`. In a detected monorepo, `analyze` also installs
91
94
  Sherif.
92
- - Presets: `react`, `react-strict`, `react-doctor`, `tanstack`, `nextjs`, `vue`, `effect`,
93
- `jest`, `vitest`, `node`, `strict`, `antislop`, and `shadcn`. `react-doctor` requires `react`.
95
+ - Presets: `react`, `react-strict`, `tanstack`, `nextjs`, `vue`, `effect`,
96
+ `jest`, `vitest`, `node`, `architecture`, `strict`, and `tailwind`. `react-strict` requires `react`.
94
97
  - Editors: `vscode` and `zed`.
95
98
 
96
99
  Presets and TypeScript require the `check` or `fix` script. Editor extension installation
97
100
  requires an editor. GitHub Actions requires a compatible script and a supported package
98
101
  manager. Omitted boolean flags are disabled.
99
102
 
103
+ The GitHub Actions workflow runs the `check` and `analyze` scripts that you select.
104
+ Agents verify custom rules with temporary cases while they work. CI runs the rules through
105
+ `check` by default. Users can add an explicit `adamantite rule test` step for optional saved tests.
106
+ Init preserves a workflow with an explicit rule-test command, including its setup and other settings.
107
+
100
108
  Existing package scripts whose commands differ from Adamantite's are kept and reported
101
109
  instead of being replaced. The interactive initializer asks before overwriting them; in
102
110
  non-interactive mode, pass `--overwrite-scripts` to replace them. To keep custom flags,
@@ -121,6 +129,11 @@ adamantite check
121
129
  adamantite check src
122
130
  ```
123
131
 
132
+ `check` fails when Oxlint reports a warning, because a warning that passes is a pattern that
133
+ agents copy. Use `--allow-warnings` to pass with warnings. A forwarded `--max-warnings` or
134
+ `--deny-warnings`, such as `adamantite check -- --max-warnings 10`, replaces this default. To keep existing violations of a
135
+ rule while new code follows it, turn the rule off for those files in an Oxlint override.
136
+
124
137
  Use `--only` to run one stage. Arguments after `--` go to that stage, and to Oxlint when
125
138
  both run:
126
139
 
@@ -185,7 +198,9 @@ adamantite analyze --only monorepo --fix -- --select highest
185
198
  ### `adamantite doctor`
186
199
 
187
200
  Assess every Adamantite-managed integration. Doctor is read-only. Each finding describes
188
- the current state, the goal state, and how to verify the repair.
201
+ the current state, the goal state, and how to verify the repair. Doctor also checks that the
202
+ installed packages can run Oxlint: each declared package is installed, and `@effect/tsgo` has
203
+ a build for the installed Oxlint, tsrs, and platform. It starts no tool for this check.
189
204
 
190
205
  ```sh
191
206
  adamantite doctor
@@ -206,44 +221,106 @@ directly. In a non-interactive run, Doctor prints the combined repair prompt and
206
221
  when findings remain. If only assessment warnings remain, Doctor prints a Markdown
207
222
  warning report and exits 0.
208
223
 
209
- ### `adamantite update`
224
+ ### `adamantite harden`
210
225
 
211
- Update Adamantite-managed dependencies, then report any setup findings:
226
+ Ask a coding agent to find the coding standards that the project already follows, and to put
227
+ each one at the highest level of enforcement that works: a custom rule when a rule can check
228
+ it, and a line in `CODING_STANDARDS.md` when no rule can.
212
229
 
213
230
  ```sh
214
- adamantite update
215
- adamantite doctor
231
+ adamantite harden
232
+ adamantite harden --path packages/web
233
+ adamantite harden --commits 500
216
234
  ```
217
235
 
218
- `update` exits 0 when dependency updates succeed, even if doctor findings remain. Use
219
- `adamantite doctor` as the CI gate. After it installs packages, `update` patches Oxlint and TypeScript again for
220
- [the effect preset](#the-effect-preset).
236
+ The prompt lists the Oxlint config of the root and of each workspace package, the rules folders
237
+ that their `custom()` calls load, and the `AGENTS.md` of the root and of each package. Agents start
238
+ from `AGENTS.md`, so it must point to the other documentation. The prompt also lists each Markdown
239
+ file that `git ls-files` gives, except the changesets and the changelogs, and the agent reads each
240
+ one.
241
+ `--path` limits the session to one package or folder. The prompt then lists the configs of the
242
+ packages in that folder, or of the package that contains it, the rules folders that those configs
243
+ load, the `AGENTS.md` of the root and of those packages, and the Markdown files of those packages
244
+ and of the root. The prompt also lists the Markdown files that no chain of links or code-span paths
245
+ from an `AGENTS.md` reaches, and each link to a missing file. The agent also reads the fix commits of the last 200 commits, or of the number
246
+ that `--commits` gives, and a mistake that the fixes repeat becomes a candidate. With `--path`, it
247
+ reads only the commits that change that folder.
248
+ The agent shows the candidates and writes nothing until you approve them. When no human can
249
+ approve, the agent stops at the candidates.
250
+
251
+ In an interactive terminal, `harden` offers the same menu as Doctor: hand off to an installed
252
+ coding agent seeded with the prompt, copy the prompt, or do nothing. After a handoff, `harden`
253
+ runs `check`, then the Doctor assessment, and exits 1 when either fails.
254
+ During the session, the agent verifies each new or changed custom rule with temporary
255
+ RuleTester cases and removes the cases before handback.
256
+ Harden also exits 1 when the session added a link to a Markdown file that does not exist. A copy or "do nothing"
257
+ exits 0 without verification. Without a terminal, it prints the prompt and exits 0. `harden` never produces Doctor findings. See
258
+ [ADR 0012](docs/adr/0012-harden-instructs-agents-to-write-rules.md).
221
259
 
222
- ### `adamantite prepare`
260
+ ### `adamantite update`
223
261
 
224
- Patch Oxlint and TypeScript for [the effect preset](#the-effect-preset). The `prepare`
225
- script in `package.json` runs it after each install:
262
+ Update Adamantite-managed dependencies, then report any setup findings:
226
263
 
227
- ```json
228
- { "scripts": { "prepare": "adamantite prepare" } }
264
+ ```sh
265
+ adamantite update
266
+ adamantite doctor
229
267
  ```
230
268
 
231
- Without the effect preset, `prepare` does nothing and exits 0. If the patch fails, `prepare`
232
- fails, so the install fails.
269
+ `update` exits 0 when dependency updates succeed, even if doctor findings remain. Use
270
+ `adamantite doctor` as the CI gate. It also refreshes each copy of the
271
+ [Adamantite skill](#agent-skill) that differs from the skill of the installed Adamantite version.
233
272
 
234
273
  ### `adamantite rule`
235
274
 
236
- Write and inspect [custom rules](#custom-rules):
275
+ Write, try, and inspect [custom rules](#custom-rules) and other Oxlint rules:
237
276
 
238
277
  ```sh
239
278
  adamantite rule add no-process-env
240
279
  adamantite rule add no-window --dir tooling/lint/rules
280
+ adamantite rule test add
281
+ adamantite rule test add no-process-env
282
+ adamantite rule test add no-process-env --path tests/no-process-env.test.ts
283
+ adamantite rule test
284
+ adamantite rule test --path tests/no-process-env.test.ts
285
+ adamantite rule try no-console --report src/debug.ts --accept src/index.ts
286
+ adamantite rule try no-restricted-imports --options '[{"paths":["node:fs"]}]' --report src/new.ts=draft.ts
287
+ adamantite rule try project/no-process-env --current --report src/env.ts
241
288
  adamantite rule ast src/index.ts
242
289
  ```
243
290
 
244
- `rule add` writes a rule stub to `.adamantite/rules/`, or to the folder that `--dir` names,
245
- and an `AGENTS.md` with the authoring guidance when the folder has none. `rule ast` prints the
246
- ESTree-shaped AST that Oxlint rules visit, so you can read node names off real code.
291
+ `rule add` writes only a rule stub to `.adamantite/lint/`, or to the folder that `--dir` names.
292
+ Agents verify it with temporary `RuleTester` cases by default. `rule test add` lists existing
293
+ rules for selection. Pass a rule name to skip the list; the command fails if the rule does not
294
+ exist. It writes an optional `<name>.test.ts` beside the rule, or at the file path that `--path`
295
+ names. `--dir` selects another rules folder. It preserves existing files. Adapt the generated
296
+ valid and invalid cases to the rule before running them.
297
+
298
+ `rule test` runs saved `.test.*` files beside the rules that `custom()` loads. Use
299
+ `rule test --path <file>` for a test saved elsewhere. CI and harden do not run saved tests
300
+ automatically. Agents remove their temporary verification cases before they finish.
301
+ During harden, agents can use `rule test add` to prepare those temporary cases and
302
+ `rule test --path <file>` to run them. They preserve user-owned saved tests.
303
+
304
+ `rule try` runs a trial. It lints cases with one rule and shows whether the rule reports or
305
+ accepts each case. Give the full rule name, such as `no-console`, `typescript/no-explicit-any`,
306
+ or `project/no-process-env`. Each `--report` adds a case that the rule must report, and each
307
+ `--accept` adds a case that the rule must accept. A trial needs at least one `--report` case.
308
+ Repeat either flag to add more cases.
309
+
310
+ Run `rule try` from the project root. A case is a file path relative to the project root. Use
311
+ `<path>=<file>` to lint the content of `<file>` as if it were at `<path>`. This form lets you try
312
+ code that is not in the project yet, and code in files that git ignores.
313
+
314
+ By default, the trial sets the rule to `error` with no options. `--options` gives the options
315
+ that come after the severity, as a JSON array. `--current` uses the rule setting from the
316
+ project config instead. You cannot use `--options` and `--current` together.
317
+
318
+ The trial lints a copy of the project in a temporary folder, so it does not change the project.
319
+ It exits 0 when every case gives the expected result, 1 when a case does not, and 2 when the
320
+ trial cannot check the cases, such as for a rule that does not exist.
321
+
322
+ `rule ast` prints the ESTree-shaped AST that Oxlint rules visit, so you can read node names off
323
+ real code.
247
324
 
248
325
  ### Pass arguments to underlying tools
249
326
 
@@ -251,7 +328,7 @@ Commands that invoke Knip, Oxlint, Oxfmt, or Sherif forward arguments after `--`
251
328
 
252
329
  ```sh
253
330
  adamantite analyze --strict -- --directory packages/app
254
- adamantite check src -- --deny-warnings
331
+ adamantite check src -- --format github
255
332
  adamantite analyze --only monorepo -- --ignore-package package-a
256
333
  ```
257
334
 
@@ -262,34 +339,35 @@ bun run analyze -- -- --directory packages/app
262
339
  npm run analyze -- -- --directory packages/app
263
340
  ```
264
341
 
265
- `init`, `doctor`, and `update` do not forward arguments because they do not invoke one
342
+ `init`, `doctor`, `harden`, and `update` do not forward arguments because they do not invoke one
266
343
  underlying CLI.
267
344
 
268
345
  ## Presets
269
346
 
270
- Adamantite publishes configuration that can also be consumed directly:
271
-
272
- | Export | Purpose |
273
- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
274
- | `adamantite/lint` | Core Oxlint rules. |
275
- | `adamantite/lint/react` | React, JSX accessibility, and performance. |
276
- | `adamantite/lint/react-strict` | Opinions for React feature code: no state, effect, or memoization hooks outside hook modules. See [the react-strict preset](#the-react-strict-preset). |
277
- | `adamantite/lint/react-doctor` | Curated [React Doctor](https://github.com/millionco/react-doctor) rules for React state and effect misuse. See [the react-doctor preset](#the-react-doctor-preset). |
278
- | `adamantite/lint/tanstack` | Opinions for [TanStack Query](https://tanstack.com/query) with route loaders: queries defined once with `queryOptions()`, and no query data copied into state. See [the tanstack preset](#the-tanstack-preset). |
279
- | `adamantite/lint/nextjs` | Next.js rules. |
280
- | `adamantite/lint/vue` | Vue rules. |
281
- | `adamantite/lint/effect` | Curated [@effect/tsgo](https://github.com/Effect-TS/tsgo) rules for Effect misuse, such as effects that never run and unhandled errors. See [the effect preset](#the-effect-preset). |
282
- | `adamantite/lint/node` | Node.js rules. |
283
- | `adamantite/lint/jest` | Jest rules. |
284
- | `adamantite/lint/vitest` | Vitest rules. |
285
- | `adamantite/lint/strict` | Framework-neutral opinions: no deep or wide destructuring, and no type assertions outside tests. See [the strict preset](#the-strict-preset). |
286
- | `adamantite/lint/antislop` | Vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules that reject low-evidence, low-signal patterns. Also turns off `typescript/consistent-indexed-object-style` and `unicorn/no-immediate-mutation` from the core preset, which conflict with these rules. |
287
- | `adamantite/lint/shadcn` | [@shadcn/lint](https://github.com/shadcn-ui/lint) rules for Tailwind v4 design systems: no restyled components, raw colors, arbitrary values, inline styles, unknown classes, or unreadable class expressions. shadcn/ui is not required. See [the shadcn preset](#the-shadcn-preset). |
288
- | `adamantite/lint/custom` | A function, `custom()`, that loads the project's own rules from `.adamantite/rules/`. See [custom rules](#custom-rules). |
289
- | `adamantite/rules` | `defineRule` and the rule and AST types for custom rules. |
290
- | `adamantite/format` | Oxfmt configuration. |
291
- | `adamantite/analyze` | Knip configuration. The `ignoreDependencies` named export groups suggested ignore lists; `init` sets `ignoreDependencies.monorepo` in a monorepo and `ignoreDependencies.effect` with the effect preset. |
292
- | `adamantite/typescript` | Strict TypeScript configuration for TS 7+. |
347
+ Adamantite publishes configuration that can also be consumed directly. The package exports only
348
+ the imports in this table, and Node.js rejects any other path in the package:
349
+
350
+ | Export | Purpose |
351
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
352
+ | `adamantite/lint` | Core Oxlint rules. |
353
+ | `adamantite/lint/react` | React, JSX accessibility, and performance. |
354
+ | `adamantite/lint/react-strict` | React feature-code restrictions and curated [React Doctor](https://github.com/millionco/react-doctor) checks for state, effects, cleanup, and render lifetimes. See [the react-strict preset](#the-react-strict-preset). |
355
+ | `adamantite/lint/tanstack` | Opinions for [TanStack Query](https://tanstack.com/query) with route loaders: queries defined once with `queryOptions()`, and no query data copied into state. See [the tanstack preset](#the-tanstack-preset). |
356
+ | `adamantite/lint/nextjs` | Next.js rules. |
357
+ | `adamantite/lint/vue` | Vue rules. |
358
+ | `adamantite/lint/effect` | Curated [@effect/tsgo](https://github.com/Effect-TS/tsgo) rules for Effect misuse, such as effects that never run and unhandled errors, and vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules for tagged values. See [the effect preset](#the-effect-preset). |
359
+ | `adamantite/lint/node` | Node.js rules. |
360
+ | `adamantite/lint/jest` | Jest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets). |
361
+ | `adamantite/lint/vitest` | Vitest rules for test files. See [the jest and vitest presets](#the-jest-and-vitest-presets). |
362
+ | `adamantite/lint/architecture` | Load first-party rules for project-defined layer maps and import owners. No rules are enabled by default. |
363
+ | `adamantite/lint/strict` | Framework-neutral opinions: no type assertions outside tests, no `unknown` in signatures, no module mocks, no deep or wide destructuring, a reason on each suppression, no console calls, and no task comments. See [the strict preset](#the-strict-preset). |
364
+ | `adamantite/lint/tailwind` | [@shadcn/lint](https://github.com/shadcn-ui/lint) rules for Tailwind v4 design systems: no restyled components, raw colors, arbitrary values, inline styles, unknown classes, or unreadable class expressions. shadcn/ui is not required. See [the tailwind preset](#the-tailwind-preset). |
365
+ | `adamantite/rules` | A function, `custom()`, that loads the project's own rules from `.adamantite/lint/`. See [custom rules](#custom-rules). |
366
+ | `adamantite/rules/plugin` | `definePlugin`, `defineRule`, `eslintCompatPlugin`, and all Oxlint authoring types. |
367
+ | `adamantite/rules/testing` | `RuleTester` and its types for temporary agent verification and optional saved tests. |
368
+ | `adamantite/format` | Oxfmt configuration. |
369
+ | `adamantite/analyze` | Knip configuration. The `ignoreDependencies` named export groups suggested ignore lists; `init` sets `ignoreDependencies.monorepo` in a monorepo and `ignoreDependencies.effect` with the effect preset. |
370
+ | `adamantite/typescript` | Strict TypeScript configuration for TS 7+. Allows only erasable syntax, so `enum`, a `namespace` with values, and parameter properties fail type checking. |
293
371
 
294
372
  When consuming the lint presets directly, hoist the core preset's ignore patterns onto the
295
373
  root config. Oxlint does not merge `ignorePatterns` from extended configs, so without the
@@ -308,11 +386,57 @@ export default defineConfig({
308
386
 
309
387
  Configs generated by `adamantite init` include this automatically.
310
388
 
389
+ ### The jest and vitest presets
390
+
391
+ The `jest` and `vitest` presets apply their rules only to test files, so rules such as
392
+ `vitest/require-hook` do not report scripts and library code. Each preset exports `testFiles`, the
393
+ files that its test runner runs as tests by default. `vitest` `testFiles` match `*.test.*` and
394
+ `*.spec.*` files. `jest` `testFiles` also match files in `__tests__` folders.
395
+
396
+ Extend the preset to use these files:
397
+
398
+ ```ts
399
+ import core from "adamantite/lint"
400
+ import vitest from "adamantite/lint/vitest"
401
+ import { defineConfig } from "oxlint"
402
+
403
+ export default defineConfig({
404
+ extends: [core, vitest],
405
+ ignorePatterns: core.ignorePatterns,
406
+ })
407
+ ```
408
+
409
+ If your test runner finds tests in other files, use the preset in an override of your own
410
+ instead of `extends`. `vitest.plugins` and `vitest.rules` hold the preset's plugins and rules:
411
+
412
+ ```ts
413
+ import core from "adamantite/lint"
414
+ import vitest, { testFiles } from "adamantite/lint/vitest"
415
+ import { defineConfig } from "oxlint"
416
+
417
+ export default defineConfig({
418
+ extends: [core],
419
+ ignorePatterns: core.ignorePatterns,
420
+ overrides: [
421
+ {
422
+ files: [...testFiles, "e2e/**/*.ts"],
423
+ plugins: vitest.plugins,
424
+ rules: { ...vitest.rules, "vitest/max-expects": "off" },
425
+ },
426
+ ],
427
+ })
428
+ ```
429
+
430
+ Change a test rule in an override, not in the top-level `rules`: the preset's rules for test files
431
+ replace top-level settings. Keep `plugins: vitest.plugins` in that override too, because Oxlint
432
+ ignores the `vitest/*` rules of an override that does not enable the `vitest` plugin.
433
+
311
434
  ### The react-strict preset
312
435
 
313
436
  `adamantite/lint/react-strict` keeps state and side effects out of React feature code. Use
314
- it together with `adamantite/lint/react`. It needs no extra package: the rules come from
315
- Adamantite's own Oxlint plugin, which ships inside the package.
437
+ it together with `adamantite/lint/react`. It loads Adamantite's first-party plugin and the
438
+ managed `oxlint-plugin-react-doctor` package. Init installs the pinned package when you
439
+ select `react-strict`. Doctor and update maintain its version.
316
440
 
317
441
  `adamantite/no-react-state-hooks` reports calls to `useState`, `useReducer`, `useEffect`,
318
442
  `useLayoutEffect`, `useSyncExternalStore`, `useMemo`, and `useCallback` imported from
@@ -346,23 +470,17 @@ export default defineConfig({
346
470
 
347
471
  Each option replaces its default list.
348
472
 
349
- ### The react-doctor preset
350
-
351
- `adamantite/lint/react-doctor` reports specific misuse of React state and effects. Use it
352
- together with `adamantite/lint/react`. It needs the `oxlint-plugin-react-doctor` package.
353
- `adamantite init` installs the pinned version when you select the preset, and
354
- `adamantite doctor` and `adamantite update` keep it on that version. If you add the preset
355
- by hand, install `oxlint-plugin-react-doctor` as a devDependency too.
356
-
357
- The plugin exports more than 900 rules. The preset enables only rules that run on one file
473
+ The React Doctor package exports more than 900 rules. The preset enables only rules that run on one file
358
474
  and that the native `react`, `react-hooks`, `jsx-a11y`, and `unicorn` rules do not already
359
475
  report. Examples are an effect that does the work of an event handler (`no-effect-event-handler`), data fetched in an effect
360
- (`no-fetch-in-effect`), and state changed in place (`no-direct-state-mutation`). The
476
+ (`no-fetch-in-effect`), and state changed in place (`no-direct-state-mutation`). It also
477
+ checks cleanup, stale timer references, discarded effect cleanup callbacks, loading flags
478
+ that stay set after a failed request, and contexts or object URLs created during render. The
361
479
  TanStack Query and TanStack Start rules are not in this preset. See
362
480
  [ADR 0005](docs/adr/0005-curate-react-doctor-rules.md) for the criteria.
363
481
 
364
- The preset works together with `adamantite/lint/react-strict`. React Doctor rules report
365
- specific misuse, and `react-strict` bans the hooks in feature code. Some React Doctor rules
482
+ React Doctor checks also run in hook modules where state and effect hooks are allowed.
483
+ Some React Doctor rules
366
484
  skip test files and fixtures by path, such as `__tests__/` and `*.test.tsx`.
367
485
 
368
486
  `oxlint-plugin-react-doctor` has a modified MIT license. It needs written permission from
@@ -371,11 +489,15 @@ as a hosted product. Read the
371
489
  [license](https://www.npmjs.com/package/oxlint-plugin-react-doctor?activeTab=code) before
372
490
  you select the preset.
373
491
 
492
+ If you add `react-strict` by hand, install `oxlint-plugin-react-doctor` as a devDependency.
493
+ Run `adamantite doctor` for an existing `react-doctor` configuration. Its repair prompt
494
+ moves the preset to `react-strict` and preserves project settings and rule overrides.
495
+
374
496
  ### The tanstack preset
375
497
 
376
498
  `adamantite/lint/tanstack` holds opinions for TanStack Query (`@tanstack/react-query`) in
377
499
  apps that preload queries in route loaders, such as TanStack Router and TanStack Start apps.
378
- Like `react-strict`, it needs no extra package.
500
+ It needs no extra package.
379
501
 
380
502
  - `adamantite/query-from-loader` reports `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`,
381
503
  and `useSuspenseInfiniteQuery` calls in route files that take a plain options object or a `queryOptions()`
@@ -396,9 +518,8 @@ A route file is a file that calls a route factory from `@tanstack/react-router`,
396
518
  the query, so components outside route files can define their queries inline.
397
519
  `query-from-loader` checks one file at a time. It cannot prove that a loader preloads the
398
520
  options, so it moves queries toward shared definitions but does not guarantee the preload.
399
- The `react-doctor` preset reports other query misuse, such as refetches from effects and
400
- mutations that do not invalidate queries. See
401
- [ADR 0008](docs/adr/0008-tanstack-query-options-from-loaders.md).
521
+ Query refetches from effects and mutation invalidation are not checked by these presets.
522
+ See [ADR 0008](docs/adr/0008-tanstack-query-options-from-loaders.md).
402
523
 
403
524
  ### The effect preset
404
525
 
@@ -409,43 +530,77 @@ simpler replacement (`catch-all-to-map-error`). The rules come from
409
530
  [@effect/tsgo](https://github.com/Effect-TS/tsgo), the Effect Language Service for
410
531
  TypeScript-Go, and need Oxlint's type-aware mode.
411
532
 
412
- The rules are not a JavaScript plugin. They exist only after `effect-tsgo patch --oxlint
413
- --typescript` replaces the Oxlint, oxlint-tsgolint, and TypeScript binaries in
414
- `node_modules`. Without the patch, Oxlint stops with `Unknown plugin: 'effecttsgo'`. Each
415
- install of one of those packages restores the original binaries, so the patch must run again
416
- after it. Adamantite runs it in these places:
417
-
418
- - `adamantite prepare`, which the `prepare` script runs after a bare install, such as
419
- `npm install`, `npm ci`, or a fresh clone in CI.
420
- - `adamantite init` and `adamantite update`, after they install packages. A named install,
421
- such as `npm install -D oxlint@1.88.0`, does not run the `prepare` script. If you change one
422
- of those versions yourself, doctor reports the version drift, and `adamantite update`
423
- installs the pinned version and patches it.
533
+ The preset also turns on the rules of the `anti-slop-effect` plugin from
534
+ [anti-slop](https://github.com/dmmulroy/anti-slop). Adamantite ships a build of it, so nothing
535
+ extra needs to be installed. The rules report tagged values that code handles by hand:
536
+
537
+ - `no-manual-tagged-construction` reports an object literal with a `_tag`. Use a tagged class,
538
+ such as `Data.TaggedClass` or `Data.TaggedError`, or the `make` of a tagged Schema.
539
+ - `no-manual-tag-comparison` reports a comparison or a `switch` on `_tag`. Use `Match.tag`,
540
+ `Predicate.isTagged`, or a helper such as `Option.isNone`.
541
+ - `no-manual-effect-error-tag` reports a broad `Effect.catch` handler that branches on `_tag`.
542
+ Use `Effect.catchTag` or `Effect.catchReason`.
543
+ - `prefer-effect-match` reports a chain of ternaries that compare one value with literals. Use
544
+ `Match` or a lookup table.
545
+ - `no-service-constructor-imports` reports a `make*` import from a project file outside tests.
546
+ Import the Layer of the service instead.
547
+
548
+ The preset turns off two core rules, `unicorn/no-array-callback-reference` and
549
+ `unicorn/no-array-method-this-argument`. They match an array method by its name only, so they
550
+ report Effect calls such as `Option.some(value)` and `Array.findLast(values, predicate)`.
551
+
552
+ The `@effect/tsgo` rules are not a JavaScript plugin. They exist only in the Effect builds of the Oxlint
553
+ binding and tsrs, which `@effect/tsgo` ships. When the project installs
554
+ `@effect/tsgo`, Adamantite runs Oxlint with those builds. Nothing changes in
555
+ installed package files, so linting needs no install script. These run Oxlint with the builds:
556
+
557
+ - `adamantite check`, `adamantite fix`, and `adamantite harden`.
558
+ - VS Code and Zed, through the settings that `adamantite init` writes. They start
559
+ `node_modules/adamantite/dist/oxlint.js` in place of `oxlint`.
560
+
561
+ A plain `oxlint` call, such as in a lint-staged config, stops with
562
+ `Unknown plugin: 'effecttsgo'`. Run `adamantite check --only lint` instead, which also takes
563
+ file arguments.
424
564
 
425
565
  When you select the preset, `adamantite init` does these steps:
426
566
 
427
- - Installs the pinned `@effect/tsgo` and runs the patch.
428
- - Adds `"prepare": "adamantite prepare"` to `package.json`. If the project already has a
429
- `prepare` script, init rewrites it as `adamantite prepare && (<existing>)`. A command such as
430
- `cd ..` then cannot move the patch out of the project, and a fallback such as `|| true`
431
- cannot hide a failed patch.
432
- - Adds `{ "name": "@effect/language-service", "diagnostics": false }` to
433
- `compilerOptions.plugins` in `tsconfig.json`. Editors that use the workspace TypeScript
434
- get Effect quick fixes, refactors, and hovers. Oxlint reports the diagnostics, so the
435
- language service does not report them a second time.
567
+ - Installs the pinned `@effect/tsgo`.
568
+ - Adds `{ "name": "@effect/language-service", "diagnostics": true }` to
569
+ `compilerOptions.plugins` in `tsconfig.json`. The rules read their options from this entry.
570
+ The Effect language server needs diagnostics enabled to offer semantic quick fixes.
571
+ - Configures the selected editors to use the installed Effect language server. Their Oxlint
572
+ settings hide duplicate Effect rule reports. CLI Oxlint keeps the effect preset.
436
573
  - Sets `ignoreDependencies.effect` in `knip.config.ts`, because no package has the name
437
574
  `@effect/language-service`.
438
575
 
439
576
  `adamantite doctor` reports each missing part, and `adamantite update` keeps
440
- `@effect/tsgo` on its pinned version. Each `@effect/tsgo` release supports only some Oxlint,
441
- oxlint-tsgolint, and TypeScript versions, so Adamantite moves the pins together. If you
442
- install a TypeScript version that the pinned `@effect/tsgo` does not support, the `prepare`
443
- script fails.
577
+ `@effect/tsgo` on its pinned version. Each `@effect/tsgo` release has Effect builds only for
578
+ some Oxlint and tsrs versions, so Adamantite moves the pins together. With an
579
+ Oxlint or tsrs version that the pinned `@effect/tsgo` has no build of, Oxlint
580
+ does not start, and the message names the versions that it supports. `@effect/tsgo` has no
581
+ builds for Linux with musl.
582
+
583
+ VS Code uses a copy of the Effect compiler and its standard libraries in
584
+ `node_modules/.cache/adamantite/effect/`. Init creates this cache without changing installed
585
+ package files. Zed starts the project's installed `effect-tsgo` CLI with `tsc --lsp --stdio`.
586
+ Both use a native TypeScript version that the installed `@effect/tsgo` supports.
444
587
 
445
- A production-only install, such as `npm ci --omit=dev` or `pnpm install --prod`, still runs
446
- the `prepare` script, but it does not install Adamantite, so the install fails with
447
- `adamantite: not found`. Add `--ignore-scripts` to those installs. Nothing in a production
448
- install needs the patch.
588
+ To upgrade an existing editor setup, run:
589
+
590
+ ```sh
591
+ adamantite update
592
+ adamantite init --non-interactive --script check --preset effect --editor vscode --editor zed --install-extensions
593
+ ```
594
+
595
+ Init installs the TypeScript 7 extension for VS Code when `--install-extensions` is set.
596
+ In VS Code, run **TypeScript: Select TypeScript Version...**, then select **Use Workspace Version**
597
+ to use the Effect SDK. Install Zed's TypeScript language server extension (`zed://extension/tsgo`);
598
+ the managed server ID is `typescript-ls`.
599
+
600
+ After a fresh dependency install or an update, run
601
+ `adamantite init --non-interactive --script check --editor vscode` to prepare or refresh the SDK cache.
602
+ Doctor reports missing editor settings and a missing, incomplete, or stale SDK. It does not
603
+ write files. Install scripts can stay disabled.
449
604
 
450
605
  The rules read their options from the tsconfig entry. For example, `unstable-api-usage`
451
606
  reports each use of an API marked `@stability unstable`. To allow a module on purpose, list
@@ -457,7 +612,7 @@ it in `allowedUnstableApis`:
457
612
  "plugins": [
458
613
  {
459
614
  "name": "@effect/language-service",
460
- "diagnostics": false,
615
+ "diagnostics": true,
461
616
  "allowedUnstableApis": ["effect/cli"],
462
617
  },
463
618
  ],
@@ -476,10 +631,55 @@ as `Date.now()` or `process.env`, in code that is not Effect code. Inside Effect
476
631
  reports them, because `Clock`, `Random`, and `Config` let tests control them. See
477
632
  [ADR 0007](docs/adr/0007-effect-preset-patches-oxlint.md) for the criteria.
478
633
 
634
+ ### The architecture preset
635
+
636
+ `adamantite/lint/architecture` loads the first-party plugin without enabling any rules.
637
+ Use it to configure `adamantite/layers` and `adamantite/import-owners` without the other
638
+ rules of `strict`. It needs no extra package. The `strict` preset still loads the same plugin.
639
+
640
+ ```ts
641
+ import core from "adamantite/lint"
642
+ import architecture from "adamantite/lint/architecture"
643
+ import { defineConfig } from "oxlint"
644
+
645
+ export default defineConfig({
646
+ extends: [core, architecture],
647
+ ignorePatterns: core.ignorePatterns,
648
+ rules: {
649
+ "adamantite/layers": [
650
+ "error",
651
+ {
652
+ root: "src/lib",
653
+ layers: {
654
+ shared: { imports: [] },
655
+ services: { imports: ["shared"] },
656
+ },
657
+ },
658
+ ],
659
+ "adamantite/import-owners": [
660
+ "error",
661
+ { import: "giget", owners: ["src/lib/services/download.ts"] },
662
+ ],
663
+ },
664
+ })
665
+ ```
666
+
667
+ Each option after the severity is one layer map or one import and its owners. Set these
668
+ options for your project. The preset enables neither rule by default.
669
+
670
+ Each layer's `imports` list names siblings, and permissions are transitive. Put a child map
671
+ in that layer's `layers` property. Its root derives from the containing folder, and its
672
+ settings remain local. Every containing map checks the file independently. For the previous
673
+ array-valued declarations, run `adamantite doctor` and follow its migration instructions.
674
+
675
+ You can also select it during setup with
676
+ `adamantite init --non-interactive --script check --preset architecture`.
677
+
479
678
  ### The strict preset
480
679
 
481
- `adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset. Like
482
- `react-strict`, it needs no extra package.
680
+ `adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset.
681
+ It needs no extra package. Most of its type rules come from
682
+ [anti-slop](https://github.com/dmmulroy/anti-slop), which Adamantite ships as a vendored build.
483
683
 
484
684
  - `adamantite/no-overzealous-destructuring` reports destructuring patterns nested more than
485
685
  `maxDepth` levels deep (default 2), such as `const { data: { user: { name } } } = query`,
@@ -487,6 +687,26 @@ reports them, because `Clock`, `Random`, and `Config` let tests control them. Se
487
687
  element does not count. Keep the object and read its members, or split the pattern.
488
688
  - `typescript/consistent-type-assertions` bans type assertions. `as const` stays allowed,
489
689
  and test files (`*.test.*`, `*.spec.*`, and `__tests__/`) keep the core preset's setting.
690
+ - `no-console` reports a console call other than `console.info`.
691
+ - `adamantite/require-suppression-reason` reports an `oxlint-disable` or `eslint-disable`
692
+ comment, including the `-line` and `-next-line` forms, that gives no reason after `--`,
693
+ such as `// oxlint-disable-next-line no-console -- the CLI writes its report to stdout`. A
694
+ comment that names no rule is reported by the core preset's `unicorn/no-abusive-eslint-disable`.
695
+ - `no-warning-comments` reports a comment that starts with `TODO`, `FIXME`, `XXX`, or `HACK`.
696
+ Fix the code now, or track the work in your issue tracker. Do not only rename the marker.
697
+ - The anti-slop rules ask the code to decode input at its boundary into types that it owns.
698
+ They report `unknown` in function signatures and type aliases, loose dictionary types, a
699
+ `typeof` check outside a type predicate, `Reflect.get` and `Reflect.apply`, and Vitest or Jest
700
+ module mocks. They also report adjacent `filter` and `map` passes, a `reduce` that copies its
701
+ accumulator, `shape` in symbol names, and a missing blank line between statement groups.
702
+ - In test files, where type assertions are allowed, `anti-slop/require-safety-comment-for-type-assertion`
703
+ requires a `SAFETY:` comment on each assertion, and `anti-slop/no-chained-type-assertions` and
704
+ `anti-slop/no-widen-then-assert` report assertions that hide the source type. Outside tests,
705
+ `typescript/consistent-type-assertions` is the only rule that reports an assertion. To change
706
+ one of these three rules, set it in an `overrides` entry for the same test files, because the
707
+ preset's override takes priority over top-level `rules`.
708
+ - The preset turns off the core preset's `typescript/consistent-indexed-object-style` and
709
+ `unicorn/no-immediate-mutation`, which conflict with `anti-slop/no-known-value-widening`.
490
710
 
491
711
  Set `maxDepth` and `maxProperties` to change the destructuring limits:
492
712
 
@@ -504,9 +724,11 @@ export default defineConfig({
504
724
  })
505
725
  ```
506
726
 
507
- ### The shadcn preset
727
+ ### The Tailwind preset
508
728
 
509
- `adamantite/lint/shadcn` needs Tailwind v4 and the `@shadcn/lint` package. `adamantite init`
729
+ The preset uses upstream `shadcn/*` rule names and `settings.shadcn` keys.
730
+
731
+ `adamantite/lint/tailwind` needs Tailwind v4 and the `@shadcn/lint` package. `adamantite init`
510
732
  installs the pinned version when you select the preset, and `adamantite doctor` and
511
733
  `adamantite update` keep it on that version. If you add the preset by hand, install
512
734
  `@shadcn/lint` as a devDependency too. The plugin finds your components and theme
@@ -516,11 +738,11 @@ components live elsewhere, set `settings.shadcn.ui`:
516
738
 
517
739
  ```ts
518
740
  import core from "adamantite/lint"
519
- import shadcn from "adamantite/lint/shadcn"
741
+ import tailwind from "adamantite/lint/tailwind"
520
742
  import { defineConfig } from "oxlint"
521
743
 
522
744
  export default defineConfig({
523
- extends: [core, shadcn],
745
+ extends: [core, tailwind],
524
746
  ignorePatterns: core.ignorePatterns,
525
747
  settings: { shadcn: { ui: "@/ds" } },
526
748
  })
@@ -535,21 +757,23 @@ contracts, and custom messages.
535
757
 
536
758
  ## Custom rules
537
759
 
538
- Custom rules are Oxlint rules that your project writes and owns. Each file in
539
- `.adamantite/rules/` is one rule. `custom()` from `adamantite/lint/custom` loads the folder
760
+ Custom rules are Oxlint rules that your project writes and owns. Each rule file in
761
+ `.adamantite/lint/` is one rule. `custom()` from `adamantite/rules` loads the folder
540
762
  and enables each rule as `error` under the `project` plugin, so `no-process-env.ts` becomes
541
763
  `project/no-process-env`. Add a file to add a rule, and delete the file to remove it. A file
542
- that starts with `_`, such as `_helpers.ts`, is a helper, not a rule.
764
+ that starts with `_`, such as `_helpers.ts`, is a helper. Declaration files and optional
765
+ `.test.*` files are also excluded from plugin loading.
543
766
 
544
767
  ```text
545
- .adamantite/rules/
768
+ .adamantite/lint/
546
769
  no-process-env.ts # enabled as project/no-process-env
770
+ no-process-env.test.ts # optional test, skipped by the plugin
547
771
  _helpers.ts # skipped
548
772
  ```
549
773
 
550
774
  ```ts
551
- // .adamantite/rules/no-process-env.ts
552
- import { defineRule } from "adamantite/rules"
775
+ // .adamantite/lint/no-process-env.ts
776
+ import { defineRule } from "adamantite/rules/plugin"
553
777
 
554
778
  export default defineRule({
555
779
  meta: {
@@ -571,7 +795,7 @@ export default defineRule({
571
795
  ```ts
572
796
  // oxlint.config.ts
573
797
  import core from "adamantite/lint"
574
- import custom from "adamantite/lint/custom"
798
+ import custom from "adamantite/rules"
575
799
  import { defineConfig } from "oxlint"
576
800
 
577
801
  export default defineConfig({
@@ -584,20 +808,64 @@ export default defineConfig({
584
808
  it to every generated config. It takes these options:
585
809
 
586
810
  - `dir`: the rules folder. A relative path resolves from the file that calls `custom()`, not
587
- from the working directory. Default: `.adamantite/rules`.
811
+ from the working directory. Default: `.adamantite/lint`.
588
812
  - `name`: the plugin name that prefixes each rule. Default: `project`.
589
813
  - `rules`: severity or options for a rule, by rule name without the prefix, such as
590
814
  `{ "no-process-env": "warn" }`.
591
815
 
816
+ `adamantite/rules/plugin` re-exports the helpers and types from Adamantite's pinned
817
+ `@oxlint/plugins` dependency. Use `definePlugin` from that module if you write a plugin
818
+ that you register in `jsPlugins` yourself. You do not need to add `@oxlint/plugins` to your project.
819
+
820
+ Optional saved RuleTester tests use `node:test`. Exclude them from Vitest or Jest discovery
821
+ so those runners do not also try to run them. Keep the runner's default and existing
822
+ exclusions. For Vitest:
823
+
824
+ ```ts
825
+ // vitest.config.ts
826
+ import { configDefaults, defineConfig } from "vitest/config"
827
+
828
+ export default defineConfig({
829
+ test: {
830
+ exclude: [...configDefaults.exclude, ".adamantite/lint/**/*.test.*"],
831
+ },
832
+ })
833
+ ```
834
+
835
+ For Jest:
836
+
837
+ ```js
838
+ // jest.config.mjs
839
+ export default {
840
+ testPathIgnorePatterns: ["/node_modules/", "<rootDir>/.adamantite/lint/"],
841
+ }
842
+ ```
843
+
844
+ For another rules folder or a custom test `--path`, use its path in the exclusion. To
845
+ type-check tests that import `.ts` rule files, enable `compilerOptions.allowImportingTsExtensions`
846
+ in `tsconfig.json`. To check the hidden rules folder too, add `.adamantite/lint` to `include`.
847
+
848
+ To keep an existing `.adamantite/rules` folder, set `custom({ dir: ".adamantite/rules" })`
849
+ and use `rule add --dir .adamantite/rules`. You can instead move the folder to
850
+ `.adamantite/lint`. The previous `adamantite/lint/custom` import and named authoring imports
851
+ from `adamantite/rules` are removed. Import `custom` from `adamantite/rules` and the
852
+ authoring helpers and types from `adamantite/rules/plugin`. Run `adamantite doctor` for
853
+ migration instructions. Doctor reports the old imports and default folder without changing files.
854
+
592
855
  Rule files run with Node.js type stripping, so use erasable TypeScript only: no `enum`,
593
856
  `namespace` with values, or parameter properties. Rules get no type information. A rule
594
857
  that throws prints an error for each file, and the lint run still exits 0. Adamantite owns
595
- the wiring and the authoring guidance; your project owns the correctness and the tests of
596
- its rules. To test a rule, use `RuleTester` from `oxlint/plugins-dev`. `adamantite rule add`
597
- writes the full authoring guidance to `.adamantite/rules/AGENTS.md`.
858
+ the wiring and the authoring guidance; your project owns the correctness of its rules.
859
+ Agents use `RuleTester` from `adamantite/rules/testing` to verify new and changed rules.
860
+ They run valid and invalid cases from stdin or a temporary file with Node.js, also in Bun
861
+ projects, and remove their temporary verification cases and fixtures before handback. The rules and their
862
+ runtime helpers stay in the target project. The "Custom rules" section of the
863
+ [Adamantite skill](#agent-skill) has the command and the full authoring guidance.
598
864
 
599
865
  `adamantite doctor` reports a rule file that cannot load, with the reason, a rules folder
600
- that no `custom()` call loads, and two rules folders that use the same plugin name.
866
+ that no `custom()` call loads, and two rules folders that use the same plugin name. It also
867
+ provides migration guidance for old API imports and the previous default rules folder.
868
+ User-owned saved tests and optional CI steps remain supported.
601
869
 
602
870
  ### Custom rules in a monorepo
603
871
 
@@ -607,7 +875,7 @@ root rules extends the root config:
607
875
 
608
876
  ```ts
609
877
  // packages/web/oxlint.config.ts
610
- import custom from "adamantite/lint/custom"
878
+ import custom from "adamantite/rules"
611
879
  import { defineConfig } from "oxlint"
612
880
  import root from "../../oxlint.config.ts"
613
881
 
@@ -620,14 +888,15 @@ extends it loads the same rules:
620
888
 
621
889
  ```ts
622
890
  // tooling/lint/index.ts
623
- import custom from "adamantite/lint/custom"
891
+ import custom from "adamantite/rules"
624
892
 
625
893
  export default custom({ dir: "rules", name: "acme" })
626
894
  ```
627
895
 
628
896
  Run `adamantite rule add <name> --dir tooling/lint/rules` to add a rule to that folder.
629
897
  Doctor starts from the Oxlint config of the root and of each workspace package, and follows
630
- relative imports and imports of workspace packages to find the `custom()` calls. It resolves
898
+ relative imports, `#` imports, and imports of workspace packages to find the `custom()` calls. It
899
+ resolves them as Node.js does, so run it after you install the dependencies. It resolves
631
900
  `dir` and `name` when they are string literals.
632
901
 
633
902
  ## Requirements and boundaries
@@ -647,16 +916,38 @@ relative imports and imports of workspace packages to find the `custom()` calls.
647
916
 
648
917
  ## Agent skill
649
918
 
650
- Install the first-party Adamantite skill to teach coding agents how to initialize, assess,
651
- repair, and update a project:
919
+ The Adamantite skill teaches coding agents how to initialize, assess, repair, and update a
920
+ project, and how to write [custom rules](#custom-rules). The Adamantite package ships it.
921
+
922
+ `adamantite init` asks whether to set up coding agents. When you answer yes, or pass
923
+ `--agents` in non-interactive mode, init adds the Adamantite section to `AGENTS.md` and writes
924
+ the skill to these folders:
925
+
926
+ | Skill folder | Agents | When |
927
+ | ---------------- | --------------------------------------- | --------------------------- |
928
+ | `.agents/skills` | Codex, Cursor, Gemini CLI, and OpenCode | Always |
929
+ | `.claude/skills` | Claude Code | The project has `.claude/`. |
930
+ | `.grok/skills` | Grok Build | The project has `.grok/`. |
931
+
932
+ The Adamantite CLI bundles the skill, so the copy matches the Adamantite version that wrote
933
+ it. After you update Adamantite, `adamantite update` writes the skill again to each folder
934
+ whose copy changed. It also removes the `adamantite` entry from `skills-lock.json`, so the
935
+ `skills` CLI does not write the same folders. Commit the skill folders, so every clone has
936
+ the skill.
937
+
938
+ To install the skill from GitHub instead, with the
939
+ [`skills` CLI](https://github.com/vercel-labs/skills):
652
940
 
653
941
  ```sh
654
942
  npx skills add adelrodriguez/adamantite --list
655
943
  npx skills add adelrodriguez/adamantite --skill adamantite
656
944
  ```
657
945
 
658
- The Adamantite package also ships the skill. With pnpm 12.11 or later, `pnpm install` links
659
- it into the agent skill directories that exist in the project, such as `.claude/skills`,
946
+ `adamantite update` replaces a copy from GitHub with the skill of the installed Adamantite
947
+ version.
948
+
949
+ With pnpm 12.11 or later, `pnpm install` can also link the skill that the package ships
950
+ into the agent skill directories that exist in the project, such as `.claude/skills`,
660
951
  after you approve it. pnpm creates the directory only when the agent that runs pnpm sets an
661
952
  environment variable that identifies it, such as `CLAUDECODE` for `.claude/skills`.
662
953
  Otherwise, if no skill directory exists, the install fails, so create one before you