@kirill.konshin/lint 0.5.0 → 0.5.2

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.
package/README.md CHANGED
@@ -329,13 +329,15 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
329
329
 
330
330
  In the project root, `lint-prepare`:
331
331
 
332
- - Symlinks every `rules/*.md` into `.claude/rules/`, where Claude Code auto-discovers them.
333
- - Symlinks every skill into `.claude/skills/<name>/` and `.codex/skills/<name>/` (`SKILL.md` plus this `README.md` alongside it, so a skill can reference `@README.md`) — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules.
334
- - Generates `AGENTS.md` referencing the same rules for other assistants (Codex, Cursor, Copilot, …) and symlinks `CLAUDE.md` to it.
332
+ - Creates real `rules/`, `commands/` and `skills/` directories in `.agents/` (canonical, cross-tool), `.claude/` (Claude Code) and `.codex/`, and only ever symlinks files into them.
333
+ - Links every `rules/*.md` and skill (`skills/<name>/SKILL.md` plus this `README.md` alongside it, so a skill can reference `@README.md`) into all three — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules. Links point straight at the installed package's real location (`node_modules/@kirill.konshin/lint`, or the workspace package).
334
+ - Mirrors your own files from `.agents/{rules,commands,skills}/` into `.claude/` and `.codex/`; a file of yours wins over the package file at the same path.
335
+ - Removes dead links (e.g. after renaming a file) and the links it placed before but no longer needs. Each directory gets a generated `.gitignore` listing its links, so your own files stay tracked.
336
+ - Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — per rule (the package's and yours) a `## <Title>` (from the file name), its frontmatter `description` and an `@path` to its `.agents/rules/<file>` entry — and symlinks `CLAUDE.md` to it.
335
337
 
336
338
  ### Safety checks
337
339
 
338
- `init`/`update` refuse to run if `.claude/rules`, a skill target dir, or `CLAUDE.md` contains anything that isn't a symlink — this avoids silently overwriting files you created by hand. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
340
+ Only the files `lint-prepare` knows (package files and mirrors of yours) and dead links are touched: real files are never overwritten (e.g. your own `.claude/rules/*.md`, Codex command policies in `.codex/rules/*.rules`) and nothing is written through a symlinked directory. `init`/`update` refuse to run if `CLAUDE.md` isn't a symlink. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
339
341
 
340
342
  ## Migration
341
343
 
@@ -2,11 +2,12 @@
2
2
  /**
3
3
  * @kirill.konshin/lint
4
4
  *
5
- * This script symlinks all markdown rule files from the package into the consuming
6
- * project's `.claude/rules` directory (auto-discovered by Claude Code), symlinks every
7
- * package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/` (SKILL.md plus
8
- * the package README.md alongside it, so a skill can reference `@README.md`), and generates
9
- * an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
5
+ * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
+ * `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
7
+ * file symlinks only: package rules and skills (SKILL.md plus the package README.md alongside it,
8
+ * so a skill can reference `@README.md`) go into all three, pointing straight at the installed
9
+ * package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
10
+ * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
10
11
  *
11
12
  * Usage:
12
13
  * lint-prepare init - Initialize AGENTS.md in the current directory (default)
@@ -19,6 +20,7 @@
19
20
  type Rule = {
20
21
  file: string;
21
22
  name: string;
23
+ description?: string;
22
24
  content: string;
23
25
  };
24
26
  type Skill = {
@@ -40,18 +42,21 @@ export declare function readRules(): Rule[];
40
42
  */
41
43
  export declare function readSkills(): Skill[];
42
44
  /**
43
- * Fail if `.claude/rules` contains anything that isn't a symlink - we don't want to
44
- * silently blow away a real file/directory a user placed there by hand.
45
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and `skills/<name>/SKILL.md` plus
46
+ * the package README.md next to it, so a skill can reference `@README.md`.
45
47
  */
46
- export declare function checkRulesDirSafety(rulesTargetDir: string): void;
48
+ export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string, string>;
47
49
  /**
48
- * Fail if `CLAUDE.md` exists and isn't a symlink - same reasoning as checkRulesDirSafety.
50
+ * The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
51
+ * except the package links (and dotfiles).
49
52
  */
50
- export declare function checkClaudeMdSafety(claudeMdPath: string): void;
53
+ export declare function readUserFiles(cwd: string): Map<string, string>;
51
54
  /**
52
- * Symlink rules into the consuming project's `.claude/rules` directory.
53
- * Safe to wipe and recreate: checkRulesDirSafety already guaranteed every existing
54
- * entry is a symlink.
55
+ * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
56
+ * package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
57
+ * `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
58
+ * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
59
+ * records them (and keeps them out of git, so the user's own files there stay tracked).
55
60
  *
56
61
  * FIXME Codex Includes
57
62
  * https://github.com/openai/codex/issues/17401
@@ -62,34 +67,29 @@ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
62
67
  * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
63
68
  * indexed anywhere).
64
69
  */
65
- export declare function symlinkRules(cwd: string, rules: Rule[]): string;
70
+ export declare function syncAgentDirs(cwd: string, packageFiles: Map<string, string>, userFiles: Map<string, string>): void;
66
71
  /**
67
- * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
68
- * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
69
- * own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
70
- * parent, since other packages (or the user) may keep unrelated skills there.
72
+ * Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
71
73
  */
72
- export declare function checkSkillDirSafety(skillDir: string): void;
74
+ export declare function installedRules(rules: Rule[], userFiles: Map<string, string>): Rule[];
73
75
  /**
74
- * Symlink each package skill into `<cwd>/.claude/skills/<name>/` and
75
- * `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
76
- * them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
77
- * via `@README.md` regardless of how the tool resolves relative mentions.
76
+ * Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
78
77
  */
79
- export declare function symlinkSkills(cwd: string, skills: Skill[]): string[];
78
+ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
80
79
  /**
81
80
  * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
82
81
  */
83
82
  export declare function symlinkClaudeMd(cwd: string): void;
84
83
  /**
85
- * Generate AGENTS.md with references to the rule files.
84
+ * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
85
+ * and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
86
86
  *
87
- * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
87
+ * `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
88
88
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
89
89
  * under `.claude/rules`, symlinks included) - no reference to them is needed here.
90
90
  * The sections below are for other tools that only read AGENTS.md.
91
91
  */
92
- export declare function generateAgentsFile(rules: Rule[], cwd: string, customSection: string | null): string;
92
+ export declare function generateAgentsFile(rules: Rule[], customSection: string | null): string;
93
93
  /**
94
94
  * Check if AGENTS.md exists and was generated by this tool. When it was, also return
95
95
  * whatever follows the marker (the user's custom section) so it can be carried forward -
@@ -1 +1 @@
1
- {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AASH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5D,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5C,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAuB1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAwBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAYhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAa/D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAY1D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,CA2BpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAenG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAuD3B"}
1
+ {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;GAiBG;AAUH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5C,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AA8M1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAmBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAchF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkClH;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAYpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAsBtF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAmD3B"}
@@ -2,11 +2,12 @@
2
2
  /**
3
3
  * @kirill.konshin/lint
4
4
  *
5
- * This script symlinks all markdown rule files from the package into the consuming
6
- * project's `.claude/rules` directory (auto-discovered by Claude Code), symlinks every
7
- * package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/` (SKILL.md plus
8
- * the package README.md alongside it, so a skill can reference `@README.md`), and generates
9
- * an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
5
+ * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
+ * `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
7
+ * file symlinks only: package rules and skills (SKILL.md plus the package README.md alongside it,
8
+ * so a skill can reference `@README.md`) go into all three, pointing straight at the installed
9
+ * package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
10
+ * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
10
11
  *
11
12
  * Usage:
12
13
  * lint-prepare init - Initialize AGENTS.md in the current directory (default)
@@ -19,15 +20,23 @@
19
20
  import fs from 'node:fs';
20
21
  import path from 'node:path';
21
22
  import { fileURLToPath } from 'node:url';
23
+ import { parse } from 'yaml';
22
24
  const __filename = fileURLToPath(import.meta.url);
23
25
  const __dirname = path.dirname(__filename);
24
26
  const AGENTS_FILE = 'AGENTS.md';
25
27
  const CLAUDE_FILE = 'CLAUDE.md';
26
- const CLAUDE_RULES_DIR = '.claude/rules';
27
28
  const RULES_DIR = path.join(__dirname, '../rules');
28
29
  const SKILLS_DIR = path.join(__dirname, '../skills');
29
30
  const README_FILE = path.join(__dirname, '../README.md');
30
- const SKILLS_TARGET_DIRS = ['.claude/skills', '.codex/skills'];
31
+ // `.agents` is the cross-tool location (Codex, Cursor, Antigravity) holding the package links and the user's own
32
+ // files, the latter are mirrored into `.claude` (Claude Code reads nothing else) and `.codex`
33
+ const CANONICAL_AGENT_DIR = '.agents';
34
+ const MIRROR_AGENT_DIRS = ['.claude', '.codex'];
35
+ const AGENT_DIRS = [CANONICAL_AGENT_DIR, ...MIRROR_AGENT_DIRS];
36
+ const AGENT_KINDS = ['rules', 'commands', 'skills'];
37
+ const GITIGNORE = '.gitignore';
38
+ const GITIGNORE_HEADER = '# Generated by @kirill.konshin/lint: symlinks it manages here, your own files stay tracked';
39
+ const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
31
40
  const HEADER = `# AI Agent Rules
32
41
 
33
42
  This file is auto-generated by @kirill.konshin/lint. Do not edit directly - customize by adding your own rules below the generated section.
@@ -39,6 +48,156 @@ const FOOTER = `---
39
48
 
40
49
  Add your project-specific rules below the comment line.`;
41
50
  const GENERATED_MARKER = '<!-- @kirill.konshin/lint:generated -->';
51
+ const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
52
+ /**
53
+ * `monorepo-turbo-nx` -> `Monorepo turbo nx`
54
+ */
55
+ const toTitle = (name) => {
56
+ const title = name.replaceAll('-', ' ');
57
+ return title.charAt(0).toUpperCase() + title.slice(1);
58
+ };
59
+ /**
60
+ * The `description` field of a rule's YAML frontmatter.
61
+ */
62
+ const readDescription = (content) => {
63
+ const frontmatter = FRONTMATTER.exec(content)?.[1];
64
+ const description = frontmatter ? parse(frontmatter)?.description : undefined;
65
+ return typeof description === 'string' ? description.trim() : undefined;
66
+ };
67
+ /**
68
+ * `file` is the path inside a rules dir, e.g. `auth.md` or `frontend/react.md`.
69
+ */
70
+ const toRule = (file, content) => ({
71
+ file,
72
+ name: path.posix.basename(file, '.md'),
73
+ description: readDescription(content),
74
+ content,
75
+ });
76
+ /**
77
+ * Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
78
+ * directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
79
+ */
80
+ function listRealFiles(root, dir = root) {
81
+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
82
+ const entryPath = path.join(dir, entry.name);
83
+ if (entry.name.startsWith('.'))
84
+ return [];
85
+ if (entry.isDirectory())
86
+ return listRealFiles(root, entryPath);
87
+ return entry.isFile() ? [path.relative(root, entryPath)] : [];
88
+ });
89
+ }
90
+ /**
91
+ * Dead symlinks under `dir`, walking real directories only.
92
+ */
93
+ function findDeadLinks(dir) {
94
+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
95
+ const entryPath = path.join(dir, entry.name);
96
+ if (entry.isDirectory())
97
+ return findDeadLinks(entryPath);
98
+ return entry.isSymbolicLink() && !fs.existsSync(entryPath) ? [entryPath] : [];
99
+ });
100
+ }
101
+ /**
102
+ * Remove `link` and the directories it leaves empty, up to `root`.
103
+ */
104
+ function removeLink(link, root) {
105
+ fs.unlinkSync(link);
106
+ for (let dir = path.dirname(link); dir !== root && !fs.readdirSync(dir).length; dir = path.dirname(dir)) {
107
+ fs.rmdirSync(dir);
108
+ }
109
+ }
110
+ /**
111
+ * mkdir -p `dir` (relative to cwd, starting with an agent dir, which itself may be a link) without going through
112
+ * links below it: false when a part is a symlink or a file - those are the user's, nothing is written through them.
113
+ */
114
+ function ensureRealDir(cwd, dir) {
115
+ const [agentDir, ...parts] = dir.split(path.sep);
116
+ let current = path.join(cwd, agentDir);
117
+ fs.mkdirSync(current, { recursive: true });
118
+ for (const part of parts) {
119
+ current = path.join(current, part);
120
+ const stat = lstat(current);
121
+ if (!stat)
122
+ fs.mkdirSync(current);
123
+ else if (!stat.isDirectory())
124
+ return false;
125
+ }
126
+ return true;
127
+ }
128
+ /**
129
+ * Point `link` (relative to cwd) at `target`, unless the spot is the user's: a real file there, or a linked
130
+ * directory on the way. Returns whether the link is in place.
131
+ */
132
+ function placeLink(cwd, link, target) {
133
+ const linkPath = path.join(cwd, link);
134
+ if (!ensureRealDir(cwd, path.dirname(link))) {
135
+ console.log(`Skipped ${link}: ${path.dirname(link)} is not a real directory`);
136
+ return false;
137
+ }
138
+ const stat = lstat(linkPath);
139
+ if (stat && !stat.isSymbolicLink()) {
140
+ console.log(`Kept ${link}: not a symlink`);
141
+ return false;
142
+ }
143
+ // relative between REAL locations: cwd and the package (workspaces, yalc, pnpm store) may be reached through
144
+ // symlinks, and a path computed between a symlinked and a real location dangles
145
+ const text = path.relative(fs.realpathSync(path.dirname(linkPath)), target);
146
+ if (stat && fs.readlinkSync(linkPath) === text)
147
+ return true;
148
+ if (stat)
149
+ fs.unlinkSync(linkPath);
150
+ fs.symlinkSync(text, linkPath);
151
+ return true;
152
+ }
153
+ /**
154
+ * Links listed in a `.gitignore` this tool generated - it doubles as the record of what to clean up next time.
155
+ */
156
+ function readManifest(gitignore) {
157
+ const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf-8') : '';
158
+ if (!content.startsWith(GITIGNORE_HEADER))
159
+ return [];
160
+ return content
161
+ .split('\n')
162
+ .filter((line) => line.startsWith('/') && line !== `/${GITIGNORE}`)
163
+ .map((line) => path.normalize(line.slice(1)));
164
+ }
165
+ /**
166
+ * Write the `.gitignore` listing `links` (remove it when there are none), unless the user owns that file.
167
+ */
168
+ function writeManifest(gitignore, links) {
169
+ const exists = fs.existsSync(gitignore);
170
+ if (exists && !fs.readFileSync(gitignore, 'utf-8').startsWith(GITIGNORE_HEADER))
171
+ return;
172
+ if (!links.length) {
173
+ if (exists)
174
+ fs.unlinkSync(gitignore);
175
+ return;
176
+ }
177
+ const entries = links.map((link) => `/${link.split(path.sep).join('/')}`).sort();
178
+ fs.writeFileSync(gitignore, [GITIGNORE_HEADER, `/${GITIGNORE}`, ...entries, ''].join('\n'));
179
+ }
180
+ /**
181
+ * Links to place, keyed by their path relative to cwd: package files into every agent dir, the user's own `.agents`
182
+ * files into the mirrors. A user file wins over the package file at the same path.
183
+ */
184
+ function plannedLinks(cwd, packageFiles, userFiles) {
185
+ const canonicalDir = path.join(fs.realpathSync(cwd), CANONICAL_AGENT_DIR);
186
+ const links = new Map();
187
+ for (const [file, source] of packageFiles) {
188
+ if (userFiles.has(file)) {
189
+ console.log(`${path.join(CANONICAL_AGENT_DIR, file)} overrides the package file`);
190
+ continue;
191
+ }
192
+ for (const dir of AGENT_DIRS)
193
+ links.set(path.join(dir, file), fs.realpathSync(source));
194
+ }
195
+ for (const file of userFiles.keys()) {
196
+ for (const dir of MIRROR_AGENT_DIRS)
197
+ links.set(path.join(dir, file), path.join(canonicalDir, file));
198
+ }
199
+ return links;
200
+ }
42
201
  /**
43
202
  * Read all markdown files from the package rules directory.
44
203
  */
