@kirill.konshin/lint 0.5.1 → 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/` (auto-discovered by Claude Code) and `.codex/rules/`.
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` 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.
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`, `.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.
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` (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`) 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)
@@ -41,19 +42,21 @@ export declare function readRules(): Rule[];
41
42
  */
42
43
  export declare function readSkills(): Skill[];
43
44
  /**
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
+ * 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`.
47
47
  */
48
- export declare function checkRulesDirSafety(rulesTargetDir: string): void;
48
+ export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string, string>;
49
49
  /**
50
- * 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).
51
52
  */
52
- export declare function checkClaudeMdSafety(claudeMdPath: string): void;
53
+ export declare function readUserFiles(cwd: string): Map<string, string>;
53
54
  /**
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
+ * 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).
57
60
  *
58
61
  * FIXME Codex Includes
59
62
  * https://github.com/openai/codex/issues/17401
@@ -64,35 +67,29 @@ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
64
67
  * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
65
68
  * indexed anywhere).
66
69
  */
67
- 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;
68
71
  /**
69
- * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
70
- * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
71
- * own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
72
- * 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.
73
73
  */
74
- export declare function checkSkillDirSafety(skillDir: string): void;
74
+ export declare function installedRules(rules: Rule[], userFiles: Map<string, string>): Rule[];
75
75
  /**
76
- * Symlink each package skill into `<cwd>/.claude/skills/<name>/` and
77
- * `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
78
- * them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
79
- * 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.
80
77
  */
81
- export declare function symlinkSkills(cwd: string, skills: Skill[]): string[];
78
+ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
82
79
  /**
83
80
  * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
84
81
  */
85
82
  export declare function symlinkClaudeMd(cwd: string): void;
86
83
  /**
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.
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.
89
86
  *
90
- * `.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
91
88
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
92
89
  * under `.claude/rules`, symlinks included) - no reference to them is needed here.
93
90
  * The sections below are for other tools that only read AGENTS.md.
94
91
  */
95
- export declare function generateAgentsFile(rules: Rule[], cwd: string, customSection: string | null): string;
92
+ export declare function generateAgentsFile(rules: Rule[], customSection: string | null): string;
96
93
  /**
97
94
  * Check if AGENTS.md exists and was generated by this tool. When it was, also return
98
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;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"}
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` (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`) 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)
@@ -27,10 +28,14 @@ const CLAUDE_FILE = 'CLAUDE.md';
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 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';
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';
34
39
  const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
35
40
  const HEADER = `# AI Agent Rules
36
41
 
@@ -43,11 +48,7 @@ const FOOTER = `---
43
48
 
44
49
  Add your project-specific rules below the comment line.`;
45
50
  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
+ const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
51
52
  /**
52
53
  * `monorepo-turbo-nx` -> `Monorepo turbo nx`
53
54
  */
@@ -63,6 +64,140 @@ const readDescription = (content) => {
63
64
  const description = frontmatter ? parse(frontmatter)?.description : undefined;
64
65
  return typeof description === 'string' ? description.trim() : undefined;
65
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
+ }
66
201
  /**
67
202
  * Read all markdown files from the package rules directory.
68
203
  */
@@ -78,13 +213,7 @@ export function readRules() {
78
213
  .sort();
79
214
  for (const file of files) {
80
215
  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
- });
216
+ rules.push(toRule(file, fs.readFileSync(filePath, 'utf-8')));
88
217
  }
89
218
  return rules;
90
219
  }
@@ -102,43 +231,44 @@ export function readSkills() {
102
231
  .map((file) => ({ file, name: file.replace('.md', '') }));
103
232
  }
104
233
  /**
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.
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`.
108
236
  */
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);
118
- }
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));
119
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);
247
+ }
248
+ return files;
120
249
  }
121
250
  /**
122
- * 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).
123
253
  */
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);
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
+ }
136
263
  }
264
+ return files;
137
265
  }
138
266
  /**
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.
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).
142
272
  *
143
273
  * FIXME Codex Includes
144
274
  * https://github.com/openai/codex/issues/17401
@@ -149,66 +279,65 @@ export function checkClaudeMdSafety(claudeMdPath) {
149
279
  * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
150
280
  * indexed anywhere).
151
281
  */
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);
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);
164
308
  }
165
- return targetDir;
166
- });
309
+ }
167
310
  }
168
311
  /**
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.
312
+ * Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
173
313
  */
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
- }
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')));
184
322
  }
323
+ return [...byFile].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, rule]) => rule);
185
324
  }
186
325
  /**
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.
326
+ * Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
191
327
  */
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
- }
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);
210
340
  }
211
- return targetDirs;
212
341
  }
