@kirill.konshin/lint 0.5.0 → 0.5.1

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,13 @@ 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.
332
+ - Symlinks every `rules/*.md` into `.claude/rules/` (auto-discovered by Claude Code) and `.codex/rules/`.
333
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.
334
+ - Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — per rule a `## <Title>` (from the file name), its frontmatter `description` and an `@path` to the rule file, relative to the project root from the package's real (symlink-resolved) location — and symlinks `CLAUDE.md` to it.
335
335
 
336
336
  ### Safety checks
337
337
 
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.
338
+ `init`/`update` refuse to run if `.claude/rules`, `.codex/rules`, a skill target dir, or `CLAUDE.md` contains anything that isn't a symlink — this avoids silently overwriting files you created by hand. Codex command policies (`.codex/rules/*.rules`) are left alone. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
339
339
 
340
340
  ## Migration
341
341
 
@@ -3,10 +3,10 @@
3
3
  * @kirill.konshin/lint
4
4
  *
5
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`.
6
+ * project's `.claude/rules` (auto-discovered by Claude Code) and `.codex/rules` directories,
7
+ * symlinks every package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
8
+ * (SKILL.md plus the package README.md alongside it, so a skill can reference `@README.md`),
9
+ * and generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
10
10
  *
11
11
  * Usage:
12
12
  * lint-prepare init - Initialize AGENTS.md in the current directory (default)
@@ -19,6 +19,7 @@
19
19
  type Rule = {
20
20
  file: string;
21
21
  name: string;
22
+ description?: string;
22
23
  content: string;
23
24
  };
24
25
  type Skill = {
@@ -40,8 +41,9 @@ export declare function readRules(): Rule[];
40
41
  */
41
42
  export declare function readSkills(): Skill[];
42
43
  /**
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.
44
+ * Fail if `.claude/rules` or `.codex/rules` contains anything that isn't a symlink - we don't want to
45
+ * silently blow away a real file/directory a user placed there by hand. Codex command policies
46
+ * (`*.rules`) are not ours and are left alone.
45
47
  */
46
48
  export declare function checkRulesDirSafety(rulesTargetDir: string): void;
47
49
  /**
@@ -49,9 +51,9 @@ export declare function checkRulesDirSafety(rulesTargetDir: string): void;
49
51
  */
50
52
  export declare function checkClaudeMdSafety(claudeMdPath: string): void;
51
53
  /**
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.
54
+ * Symlink rules into the consuming project's `.claude/rules` and `.codex/rules` directories.
55
+ * Safe to clear and recreate: checkRulesDirSafety already guaranteed every existing
56
+ * entry except Codex command policies (kept) is a symlink.
55
57
  *
56
58
  * FIXME Codex Includes
57
59
  * https://github.com/openai/codex/issues/17401
@@ -62,7 +64,7 @@ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
62
64
  * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
63
65
  * indexed anywhere).
64
66
  */
65
- export declare function symlinkRules(cwd: string, rules: Rule[]): string;
67
+ export declare function symlinkRules(cwd: string, rules: Rule[]): string[];
66
68
  /**
67
69
  * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
68
70
  * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
@@ -82,7 +84,8 @@ export declare function symlinkSkills(cwd: string, skills: Skill[]): string[];
82
84
  */
83
85
  export declare function symlinkClaudeMd(cwd: string): void;
84
86
  /**
85
- * Generate AGENTS.md with references to the rule files.
87
+ * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file with its
88
+ * frontmatter `description` and a reference to the file.
86
89
  *
87
90
  * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
88
91
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
@@ -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;;;;;;;;;;;;;;;;GAgBG;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;AAiD1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAyBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;;GAIG;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,EAAE,CAkBjE;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;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAwBnG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CA0D3B"}
@@ -3,10 +3,10 @@
3
3
  * @kirill.konshin/lint
4
4
  *
5
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`.
6
+ * project's `.claude/rules` (auto-discovered by Claude Code) and `.codex/rules` directories,
7
+ * symlinks every package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
8
+ * (SKILL.md plus the package README.md alongside it, so a skill can reference `@README.md`),
9
+ * and generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
10
10
  *
11
11
  * Usage:
12
12
  * lint-prepare init - Initialize AGENTS.md in the current directory (default)
@@ -19,15 +19,19 @@
19
19
  import fs from 'node:fs';
20
20
  import path from 'node:path';
21
21
  import { fileURLToPath } from 'node:url';
22
+ import { parse } from 'yaml';
22
23
  const __filename = fileURLToPath(import.meta.url);
23
24
  const __dirname = path.dirname(__filename);
24
25
  const AGENTS_FILE = 'AGENTS.md';
25
26
  const CLAUDE_FILE = 'CLAUDE.md';
