@kirill.konshin/lint 0.5.1 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +6 -4
  2. package/dist/lintPrepare.d.ts +32 -31
  3. package/dist/lintPrepare.d.ts.map +1 -1
  4. package/dist/lintPrepare.js +261 -125
  5. package/package.json +5 -3
  6. package/rules/agent.md +42 -36
  7. package/rules/openspec.md +12 -0
  8. package/rules/testing.md +1 -0
  9. package/skills/lint-repo.md +2 -2
  10. package/skills/spec-steward/SKILL.md +76 -0
  11. package/skills/spec-steward/references/apply.md +18 -0
  12. package/skills/spec-steward/references/audit.md +57 -0
  13. package/skills/spec-steward/references/contract.md +186 -0
  14. package/skills/spec-steward/references/criteria.md +59 -0
  15. package/skills/spec-steward/references/model.md +71 -0
  16. package/skills/spec-steward/references/review-format.md +61 -0
  17. package/skills/spec-steward/references/wiring.md +19 -0
  18. package/skills/spec-steward/scripts/lib/align.mjs +126 -0
  19. package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
  20. package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
  21. package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
  22. package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
  23. package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
  24. package/skills/spec-steward/scripts/lib/git.mjs +138 -0
  25. package/skills/spec-steward/scripts/lib/review.mjs +347 -0
  26. package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
  27. package/skills/spec-steward/scripts/lib/util.mjs +161 -0
  28. package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
  29. package/skills/spec-steward/scripts/steward.mjs +350 -0
  30. package/skills/spec-steward/workflows/audit.js +539 -0
@@ -2,11 +2,13 @@
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` (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`.
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`; a folder skill with every file it ships) go into all three, pointing straight
9
+ * at the installed
10
+ * package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
11
+ * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
10
12
  *
11
13
  * Usage:
12
14
  * lint-prepare init - Initialize AGENTS.md in the current directory (default)
@@ -27,10 +29,14 @@ const CLAUDE_FILE = 'CLAUDE.md';
27
29
  const RULES_DIR = path.join(__dirname, '../rules');
28
30
  const SKILLS_DIR = path.join(__dirname, '../skills');
29
31
  const README_FILE = path.join(__dirname, '../README.md');
30
- const RULES_TARGET_DIRS = ['.claude/rules', '.codex/rules'];
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';
32
+ // `.agents` is the cross-tool location (Codex, Cursor, Antigravity) holding the package links and the user's own
33
+ // files, the latter are mirrored into `.claude` (Claude Code reads nothing else) and `.codex`
34
+ const CANONICAL_AGENT_DIR = '.agents';
35
+ const MIRROR_AGENT_DIRS = ['.claude', '.codex'];
36
+ const AGENT_DIRS = [CANONICAL_AGENT_DIR, ...MIRROR_AGENT_DIRS];
37
+ const AGENT_KINDS = ['rules', 'commands', 'skills'];
38
+ const GITIGNORE = '.gitignore';
39
+ const GITIGNORE_HEADER = '# Generated by @kirill.konshin/lint: symlinks it manages here, your own files stay tracked';
34
40
  const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
35
41
  const HEADER = `# AI Agent Rules
36
42
 
@@ -43,11 +49,7 @@ const FOOTER = `---
43
49
 
44
50
  Add your project-specific rules below the comment line.`;
45
51
  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));
52
+ const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
51
53
  /**
52
54
  * `monorepo-turbo-nx` -> `Monorepo turbo nx`
53
55
  */
@@ -63,6 +65,140 @@ const readDescription = (content) => {
63
65
  const description = frontmatter ? parse(frontmatter)?.description : undefined;
64
66
  return typeof description === 'string' ? description.trim() : undefined;
65
67
  };
