@kirill.konshin/lint 0.6.5 → 0.6.6
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
|
@@ -334,10 +334,10 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
|
|
|
334
334
|
|
|
335
335
|
In the project root, `lint-prepare`:
|
|
336
336
|
|
|
337
|
-
- Creates real `rules
|
|
338
|
-
- Links every `rules/*.md
|
|
339
|
-
- Mirrors your own
|
|
340
|
-
- 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
|
|
337
|
+
- Creates real `rules/` and `skills/` directories in `.agents/` (canonical, cross-tool — Codex reads it) and `.claude/` (Claude Code), and symlinks the top-level entries it knows into them: a rule file, a skill folder.
|
|
338
|
+
- Links every `rules/*.md` file and every `skills/<name>/` folder into both — 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). A rule or skill of yours with the same name in `.agents/` wins, the package one is not installed.
|
|
339
|
+
- Mirrors your own top-level entries from `.agents/{rules,skills}/` into `.claude/`. Commands are not synced: make them skills.
|
|
340
|
+
- Removes dead links (e.g. after renaming a file) and the links it placed before but no longer needs, including what older versions placed (per-file skill links, `commands/`). Each directory gets a generated `.gitignore` listing its links, so your own entries stay tracked.
|
|
341
341
|
- Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — one entry per rule (the package's and yours): its title, frontmatter `description`, the `paths` it is scoped to and a plain link to its `.agents/rules/<file>` entry — and symlinks `CLAUDE.md` to it. The links are never `@` imports: Claude Code loads `.claude/rules` itself and honours each rule's `paths`, while an import would load every rule into every session.
|
|
342
342
|
|
|
343
343
|
### OpenSpec
|
package/dist/lintPrepare.d.ts
CHANGED
|
@@ -2,11 +2,10 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
|
-
* This script makes `rules
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`. It also
|
|
5
|
+
* This script makes `rules` and `skills` real directories in the consuming project's `.agents`
|
|
6
|
+
* (canonical, cross-tool, Codex reads it) and `.claude` (Claude Code), and symlinks the top-level
|
|
7
|
+
* entries it knows into them: package rule files and skill folders go into both, pointing straight at
|
|
8
|
+
* the installed package; the user's own `.agents` entries are mirrored into `.claude`. It also
|
|
10
9
|
* generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
11
10
|
*
|
|
12
11
|
* Usage:
|
|
@@ -45,26 +44,22 @@ export declare function readRules(): Rule[];
|
|
|
45
44
|
*/
|
|
46
45
|
export declare function readSkills(): Skill[];
|
|
47
46
|
/**
|
|
48
|
-
*
|
|
47
|
+
* Package entries to link, keyed by their path inside an agent dir: every rule file as `rules/<file>` and every skill
|
|
48
|
+
* folder as `skills/<name>`.
|
|
49
49
|
*/
|
|
50
|
-
export declare function
|
|
50
|
+
export declare function packageEntries(rules: Rule[], skills: Skill[]): Map<string, string>;
|
|
51
51
|
/**
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
* one), so a skill can reference `@README.md`.
|
|
52
|
+
* The user's own top-level entries in `.agents/rules` and `.agents/skills`, keyed like packageEntries() - everything
|
|
53
|
+
* there except the links this tool placed (its generated `.gitignore` lists them), dead links and dotfiles.
|
|
55
54
|
*/
|
|
56
|
-
export declare function
|
|
55
|
+
export declare function readUserEntries(cwd: string): Map<string, string>;
|
|
57
56
|
/**
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
*
|
|
64
|
-
* package files into both, pointing straight at the package, and the user's own `.agents` files into `.claude`.
|
|
65
|
-
* Real files and linked directories are the user's - never written over or through. Dead links are
|
|
66
|
-
* removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
|
|
67
|
-
* records them (and keeps them out of git, so the user's own files there stay tracked).
|
|
57
|
+
* Make `rules` and `skills` real directories in every agent dir and link the top-level entries we know into them:
|
|
58
|
+
* package rule files and skill folders into both, pointing straight at the package, the user's own `.agents` entries
|
|
59
|
+
* into `.claude`. A real entry is the user's - never written over or through. Dead links are removed, and so are
|
|
60
|
+
* links from the previous run that are no longer placed (incl. the per-file links of older versions): each
|
|
61
|
+
* directory's generated `.gitignore` records them (and keeps them out of git, so the user's own entries there stay
|
|
62
|
+
* tracked). The `commands` directories older versions synced are cleaned up the same way, `.codex` is not touched.
|
|
68
63
|
*
|
|
69
64
|
* FIXME Codex Includes
|
|
70
65
|
* https://github.com/openai/codex/issues/17401
|
|
@@ -75,11 +70,11 @@ export declare function readUserFiles(cwd: string): Map<string, string>;
|
|
|
75
70
|
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
76
71
|
* indexed anywhere).
|
|
77
72
|
*/
|
|
78
|
-
export declare function syncAgentDirs(cwd: string,
|
|
73
|
+
export declare function syncAgentDirs(cwd: string, packageEntries: Map<string, string>, userEntries: Map<string, string>): void;
|
|
79
74
|
/**
|
|
80
75
|
* Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
|
|
81
76
|
*/
|
|
82
|
-
export declare function installedRules(rules: Rule[],
|
|
77
|
+
export declare function installedRules(rules: Rule[], userEntries: Map<string, string>): Rule[];
|
|
83
78
|
/**
|
|
84
79
|
* Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
|
|
85
80
|
*/
|
package/dist/lintPrepare.js
CHANGED
|
@@ -7,11 +7,10 @@ import { parse } from "yaml";
|
|
|
7
7
|
/**
|
|
8
8
|
* @kirill.konshin/lint
|
|
9
9
|
*
|
|
10
|
-
* This script makes `rules
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`. It also
|
|
10
|
+
* This script makes `rules` and `skills` real directories in the consuming project's `.agents`
|
|
11
|
+
* (canonical, cross-tool, Codex reads it) and `.claude` (Claude Code), and symlinks the top-level
|
|
12
|
+
* entries it knows into them: package rule files and skill folders go into both, pointing straight at
|
|
13
|
+
* the installed package; the user's own `.agents` entries are mirrored into `.claude`. It also
|
|
15
14
|
* generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
16
15
|
*
|
|
17
16
|
* Usage:
|
|
@@ -28,16 +27,11 @@ const AGENTS_FILE = "AGENTS.md";
|
|
|
28
27
|
const CLAUDE_FILE = "CLAUDE.md";
|
|
29
28
|
const RULES_DIR = path.join(__dirname, "../rules");
|
|
30
29
|
const SKILLS_DIR = path.join(__dirname, "../skills");
|
|
31
|
-
const COMMANDS_DIR = path.join(__dirname, "../commands");
|
|
32
|
-
const README_FILE = path.join(__dirname, "../README.md");
|
|
33
30
|
const CANONICAL_AGENT_DIR = ".agents";
|
|
34
31
|
const MIRROR_AGENT_DIRS = [".claude"];
|
|
35
32
|
const AGENT_DIRS = [CANONICAL_AGENT_DIR, ...MIRROR_AGENT_DIRS];
|
|
36
|
-
const AGENT_KINDS = [
|
|
37
|
-
|
|
38
|
-
"commands",
|
|
39
|
-
"skills"
|
|
40
|
-
];
|
|
33
|
+
const AGENT_KINDS = ["rules", "skills"];
|
|
34
|
+
const LEGACY_DIRS = AGENT_DIRS.map((dir) => path.join(dir, "commands"));
|
|
41
35
|
const GITIGNORE = ".gitignore";
|
|
42
36
|
const GITIGNORE_HEADER = "# Generated by @kirill.konshin/lint: symlinks it manages here, your own files stay tracked";
|
|
43
37
|
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
|
|
@@ -89,18 +83,6 @@ const toRule = (file, content) => {
|
|
|
89
83
|
};
|
|
90
84
|
};
|
|
91
85
|
/**
|
|
92
|
-
* Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
|
|
93
|
-
* directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
|
|
94
|
-
*/
|
|
95
|
-
function listRealFiles(root, dir = root) {
|
|
96
|
-
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
97
|
-
const entryPath = path.join(dir, entry.name);
|
|
98
|
-
if (entry.name.startsWith(".")) return [];
|
|
99
|
-
if (entry.isDirectory()) return listRealFiles(root, entryPath);
|
|
100
|
-
return entry.isFile() ? [path.relative(root, entryPath)] : [];
|
|
101
|
-
});
|
|
102
|
-
}
|
|
103
|
-
/**
|
|
104
86
|
* Dead symlinks under `dir`, walking real directories only.
|
|
105
87
|
*/
|
|
106
88
|
function findDeadLinks(dir) {
|
|
@@ -181,20 +163,36 @@ function writeManifest(gitignore, links) {
|
|
|
181
163
|
].join("\n"));
|
|
182
164
|
}
|
|
183
165
|
/**
|
|
184
|
-
*
|
|
185
|
-
|
|
166
|
+
* Top-level names this tool linked into a directory on a previous run, from its generated `.gitignore`.
|
|
167
|
+
*/
|
|
168
|
+
const manifestNames = (dir) => new Set(readManifest(path.join(dir, GITIGNORE)).map((link) => link.split(path.sep)[0]));
|
|
169
|
+
/**
|
|
170
|
+
* Remove the links listed in a generated `.gitignore` of a directory this tool no longer manages, then the
|
|
171
|
+
* `.gitignore` and the directory itself when nothing else is left.
|
|
172
|
+
*/
|
|
173
|
+
function cleanUpLegacyDir(cwd, dir) {
|
|
174
|
+
const root = path.join(cwd, dir);
|
|
175
|
+
if (!lstat(root)?.isDirectory()) return;
|
|
176
|
+
for (const link of [...findDeadLinks(root), ...readManifest(path.join(root, GITIGNORE)).map((l) => path.join(root, l))]) if (lstat(link)?.isSymbolicLink()) removeLink(link, root);
|
|
177
|
+
writeManifest(path.join(root, GITIGNORE), []);
|
|
178
|
+
for (const entry of fs.readdirSync(root).filter((name) => !name.startsWith("."))) console.log(`Kept ${path.join(dir, entry)}: commands are no longer synced, make it a skill in ${CANONICAL_AGENT_DIR}/skills`);
|
|
179
|
+
if (!fs.readdirSync(root).length) fs.rmdirSync(root);
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Links to place, keyed by their path relative to cwd: package entries into every agent dir, the user's own `.agents`
|
|
183
|
+
* entries into the mirrors. A user entry wins over the package entry of the same name.
|
|
186
184
|
*/
|
|
187
|
-
function plannedLinks(cwd,
|
|
185
|
+
function plannedLinks(cwd, packageEntries, userEntries) {
|
|
188
186
|
const canonicalDir = path.join(fs.realpathSync(cwd), CANONICAL_AGENT_DIR);
|
|
189
187
|
const links = /* @__PURE__ */ new Map();
|
|
190
|
-
for (const [
|
|
191
|
-
if (
|
|
192
|
-
console.log(`${path.join(CANONICAL_AGENT_DIR,
|
|
188
|
+
for (const [entry, source] of packageEntries) {
|
|
189
|
+
if (userEntries.has(entry)) {
|
|
190
|
+
console.log(`${path.join(CANONICAL_AGENT_DIR, entry)} is the user's, the package one is not installed`);
|
|
193
191
|
continue;
|
|
194
192
|
}
|
|
195
|
-
for (const dir of AGENT_DIRS) links.set(path.join(dir,
|
|
193
|
+
for (const dir of AGENT_DIRS) links.set(path.join(dir, entry), fs.realpathSync(source));
|
|
196
194
|
}
|
|
197
|
-
for (const
|
|
195
|
+
for (const entry of userEntries.keys()) for (const dir of MIRROR_AGENT_DIRS) links.set(path.join(dir, entry), path.join(canonicalDir, entry));
|
|
198
196
|
return links;
|
|
199
197
|
}
|
|
200
198
|
/**
|
|
@@ -222,49 +220,39 @@ function readSkills() {
|
|
|
222
220
|
return fs.readdirSync(SKILLS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, "SKILL.md"))).map((entry) => ({ name: entry.name })).sort((a, b) => a.name.localeCompare(b.name));
|
|
223
221
|
}
|
|
224
222
|
/**
|
|
225
|
-
*
|
|
226
|
-
|
|
227
|
-
function readCommands() {
|
|
228
|
-
if (!fs.existsSync(COMMANDS_DIR)) return [];
|
|
229
|
-
return fs.readdirSync(COMMANDS_DIR).filter((f) => f.endsWith(".md")).sort();
|
|
230
|
-
}
|
|
231
|
-
/**
|
|
232
|
-
* Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `commands/<file>`, and every file
|
|
233
|
-
* of a skill at its own relative path, plus the package README.md next to its `SKILL.md` (unless the skill ships
|
|
234
|
-
* one), so a skill can reference `@README.md`.
|
|
223
|
+
* Package entries to link, keyed by their path inside an agent dir: every rule file as `rules/<file>` and every skill
|
|
224
|
+
* folder as `skills/<name>`.
|
|
235
225
|
*/
|
|
236
|
-
function
|
|
237
|
-
const
|
|
238
|
-
const
|
|
239
|
-
for (const
|
|
240
|
-
|
|
241
|
-
for (const skill of skills) {
|
|
242
|
-
const root = path.join(SKILLS_DIR, skill.name);
|
|
243
|
-
const readme = path.join("skills", skill.name, "README.md");
|
|
244
|
-
for (const file of listRealFiles(root)) files.set(path.join("skills", skill.name, file), path.join(root, file));
|
|
245
|
-
if (hasReadme && !files.has(readme)) files.set(readme, README_FILE);
|
|
246
|
-
}
|
|
247
|
-
return files;
|
|
226
|
+
function packageEntries(rules, skills) {
|
|
227
|
+
const entries = /* @__PURE__ */ new Map();
|
|
228
|
+
for (const rule of rules) entries.set(path.join("rules", rule.file), path.join(RULES_DIR, rule.file));
|
|
229
|
+
for (const skill of skills) entries.set(path.join("skills", skill.name), path.join(SKILLS_DIR, skill.name));
|
|
230
|
+
return entries;
|
|
248
231
|
}
|
|
249
232
|
/**
|
|
250
|
-
* The user's own
|
|
251
|
-
* except the
|
|
233
|
+
* The user's own top-level entries in `.agents/rules` and `.agents/skills`, keyed like packageEntries() - everything
|
|
234
|
+
* there except the links this tool placed (its generated `.gitignore` lists them), dead links and dotfiles.
|
|
252
235
|
*/
|
|
253
|
-
function
|
|
254
|
-
const
|
|
236
|
+
function readUserEntries(cwd) {
|
|
237
|
+
const entries = /* @__PURE__ */ new Map();
|
|
255
238
|
for (const kind of AGENT_KINDS) {
|
|
256
239
|
const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
|
|
257
240
|
if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory()) continue;
|
|
258
|
-
|
|
241
|
+
const own = manifestNames(root);
|
|
242
|
+
for (const name of fs.readdirSync(root)) {
|
|
243
|
+
const entry = path.join(root, name);
|
|
244
|
+
if (!name.startsWith(".") && !own.has(name) && fs.existsSync(entry)) entries.set(path.join(kind, name), entry);
|
|
245
|
+
}
|
|
259
246
|
}
|
|
260
|
-
return
|
|
247
|
+
return entries;
|
|
261
248
|
}
|
|
262
249
|
/**
|
|
263
|
-
* Make `rules
|
|
264
|
-
* package files into both, pointing straight at the package,
|
|
265
|
-
*
|
|
266
|
-
*
|
|
267
|
-
* records them (and keeps them out of git, so the user's own
|
|
250
|
+
* Make `rules` and `skills` real directories in every agent dir and link the top-level entries we know into them:
|
|
251
|
+
* package rule files and skill folders into both, pointing straight at the package, the user's own `.agents` entries
|
|
252
|
+
* into `.claude`. A real entry is the user's - never written over or through. Dead links are removed, and so are
|
|
253
|
+
* links from the previous run that are no longer placed (incl. the per-file links of older versions): each
|
|
254
|
+
* directory's generated `.gitignore` records them (and keeps them out of git, so the user's own entries there stay
|
|
255
|
+
* tracked). The `commands` directories older versions synced are cleaned up the same way, `.codex` is not touched.
|
|
268
256
|
*
|
|
269
257
|
* FIXME Codex Includes
|
|
270
258
|
* https://github.com/openai/codex/issues/17401
|
|
@@ -275,35 +263,35 @@ function readUserFiles(cwd) {
|
|
|
275
263
|
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
276
264
|
* indexed anywhere).
|
|
277
265
|
*/
|
|
278
|
-
function syncAgentDirs(cwd,
|
|
279
|
-
const links = plannedLinks(cwd,
|
|
266
|
+
function syncAgentDirs(cwd, packageEntries, userEntries) {
|
|
267
|
+
const links = plannedLinks(cwd, packageEntries, userEntries);
|
|
268
|
+
for (const dir of LEGACY_DIRS) cleanUpLegacyDir(cwd, dir);
|
|
280
269
|
for (const dir of AGENT_DIRS) for (const kind of AGENT_KINDS) {
|
|
281
270
|
const root = path.join(dir, kind);
|
|
282
271
|
const rootPath = path.join(cwd, root);
|
|
283
272
|
const gitignore = path.join(rootPath, GITIGNORE);
|
|
273
|
+
const planned = [...links].filter(([link]) => path.dirname(link) === root);
|
|
284
274
|
if (!ensureRealDir(cwd, root)) {
|
|
285
275
|
console.log(`Skipped ${root}: not a real directory`);
|
|
286
276
|
continue;
|
|
287
277
|
}
|
|
288
278
|
for (const link of findDeadLinks(rootPath)) removeLink(link, rootPath);
|
|
289
|
-
const placed = [];
|
|
290
|
-
for (const [link, target] of links) if (link.startsWith(root + path.sep) && placeLink(cwd, link, target)) placed.push(path.relative(root, link));
|
|
291
279
|
for (const link of readManifest(gitignore)) {
|
|
292
280
|
const linkPath = path.join(rootPath, link);
|
|
293
|
-
if (!
|
|
281
|
+
if (!planned.some(([plannedLink]) => plannedLink === path.join(root, link)) && lstat(linkPath)?.isSymbolicLink()) removeLink(linkPath, rootPath);
|
|
294
282
|
}
|
|
295
|
-
writeManifest(gitignore,
|
|
283
|
+
writeManifest(gitignore, planned.filter(([link, target]) => placeLink(cwd, link, target)).map(([link]) => path.relative(root, link)));
|
|
296
284
|
}
|
|
297
285
|
}
|
|
298
286
|
/**
|
|
299
287
|
* Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
|
|
300
288
|
*/
|
|
301
|
-
function installedRules(rules,
|
|
289
|
+
function installedRules(rules, userEntries) {
|
|
302
290
|
const byFile = new Map(rules.map((rule) => [rule.file, rule]));
|
|
303
291
|
const rulesDir = `rules${path.sep}`;
|
|
304
|
-
for (const [
|
|
305
|
-
if (!
|
|
306
|
-
const ruleFile =
|
|
292
|
+
for (const [entry, source] of userEntries) {
|
|
293
|
+
if (!entry.startsWith(rulesDir) || !entry.endsWith(".md") || !fs.statSync(source).isFile()) continue;
|
|
294
|
+
const ruleFile = entry.slice(rulesDir.length);
|
|
307
295
|
byFile.set(ruleFile, toRule(ruleFile, fs.readFileSync(source, "utf-8")));
|
|
308
296
|
}
|
|
309
297
|
return [...byFile].sort(([a], [b]) => a < b ? -1 : 1).map(([, rule]) => rule);
|
|
@@ -396,12 +384,10 @@ function main() {
|
|
|
396
384
|
console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(", ")}`);
|
|
397
385
|
const skills = readSkills();
|
|
398
386
|
console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(", ")}`);
|
|
399
|
-
const
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
console.log(`Synced ${AGENT_DIRS.join(", ")}, mirrored ${userFiles.size} own file(s) from ${CANONICAL_AGENT_DIR}`);
|
|
404
|
-
const content = generateAgentsFile(installedRules(rules, userFiles), customSection);
|
|
387
|
+
const userEntries = readUserEntries(cwd);
|
|
388
|
+
syncAgentDirs(cwd, packageEntries(rules, skills), userEntries);
|
|
389
|
+
console.log(`Synced ${AGENT_DIRS.join(", ")}, mirrored ${userEntries.size} own entries from ${CANONICAL_AGENT_DIR}`);
|
|
390
|
+
const content = generateAgentsFile(installedRules(rules, userEntries), customSection);
|
|
405
391
|
fs.writeFileSync(targetPath, content, "utf-8");
|
|
406
392
|
console.log(`${exists ? "Updated" : "Created"} ${AGENTS_FILE}`);
|
|
407
393
|
symlinkClaudeMd(cwd);
|
|
@@ -414,4 +400,4 @@ function main() {
|
|
|
414
400
|
}
|
|
415
401
|
if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(__filename)) main();
|
|
416
402
|
//#endregion
|
|
417
|
-
export { checkClaudeMdSafety, checkExisting, generateAgentsFile, installedRules, main,
|
|
403
|
+
export { checkClaudeMdSafety, checkExisting, generateAgentsFile, installedRules, main, packageEntries, readRules, readSkills, readUserEntries, symlinkClaudeMd, syncAgentDirs };
|
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.6.
|
|
4
|
+
"version": "0.6.6",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"skipGenerate": true,
|
|
7
7
|
"bin": {
|
|
@@ -42,7 +42,6 @@
|
|
|
42
42
|
},
|
|
43
43
|
"files": [
|
|
44
44
|
"dist",
|
|
45
|
-
"commands",
|
|
46
45
|
"rules",
|
|
47
46
|
"skills",
|
|
48
47
|
"!**/*.test.*"
|
package/rules/agent.md
CHANGED
|
@@ -17,7 +17,6 @@ Use this summarized guidance to consider where to place a set of instructions
|
|
|
17
17
|
- Subdirectory `AGENTS.md` — scoped to this particular directory, auto-injected
|
|
18
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
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
|
|
21
20
|
- `openspec/specs` - SDD specifications, should define user facing behavior or API contracts, not coding instructions / best practices / etc.
|
|
22
21
|
- `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
|
|
23
22
|
- `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
@@ -44,6 +43,8 @@ When correctness depends on an instruction being observed, do NOT rely solely on
|
|
|
44
43
|
|
|
45
44
|
Prefer one authoritative location for each concern. Reference it elsewhere instead of duplicating it.
|
|
46
45
|
|
|
46
|
+
Do not use `.claude/commands` for anything. It's not portable (`.agent/commands` has compatibility gaps). Commands are essentially simplified skills, so if you pick between skill vs command, choose skill.
|
|
47
|
+
|
|
47
48
|
# `README.md`
|
|
48
49
|
|
|
49
50
|
- Should be targeted to be read by humans
|
|
@@ -94,12 +95,6 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
|
|
|
94
95
|
- Agent decides to discover it or not, use it or not, so no guarantee of honoring
|
|
95
96
|
- A requirement/rule MUST NOT exist only in a skill if correctness depends on the agent always observing it
|
|
96
97
|
|
|
97
|
-
# `.agents/commands`
|
|
98
|
-
|
|
99
|
-
- `.agents/commands` must be accompanied by symlinks in `.claude/commands`
|
|
100
|
-
- Smaller and simpler than skills
|
|
101
|
-
- One-off commands, not flows
|
|
102
|
-
|
|
103
98
|
# `openspec`
|
|
104
99
|
|
|
105
100
|
- `OpenSpec` / `SpecKit` and similar SDD specifications should define
|
|
@@ -10,11 +10,11 @@ Two jobs. Pick by the request; do only what was asked.
|
|
|
10
10
|
- **Set up / upgrade lint tooling** → [§A](#a-set-up--update-tooling)
|
|
11
11
|
- **Audit code against the rules** → [§B](#b-audit-code-against-rules)
|
|
12
12
|
|
|
13
|
-
Full config templates:
|
|
13
|
+
Full config templates: `node_modules/@kirill.konshin/lint/README.md`
|
|
14
14
|
|
|
15
15
|
## A. Set up / update tooling
|
|
16
16
|
|
|
17
|
-
Follow
|
|
17
|
+
Follow `node_modules/@kirill.konshin/lint/README.md`, reconciling (never blindly overwriting project-specific overrides). When **upgrading** `@kirill.konshin/lint` from an older version, first apply the README's "Migration" section (e.g. 0.2.x → 0.3.x: default-exported array → `defineLintConfig()` options):
|
|
18
18
|
|
|
19
19
|
1. **Install** — add `eslint`, `prettier`, `@kirill.konshin/lint`, `husky`, `lint-staged` (+ the PNPM `.npmrc` block if pnpm).
|
|
20
20
|
2. **Config** — create/reconcile `.editorconfig`, `eslint.config.mjs` and `.prettierrc.mjs` (pass `defineLintConfig` options as needed — e.g. `defaultIgnore: { importMetaUrl: import.meta.url }`, `next: { rootDir }` — and keep project rule overrides).
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
2
|
+
name: spec-author
|
|
3
3
|
description: Write or edit a capability specification in openspec/specs — the default direct-edit path
|
|
4
4
|
allowed-tools: Bash(openspec:*), Bash(spec-tools:*), Bash(spec-steward:*), Bash(yarn openspec:*), Bash(yarn spec-tools:*), Bash(yarn spec-steward:*), Bash(npx openspec:*), Bash(npx spec-tools:*), Bash(npx spec-steward:*), Bash(git diff*), Bash(git log*), Read, Edit, Write, Glob, Grep
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Write or edit a capability specification in place. This is the **default** path for specification work; the `/opsx:*` commands drive the full delta flow and run only when the user asks for them.
|
|
8
8
|
|
|
9
|
-
How a specification is written is the spec-steward model, [`references/model.md`](../
|
|
9
|
+
How a specification is written is the spec-steward model, [`references/model.md`](../spec-steward/references/model.md), and what the gate checks is its [`references/contract.md`](../spec-steward/references/contract.md); the rest of the tooling's contract is the spec-tools skill's [`references/contract.md`](../spec-tools/references/contract.md); the change paths and who commits are in the root `AGENTS.md`. Read them; this file only sequences the work.
|
|
10
10
|
|
|
11
11
|
## Steps
|
|
12
12
|
|