@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/`, `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
@@ -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.5",
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: @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