26
- const CLAUDE_RULES_DIR = '.claude/rules';
27
27
  const RULES_DIR = path.join(__dirname, '../rules');
28
28
  const SKILLS_DIR = path.join(__dirname, '../skills');
29
29
  const README_FILE = path.join(__dirname, '../README.md');
30
+ const RULES_TARGET_DIRS = ['.claude/rules', '.codex/rules'];
30
31
  const SKILLS_TARGET_DIRS = ['.claude/skills', '.codex/skills'];
32
+ // Codex keeps its own command policies in `.codex/rules/*.rules` (https://developers.openai.com/codex/rules)
33
+ const CODEX_POLICY_EXT = '.rules';
34
+ const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
31
35
  const HEADER = `# AI Agent Rules
32
36
 
33
37
  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 +43,26 @@ const FOOTER = `---
39
43
 
40
44
  Add your project-specific rules below the comment line.`;
41
45
  const GENERATED_MARKER = '<!-- @kirill.konshin/lint:generated -->';
46
+ /**
47
+ * Relative path between the REAL locations of `from` and `to`: the cwd and the package (workspaces, yalc, pnpm store)
48
+ * may be reached through symlinks, and a path computed between a symlinked and a real location dangles.
49
+ */
50
+ const realRelative = (from, to) => path.relative(fs.realpathSync(from), fs.realpathSync(to));
51
+ /**
52
+ * `monorepo-turbo-nx` -> `Monorepo turbo nx`
53
+ */
54
+ const toTitle = (name) => {
55
+ const title = name.replaceAll('-', ' ');
56
+ return title.charAt(0).toUpperCase() + title.slice(1);
57
+ };
58
+ /**
59
+ * The `description` field of a rule's YAML frontmatter.
60
+ */
61
+ const readDescription = (content) => {
62
+ const frontmatter = FRONTMATTER.exec(content)?.[1];
63
+ const description = frontmatter ? parse(frontmatter)?.description : undefined;
64
+ return typeof description === 'string' ? description.trim() : undefined;
65
+ };
42
66
  /**
43
67
  * Read all markdown files from the package rules directory.
44
68
  */
@@ -58,6 +82,7 @@ export function readRules() {
58
82
  rules.push({
59
83
  file,
60
84
  name: file.replace('.md', ''),
85
+ description: readDescription(content),
61
86
  content,
62
87
  });
63
88
  }
@@ -77,16 +102,17 @@ export function readSkills() {
77
102
  .map((file) => ({ file, name: file.replace('.md', '') }));
78
103
  }
79
104
  /**
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.
105
+ * Fail if `.claude/rules` or `.codex/rules` contains anything that isn't a symlink - we don't want to
106
+ * silently blow away a real file/directory a user placed there by hand. Codex command policies
107
+ * (`*.rules`) are not ours and are left alone.
82
108
  */
83
109
  export function checkRulesDirSafety(rulesTargetDir) {
84
110
  if (!fs.existsSync(rulesTargetDir))
85
111
  return;
86
112
  for (const entry of fs.readdirSync(rulesTargetDir)) {
87
113
  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.`);
114
+ if (!entry.endsWith(CODEX_POLICY_EXT) && !fs.lstatSync(entryPath).isSymbolicLink()) {
115
+ console.error(`${entryPath} exists and is not a symlink.`);
90
116
  console.error('Remove or back it up manually, then re-run.');
91
117
  process.exit(1);
92
118
  }
@@ -110,9 +136,9 @@ export function checkClaudeMdSafety(claudeMdPath) {
110
136
  }
111
137
  }
112
138
  /**
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.
139
+ * Symlink rules into the consuming project's `.claude/rules` and `.codex/rules` directories.
140
+ * Safe to clear and recreate: checkRulesDirSafety already guaranteed every existing
141
+ * entry except Codex command policies (kept) is a symlink.
116
142
  *
117
143
  * FIXME Codex Includes
118
144
  * https://github.com/openai/codex/issues/17401
@@ -124,15 +150,20 @@ export function checkClaudeMdSafety(claudeMdPath) {
124
150
  * indexed anywhere).
125
151
  */
126
152
  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);
134
- }
135
- return targetDir;
153
+ return RULES_TARGET_DIRS.map((dir) => {
154
+ const targetDir = path.join(cwd, dir);
155
+ fs.mkdirSync(targetDir, { recursive: true });
156
+ for (const entry of fs.readdirSync(targetDir)) {
157
+ if (!entry.endsWith(CODEX_POLICY_EXT))
158
+ fs.unlinkSync(path.join(targetDir, entry));
159
+ }
160
+ for (const rule of rules) {
161
+ const source = path.join(RULES_DIR, rule.file);
162
+ const linkPath = path.join(targetDir, rule.file);
163
+ fs.symlinkSync(realRelative(targetDir, source), linkPath);
164
+ }
165
+ return targetDir;
166
+ });
136
167
  }