68
+ /**
69
+ * `file` is the path inside a rules dir, e.g. `auth.md` or `frontend/react.md`.
70
+ */
71
+ const toRule = (file, content) => ({
72
+ file,
73
+ name: path.posix.basename(file, '.md'),
74
+ description: readDescription(content),
75
+ content,
76
+ });
77
+ /**
78
+ * Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
79
+ * directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
80
+ */
81
+ function listRealFiles(root, dir = root) {
82
+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
83
+ const entryPath = path.join(dir, entry.name);
84
+ if (entry.name.startsWith('.'))
85
+ return [];
86
+ if (entry.isDirectory())
87
+ return listRealFiles(root, entryPath);
88
+ return entry.isFile() ? [path.relative(root, entryPath)] : [];
89
+ });
90
+ }
91
+ /**
92
+ * Dead symlinks under `dir`, walking real directories only.
93
+ */
94
+ function findDeadLinks(dir) {
95
+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
96
+ const entryPath = path.join(dir, entry.name);
97
+ if (entry.isDirectory())
98
+ return findDeadLinks(entryPath);
99
+ return entry.isSymbolicLink() && !fs.existsSync(entryPath) ? [entryPath] : [];
100
+ });
101
+ }
102
+ /**
103
+ * Remove `link` and the directories it leaves empty, up to `root`.
104
+ */
105
+ function removeLink(link, root) {
106
+ fs.unlinkSync(link);
107
+ for (let dir = path.dirname(link); dir !== root && !fs.readdirSync(dir).length; dir = path.dirname(dir)) {
108
+ fs.rmdirSync(dir);
109
+ }
110
+ }
111
+ /**
112
+ * mkdir -p `dir` (relative to cwd, starting with an agent dir, which itself may be a link) without going through
113
+ * links below it: false when a part is a symlink or a file - those are the user's, nothing is written through them.
114
+ */
115
+ function ensureRealDir(cwd, dir) {
116
+ const [agentDir, ...parts] = dir.split(path.sep);
117
+ let current = path.join(cwd, agentDir);
118
+ fs.mkdirSync(current, { recursive: true });
119
+ for (const part of parts) {
120
+ current = path.join(current, part);
121
+ const stat = lstat(current);
122
+ if (!stat)
123
+ fs.mkdirSync(current);
124
+ else if (!stat.isDirectory())
125
+ return false;
126
+ }
127
+ return true;
128
+ }
129
+ /**
130
+ * Point `link` (relative to cwd) at `target`, unless the spot is the user's: a real file there, or a linked
131
+ * directory on the way. Returns whether the link is in place.
132
+ */
133
+ function placeLink(cwd, link, target) {
134
+ const linkPath = path.join(cwd, link);
135
+ if (!ensureRealDir(cwd, path.dirname(link))) {
136
+ console.log(`Skipped ${link}: ${path.dirname(link)} is not a real directory`);
137
+ return false;
138
+ }
139
+ const stat = lstat(linkPath);
140
+ if (stat && !stat.isSymbolicLink()) {
141
+ console.log(`Kept ${link}: not a symlink`);
142
+ return false;
143
+ }
144
+ // relative between REAL locations: cwd and the package (workspaces, yalc, pnpm store) may be reached through
145
+ // symlinks, and a path computed between a symlinked and a real location dangles
146
+ const text = path.relative(fs.realpathSync(path.dirname(linkPath)), target);
147
+ if (stat && fs.readlinkSync(linkPath) === text)
148
+ return true;
149
+ if (stat)
150
+ fs.unlinkSync(linkPath);
151
+ fs.symlinkSync(text, linkPath);
152
+ return true;
153
+ }
154
+ /**
155
+ * Links listed in a `.gitignore` this tool generated - it doubles as the record of what to clean up next time.
156
+ */
157
+ function readManifest(gitignore) {
158
+ const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf-8') : '';
159
+ if (!content.startsWith(GITIGNORE_HEADER))
160
+ return [];
161
+ return content
162
+ .split('\n')
163
+ .filter((line) => line.startsWith('/') && line !== `/${GITIGNORE}`)
164
+ .map((line) => path.normalize(line.slice(1)));
165
+ }
166
+ /**
167
+ * Write the `.gitignore` listing `links` (remove it when there are none), unless the user owns that file.
168
+ */
169
+ function writeManifest(gitignore, links) {
170
+ const exists = fs.existsSync(gitignore);
171
+ if (exists && !fs.readFileSync(gitignore, 'utf-8').startsWith(GITIGNORE_HEADER))
172
+ return;
173
+ if (!links.length) {
174
+ if (exists)
175
+ fs.unlinkSync(gitignore);
176
+ return;
177
+ }
178
+ const entries = links.map((link) => `/${link.split(path.sep).join('/')}`).sort();
179
+ fs.writeFileSync(gitignore, [GITIGNORE_HEADER, `/${GITIGNORE}`, ...entries, ''].join('\n'));
180
+ }
181
+ /**
182
+ * Links to place, keyed by their path relative to cwd: package files into every agent dir, the user's own `.agents`
183
+ * files into the mirrors. A user file wins over the package file at the same path.
184
+ */
185
+ function plannedLinks(cwd, packageFiles, userFiles) {
186
+ const canonicalDir = path.join(fs.realpathSync(cwd), CANONICAL_AGENT_DIR);
187
+ const links = new Map();
188
+ for (const [file, source] of packageFiles) {
189
+ if (userFiles.has(file)) {
190
+ console.log(`${path.join(CANONICAL_AGENT_DIR, file)} overrides the package file`);
191
+ continue;
192
+ }
193
+ for (const dir of AGENT_DIRS)
194
+ links.set(path.join(dir, file), fs.realpathSync(source));
195
+ }
196
+ for (const file of userFiles.keys()) {
197
+ for (const dir of MIRROR_AGENT_DIRS)
198
+ links.set(path.join(dir, file), path.join(canonicalDir, file));
199
+ }
200
+ return links;
201
+ }
66
202
  /**
67
203
  * Read all markdown files from the package rules directory.
68
204
  */
