@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 +3 -3
- package/dist/lintPrepare.d.ts +14 -11
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +76 -33
- package/package.json +3 -2
- package/rules/agent.md +117 -0
- package/rules/auth.md +1 -1
- package/rules/code-style.md +1 -1
- package/rules/db.md +9 -3
- package/rules/electron.md +1 -1
- package/rules/i18n.md +1 -1
- package/rules/jest.md +1 -0
- package/rules/nx.md +1 -1
- package/rules/turbo.md +1 -1
- package/rules/typescript.md +1 -1
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
|
|
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`
|
|
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
|
|
package/dist/lintPrepare.d.ts
CHANGED
|
@@ -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`
|
|
7
|
-
* package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
|
|
8
|
-
* the package README.md alongside it, so a skill can reference `@README.md`),
|
|
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`
|
|
53
|
-
* Safe to
|
|
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
|
|
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;
|
|
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"}
|
package/dist/lintPrepare.js
CHANGED
|
@@ -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`
|
|
7
|
-
* package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
|
|
8
|
-
* the package README.md alongside it, so a skill can reference `@README.md`),
|
|
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(`${
|
|
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`
|
|
114
|
-
* Safe to
|
|
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
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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(
|
|
203
|
+
fs.symlinkSync(realRelative(skillDir, source), linkPath);
|
|
173
204
|
if (hasReadme) {
|
|
174
205
|
const readmeLink = path.join(skillDir, 'README.md');
|
|
175
|
-
fs.symlinkSync(
|
|
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
|
|
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
|
-
|
|
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
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
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
|
-
|
|
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
|
|
256
|
-
|
|
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.
|
|
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
package/rules/code-style.md
CHANGED
package/rules/db.md
CHANGED
|
@@ -10,8 +10,7 @@ description: Database persistence and migration rules
|
|
|
10
10
|
|
|
11
11
|
# Postgres
|
|
12
12
|
|
|
13
|
-
- Use
|
|
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
package/rules/i18n.md
CHANGED
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
package/rules/turbo.md
CHANGED