@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 +6 -4
- package/dist/lintPrepare.d.ts +26 -29
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +240 -120
- package/package.json +1 -1
- package/rules/agent.md +42 -36
- package/skills/lint-repo.md +2 -2
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
|
-
-
|
|
333
|
-
-
|
|
334
|
-
-
|
|
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
|
-
|
|
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
|
|
package/dist/lintPrepare.d.ts
CHANGED
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
|
-
* This script
|
|
6
|
-
*
|
|
7
|
-
* symlinks
|
|
8
|
-
*
|
|
9
|
-
*
|
|
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
|
-
*
|
|
45
|
-
*
|
|
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
|
|
48
|
+
export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string, string>;
|
|
49
49
|
/**
|
|
50
|
-
*
|
|
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
|
|
53
|
+
export declare function readUserFiles(cwd: string): Map<string, string>;
|
|
53
54
|
/**
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
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
|
|
70
|
+
export declare function syncAgentDirs(cwd: string, packageFiles: Map<string, string>, userFiles: Map<string, string>): void;
|
|
68
71
|
/**
|
|
69
|
-
*
|
|
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
|
|
74
|
+
export declare function installedRules(rules: Rule[], userFiles: Map<string, string>): Rule[];
|
|
75
75
|
/**
|
|
76
|
-
*
|
|
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
|
|
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
|
|
88
|
-
* frontmatter `description` and a reference to
|
|
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
|
|
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[],
|
|
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
|
|
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"}
|
package/dist/lintPrepare.js
CHANGED
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
|
-
* This script
|
|
6
|
-
*
|
|
7
|
-
* symlinks
|
|
8
|
-
*
|
|
9
|
-
*
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
const
|
|
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
|
-
|
|
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
|
-
*
|
|
106
|
-
*
|
|
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
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
for (const
|
|
113
|
-
|
|
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
|
-
*
|
|
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
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
*
|
|
140
|
-
*
|
|
141
|
-
*
|
|
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
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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
|
-
|
|
166
|
-
});
|
|
309
|
+
}
|
|
167
310
|
}
|
|
168
311
|
/**
|
|
169
|
-
*
|
|
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
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
for (const
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
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
|
-
*
|
|
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
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
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
|
|
223
|
-
* frontmatter `description` and a reference to
|
|
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
|
|
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,
|
|
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
|
-
|
|
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
|
|
303
|
-
|
|
304
|
-
|
|
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
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
|
-
- `.
|
|
19
|
-
- `rules
|
|
20
|
-
- `.
|
|
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
|
|
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
|
-
-
|
|
31
|
+
- **→ `openspec/specs`**
|
|
33
32
|
2. Must the agent always know it when touching a deterministically identifiable set of files?
|
|
34
|
-
-
|
|
33
|
+
- **→ scoped `.agents/rules`**
|
|
35
34
|
3. Is it mandatory repo-wide or directory-wide context/routing?
|
|
36
|
-
-
|
|
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
|
-
- **→
|
|
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
|
|
70
|
-
- Can be decomposed as
|
|
71
|
-
-
|
|
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
|
|
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
|
-
# `.
|
|
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
|
-
# `.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
122
|
+
- Preferred instructions/rules syntax how to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
|
|
123
|
+
- Rules & instructions in these files can't be cited from tests or code, so their proof is tooling, never a citation
|
package/skills/lint-repo.md
CHANGED
|
@@ -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 .
|
|
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: `.
|
|
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
|
|