137
168
  /**
138
169
  * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
@@ -169,10 +200,10 @@ export function symlinkSkills(cwd, skills) {
169
200
  fs.mkdirSync(skillDir, { recursive: true });
170
201
  const source = path.join(SKILLS_DIR, skill.file);
171
202
  const linkPath = path.join(skillDir, 'SKILL.md');
172
- fs.symlinkSync(path.relative(skillDir, source), linkPath);
203
+ fs.symlinkSync(realRelative(skillDir, source), linkPath);
173
204
  if (hasReadme) {
174
205
  const readmeLink = path.join(skillDir, 'README.md');
175
- fs.symlinkSync(path.relative(skillDir, README_FILE), readmeLink);
206
+ fs.symlinkSync(realRelative(skillDir, README_FILE), readmeLink);
176
207
  }
177
208
  targetDirs.push(skillDir);
178
209
  }
@@ -188,7 +219,8 @@ export function symlinkClaudeMd(cwd) {
188
219
  fs.symlinkSync(AGENTS_FILE, claudeMdPath);
189
220
  }
190
221
  /**
191
- * Generate AGENTS.md with references to the rule files.
222
+ * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file with its
223
+ * frontmatter `description` and a reference to the file.
192
224
  *
193
225
  * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
194
226
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
@@ -196,16 +228,24 @@ export function symlinkClaudeMd(cwd) {
196
228
  * The sections below are for other tools that only read AGENTS.md.
197
229
  */
198
230
  export function generateAgentsFile(rules, cwd, customSection) {
199
- const relativeRulesDir = path.relative(cwd, RULES_DIR).split(path.sep).join('/');
231
+ // where the rules really are, e.g. `node_modules/@kirill.konshin/lint/rules`, `packages/lint/rules` in a workspace
232
+ const relativeRulesDir = realRelative(cwd, RULES_DIR).split(path.sep).join('/');
200
233
  /**
201
234
  * @see https://code.claude.com/docs/en/memory#import-additional-files
202
235
  * @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
203
236
  * @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
204
237
  */
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}`;
238
+ const sections = rules.map((rule) => {
239
+ const rulePath = `${relativeRulesDir}/${rule.file}`;
240
+ return [
241
+ `## ${toTitle(rule.name)}`,
242
+ rule.description,
243
+ `See instructions in @${rulePath} [${rulePath}](${rulePath}).`,
244
+ ]
245
+ .filter(Boolean)
246
+ .join('\n\n');
247
+ });
248
+ const generated = `${HEADER}\n\n# Rules\n\n${sections.join('\n\n')}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
209
249
  return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
210
250
  }
211
251
  /**
@@ -233,7 +273,6 @@ export function main() {
233
273
  const cwd = process.env.INIT_CWD || process.cwd();
234
274
  const targetPath = path.join(cwd, AGENTS_FILE);
235
275
  const claudeMdPath = path.join(cwd, CLAUDE_FILE);
236
- const rulesTargetDir = path.join(cwd, CLAUDE_RULES_DIR);
237
276
  console.log(`@kirill.konshin/lint: ${command}`);
238
277
  console.log(`Target: ${targetPath}`);
239
278
  const { exists, generated, customSection } = checkExisting(targetPath);
@@ -248,12 +287,16 @@ export function main() {
248
287
  }
249
288
  }
250
289
  if (command === 'update' || command === 'init') {
251
- checkRulesDirSafety(rulesTargetDir);
290
+ for (const dir of RULES_TARGET_DIRS) {
291
+ checkRulesDirSafety(path.join(cwd, dir));
292
+ }
252
293
  checkClaudeMdSafety(claudeMdPath);
253
294
  const rules = readRules();
254
295
  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}`);
296
+ const targetRulesDirs = symlinkRules(cwd, rules);
297
+ for (const targetRulesDir of targetRulesDirs) {
298
+ console.log(`Symlinked rules to ${targetRulesDir}`);
299
+ }
257
300
  const skills = readSkills();
258
301
  console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
