@kirill.konshin/lint 0.6.4 → 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/`, `commands/` and `skills/` directories in `.agents/` (canonical, cross-tool) and `.claude/` (Claude Code), and only ever symlinks files into them.
338
- - Links every `rules/*.md`, every `commands/*.md` and every skill folder (`skills/<name>/` with all its files, plus this `README.md` next to `SKILL.md` unless the skill ships one, 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).
339
- - Mirrors your own files from `.agents/{rules,commands,skills}/` into `.claude/`; a file of yours wins over the package file at the same path.
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 files stay tracked.
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
@@ -356,7 +356,7 @@ Which to reach for:
356
356
  | How do I write or change a rule? | `/spec-author` | The specification edited in place, with the code and tests that prove it |
357
357
  | Do citations resolve, is every new scenario bound, did a rule weaken? | `spec-tools steward check` (the gate, the edit hook) | Fails the merge request on an error |
358
358
  | Are these the right rules — placement, REQUIRED or ⚠️ ADVISORY, wording, evidence, duplicates, drift across repositories? | the `spec-steward` skill (audit on the `spec-tools` engine, review rounds, align) | A review file of proposals; the owner decides, steward applies; never a build failure |
359
- | Does the code do exactly what the rules say, and do the bound tests assert them? | the `spec-verify` skill, run by `spec-tools` | Graded, quote-proved findings; PASS / FAIL / INCOMPLETE gates CI |
359
+ | Does the code satisfy the intent of the rules, and do the bound tests assert them? | the `spec-verify` skill, run by `spec-tools` | Graded, quote-proved findings; PASS / FAIL / INCOMPLETE gates CI |
360
360
  | Is the change finished, what did it change, how does CI run the audit? | `spec-tools` (gates, evidence, diff, tier, workers, verdict, comment, html) | Gates and reports for the pipeline |
361
361
 
362
362
  Where each runs:
@@ -371,7 +371,7 @@ Where each runs:
371
371
 
372
372
  Specifications change only by hand, or when the steward skill applies the owner's accepted review answers; `spec-tools steward check --fix` makes the only mechanical repairs. No audit edits code or specifications.
373
373
 
374
- The audits share their principles: `spec-verify`'s checks 2–5 are spec-steward's criteria 10, 9, 11 and 5, worded identically — steward asks whether the rule should change, `spec-verify` whether the code or the rule has diverged.
374
+ The audits share one set of judging rules, `skills/spec-tools/references/rules/`: an ERROR is a demonstrated defect with a production effect (a broken flow, a contract or invariant violation, a sensitive-data leak, a performance problem), and it stands only when its judge confirms it above 70% confidence. `spec-verify`'s checks 2–5 are spec-steward's items 10, 9, 11 and 5, worded identically — steward asks whether the rule should change, `spec-verify` whether the code or the rule has diverged. Every file the tools write is under `.spec-audit/`, as YAML; Markdown only as the final report.
375
375
 
376
376
  Setup and the GitLab pipeline are in the `spec-tools` skill.
377
377
 
@@ -2,11 +2,10 @@
2
2
  /**
3
3
  * @kirill.konshin/lint
4
4
  *
5
- * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
- * `.agents` (canonical, cross-tool) and `.claude` (Claude Code), and fills them with
7
- * file symlinks only: package rules, commands and skills (every file a skill folder ships, plus the package
8
- * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into both, pointing
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
- * Read the package commands directory: every markdown file is a command named after the file.
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 readCommands(): string[];
50
+ export declare function packageEntries(rules: Rule[], skills: Skill[]): Map<string, string>;
51
51
  /**
52
- * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `commands/<file>`, and every file
53
- * of a skill at its own relative path, plus the package README.md next to its `SKILL.md` (unless the skill ships
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 packageFiles(rules: Rule[], skills: Skill[], commands?: string[]): Map<string, string>;
55
+ export declare function readUserEntries(cwd: string): Map<string, string>;
57
56
  /**
58
- * The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
59
- * except the package links (and dotfiles).
60
- */
61
- export declare function readUserFiles(cwd: string): Map<string, string>;
62
- /**
63
- * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
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, packageFiles: Map<string, string>, userFiles: Map<string, string>): void;
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[], userFiles: Map<string, string>): 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
  */