213
342
  /**
214
343
  * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
@@ -219,24 +348,23 @@ export function symlinkClaudeMd(cwd) {
219
348
  fs.symlinkSync(AGENTS_FILE, claudeMdPath);
220
349
  }
221
350
  /**
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.
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.
224
353
  *
225
- * `.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
226
355
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
227
356
  * under `.claude/rules`, symlinks included) - no reference to them is needed here.
228
357
  * The sections below are for other tools that only read AGENTS.md.
229
358
  */
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('/');
359
+ export function generateAgentsFile(rules, customSection) {
233
360
  /**
234
361
  * @see https://code.claude.com/docs/en/memory#import-additional-files
235
362
  * @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
236
363
  * @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
237
364
  */
238
365
  const sections = rules.map((rule) => {
239
- const rulePath = `${relativeRulesDir}/${rule.file}`;
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}`;
240
368
  return [
241
369
  `## ${toTitle(rule.name)}`,
242
370
  rule.description,
@@ -287,23 +415,15 @@ export function main() {
287
415
  }
288
416
  }
289
417
  if (command === 'update' || command === 'init') {
290
- for (const dir of RULES_TARGET_DIRS) {
291
- checkRulesDirSafety(path.join(cwd, dir));
292
- }
293
418
  checkClaudeMdSafety(claudeMdPath);
294
419
  const rules = readRules();
295
420
  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
421
  const skills = readSkills();
301
422
  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);
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);
307
427
  fs.writeFileSync(targetPath, content, 'utf-8');
308
428
  console.log(`${exists ? 'Updated' : 'Created'} ${AGENTS_FILE}`);
309
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.1",
4
+ "version": "0.5.2",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
package/rules/agent.md CHANGED
@@ -15,12 +15,11 @@ Use this summarized guidance to consider where to place a set of instructions
15
15
  - `README.md` — human-readable instructions how to work with repo
16
16
  - Root `AGENTS.md` — default context for agents, always included
17
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
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
22
21
  - `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
22
+ - `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
24
23
  - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
25
24
  - `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
26
25
 
@@ -29,15 +28,15 @@ Use this summarized guidance to consider where to place a set of instructions
29
28
  When deciding where information belongs, use this order:
30
29
 
31
30
  1. Is it durable observable system/component behavior?
32
- - → **`openspec/specs`**
31
+ - **→ `openspec/specs`**
33
32
  2. Must the agent always know it when touching a deterministically identifiable set of files?
34
- - → **scoped `.claude/rules`**
33
+ - **→ scoped `.agents/rules`**
35
34
  3. Is it mandatory repo-wide or directory-wide context/routing?
36
- - → **`AGENTS.md`**
35
+ - **→ `AGENTS.md`**
37
36
  4. Is it detailed knowledge, guidance, examples, best practices, or a reusable procedure that should be progressively disclosed?
38
37
  - **→ skill**
39
38
  5. Is it merely supporting material extracted from `AGENTS.md` to reduce default context?
40
- - **→ `rules/`**, referenced explicitly from `AGENTS.md`
39
+ - **→ skill**, referenced explicitly from `AGENTS.md`
41
40
  6. Is it primarily documentation for humans?
42
41
  - **→ `README.md`**
43
42
 
@@ -50,27 +49,12 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
50
49
  - Should be targeted to be read by humans
51
50
  - First file that's visible to humans
52
51
 
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
52
  # `AGENTS.md`
67
53
 
68
54
  - 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
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
74
58
  - Decomposition should be used when
75
59
  - Section is narrowly scoped (installation instructions / testing / particular framework or technology) and not always applicable
76
60
  - Section is large
@@ -78,12 +62,26 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
78
62
  - Repo-wide convention to use SDD should be defined here to be always visible
79
63
  - Focus on mandatory routing and instructions
80
64
  - 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
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
83
67
  - All `AGENTS.md` files should be accompanied by a symlink `CLAUDE.md`
84
68
 
85
- # `.claude/skills` and `.codex/skills`
69
+ # `.agents/rules`
86
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`
87
85
  - May define either
88
86
  - A workflow
89
87
  - A process
@@ -94,8 +92,9 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
94
92
  - Agent decides to discover it or not, use it or not, so no guarantee of honoring
95
93
  - A requirement/rule MUST NOT exist only in a skill if correctness depends on the agent always observing it
96
94
 
97
- # `.claude/commands`
95
+ # `.agents/commands`
98
96
 
97
+ - `.agents/commands` must be accompanied by symlinks in `.claude/commands` and `.codex/commands`
99
98
  - Smaller and simpler than skills
100
99
  - One-off commands, not flows
101
100
 
@@ -105,13 +104,20 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
105
104
  - User facing or externally observable behavior
106
105
  - Durable component/system/API contracts & invariants
107
106
  - 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
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
110
109
  - Context will already contain root `AGENTS.md`, no duplication needed
111
110
  - `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
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
113
118
 
114
- # Common rules for `.claude/rules`, `.codex/rules`, `AGENTS.md` and `rules/`
119
+ # Common for `AGENTS.md` `.agents/rules` `.agents/skills`
115
120
 
116
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
117
- - Preferred syntax rules to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
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
@@ -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