@@ -54,12 +213,7 @@ export function readRules() {
54
213
  .sort();
55
214
  for (const file of files) {
56
215
  const filePath = path.join(RULES_DIR, file);
57
- const content = fs.readFileSync(filePath, 'utf-8');
58
- rules.push({
59
- file,
60
- name: file.replace('.md', ''),
61
- content,
62
- });
216
+ rules.push(toRule(file, fs.readFileSync(filePath, 'utf-8')));
63
217
  }
64
218
  return rules;
65
219
  }
@@ -77,42 +231,44 @@ export function readSkills() {
77
231
  .map((file) => ({ file, name: file.replace('.md', '') }));
78
232
  }
79
233
  /**
80
- * Fail if `.claude/rules` contains anything that isn't a symlink - we don't want to
81
- * silently blow away a real file/directory a user placed there by hand.
234
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and `skills/<name>/SKILL.md` plus
235
+ * the package README.md next to it, so a skill can reference `@README.md`.
82
236
  */
83
- export function checkRulesDirSafety(rulesTargetDir) {
84
- if (!fs.existsSync(rulesTargetDir))
85
- return;
86
- for (const entry of fs.readdirSync(rulesTargetDir)) {
87
- const entryPath = path.join(rulesTargetDir, entry);
88
- if (!fs.lstatSync(entryPath).isSymbolicLink()) {
89
- console.error(`${CLAUDE_RULES_DIR}/${entry} exists and is not a symlink.`);
90
- console.error('Remove or back it up manually, then re-run.');
91
- process.exit(1);
92
- }
237
+ export function packageFiles(rules, skills) {
238
+ const files = new Map();
239
+ const hasReadme = fs.existsSync(README_FILE);
240
+ for (const rule of rules) {
241
+ files.set(path.join('rules', rule.file), path.join(RULES_DIR, rule.file));
242
+ }
243
+ for (const skill of skills) {
244
+ files.set(path.join('skills', skill.name, 'SKILL.md'), path.join(SKILLS_DIR, skill.file));
245
+ if (hasReadme)
246
+ files.set(path.join('skills', skill.name, 'README.md'), README_FILE);
93
247
  }
248
+ return files;
94
249
  }
95
250
  /**
96
- * Fail if `CLAUDE.md` exists and isn't a symlink - same reasoning as checkRulesDirSafety.
251
+ * The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
252
+ * except the package links (and dotfiles).
97
253
  */
98
- export function checkClaudeMdSafety(claudeMdPath) {
99
- let stat;
100
- try {
101
- stat = fs.lstatSync(claudeMdPath);
102
- }
103
- catch {
104
- return;
105
- }
106
- if (!stat.isSymbolicLink()) {
107
- console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
108
- console.error('Remove or back it up manually, then re-run.');
109
- process.exit(1);
254
+ export function readUserFiles(cwd) {
255
+ const files = new Map();
256
+ for (const kind of AGENT_KINDS) {
257
+ const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
258
+ if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory())
259
+ continue;
260
+ for (const file of listRealFiles(root)) {
261
+ files.set(path.join(kind, file), path.join(root, file));
262
+ }
110
263
  }
264
+ return files;
111
265
  }
112
266
  /**
113
- * Symlink rules into the consuming project's `.claude/rules` directory.
114
- * Safe to wipe and recreate: checkRulesDirSafety already guaranteed every existing
115
- * entry is a symlink.
267
+ * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
268
+ * package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
269
+ * `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
270
+ * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
271
+ * records them (and keeps them out of git, so the user's own files there stay tracked).
116
272
  *
117
273
  * FIXME Codex Includes
118
274
  * https://github.com/openai/codex/issues/17401
@@ -123,61 +279,65 @@ export function checkClaudeMdSafety(claudeMdPath) {
123
279
  * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
124
280
  * indexed anywhere).
125
281
  */
126
- export function symlinkRules(cwd, rules) {
127
- const targetDir = path.join(cwd, CLAUDE_RULES_DIR);
128
- fs.rmSync(targetDir, { recursive: true, force: true });
129
- fs.mkdirSync(targetDir, { recursive: true });
130
- for (const rule of rules) {
131
- const source = path.join(RULES_DIR, rule.file);
132
- const linkPath = path.join(targetDir, rule.file);
133
- fs.symlinkSync(path.relative(targetDir, source), linkPath);
282
+ export function syncAgentDirs(cwd, packageFiles, userFiles) {
283
+ const links = plannedLinks(cwd, packageFiles, userFiles);
284
+ for (const dir of AGENT_DIRS) {
285
+ for (const kind of AGENT_KINDS) {
286
+ const root = path.join(dir, kind);
287
+ const rootPath = path.join(cwd, root);
288
+ const gitignore = path.join(rootPath, GITIGNORE);
289
+ if (!ensureRealDir(cwd, root)) {
290
+ console.log(`Skipped ${root}: not a real directory`);
291
+ continue;
292
+ }
293
+ for (const link of findDeadLinks(rootPath)) {
294
+ removeLink(link, rootPath);
295
+ }
296
+ const placed = [];
297
+ for (const [link, target] of links) {
298
+ if (link.startsWith(root + path.sep) && placeLink(cwd, link, target)) {
299
+ placed.push(path.relative(root, link));
300
+ }
301
+ }
302
+ for (const link of readManifest(gitignore)) {
303
+ const linkPath = path.join(rootPath, link);
304
+ if (!placed.includes(link) && lstat(linkPath)?.isSymbolicLink())
305
+ removeLink(linkPath, rootPath);
306
+ }
307
+ writeManifest(gitignore, placed);
308
+ }
134
309
  }
135
- return targetDir;
136
310
  }
137
311
  /**
138
- * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
139
- * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
140
- * own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
141
- * parent, since other packages (or the user) may keep unrelated skills there.
312
+ * Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
142
313
  */
143
- export function checkSkillDirSafety(skillDir) {
144
- if (!fs.existsSync(skillDir))
145
- return;
146
- for (const entry of fs.readdirSync(skillDir)) {
147
- const entryPath = path.join(skillDir, entry);
148
- if (!fs.lstatSync(entryPath).isSymbolicLink()) {
149
- console.error(`${skillDir}/${entry} exists and is not a symlink.`);
150
- console.error('Remove or back it up manually, then re-run.');
151
- process.exit(1);
152
- }
314
+ export function installedRules(rules, userFiles) {
315
+ const byFile = new Map(rules.map((rule) => [rule.file, rule]));
316
+ const rulesDir = `rules${path.sep}`;
317
+ for (const [file, source] of userFiles) {
318
+ if (!file.startsWith(rulesDir) || !file.endsWith('.md'))
319
+ continue;
320
+ const ruleFile = file.slice(rulesDir.length).split(path.sep).join('/');
321
+ byFile.set(ruleFile, toRule(ruleFile, fs.readFileSync(source, 'utf-8')));
153
322
  }
323
+ return [...byFile].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, rule]) => rule);
154
324
  }
155
325
  /**
156
- * Symlink each package skill into `<cwd>/.claude/skills/<name>/` and
157
- * `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
158
- * them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
159
- * via `@README.md` regardless of how the tool resolves relative mentions.
326
+ * Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
160
327
  */
161
- export function symlinkSkills(cwd, skills) {
162
- const targetDirs = [];
163
- const hasReadme = fs.existsSync(README_FILE);
164
- for (const skill of skills) {
165
- for (const targetRoot of SKILLS_TARGET_DIRS) {
166
- const skillDir = path.join(cwd, targetRoot, skill.name);
167
- checkSkillDirSafety(skillDir);
168
- fs.rmSync(skillDir, { recursive: true, force: true });
169
- fs.mkdirSync(skillDir, { recursive: true });
170
- const source = path.join(SKILLS_DIR, skill.file);
171
- const linkPath = path.join(skillDir, 'SKILL.md');
172
- fs.symlinkSync(path.relative(skillDir, source), linkPath);
173
- if (hasReadme) {
174
- const readmeLink = path.join(skillDir, 'README.md');
175
- fs.symlinkSync(path.relative(skillDir, README_FILE), readmeLink);
176
- }
177
- targetDirs.push(skillDir);
178
- }
328
+ export function checkClaudeMdSafety(claudeMdPath) {
329
+ let stat;
330
+ try {
331
+ stat = fs.lstatSync(claudeMdPath);
332
+ }
333
+ catch {
334
+ return;
335
+ }
336
+ if (!stat.isSymbolicLink()) {
337
+ console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
338
+ console.error('Remove or back it up manually, then re-run.');
339
+ process.exit(1);
179
340
  }
180
- return targetDirs;
181
341
  }
182
342
  /**
183
343
  * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
@@ -188,24 +348,32 @@ export function symlinkClaudeMd(cwd) {
188
348
  fs.symlinkSync(AGENTS_FILE, claudeMdPath);
189
349
  }
190
350
  /**
191
- * Generate AGENTS.md with references to the rule files.
351
+ * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
352
+ * and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
192
353
  *
193
- * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
354
+ * `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
194
355
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
195
356
  * under `.claude/rules`, symlinks included) - no reference to them is needed here.
196
357
  * The sections below are for other tools that only read AGENTS.md.
197
358
  */
198
- export function generateAgentsFile(rules, cwd, customSection) {
199
- const relativeRulesDir = path.relative(cwd, RULES_DIR).split(path.sep).join('/');
359
+ export function generateAgentsFile(rules, customSection) {
200
360
  /**
201
361
  * @see https://code.claude.com/docs/en/memory#import-additional-files
202
362
  * @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
203
363
  * @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
204
364
  */
205
- const links = rules
206
- .map((rule) => `- @${relativeRulesDir}/${rule.file} [${rule.file}](${relativeRulesDir}/${rule.file})`)
207
- .join('\n');
208
- const generated = `${HEADER}\n\n${links}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
365
+ const sections = rules.map((rule) => {
366
+ // the canonical entry (a package link or the user's own file), not the package install path
367
+ const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
368
+ return [
369
+ `## ${toTitle(rule.name)}`,
370
+ rule.description,
371
+ `See instructions in @${rulePath} [${rulePath}](${rulePath}).`,
372
+ ]
373
+ .filter(Boolean)
374
+ .join('\n\n');
375
+ });
376
+ const generated = `${HEADER}\n\n# Rules\n\n${sections.join('\n\n')}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
209
377
  return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
210
378
  }
211
379
  /**
@@ -233,7 +401,6 @@ export function main() {
233
401
  const cwd = process.env.INIT_CWD || process.cwd();
234
402
  const targetPath = path.join(cwd, AGENTS_FILE);
235
403
  const claudeMdPath = path.join(cwd, CLAUDE_FILE);
236
- const rulesTargetDir = path.join(cwd, CLAUDE_RULES_DIR);
237
404
  console.log(`@kirill.konshin/lint: ${command}`);
238
405
  console.log(`Target: ${targetPath}`);
239
406
  const { exists, generated, customSection } = checkExisting(targetPath);
@@ -248,19 +415,15 @@ export function main() {
248
415
  }
249
416
  }
250
417
  if (command === 'update' || command === 'init') {
251
- checkRulesDirSafety(rulesTargetDir);
252
418
  checkClaudeMdSafety(claudeMdPath);
253
419
  const rules = readRules();
254
420
  console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(', ')}`);
255
- const targetRulesDir = symlinkRules(cwd, rules);
256
- console.log(`Symlinked rules to ${targetRulesDir}`);
257
421
  const skills = readSkills();
258
422
  console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
259
- const targetSkillDirs = symlinkSkills(cwd, skills);
260
- for (const targetSkillDir of targetSkillDirs) {
261
- console.log(`Symlinked skill to ${targetSkillDir}`);
262
- }
263
- const content = generateAgentsFile(rules, cwd, customSection);
423
+ const userFiles = readUserFiles(cwd);
424
+ syncAgentDirs(cwd, packageFiles(rules, skills), userFiles);
425
+ console.log(`Synced ${AGENT_DIRS.join(', ')}, mirrored ${userFiles.size} own file(s) from ${CANONICAL_AGENT_DIR}`);
426
+ const content = generateAgentsFile(installedRules(rules, userFiles), customSection);
264
427
  fs.writeFileSync(targetPath, content, 'utf-8');
265
428
  console.log(`${exists ? 'Updated' : 'Created'} ${AGENTS_FILE}`);
266
429
  symlinkClaudeMd(cwd);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
3
  "description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
4
- "version": "0.5.0",
4
+ "version": "0.5.2",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
@@ -73,7 +73,8 @@
73
73
  "globals": "^17.11.0",
74
74
  "jsonc-eslint-parser": "^3.3.0",
75
75
  "local-pkg": "^1.2.1",
76
- "path-scurry": "^2.0.2"
76
+ "path-scurry": "^2.0.2",
77
+ "yaml": "^2.9.0"
77
78
  },
78
79
  "devDependencies": {
79
80
  "@types/eslint-plugin-jsx-a11y": "^6.10.1",
package/rules/agent.md ADDED
@@ -0,0 +1,123 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for agentic coding
4
+ # paths: # removed so ALL agents read it where to find information
5
+ # - '**/*.md'
6
+ # - 'openspec/config.yml'
7
+ ---
8
+
9
+ IF IN DOUBT ASK USER!
10
+
11
+ # What Goes Where
12
+
13
+ Use this summarized guidance to consider where to place a set of instructions
14
+
15
+ - `README.md` — human-readable instructions how to work with repo
16
+ - Root `AGENTS.md` — default context for agents, always included
17
+ - Subdirectory `AGENTS.md` — scoped to this particular directory, auto-injected
18
+ - `.agents/rules` — forced rules (or automatic guardrails), that agent will read based on frontmatter, with paths scope; may pollute context if not scoped well; should NOT have detailed guidance, examples, etc.
19
+ - `.agents/skills` — one-off flows, potentially complex; but also sets of rules & instructions that agent may or may not read/follow, good for progressive disclosure, examples, thorough guidance, and something you want to offload from `AGENTS.md` (and cite from it), and has to be well-defined in frontmatter to increase likelihood of success, example: https://www.skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
20
+ - `.agents/commands` — one-off commands, usually simpler than skills
21
+ - `openspec/specs` - SDD specifications, should define user facing behavior or API contracts, not coding instructions / best practices / etc.
22
+ - `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
23
+ - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
24
+ - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
25
+
26
+ # Placement Decision
27
+
28
+ When deciding where information belongs, use this order:
29
+
30
+ 1. Is it durable observable system/component behavior?
31
+ - **→ `openspec/specs`**
32
+ 2. Must the agent always know it when touching a deterministically identifiable set of files?
33
+ - **→ scoped `.agents/rules`**
34
+ 3. Is it mandatory repo-wide or directory-wide context/routing?
35
+ - **→ `AGENTS.md`**
36
+ 4. Is it detailed knowledge, guidance, examples, best practices, or a reusable procedure that should be progressively disclosed?
37
+ - **→ skill**
38
+ 5. Is it merely supporting material extracted from `AGENTS.md` to reduce default context?
39
+ - **→ skill**, referenced explicitly from `AGENTS.md`
40
+ 6. Is it primarily documentation for humans?
41
+ - **→ `README.md`**
42
+
43
+ When correctness depends on an instruction being observed, do NOT rely solely on skill discovery.
44
+
45
+ Prefer one authoritative location for each concern. Reference it elsewhere instead of duplicating it.
46
+
47
+ # `README.md`
48
+
49
+ - Should be targeted to be read by humans
50
+ - First file that's visible to humans
51
+
52
+ # `AGENTS.md`
53
+
54
+ - Root `AGENTS.md`
55
+ - Should be minimalistic
56
+ - Can be decomposed as `skills` & `rules` (with references to them)
57
+ - Such references to skills should be referred conditional, e.g. with minimal explanation when to use so agent has better chances of reaching them
58
+ - Decomposition should be used when
59
+ - Section is narrowly scoped (installation instructions / testing / particular framework or technology) and not always applicable
60
+ - Section is large
61
+ - `AGENTS.md` can refer to `README.md` in order not to restate things
62
+ - Repo-wide convention to use SDD should be defined here to be always visible
63
+ - Focus on mandatory routing and instructions
64
+ - Sub-directory `AGENTS.md`
65
+ - Directory-specific rules & instructions should be in `AGENTS.md` of that folder
66
+ - Lift rules & instructions up the tree to higher `AGENTS.md` if multiple dirs must adhere to them, don't copy-paste them
67
+ - All `AGENTS.md` files should be accompanied by a symlink `CLAUDE.md`
68
+
69
+ # `.agents/rules`
70
+
71
+ - `.agents/rules` must be accompanied by symlinks in `.claude/rules` and `.codex/rules`
72
+ - Files should be scoped to certain paths
73
+ - Files should be small,
74
+ - Examples not allowed in general
75
+ - Should describe only coding conventions, recommendations, forced contextual instructions / automatic guardrails
76
+ - As bullet points
77
+ - Concise, terse and to the point
78
+ - Hard constraints
79
+ - That must appear in scope by `paths` glob
80
+ - Should be cited in `AGENTS.md` to ensure they're discoverable by harnesses that don't support `.xxx/rules` natively
81
+
82
+ # `.agents/skills`
83
+
84
+ - `.agents/skills` must be accompanied by symlinks in `.claude/skills` and `.codex/skills`
85
+ - May define either
86
+ - A workflow
87
+ - A process
88
+ - A set of rules
89
+ - Best practices
90
+ - Examples
91
+ - Engineering knowledge
92
+ - Agent decides to discover it or not, use it or not, so no guarantee of honoring
93
+ - A requirement/rule MUST NOT exist only in a skill if correctness depends on the agent always observing it
94
+
95
+ # `.agents/commands`
96
+
97
+ - `.agents/commands` must be accompanied by symlinks in `.claude/commands` and `.codex/commands`
98
+ - Smaller and simpler than skills
99
+ - One-off commands, not flows
100
+
101
+ # `openspec`
102
+
103
+ - `OpenSpec` / `SpecKit` and similar SDD specifications should define
104
+ - User facing or externally observable behavior
105
+ - Durable component/system/API contracts & invariants
106
+ - Not general coding instructions
107
+ - Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.agents|.claude|.codex]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
108
+ - `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
109
+ - Context will already contain root `AGENTS.md`, no duplication needed
110
+ - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
111
+ - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of instructions specifically for defined part of the flow when it's entered
112
+ - The two litmus questions:
113
+ - Could the implementation be rewritten substantially and the statement still hold? Then it is SPEC.
114
+ - Could the detail change while the contract stays the same? Then it is not SPEC.
115
+ - Requirements and scenarios should (preferrably) be proven by tests, and may be cited in tests for stronger connection
116
+ - Tests should be validated that they do what spec says (optional, unless project mandates this in root `AGENTS.md`)
117
+ - Code citations must resolve, not checked for validity
118
+
119
+ # Common for `AGENTS.md` `.agents/rules` `.agents/skills`
120
+
121
+ - If project uses Spec Driven Development framework like OpenSpec, these files should be free from product specifications / external behavior, and only focused on general coding instructions
122
+ - Preferred instructions/rules syntax how to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
123
+ - Rules & instructions in these files can't be cited from tests or code, so their proof is tooling, never a citation
package/rules/auth.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
- description: Set of rules for projects with Auth & Next.js
3
+ description: Set of rules for user auth (only for Next.js)
4
4
  paths:
5
5
  - '**/*.tsx'
6
6
  - '**/*.ts'
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
- description: Set of rules for ALL projects
3
+ description: Set of general coding style rules
4
4
  ---
5
5
 
6
6
  - When generating code respect max length set in `.editorconfig` or `.prettierrc` (could be with extension)
package/rules/db.md CHANGED
@@ -10,8 +10,7 @@ description: Database persistence and migration rules
10
10
 
11
11
  # Postgres
12
12
 
13
- - Use Neon Postgres with Drizzle and checked-in generated migrations.
14
- - Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
13
+ - Use Drizzle as ORM if user asks to add ORM
15
14
  - Keep schemas, repositories, tenancy, and authorization app-owned; keep reusable driver plumbing in `@kirill.konshin/db`.
16
15
  - Import `@kirill.konshin/db` through focused driver, migration, URL, and type subpaths so unrelated drivers are not loaded.
17
16
  - Keep database access server-only and separate the database/repository layer from API, UI, and state-management layers.
@@ -20,9 +19,16 @@ description: Database persistence and migration rules
20
19
  - Validate inputs at the application boundary and enforce critical invariants again in Postgres.
21
20
  - Use `DATABASE_URL` at runtime; prefer `DATABASE_URL_UNPOOLED` for migrations and maintenance when available.
22
21
  - Close owned pools in `finally`; do not leak clients or hide ownership of long-lived connections.
23
- - Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
24
22
  - Enforce user and tenant scope on every read and mutation; authentication alone is not authorization.
25
23
  - For LocalStorage or IndexedDB migrations, preserve behavior but improve the schema when normalization or consolidation is clearly safer.
26
24
  - Make importers transactional, validated, idempotent, and count-verifiable; never delete server data merely because a mutable export became smaller.
27
25
  - Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
28
26
  - After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
27
+
28
+ # Neon
29
+
30
+ Only applies if user specifically asked to add Neon as DB, or project already uses Neon as DB.
31
+
32
+ - Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
33
+ - Use Neon Postgres with Drizzle and checked-in generated migrations.
34
+ - Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
package/rules/electron.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
- description: Set of rules for projects which use Expo
3
+ description: Set of rules for projects which use Electron
4
4
  ---
5
5
 
6
6
  # CI Builds
package/rules/i18n.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
- description: I18n
3
+ description: General recommendations for I18N
4
4
  ---
5
5
 
6
6
  - When displaying date and time use `Intl.DateTimeFormat`.
package/rules/jest.md CHANGED
@@ -7,3 +7,4 @@ paths:
7
7
 
8
8
  - Always prefer TS-based config. Choice of loader is dictated by other installed packages, https://jestjs.io/docs/configuration (first tip about loaders)
9
9
  - In monorepo define root jest project https://jestjs.io/docs/configuration#projects-arraystring--projectconfig
10
+ - Prefer Vitest instead of Jest
package/rules/nx.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
- description: Set of rules for MONOREPO projects which use Turbo or NX
3
+ description: Set of rules for MONOREPO projects which NX
4
4
  paths:
5
5
  - '**/nx.json'
6
6
  - '**/package.json'
package/rules/turbo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
- description: Set of rules for MONOREPO projects which use Turbo or NX
3
+ description: Set of rules for MONOREPO projects which use Turbo
4
4
  paths:
5
5
  - '**/turbo.json'
6
6
  - '**/package.json'
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: always_apply
3
- description: Set of rules for projects with tests
3
+ description: Set of rules for projects with TypeScript, and partially applicable to plain JavaScript
4
4
  paths:
5
5
  - '**/*.js'
6
6
  - '**/*.mjs'
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-repo
3
- description: Set up/update this repo's ESLint + Prettier + lint-staged + Husky tooling (@kirill.konshin/lint), and/or audit the codebase against the packaged agent rules. Rules are discovered from .claude/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
3
+ description: Set up/update this repo's ESLint + Prettier + lint-staged + Husky tooling (@kirill.konshin/lint), and/or audit the codebase against the packaged agent rules. Rules are discovered from .agents/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
4
4
  ---
5
5
 
6
6
  # Lint Repo
@@ -27,7 +27,7 @@ Check the README's "Issues" section before debugging a lint crash.
27
27
 
28
28
  ## B. Audit code against rules
29
29
 
30
- Rules: `.claude/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.md`; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
30
+ Rules: `.agents/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.md`; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
31
31
 
32
32
  ### 1. Mechanical pass first
33
33