@@ -78,67 +214,77 @@ export function readRules() {
78
214
  .sort();
79
215
  for (const file of files) {
80
216
  const filePath = path.join(RULES_DIR, file);
81
- const content = fs.readFileSync(filePath, 'utf-8');
82
- rules.push({
83
- file,
84
- name: file.replace('.md', ''),
85
- description: readDescription(content),
86
- content,
87
- });
217
+ rules.push(toRule(file, fs.readFileSync(filePath, 'utf-8')));
88
218
  }
89
219
  return rules;
90
220
  }
91
221
  /**
92
- * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
93
- * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
222
+ * Read the package skills directory. A markdown file becomes its own skill, named after the file (without extension)
223
+ * - e.g. `lint-repo.md` becomes the `lint-repo` skill; a directory holding a `SKILL.md` is a folder skill named after
224
+ * the directory, shipped with its scripts and references.
94
225
  */
95
226
  export function readSkills() {
96
227
  if (!fs.existsSync(SKILLS_DIR))
97
228
  return [];
98
229
  return fs
99
- .readdirSync(SKILLS_DIR)
100
- .filter((f) => f.endsWith('.md'))
101
- .sort()
102
- .map((file) => ({ file, name: file.replace('.md', '') }));
230
+ .readdirSync(SKILLS_DIR, { withFileTypes: true })
231
+ .flatMap((entry) => {
232
+ if (entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md'))) {
233
+ return [{ file: entry.name, name: entry.name, folder: true }];
234
+ }
235
+ return entry.isFile() && entry.name.endsWith('.md')
236
+ ? [{ file: entry.name, name: entry.name.replace('.md', '') }]
237
+ : [];
238
+ })
239
+ .sort((a, b) => a.name.localeCompare(b.name));
103
240
  }
104
241
  /**
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.
242
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `skills/<name>/SKILL.md` plus the
243
+ * package README.md next to it, so a skill can reference `@README.md`, and every file of a folder skill at its own
244
+ * relative path.
108
245
  */