259
302
  const targetSkillDirs = symlinkSkills(cwd, skills);
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.1",
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,117 @@
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
+ - `.claude/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
+ - `rules/` referred from `AGENTS.md` — simple decomposition to clear up default context from specific / scoped / rarely used instructions, no frontmatter
20
+ - `.claude/skills` or `.codex/skills` — one-off flows, potentially complex; but also sets of rules that agent may or may not read/follow, good for progressive disclosure, examples, thorough guidance, 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
21
+ - `.claude/commands` — one-off commands, usually simpler than skills
22
+ - `openspec/specs` - SDD specifications, should define user facing behavior or API contracts, not coding instructions / best practices / etc.
23
+ - `openspec/config.yml#context` - should only have very narrow rules for OpenSpec specifically, when user entered flow
24
+ - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
25
+ - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
26
+
27
+ # Placement Decision
28
+
29
+ When deciding where information belongs, use this order:
30
+
31
+ 1. Is it durable observable system/component behavior?
32
+ - → **`openspec/specs`**
33
+ 2. Must the agent always know it when touching a deterministically identifiable set of files?
34
+ - → **scoped `.claude/rules`**
35
+ 3. Is it mandatory repo-wide or directory-wide context/routing?
36
+ - → **`AGENTS.md`**
37
+ 4. Is it detailed knowledge, guidance, examples, best practices, or a reusable procedure that should be progressively disclosed?
38
+ - **→ skill**
39
+ 5. Is it merely supporting material extracted from `AGENTS.md` to reduce default context?
40
+ - **→ `rules/`**, referenced explicitly from `AGENTS.md`
41
+ 6. Is it primarily documentation for humans?
42
+ - **→ `README.md`**
43
+
44
+ When correctness depends on an instruction being observed, do NOT rely solely on skill discovery.
45
+
46
+ Prefer one authoritative location for each concern. Reference it elsewhere instead of duplicating it.
47
+
48
+ # `README.md`
49
+
50
+ - Should be targeted to be read by humans
51
+ - First file that's visible to humans
52
+
53
+ # `.claude/rules` and `.codex/rules`
54
+
55
+ - Can itself be a link to rules from a package; or individual files inside can be symlinks
56
+ - Must be accompanied by symlink `.codex/rules`
57
+ - Files should be scoped to certain paths
58
+ - Files should be small,
59
+ - Examples not allowed in general
60
+ - Should describe only coding conventions, recommendations, forced contextual instructions / automatic guardrails
61
+ - As bullet points
62
+ - Concise, terse and to the point
63
+ - Hard constraints
64
+ - That must appear in scope by `paths` glob
65
+
66
+ # `AGENTS.md`
67
+
68
+ - Root `AGENTS.md`
69
+ - Should be minimalistic and should refer to `rules/xxx.md` in order not to pollute default context if
70
+ - Can be decomposed as references to files in `rules/` folder also located at repo root
71
+ - Folder has no semantics of its own; it is not a standard but merely a convention for progressive-disclosure documentation referenced by AGENTS.md.
72
+ - Files in `rules/` should be referred conditionally, e.g. with minimal explanation what's inside so agent has better chances of reaching them
73
+ - Frontmatter not supported
74
+ - Decomposition should be used when
75
+ - Section is narrowly scoped (installation instructions / testing / particular framework or technology) and not always applicable
76
+ - Section is large
77
+ - `AGENTS.md` can refer to `README.md` in order not to restate things
78
+ - Repo-wide convention to use SDD should be defined here to be always visible
79
+ - Focus on mandatory routing and instructions
80
+ - Sub-directory `AGENTS.md`
81
+ - Directory-specific rules should be in `AGENTS.md` of that folder
82
+ - Lift rules up the tree to higher `AGENTS.md` if multiple dirs must adhere to rules, don't copy-paste them
83
+ - All `AGENTS.md` files should be accompanied by a symlink `CLAUDE.md`
84
+
85
+ # `.claude/skills` and `.codex/skills`
86
+
87
+ - May define either
88
+ - A workflow
89
+ - A process
90
+ - A set of rules
91
+ - Best practices
92
+ - Examples
93
+ - Engineering knowledge
94
+ - Agent decides to discover it or not, use it or not, so no guarantee of honoring
95
+ - A requirement/rule MUST NOT exist only in a skill if correctness depends on the agent always observing it
96
+
97
+ # `.claude/commands`
98
+
99
+ - Smaller and simpler than skills
100
+ - One-off commands, not flows
101
+
102
+ # `openspec`
103
+
104
+ - `OpenSpec` / `SpecKit` and similar SDD specifications should define
105
+ - User facing or externally observable behavior
106
+ - Durable component/system/API contracts & invariants
107
+ - Not general coding instructions
108
+ - Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.claude|.codex]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
109
+ - `openspec/config.yml#context` - should only have very narrow rules for OpenSpec specifically, when user entered flow
110
+ - Context will already contain root `AGENTS.md`, no duplication needed
111
+ - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
112
+ - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
113
+
114
+ # Common rules for `.claude/rules`, `.codex/rules`, `AGENTS.md` and `rules/`
115
+
116
+ - 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
117
+ - Preferred syntax rules to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
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'