@@ -7,11 +7,10 @@ import { parse } from "yaml";
7
7
  /**
8
8
  * @kirill.konshin/lint
9
9
  *
10
- * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
11
- * `.agents` (canonical, cross-tool) and `.claude` (Claude Code), and fills them with
12
- * file symlinks only: package rules, commands and skills (every file a skill folder ships, plus the package
13
- * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into both, pointing
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
- "rules",
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
- * Links to place, keyed by their path relative to cwd: package files into every agent dir, the user's own `.agents`
185
- * files into the mirrors. A user file wins over the package file at the same path.
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, packageFiles, userFiles) {
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 [file, source] of packageFiles) {
191
- if (userFiles.has(file)) {
192
- console.log(`${path.join(CANONICAL_AGENT_DIR, file)} overrides the package file`);
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, file), fs.realpathSync(source));
193
+ for (const dir of AGENT_DIRS) links.set(path.join(dir, entry), fs.realpathSync(source));
196
194
  }
197
- for (const file of userFiles.keys()) for (const dir of MIRROR_AGENT_DIRS) links.set(path.join(dir, file), path.join(canonicalDir, file));
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
- * Read the package commands directory: every markdown file is a command named after the file.
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 packageFiles(rules, skills, commands = []) {
237
- const files = /* @__PURE__ */ new Map();
238
- const hasReadme = fs.existsSync(README_FILE);
239
- for (const rule of rules) files.set(path.join("rules", rule.file), path.join(RULES_DIR, rule.file));
240
- for (const command of commands) files.set(path.join("commands", command), path.join(COMMANDS_DIR, command));
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 files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
251
- * except the package links (and dotfiles).
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 readUserFiles(cwd) {
254
- const files = /* @__PURE__ */ new Map();
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
- for (const file of listRealFiles(root)) files.set(path.join(kind, file), path.join(root, file));
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 files;
247
+ return entries;
261
248
  }