109
- export function checkRulesDirSafety(rulesTargetDir) {
110
- if (!fs.existsSync(rulesTargetDir))
111
- return;
112
- for (const entry of fs.readdirSync(rulesTargetDir)) {
113
- const entryPath = path.join(rulesTargetDir, entry);
114
- if (!entry.endsWith(CODEX_POLICY_EXT) && !fs.lstatSync(entryPath).isSymbolicLink()) {
115
- console.error(`${entryPath} exists and is not a symlink.`);
116
- console.error('Remove or back it up manually, then re-run.');
117
- process.exit(1);
246
+ export function packageFiles(rules, skills) {
247
+ const files = new Map();
248
+ const hasReadme = fs.existsSync(README_FILE);
249
+ for (const rule of rules) {
250
+ files.set(path.join('rules', rule.file), path.join(RULES_DIR, rule.file));
251
+ }
252
+ for (const skill of skills) {
253
+ if (skill.folder) {
254
+ const root = path.join(SKILLS_DIR, skill.file);
255
+ for (const file of listRealFiles(root)) {
256
+ files.set(path.join('skills', skill.name, file), path.join(root, file));
257
+ }
258
+ continue;
118
259
  }
260
+ files.set(path.join('skills', skill.name, 'SKILL.md'), path.join(SKILLS_DIR, skill.file));
261
+ if (hasReadme)
262
+ files.set(path.join('skills', skill.name, 'README.md'), README_FILE);
119
263
  }
264
+ return files;
120
265
  }
121
266
  /**
122
- * Fail if `CLAUDE.md` exists and isn't a symlink - same reasoning as checkRulesDirSafety.
267
+ * The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
268
+ * except the package links (and dotfiles).
123
269
  */
124
- export function checkClaudeMdSafety(claudeMdPath) {
125
- let stat;
126
- try {
127
- stat = fs.lstatSync(claudeMdPath);
128
- }
129
- catch {
130
- return;
131
- }
132
- if (!stat.isSymbolicLink()) {
133
- console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
134
- console.error('Remove or back it up manually, then re-run.');
135
- process.exit(1);
270
+ export function readUserFiles(cwd) {
271
+ const files = new Map();
272
+ for (const kind of AGENT_KINDS) {
273
+ const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
274
+ if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory())
275
+ continue;
276
+ for (const file of listRealFiles(root)) {
277
+ files.set(path.join(kind, file), path.join(root, file));
278
+ }
136
279
  }
280
+ return files;
137
281
  }
138
282
  /**
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.
283
+ * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
284
+ * package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
285
+ * `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
286
+ * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
287
+ * records them (and keeps them out of git, so the user's own files there stay tracked).
142
288
  *
143
289
  * FIXME Codex Includes
144
290
  * https://github.com/openai/codex/issues/17401
@@ -149,66 +295,65 @@ export function checkClaudeMdSafety(claudeMdPath) {
149
295
  * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
150
296
  * indexed anywhere).
151
297
  */
152
- export function symlinkRules(cwd, rules) {
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);
298
+ export function syncAgentDirs(cwd, packageFiles, userFiles) {
299
+ const links = plannedLinks(cwd, packageFiles, userFiles);
300
+ for (const dir of AGENT_DIRS) {
301
+ for (const kind of AGENT_KINDS) {
302
+ const root = path.join(dir, kind);
303
+ const rootPath = path.join(cwd, root);
304
+ const gitignore = path.join(rootPath, GITIGNORE);
305
+ if (!ensureRealDir(cwd, root)) {
306
+ console.log(`Skipped ${root}: not a real directory`);
307
+ continue;
308
+ }
309
+ for (const link of findDeadLinks(rootPath)) {
310
+ removeLink(link, rootPath);
311
+ }
312
+ const placed = [];
313
+ for (const [link, target] of links) {
314
+ if (link.startsWith(root + path.sep) && placeLink(cwd, link, target)) {
315
+ placed.push(path.relative(root, link));
316
+ }
317
+ }
318
+ for (const link of readManifest(gitignore)) {
319
+ const linkPath = path.join(rootPath, link);
320
+ if (!placed.includes(link) && lstat(linkPath)?.isSymbolicLink())
321
+ removeLink(linkPath, rootPath);
322
+ }
323
+ writeManifest(gitignore, placed);
164
324
  }
165
- return targetDir;
166
- });
325
+ }
167
326
  }
168
327
  /**
169
- * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
170
- * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
171
- * own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
172
- * parent, since other packages (or the user) may keep unrelated skills there.
328
+ * Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
173
329
  */
174
- export function checkSkillDirSafety(skillDir) {
175
- if (!fs.existsSync(skillDir))
176
- return;
177
- for (const entry of fs.readdirSync(skillDir)) {
178
- const entryPath = path.join(skillDir, entry);
179
- if (!fs.lstatSync(entryPath).isSymbolicLink()) {
180
- console.error(`${skillDir}/${entry} exists and is not a symlink.`);
181
- console.error('Remove or back it up manually, then re-run.');
182
- process.exit(1);
183
- }
330
+ export function installedRules(rules, userFiles) {
331
+ const byFile = new Map(rules.map((rule) => [rule.file, rule]));
332
+ const rulesDir = `rules${path.sep}`;
333
+ for (const [file, source] of userFiles) {
334
+ if (!file.startsWith(rulesDir) || !file.endsWith('.md'))
335
+ continue;
336
+ const ruleFile = file.slice(rulesDir.length).split(path.sep).join('/');
337
+ byFile.set(ruleFile, toRule(ruleFile, fs.readFileSync(source, 'utf-8')));
184
338
  }
339
+ return [...byFile].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, rule]) => rule);
185
340
  }
186
341
  /**
187
- * Symlink each package skill into `<cwd>/.claude/skills/<name>/` and
188
- * `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
189
- * them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
190
- * via `@README.md` regardless of how the tool resolves relative mentions.
342
+ * Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
191
343
  */
192
- export function symlinkSkills(cwd, skills) {
193
- const targetDirs = [];
194
- const hasReadme = fs.existsSync(README_FILE);
195
- for (const skill of skills) {
196
- for (const targetRoot of SKILLS_TARGET_DIRS) {
197
- const skillDir = path.join(cwd, targetRoot, skill.name);
198
- checkSkillDirSafety(skillDir);
199
- fs.rmSync(skillDir, { recursive: true, force: true });
200
- fs.mkdirSync(skillDir, { recursive: true });
201
- const source = path.join(SKILLS_DIR, skill.file);
202
- const linkPath = path.join(skillDir, 'SKILL.md');
203
- fs.symlinkSync(realRelative(skillDir, source), linkPath);
204
- if (hasReadme) {
205
- const readmeLink = path.join(skillDir, 'README.md');
206
- fs.symlinkSync(realRelative(skillDir, README_FILE), readmeLink);
207
- }
208
- targetDirs.push(skillDir);
209
- }
344
+ export function checkClaudeMdSafety(claudeMdPath) {
345
+ let stat;
346
+ try {
347
+ stat = fs.lstatSync(claudeMdPath);
348
+ }
349
+ catch {
350
+ return;
351
+ }
352
+ if (!stat.isSymbolicLink()) {
353
+ console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
354
+ console.error('Remove or back it up manually, then re-run.');
355
+ process.exit(1);
210
356
  }
211
- return targetDirs;
212
357
  }
213
358
  /**
214
359
  * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
@@ -219,24 +364,23 @@ export function symlinkClaudeMd(cwd) {
219
364
  fs.symlinkSync(AGENTS_FILE, claudeMdPath);
220
365
  }
221
366
  /**
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.
367
+ * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
368
+ * and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
224
369
  *
225
- * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
370
+ * `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
226
371
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
227
372
  * under `.claude/rules`, symlinks included) - no reference to them is needed here.
228
373
  * The sections below are for other tools that only read AGENTS.md.
229
374
  */
230
- export function generateAgentsFile(rules, cwd, customSection) {
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('/');
375
+ export function generateAgentsFile(rules, customSection) {
233
376
  /**
234
377
  * @see https://code.claude.com/docs/en/memory#import-additional-files
235
378
  * @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
236
379
  * @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
237
380
  */
238
381
  const sections = rules.map((rule) => {
239
- const rulePath = `${relativeRulesDir}/${rule.file}`;
382
+ // the canonical entry (a package link or the user's own file), not the package install path
383
+ const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
240
384
  return [
241
385
  `## ${toTitle(rule.name)}`,
242
386
  rule.description,
@@ -287,23 +431,15 @@ export function main() {
287
431
  }
288
432
  }
289
433
  if (command === 'update' || command === 'init') {
290
- for (const dir of RULES_TARGET_DIRS) {
291
- checkRulesDirSafety(path.join(cwd, dir));
292
- }
293
434
  checkClaudeMdSafety(claudeMdPath);
294
435
  const rules = readRules();
295
436
  console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(', ')}`);
296
- const targetRulesDirs = symlinkRules(cwd, rules);
297
- for (const targetRulesDir of targetRulesDirs) {
298
- console.log(`Symlinked rules to ${targetRulesDir}`);
299
- }
300
437
  const skills = readSkills();
301
438
  console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
302
- const targetSkillDirs = symlinkSkills(cwd, skills);
303
- for (const targetSkillDir of targetSkillDirs) {
304
- console.log(`Symlinked skill to ${targetSkillDir}`);
305
- }
306
- const content = generateAgentsFile(rules, cwd, customSection);
439
+ const userFiles = readUserFiles(cwd);
440
+ syncAgentDirs(cwd, packageFiles(rules, skills), userFiles);
441
+ console.log(`Synced ${AGENT_DIRS.join(', ')}, mirrored ${userFiles.size} own file(s) from ${CANONICAL_AGENT_DIR}`);
442
+ const content = generateAgentsFile(installedRules(rules, userFiles), customSection);
307
443
  fs.writeFileSync(targetPath, content, 'utf-8');
308
444
  console.log(`${exists ? 'Updated' : 'Created'} ${AGENTS_FILE}`);
309
445
  symlinkClaudeMd(cwd);
package/package.json CHANGED
@@ -1,11 +1,12 @@
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.1",
4
+ "version": "0.5.3",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
8
- "lint-prepare": "./dist/lintPrepare.js"
8
+ "lint-prepare": "./dist/lintPrepare.js",
9
+ "spec-steward": "./skills/spec-steward/scripts/steward.mjs"
9
10
  },
10
11
  "main": "./dist/index.js",
11
12
  "module": "./dist/index.js",
@@ -41,7 +42,8 @@
41
42
  "files": [
42
43
  "dist",
43
44
  "rules",
44
- "skills"
45
+ "skills",
46
+ "!skills/**/*.test.mjs"
45
47
  ],
46
48
  "dependencies": {
47
49
  "@eslint/config-helpers": "^0.7.0",