262
249
  /**
263
- * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
264
- * package files into both, pointing straight at the package, and the user's own `.agents` files into `.claude`.
265
- * Real files and linked directories are the user's - never written over or through. Dead links are
266
- * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
267
- * records them (and keeps them out of git, so the user's own files there stay tracked).
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, packageFiles, userFiles) {
279
- const links = plannedLinks(cwd, packageFiles, userFiles);
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 (!placed.includes(link) && lstat(linkPath)?.isSymbolicLink()) removeLink(linkPath, rootPath);
281
+ if (!planned.some(([plannedLink]) => plannedLink === path.join(root, link)) && lstat(linkPath)?.isSymbolicLink()) removeLink(linkPath, rootPath);
294
282
  }
295
- writeManifest(gitignore, placed);
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, userFiles) {
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 [file, source] of userFiles) {
305
- if (!file.startsWith(rulesDir) || !file.endsWith(".md")) continue;
306
- const ruleFile = file.slice(rulesDir.length).split(path.sep).join("/");
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 commands = readCommands();
400
- console.log(`Found ${commands.length} command(s): ${commands.map((c) => c.replace(/\.md$/, "")).join(", ")}`);
401
- const userFiles = readUserFiles(cwd);
402
- syncAgentDirs(cwd, packageFiles(rules, skills, commands), userFiles);
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, packageFiles, readCommands, readRules, readSkills, readUserFiles, symlinkClaudeMd, syncAgentDirs };
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",
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.*"
@@ -84,7 +83,6 @@
84
83
  "@types/eslint-plugin-jsx-a11y": "^6.10.1",
85
84
  "@types/eslint-plugin-promise": "^7.3.0",
86
85
  "github-markdown-css": "^5.9.0",
87
- "jsonrepair": "^3.15.0",
88
86
  "marked": "^18.0.5",
89
87
  "tsdown": "^0.23.0",
90
88
  "vitest": "^4.1.10"
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: @README.md
13
+ Full config templates: `node_modules/@kirill.konshin/lint/README.md`
14
14
 
15
15
  ## A. Set up / update tooling
16
16
 
17
- Follow @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):
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: Spec author
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`](../skills/spec-steward/references/model.md), and what the gate checks is its [`references/contract.md`](../skills/spec-steward/references/contract.md); the rest of the tooling's contract is the spec-tools skill's [`references/contract.md`](../skills/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.
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
 
@@ -18,7 +18,7 @@ How a specification is written is the spec-steward model, [`references/model.md`
18
18
 
19
19
  4. **If the user chose a change folder**: `openspec new change <name>`, set `skip_specs: true` in its `.openspec.yaml`, write `proposal.md`, `design.md` and `tasks.md`. The behaviour still lands as a direct edit — the folder carries the plan, never deltas. Set `skip_specs` yourself when the change is plainly simple (a bugfix, a small feature); ask when in doubt. The folder is archived inside the merge or pull request, on the user's word.
20
20
 
21
- 5. **Write it.** Name the observable failure the rule prevents and the cheapest evidence that catches it; if there is none, mark the requirement `**⚠️ Advisory:** <why review is its evidence>`, and record what is knowingly missing as `**⚠️ Known gap (<tracker>):** <what is missing>`. Write a new or edited statement in EARS (`When <trigger>, the <system> SHALL <response>`, `While <state>, …`, `If <condition>, then …`, or `The <system> SHALL …`), keeping the RFC 2119 keyword in capitals, and each new or edited scenario in Given/When/Then, one case each, Given only where a precondition matters; leave untouched text as it is. Scenario names are unique within the file:
21
+ 5. **Write it.** Name the observable failure the rule prevents and the cheapest evidence that catches it; if there is none, mark the requirement `**⚠️ Advisory:** <why review is its evidence>`, and record what is knowingly missing as `**⚠️ Known gap (<tracker>):** <what is missing>`. Write a new or edited statement in EARS (`When <trigger>, the <system> SHALL <response>`, `While <state>, …`, `If <condition>, then …`, or `The <system> SHALL …`), keeping the RFC 2119 keyword in capitals, and each new or edited scenario in Given/When/Then, one case each, Given only where a precondition matters; leave untouched text as it is. Write new and edited text in the model's light ASD-STE100 subset: one obligation per sentence, at most 25 words per sentence, one term for one concept, active voice, no vague word in a REQUIRED statement. Scenario names are unique within the file:
22
22
 
23
23
  ```markdown
24
24
  ### Requirement: <name>
@@ -36,4 +36,4 @@ How a specification is written is the spec-steward model, [`references/model.md`
36
36
 
37
37
  6. **Verify**: run the checks the root `AGENTS.md` lists; where it lists none, `openspec validate --strict --all` and `spec-tools gates`.
38
38
 
39
- 7. **Hand back.** Say what changed and show the `spec-tools diff` first line. Do not commit, push, or archive; end with the decisions the user has to make.
39
+ 7. **Hand back.** Say what changed, in ASD-STE100, and show the `spec-tools diff` first line. Do not commit, push, or archive; end with the decisions the user has to make.
@@ -1,16 +1,17 @@
1
1
  ---
2
2
  name: spec-steward
3
- description: Guard, audit and repair an OpenSpec specification corpus — whether these are the right rules, in the right place, with the right evidence; it proposes spec changes and never fails a build. Use when auditing specs for corpus quality (the whole corpus, a change, or one capability), producing or processing a spec review file (review rounds where the owner answers items with ⬜ / ✅ / ❌), aligning rules shared by several repositories, wiring the spec guard (edit hook, AGENTS.md routing, OPSX config) into a repository, or when the repository's spec gate, `spec-tools steward check` or the edit hook reports a finding. Deterministic scripts do the mechanical work; the skill supplies the procedure. It does not audit code conformance; the `spec-verify` skill does. Writing a rule is the `/spec-author` command.
3
+ description: Guard, audit and repair an OpenSpec specification corpus — whether these are the right rules, in the right place, with the right evidence; it proposes spec changes and never fails a build. Use when auditing specs for corpus quality (the whole corpus, a change, or one capability), producing or processing a spec review file (the YAML review `.spec-audit/spec-review.yaml`, where the owner answers each item's `decision` with ✅ / ❌ / a comment), aligning rules shared by several repositories, wiring the spec guard (edit hook, AGENTS.md routing, OPSX config) into a repository, or when the repository's spec gate, `spec-tools steward check` or the edit hook reports a finding. Deterministic scripts do the mechanical work; the skill supplies the procedure. It does not audit code conformance; the `spec-verify` skill does. Writing a rule is the `/spec-author` command.
4
4
  ---
5
5
 
6
6
  # Spec steward
7
7
 
8
- Procedures for an OpenSpec corpus. Four things live elsewhere and are not repeated here:
8
+ Procedures for an OpenSpec corpus. Five things live elsewhere and are not repeated here:
9
9
 
10
10
  - the hard constraints for editing specs — the scoped rule `.agents/rules/openspec.md`
11
11
  - where any guidance belongs — `.agents/rules/agent.md`
12
12
  - the specification model (REQUIRED versus ⚠️ ADVISORY, Known gaps, the evidence ladder, what is not evidence, how requirements and scenarios are written) — [references/model.md](references/model.md)
13
- - what the gate checks and emits (citations, binding, markers, size lines, the scenario ratchet, base resolution, exit codes, the coverage report, the evidence JSON) — [references/contract.md](references/contract.md)
13
+ - what the gate checks and emits (citations, binding, markers, size lines, the scenario ratchet, base resolution, exit codes, the coverage report, the evidence data) — [references/contract.md](references/contract.md)
14
+ - what the audit judges and how sure a finding must be — the judging rules, [`common.md`](../spec-tools/references/rules/common.md) and [`spec-steward.md`](../spec-tools/references/rules/spec-steward.md)
14
15
 
15
16
  `steward` below means `spec-tools steward`, through the `spec-tools` bin `@kirill.konshin/lint` installs; where the bin is absent, `node <the spec-tools skill's folder>/scripts/cli.js steward`. The file is self-contained and needs Node ≥ 20 and git. Every command takes `--root NAME=path` (repeatable, for several repositories) and `--specs <dir>` (default `openspec/specs`).
16
17
 
@@ -49,19 +50,23 @@ The exact rule behind each kind is in [contract.md](references/contract.md#kinds
49
50
 
50
51
  ## Audit
51
52
 
52
- Local only, on the owner's request — CI runs this skill's `check` (inside `spec-tools gates`), `coverage` and `evidence`, never the audit. Corpus-wide or affected-set, for corpus quality: placement, REQUIRED versus ⚠️ ADVISORY, evidence. It runs on the engine `spec-verify` runs on — `spec-tools audit --audit spec-steward` — with this skill's [worker contract](references/worker.md) and [sweeps](sweeps.json). Pass the owner's earlier decisions with `--context <file>`. The procedure around it is [references/audit.md](references/audit.md). The output is a review file in the format of [references/review-format.md](references/review-format.md), and nothing in the specs or the code changes until the owner answers it.
53
+ Local only, on the owner's request — CI runs this skill's `check` (inside `spec-tools gates`), `coverage` and `evidence`, never the audit. Corpus-wide or affected-set, for corpus quality: placement, REQUIRED versus ⚠️ ADVISORY, evidence. It runs on the engine `spec-verify` runs on — `spec-tools audit --audit spec-steward` — with this skill's [worker contract](references/worker.md) and [sweeps](sweeps.json). Pass the owner's earlier decisions with `--context <file>`. The procedure around it is [references/audit.md](references/audit.md). The output is the YAML review file `.spec-audit/spec-review.yaml`, in the format of [references/review-format.md](references/review-format.md). Nothing in the specs or the code changes until the owner answers it.
53
54
 
54
55
  ## Apply
55
56
 
56
- The owner answers each item in the review file. [references/apply.md](references/apply.md) processes the answers round by round:
57
+ The owner answers each item in the review file, in its `decision`. [references/apply.md](references/apply.md) processes the answers round by round:
57
58
 
58
59
  - apply ✅
59
60
  - respect ❌
60
- - investigate a bare comment
61
- - re-audit what changed
62
- - append new items
61
+ - examine a comment again
62
+ - audit again what changed
63
+ - add new items
63
64
 
64
- `steward review status` shows what is open.
65
+ `steward review status <review.yaml>` shows what is open.
66
+
67
+ ## Language
68
+
69
+ Write review items, finding details, verdict reasons and messages to the owner in ASD-STE100 ([common rules](../spec-tools/references/rules/common.md#language)).
65
70
 
66
71
  ## Align
67
72
 
@@ -1,18 +1,18 @@
1
1
  # Apply a review round
2
2
 
3
- The owner has answered a review file ([review-format.md](review-format.md)). Process every item. Leave nothing half-done, and decide nothing on the owner's behalf.
3
+ The owner has answered a review file ([review-format.md](review-format.md)). Process each item. Do each one fully, and decide nothing for the owner.
4
4
 
5
- 1. **Read the whole file again.** Then run `steward review status <review.md>`, which lists the open items, the comments, the accepted-but-not-applied items and the member comments of themes.
6
- 2. **Accepted (`✅`, `✅ <comment>`).** Apply the proposal, adjusted by the comment.
7
- - Before you touch a requirement, read the requirements that name it and that it names, and the code and tests involved. A fix must not break a sibling.
8
- - A rule shared by several repositories changes identically in each; `steward align` shows the drift.
9
- - When a change moves guidance to a new place, put it in the place `rules/agent.md` assigns, remove every copy, and reference it from where it used to live.
10
- - Add `Applied: R<n> — <what changed>` under the item.
11
- 3. **Rejected (`❌`, `❌ <comment>`).** Keep the rule as it is, or follow the owner's alternative instruction, and record what was done.
12
- 4. **Comment only.** Investigate further and revise the proposal or the explanation in place. Move the owner's comment into `Previous response (R<n>): …` and reset the response to `⬜`. Never read a comment as acceptance.
13
- 5. **Theme with member comments.** Apply the theme's verdict to the members without comments. Handle each commented member by its comment, as above.
14
- 6. **Re-audit what changed.** Run the audit ([audit.md](audit.md)) over the affected set: the capabilities you edited, those that name them, and the moved guidance. Then run the repository's spec gate (`AGENTS.md` → Checks), or `steward check --base auto` where it names none. Append new findings under `## Round <n> — new`.
15
- 7. **Verify.** Run the repository's own checks, as its `AGENTS.md` lists them, plus `steward review lint` and `steward review verify`. Report what failed or was skipped, with the reason.
16
- 8. **Stop** while any item is open or carries an unresolved comment. Report the file, the counts and the decisions still needed. The loop ends only when every item is resolved, the accepted changes are in place, the repositories agree on shared rules, and a focused re-audit finds nothing material.
5
+ 1. **Read the full file again.** Then run `steward review status <review.yaml>`. It lists the open items, the comments, and the accepted items that are not applied.
6
+ 2. **Accepted (`✅`, `✅ <comment>`).** Apply the proposal, changed as the comment tells.
7
+ - Before you change a requirement, read the requirements that name it and that it names, and the code and tests involved. A fix must not break a sibling.
8
+ - A rule that several repositories share changes identically in each. `steward align` shows the drift.
9
+ - When a change moves guidance to a new place, put it where `rules/agent.md` tells, remove each copy, and reference it from its old place.
10
+ - Add `applied: "R<round> — <what changed, with paths>"` to the item. A second application makes `applied` a list.
11
+ 3. **Rejected (`❌`, `❌ <comment>`).** Keep the rule as it is, or follow the owner's other instruction. Record what you did in `applied`.
12
+ 4. **Comment only.** Examine the item again, and change the proposal or the explanation in place. Move the owner's comment into `previousDecision: "R<n>: <comment>"` and set `decision` to `""`. A comment is never acceptance.
13
+ 5. **Theme with member decisions.** Apply the theme's decision to the members with no `decision` of their own. Do each member that has one as its decision tells, as above.
14
+ 6. **Audit again what changed.** Run the audit ([audit.md](audit.md)) over the affected set: the capabilities you changed, the capabilities that name them, and the moved guidance. Then run the repository's spec gate (`AGENTS.md` → Checks), or `steward check --base auto` when it names none. Add the new findings with `steward review render <data> --out <review.yaml> --append --round <n>`.
15
+ 7. **Verify.** Run the repository's checks, as its `AGENTS.md` lists them, plus `steward review lint` and `steward review verify`. Report each check that failed or that you did not run, with the reason.
16
+ 8. **Stop** while an item is open or has an unresolved comment. Report the file, the counts and the decisions that are necessary. The loop ends only when each item is resolved, the accepted changes are in place, the repositories agree on shared rules, and a focused audit finds nothing important.
17
17
 
18
- Never commit unless the repository's instructions say you may.
18
+ Do not commit unless the repository's instructions let you.