@kirill.konshin/lint 0.5.0 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -4
- package/dist/lintPrepare.d.ts +27 -27
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +267 -104
- package/package.json +3 -2
- package/rules/agent.md +123 -0
- package/rules/auth.md +1 -1
- package/rules/code-style.md +1 -1
- package/rules/db.md +9 -3
- package/rules/electron.md +1 -1
- package/rules/i18n.md +1 -1
- package/rules/jest.md +1 -0
- package/rules/nx.md +1 -1
- package/rules/turbo.md +1 -1
- package/rules/typescript.md +1 -1
- package/skills/lint-repo.md +2 -2
package/README.md
CHANGED
|
@@ -329,13 +329,15 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
|
|
|
329
329
|
|
|
330
330
|
In the project root, `lint-prepare`:
|
|
331
331
|
|
|
332
|
-
-
|
|
333
|
-
-
|
|
334
|
-
-
|
|
332
|
+
- Creates real `rules/`, `commands/` and `skills/` directories in `.agents/` (canonical, cross-tool), `.claude/` (Claude Code) and `.codex/`, and only ever symlinks files into them.
|
|
333
|
+
- Links every `rules/*.md` and skill (`skills/<name>/SKILL.md` plus this `README.md` alongside it, so a skill can reference `@README.md`) into all three — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules. Links point straight at the installed package's real location (`node_modules/@kirill.konshin/lint`, or the workspace package).
|
|
334
|
+
- Mirrors your own files from `.agents/{rules,commands,skills}/` into `.claude/` and `.codex/`; a file of yours wins over the package file at the same path.
|
|
335
|
+
- Removes dead links (e.g. after renaming a file) and the links it placed before but no longer needs. Each directory gets a generated `.gitignore` listing its links, so your own files stay tracked.
|
|
336
|
+
- Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — per rule (the package's and yours) a `## <Title>` (from the file name), its frontmatter `description` and an `@path` to its `.agents/rules/<file>` entry — and symlinks `CLAUDE.md` to it.
|
|
335
337
|
|
|
336
338
|
### Safety checks
|
|
337
339
|
|
|
338
|
-
`
|
|
340
|
+
Only the files `lint-prepare` knows (package files and mirrors of yours) and dead links are touched: real files are never overwritten (e.g. your own `.claude/rules/*.md`, Codex command policies in `.codex/rules/*.rules`) and nothing is written through a symlinked directory. `init`/`update` refuse to run if `CLAUDE.md` isn't a symlink. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
|
|
339
341
|
|
|
340
342
|
## Migration
|
|
341
343
|
|
package/dist/lintPrepare.d.ts
CHANGED
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
|
-
* This script
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
5
|
+
* This script makes `rules`, `commands` and `skills` real directories in the consuming project's
|
|
6
|
+
* `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
|
|
7
|
+
* file symlinks only: package rules and skills (SKILL.md plus the package README.md alongside it,
|
|
8
|
+
* so a skill can reference `@README.md`) go into all three, pointing straight at the installed
|
|
9
|
+
* package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
|
|
10
|
+
* generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
10
11
|
*
|
|
11
12
|
* Usage:
|
|
12
13
|
* lint-prepare init - Initialize AGENTS.md in the current directory (default)
|
|
@@ -19,6 +20,7 @@
|
|
|
19
20
|
type Rule = {
|
|
20
21
|
file: string;
|
|
21
22
|
name: string;
|
|
23
|
+
description?: string;
|
|
22
24
|
content: string;
|
|
23
25
|
};
|
|
24
26
|
type Skill = {
|
|
@@ -40,18 +42,21 @@ export declare function readRules(): Rule[];
|
|
|
40
42
|
*/
|
|
41
43
|
export declare function readSkills(): Skill[];
|
|
42
44
|
/**
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
+
* Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and `skills/<name>/SKILL.md` plus
|
|
46
|
+
* the package README.md next to it, so a skill can reference `@README.md`.
|
|
45
47
|
*/
|
|
46
|
-
export declare function
|
|
48
|
+
export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string, string>;
|
|
47
49
|
/**
|
|
48
|
-
*
|
|
50
|
+
* The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
|
|
51
|
+
* except the package links (and dotfiles).
|
|
49
52
|
*/
|
|
50
|
-
export declare function
|
|
53
|
+
export declare function readUserFiles(cwd: string): Map<string, string>;
|
|
51
54
|
/**
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
+
* Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
|
|
56
|
+
* package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
|
|
57
|
+
* `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
|
|
58
|
+
* removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
|
|
59
|
+
* records them (and keeps them out of git, so the user's own files there stay tracked).
|
|
55
60
|
*
|
|
56
61
|
* FIXME Codex Includes
|
|
57
62
|
* https://github.com/openai/codex/issues/17401
|
|
@@ -62,34 +67,29 @@ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
|
|
|
62
67
|
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
63
68
|
* indexed anywhere).
|
|
64
69
|
*/
|
|
65
|
-
export declare function
|
|
70
|
+
export declare function syncAgentDirs(cwd: string, packageFiles: Map<string, string>, userFiles: Map<string, string>): void;
|
|
66
71
|
/**
|
|
67
|
-
*
|
|
68
|
-
* that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
|
|
69
|
-
* own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
|
|
70
|
-
* parent, since other packages (or the user) may keep unrelated skills there.
|
|
72
|
+
* Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
|
|
71
73
|
*/
|
|
72
|
-
export declare function
|
|
74
|
+
export declare function installedRules(rules: Rule[], userFiles: Map<string, string>): Rule[];
|
|
73
75
|
/**
|
|
74
|
-
*
|
|
75
|
-
* `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
|
|
76
|
-
* them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
|
|
77
|
-
* via `@README.md` regardless of how the tool resolves relative mentions.
|
|
76
|
+
* Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
|
|
78
77
|
*/
|
|
79
|
-
export declare function
|
|
78
|
+
export declare function checkClaudeMdSafety(claudeMdPath: string): void;
|
|
80
79
|
/**
|
|
81
80
|
* Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
|
|
82
81
|
*/
|
|
83
82
|
export declare function symlinkClaudeMd(cwd: string): void;
|
|
84
83
|
/**
|
|
85
|
-
* Generate AGENTS.md with
|
|
84
|
+
* Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
|
|
85
|
+
* and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
|
|
86
86
|
*
|
|
87
|
-
* `.claude/rules/*.md` are symlinked by
|
|
87
|
+
* `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
|
|
88
88
|
* Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
|
|
89
89
|
* under `.claude/rules`, symlinks included) - no reference to them is needed here.
|
|
90
90
|
* The sections below are for other tools that only read AGENTS.md.
|
|
91
91
|
*/
|
|
92
|
-
export declare function generateAgentsFile(rules: Rule[],
|
|
92
|
+
export declare function generateAgentsFile(rules: Rule[], customSection: string | null): string;
|
|
93
93
|
/**
|
|
94
94
|
* Check if AGENTS.md exists and was generated by this tool. When it was, also return
|
|
95
95
|
* whatever follows the marker (the user's custom section) so it can be carried forward -
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA
|
|
1
|
+
{"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;GAiBG;AAUH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5C,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AA8M1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAmBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAchF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkClH;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAYpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAsBtF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAmD3B"}
|
package/dist/lintPrepare.js
CHANGED
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
|
-
* This script
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
5
|
+
* This script makes `rules`, `commands` and `skills` real directories in the consuming project's
|
|
6
|
+
* `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
|
|
7
|
+
* file symlinks only: package rules and skills (SKILL.md plus the package README.md alongside it,
|
|
8
|
+
* so a skill can reference `@README.md`) go into all three, pointing straight at the installed
|
|
9
|
+
* package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
|
|
10
|
+
* generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
10
11
|
*
|
|
11
12
|
* Usage:
|
|
12
13
|
* lint-prepare init - Initialize AGENTS.md in the current directory (default)
|
|
@@ -19,15 +20,23 @@
|
|
|
19
20
|
import fs from 'node:fs';
|
|
20
21
|
import path from 'node:path';
|
|
21
22
|
import { fileURLToPath } from 'node:url';
|
|
23
|
+
import { parse } from 'yaml';
|
|
22
24
|
const __filename = fileURLToPath(import.meta.url);
|
|
23
25
|
const __dirname = path.dirname(__filename);
|
|
24
26
|
const AGENTS_FILE = 'AGENTS.md';
|
|
25
27
|
const CLAUDE_FILE = 'CLAUDE.md';
|
|
26
|
-
const CLAUDE_RULES_DIR = '.claude/rules';
|
|
27
28
|
const RULES_DIR = path.join(__dirname, '../rules');
|
|
28
29
|
const SKILLS_DIR = path.join(__dirname, '../skills');
|
|
29
30
|
const README_FILE = path.join(__dirname, '../README.md');
|
|
30
|
-
|
|
31
|
+
// `.agents` is the cross-tool location (Codex, Cursor, Antigravity) holding the package links and the user's own
|
|
32
|
+
// files, the latter are mirrored into `.claude` (Claude Code reads nothing else) and `.codex`
|
|
33
|
+
const CANONICAL_AGENT_DIR = '.agents';
|
|
34
|
+
const MIRROR_AGENT_DIRS = ['.claude', '.codex'];
|
|
35
|
+
const AGENT_DIRS = [CANONICAL_AGENT_DIR, ...MIRROR_AGENT_DIRS];
|
|
36
|
+
const AGENT_KINDS = ['rules', 'commands', 'skills'];
|
|
37
|
+
const GITIGNORE = '.gitignore';
|
|
38
|
+
const GITIGNORE_HEADER = '# Generated by @kirill.konshin/lint: symlinks it manages here, your own files stay tracked';
|
|
39
|
+
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
|
|
31
40
|
const HEADER = `# AI Agent Rules
|
|
32
41
|
|
|
33
42
|
This file is auto-generated by @kirill.konshin/lint. Do not edit directly - customize by adding your own rules below the generated section.
|
|
@@ -39,6 +48,156 @@ const FOOTER = `---
|
|
|
39
48
|
|
|
40
49
|
Add your project-specific rules below the comment line.`;
|
|
41
50
|
const GENERATED_MARKER = '<!-- @kirill.konshin/lint:generated -->';
|
|
51
|
+
const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
|
|
52
|
+
/**
|
|
53
|
+
* `monorepo-turbo-nx` -> `Monorepo turbo nx`
|
|
54
|
+
*/
|
|
55
|
+
const toTitle = (name) => {
|
|
56
|
+
const title = name.replaceAll('-', ' ');
|
|
57
|
+
return title.charAt(0).toUpperCase() + title.slice(1);
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* The `description` field of a rule's YAML frontmatter.
|
|
61
|
+
*/
|
|
62
|
+
const readDescription = (content) => {
|
|
63
|
+
const frontmatter = FRONTMATTER.exec(content)?.[1];
|
|
64
|
+
const description = frontmatter ? parse(frontmatter)?.description : undefined;
|
|
65
|
+
return typeof description === 'string' ? description.trim() : undefined;
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* `file` is the path inside a rules dir, e.g. `auth.md` or `frontend/react.md`.
|
|
69
|
+
*/
|
|
70
|
+
const toRule = (file, content) => ({
|
|
71
|
+
file,
|
|
72
|
+
name: path.posix.basename(file, '.md'),
|
|
73
|
+
description: readDescription(content),
|
|
74
|
+
content,
|
|
75
|
+
});
|
|
76
|
+
/**
|
|
77
|
+
* Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
|
|
78
|
+
* directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
|
|
79
|
+
*/
|
|
80
|
+
function listRealFiles(root, dir = root) {
|
|
81
|
+
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
82
|
+
const entryPath = path.join(dir, entry.name);
|
|
83
|
+
if (entry.name.startsWith('.'))
|
|
84
|
+
return [];
|
|
85
|
+
if (entry.isDirectory())
|
|
86
|
+
return listRealFiles(root, entryPath);
|
|
87
|
+
return entry.isFile() ? [path.relative(root, entryPath)] : [];
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Dead symlinks under `dir`, walking real directories only.
|
|
92
|
+
*/
|
|
93
|
+
function findDeadLinks(dir) {
|
|
94
|
+
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
95
|
+
const entryPath = path.join(dir, entry.name);
|
|
96
|
+
if (entry.isDirectory())
|
|
97
|
+
return findDeadLinks(entryPath);
|
|
98
|
+
return entry.isSymbolicLink() && !fs.existsSync(entryPath) ? [entryPath] : [];
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Remove `link` and the directories it leaves empty, up to `root`.
|
|
103
|
+
*/
|
|
104
|
+
function removeLink(link, root) {
|
|
105
|
+
fs.unlinkSync(link);
|
|
106
|
+
for (let dir = path.dirname(link); dir !== root && !fs.readdirSync(dir).length; dir = path.dirname(dir)) {
|
|
107
|
+
fs.rmdirSync(dir);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* mkdir -p `dir` (relative to cwd, starting with an agent dir, which itself may be a link) without going through
|
|
112
|
+
* links below it: false when a part is a symlink or a file - those are the user's, nothing is written through them.
|
|
113
|
+
*/
|
|
114
|
+
function ensureRealDir(cwd, dir) {
|
|
115
|
+
const [agentDir, ...parts] = dir.split(path.sep);
|
|
116
|
+
let current = path.join(cwd, agentDir);
|
|
117
|
+
fs.mkdirSync(current, { recursive: true });
|
|
118
|
+
for (const part of parts) {
|
|
119
|
+
current = path.join(current, part);
|
|
120
|
+
const stat = lstat(current);
|
|
121
|
+
if (!stat)
|
|
122
|
+
fs.mkdirSync(current);
|
|
123
|
+
else if (!stat.isDirectory())
|
|
124
|
+
return false;
|
|
125
|
+
}
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Point `link` (relative to cwd) at `target`, unless the spot is the user's: a real file there, or a linked
|
|
130
|
+
* directory on the way. Returns whether the link is in place.
|
|
131
|
+
*/
|
|
132
|
+
function placeLink(cwd, link, target) {
|
|
133
|
+
const linkPath = path.join(cwd, link);
|
|
134
|
+
if (!ensureRealDir(cwd, path.dirname(link))) {
|
|
135
|
+
console.log(`Skipped ${link}: ${path.dirname(link)} is not a real directory`);
|
|
136
|
+
return false;
|
|
137
|
+
}
|
|
138
|
+
const stat = lstat(linkPath);
|
|
139
|
+
if (stat && !stat.isSymbolicLink()) {
|
|
140
|
+
console.log(`Kept ${link}: not a symlink`);
|
|
141
|
+
return false;
|
|
142
|
+
}
|
|
143
|
+
// relative between REAL locations: cwd and the package (workspaces, yalc, pnpm store) may be reached through
|
|
144
|
+
// symlinks, and a path computed between a symlinked and a real location dangles
|
|
145
|
+
const text = path.relative(fs.realpathSync(path.dirname(linkPath)), target);
|
|
146
|
+
if (stat && fs.readlinkSync(linkPath) === text)
|
|
147
|
+
return true;
|
|
148
|
+
if (stat)
|
|
149
|
+
fs.unlinkSync(linkPath);
|
|
150
|
+
fs.symlinkSync(text, linkPath);
|
|
151
|
+
return true;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Links listed in a `.gitignore` this tool generated - it doubles as the record of what to clean up next time.
|
|
155
|
+
*/
|
|
156
|
+
function readManifest(gitignore) {
|
|
157
|
+
const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf-8') : '';
|
|
158
|
+
if (!content.startsWith(GITIGNORE_HEADER))
|
|
159
|
+
return [];
|
|
160
|
+
return content
|
|
161
|
+
.split('\n')
|
|
162
|
+
.filter((line) => line.startsWith('/') && line !== `/${GITIGNORE}`)
|
|
163
|
+
.map((line) => path.normalize(line.slice(1)));
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Write the `.gitignore` listing `links` (remove it when there are none), unless the user owns that file.
|
|
167
|
+
*/
|
|
168
|
+
function writeManifest(gitignore, links) {
|
|
169
|
+
const exists = fs.existsSync(gitignore);
|
|
170
|
+
if (exists && !fs.readFileSync(gitignore, 'utf-8').startsWith(GITIGNORE_HEADER))
|
|
171
|
+
return;
|
|
172
|
+
if (!links.length) {
|
|
173
|
+
if (exists)
|
|
174
|
+
fs.unlinkSync(gitignore);
|
|
175
|
+
return;
|
|
176
|
+
}
|
|
177
|
+
const entries = links.map((link) => `/${link.split(path.sep).join('/')}`).sort();
|
|
178
|
+
fs.writeFileSync(gitignore, [GITIGNORE_HEADER, `/${GITIGNORE}`, ...entries, ''].join('\n'));
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Links to place, keyed by their path relative to cwd: package files into every agent dir, the user's own `.agents`
|
|
182
|
+
* files into the mirrors. A user file wins over the package file at the same path.
|
|
183
|
+
*/
|
|
184
|
+
function plannedLinks(cwd, packageFiles, userFiles) {
|
|
185
|
+
const canonicalDir = path.join(fs.realpathSync(cwd), CANONICAL_AGENT_DIR);
|
|
186
|
+
const links = new Map();
|
|
187
|
+
for (const [file, source] of packageFiles) {
|
|
188
|
+
if (userFiles.has(file)) {
|
|
189
|
+
console.log(`${path.join(CANONICAL_AGENT_DIR, file)} overrides the package file`);
|
|
190
|
+
continue;
|
|
191
|
+
}
|
|
192
|
+
for (const dir of AGENT_DIRS)
|
|
193
|
+
links.set(path.join(dir, file), fs.realpathSync(source));
|
|
194
|
+
}
|
|
195
|
+
for (const file of userFiles.keys()) {
|
|
196
|
+
for (const dir of MIRROR_AGENT_DIRS)
|
|
197
|
+
links.set(path.join(dir, file), path.join(canonicalDir, file));
|
|
198
|
+
}
|
|
199
|
+
return links;
|
|
200
|
+
}
|
|
42
201
|
/**
|
|
43
202
|
* Read all markdown files from the package rules directory.
|
|
44
203
|
*/
|
|
@@ -54,12 +213,7 @@ export function readRules() {
|
|
|
54
213
|
.sort();
|
|
55
214
|
for (const file of files) {
|
|
56
215
|
const filePath = path.join(RULES_DIR, file);
|
|
57
|
-
|
|
58
|
-
rules.push({
|
|
59
|
-
file,
|
|
60
|
-
name: file.replace('.md', ''),
|
|
61
|
-
content,
|
|
62
|
-
});
|
|
216
|
+
rules.push(toRule(file, fs.readFileSync(filePath, 'utf-8')));
|
|
63
217
|
}
|
|
64
218
|
return rules;
|
|
65
219
|
}
|
|
@@ -77,42 +231,44 @@ export function readSkills() {
|
|
|
77
231
|
.map((file) => ({ file, name: file.replace('.md', '') }));
|
|
78
232
|
}
|
|
79
233
|
/**
|
|
80
|
-
*
|
|
81
|
-
*
|
|
234
|
+
* Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and `skills/<name>/SKILL.md` plus
|
|
235
|
+
* the package README.md next to it, so a skill can reference `@README.md`.
|
|
82
236
|
*/
|
|
83
|
-
export function
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
for (const
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
237
|
+
export function packageFiles(rules, skills) {
|
|
238
|
+
const files = new Map();
|
|
239
|
+
const hasReadme = fs.existsSync(README_FILE);
|
|
240
|
+
for (const rule of rules) {
|
|
241
|
+
files.set(path.join('rules', rule.file), path.join(RULES_DIR, rule.file));
|
|
242
|
+
}
|
|
243
|
+
for (const skill of skills) {
|
|
244
|
+
files.set(path.join('skills', skill.name, 'SKILL.md'), path.join(SKILLS_DIR, skill.file));
|
|
245
|
+
if (hasReadme)
|
|
246
|
+
files.set(path.join('skills', skill.name, 'README.md'), README_FILE);
|
|
93
247
|
}
|
|
248
|
+
return files;
|
|
94
249
|
}
|
|
95
250
|
/**
|
|
96
|
-
*
|
|
251
|
+
* The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
|
|
252
|
+
* except the package links (and dotfiles).
|
|
97
253
|
*/
|
|
98
|
-
export function
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
|
|
108
|
-
console.error('Remove or back it up manually, then re-run.');
|
|
109
|
-
process.exit(1);
|
|
254
|
+
export function readUserFiles(cwd) {
|
|
255
|
+
const files = new Map();
|
|
256
|
+
for (const kind of AGENT_KINDS) {
|
|
257
|
+
const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
|
|
258
|
+
if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory())
|
|
259
|
+
continue;
|
|
260
|
+
for (const file of listRealFiles(root)) {
|
|
261
|
+
files.set(path.join(kind, file), path.join(root, file));
|
|
262
|
+
}
|
|
110
263
|
}
|
|
264
|
+
return files;
|
|
111
265
|
}
|
|
112
266
|
/**
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
267
|
+
* Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
|
|
268
|
+
* package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
|
|
269
|
+
* `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
|
|
270
|
+
* removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
|
|
271
|
+
* records them (and keeps them out of git, so the user's own files there stay tracked).
|
|
116
272
|
*
|
|
117
273
|
* FIXME Codex Includes
|
|
118
274
|
* https://github.com/openai/codex/issues/17401
|
|
@@ -123,61 +279,65 @@ export function checkClaudeMdSafety(claudeMdPath) {
|
|
|
123
279
|
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
124
280
|
* indexed anywhere).
|
|
125
281
|
*/
|
|
126
|
-
export function
|
|
127
|
-
const
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
282
|
+
export function syncAgentDirs(cwd, packageFiles, userFiles) {
|
|
283
|
+
const links = plannedLinks(cwd, packageFiles, userFiles);
|
|
284
|
+
for (const dir of AGENT_DIRS) {
|
|
285
|
+
for (const kind of AGENT_KINDS) {
|
|
286
|
+
const root = path.join(dir, kind);
|
|
287
|
+
const rootPath = path.join(cwd, root);
|
|
288
|
+
const gitignore = path.join(rootPath, GITIGNORE);
|
|
289
|
+
if (!ensureRealDir(cwd, root)) {
|
|
290
|
+
console.log(`Skipped ${root}: not a real directory`);
|
|
291
|
+
continue;
|
|
292
|
+
}
|
|
293
|
+
for (const link of findDeadLinks(rootPath)) {
|
|
294
|
+
removeLink(link, rootPath);
|
|
295
|
+
}
|
|
296
|
+
const placed = [];
|
|
297
|
+
for (const [link, target] of links) {
|
|
298
|
+
if (link.startsWith(root + path.sep) && placeLink(cwd, link, target)) {
|
|
299
|
+
placed.push(path.relative(root, link));
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
for (const link of readManifest(gitignore)) {
|
|
303
|
+
const linkPath = path.join(rootPath, link);
|
|
304
|
+
if (!placed.includes(link) && lstat(linkPath)?.isSymbolicLink())
|
|
305
|
+
removeLink(linkPath, rootPath);
|
|
306
|
+
}
|
|
307
|
+
writeManifest(gitignore, placed);
|
|
308
|
+
}
|
|
134
309
|
}
|
|
135
|
-
return targetDir;
|
|
136
310
|
}
|
|
137
311
|
/**
|
|
138
|
-
*
|
|
139
|
-
* that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
|
|
140
|
-
* own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
|
|
141
|
-
* parent, since other packages (or the user) may keep unrelated skills there.
|
|
312
|
+
* Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
|
|
142
313
|
*/
|
|
143
|
-
export function
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
for (const
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
process.exit(1);
|
|
152
|
-
}
|
|
314
|
+
export function installedRules(rules, userFiles) {
|
|
315
|
+
const byFile = new Map(rules.map((rule) => [rule.file, rule]));
|
|
316
|
+
const rulesDir = `rules${path.sep}`;
|
|
317
|
+
for (const [file, source] of userFiles) {
|
|
318
|
+
if (!file.startsWith(rulesDir) || !file.endsWith('.md'))
|
|
319
|
+
continue;
|
|
320
|
+
const ruleFile = file.slice(rulesDir.length).split(path.sep).join('/');
|
|
321
|
+
byFile.set(ruleFile, toRule(ruleFile, fs.readFileSync(source, 'utf-8')));
|
|
153
322
|
}
|
|
323
|
+
return [...byFile].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, rule]) => rule);
|
|
154
324
|
}
|
|
155
325
|
/**
|
|
156
|
-
*
|
|
157
|
-
* `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
|
|
158
|
-
* them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
|
|
159
|
-
* via `@README.md` regardless of how the tool resolves relative mentions.
|
|
326
|
+
* Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
|
|
160
327
|
*/
|
|
161
|
-
export function
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
if (hasReadme) {
|
|
174
|
-
const readmeLink = path.join(skillDir, 'README.md');
|
|
175
|
-
fs.symlinkSync(path.relative(skillDir, README_FILE), readmeLink);
|
|
176
|
-
}
|
|
177
|
-
targetDirs.push(skillDir);
|
|
178
|
-
}
|
|
328
|
+
export function checkClaudeMdSafety(claudeMdPath) {
|
|
329
|
+
let stat;
|
|
330
|
+
try {
|
|
331
|
+
stat = fs.lstatSync(claudeMdPath);
|
|
332
|
+
}
|
|
333
|
+
catch {
|
|
334
|
+
return;
|
|
335
|
+
}
|
|
336
|
+
if (!stat.isSymbolicLink()) {
|
|
337
|
+
console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
|
|
338
|
+
console.error('Remove or back it up manually, then re-run.');
|
|
339
|
+
process.exit(1);
|
|
179
340
|
}
|
|
180
|
-
return targetDirs;
|
|
181
341
|
}
|
|
182
342
|
/**
|
|
183
343
|
* Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
|
|
@@ -188,24 +348,32 @@ export function symlinkClaudeMd(cwd) {
|
|
|
188
348
|
fs.symlinkSync(AGENTS_FILE, claudeMdPath);
|
|
189
349
|
}
|
|
190
350
|
/**
|
|
191
|
-
* Generate AGENTS.md with
|
|
351
|
+
* Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
|
|
352
|
+
* and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
|
|
192
353
|
*
|
|
193
|
-
* `.claude/rules/*.md` are symlinked by
|
|
354
|
+
* `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
|
|
194
355
|
* Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
|
|
195
356
|
* under `.claude/rules`, symlinks included) - no reference to them is needed here.
|
|
196
357
|
* The sections below are for other tools that only read AGENTS.md.
|
|
197
358
|
*/
|
|
198
|
-
export function generateAgentsFile(rules,
|
|
199
|
-
const relativeRulesDir = path.relative(cwd, RULES_DIR).split(path.sep).join('/');
|
|
359
|
+
export function generateAgentsFile(rules, customSection) {
|
|
200
360
|
/**
|
|
201
361
|
* @see https://code.claude.com/docs/en/memory#import-additional-files
|
|
202
362
|
* @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
|
|
203
363
|
* @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
|
|
204
364
|
*/
|
|
205
|
-
const
|
|
206
|
-
|
|
207
|
-
.
|
|
208
|
-
|
|
365
|
+
const sections = rules.map((rule) => {
|
|
366
|
+
// the canonical entry (a package link or the user's own file), not the package install path
|
|
367
|
+
const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
|
|
368
|
+
return [
|
|
369
|
+
`## ${toTitle(rule.name)}`,
|
|
370
|
+
rule.description,
|
|
371
|
+
`See instructions in @${rulePath} [${rulePath}](${rulePath}).`,
|
|
372
|
+
]
|
|
373
|
+
.filter(Boolean)
|
|
374
|
+
.join('\n\n');
|
|
375
|
+
});
|
|
376
|
+
const generated = `${HEADER}\n\n# Rules\n\n${sections.join('\n\n')}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
|
|
209
377
|
return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
|
|
210
378
|
}
|
|
211
379
|
/**
|
|
@@ -233,7 +401,6 @@ export function main() {
|
|
|
233
401
|
const cwd = process.env.INIT_CWD || process.cwd();
|
|
234
402
|
const targetPath = path.join(cwd, AGENTS_FILE);
|
|
235
403
|
const claudeMdPath = path.join(cwd, CLAUDE_FILE);
|
|
236
|
-
const rulesTargetDir = path.join(cwd, CLAUDE_RULES_DIR);
|
|
237
404
|
console.log(`@kirill.konshin/lint: ${command}`);
|
|
238
405
|
console.log(`Target: ${targetPath}`);
|
|
239
406
|
const { exists, generated, customSection } = checkExisting(targetPath);
|
|
@@ -248,19 +415,15 @@ export function main() {
|
|
|
248
415
|
}
|
|
249
416
|
}
|
|
250
417
|
if (command === 'update' || command === 'init') {
|
|
251
|
-
checkRulesDirSafety(rulesTargetDir);
|
|
252
418
|
checkClaudeMdSafety(claudeMdPath);
|
|
253
419
|
const rules = readRules();
|
|
254
420
|
console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(', ')}`);
|
|
255
|
-
const targetRulesDir = symlinkRules(cwd, rules);
|
|
256
|
-
console.log(`Symlinked rules to ${targetRulesDir}`);
|
|
257
421
|
const skills = readSkills();
|
|
258
422
|
console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
|
|
259
|
-
const
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
const content = generateAgentsFile(rules, cwd, customSection);
|
|
423
|
+
const userFiles = readUserFiles(cwd);
|
|
424
|
+
syncAgentDirs(cwd, packageFiles(rules, skills), userFiles);
|
|
425
|
+
console.log(`Synced ${AGENT_DIRS.join(', ')}, mirrored ${userFiles.size} own file(s) from ${CANONICAL_AGENT_DIR}`);
|
|
426
|
+
const content = generateAgentsFile(installedRules(rules, userFiles), customSection);
|
|
264
427
|
fs.writeFileSync(targetPath, content, 'utf-8');
|
|
265
428
|
console.log(`${exists ? 'Updated' : 'Created'} ${AGENTS_FILE}`);
|
|
266
429
|
symlinkClaudeMd(cwd);
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kirill.konshin/lint",
|
|
3
3
|
"description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
|
|
4
|
-
"version": "0.5.
|
|
4
|
+
"version": "0.5.2",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"skipGenerate": true,
|
|
7
7
|
"bin": {
|
|
@@ -73,7 +73,8 @@
|
|
|
73
73
|
"globals": "^17.11.0",
|
|
74
74
|
"jsonc-eslint-parser": "^3.3.0",
|
|
75
75
|
"local-pkg": "^1.2.1",
|
|
76
|
-
"path-scurry": "^2.0.2"
|
|
76
|
+
"path-scurry": "^2.0.2",
|
|
77
|
+
"yaml": "^2.9.0"
|
|
77
78
|
},
|
|
78
79
|
"devDependencies": {
|
|
79
80
|
"@types/eslint-plugin-jsx-a11y": "^6.10.1",
|
package/rules/agent.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: always_apply
|
|
3
|
+
description: Set of rules for agentic coding
|
|
4
|
+
# paths: # removed so ALL agents read it where to find information
|
|
5
|
+
# - '**/*.md'
|
|
6
|
+
# - 'openspec/config.yml'
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
IF IN DOUBT ASK USER!
|
|
10
|
+
|
|
11
|
+
# What Goes Where
|
|
12
|
+
|
|
13
|
+
Use this summarized guidance to consider where to place a set of instructions
|
|
14
|
+
|
|
15
|
+
- `README.md` — human-readable instructions how to work with repo
|
|
16
|
+
- Root `AGENTS.md` — default context for agents, always included
|
|
17
|
+
- Subdirectory `AGENTS.md` — scoped to this particular directory, auto-injected
|
|
18
|
+
- `.agents/rules` — forced rules (or automatic guardrails), that agent will read based on frontmatter, with paths scope; may pollute context if not scoped well; should NOT have detailed guidance, examples, etc.
|
|
19
|
+
- `.agents/skills` — one-off flows, potentially complex; but also sets of rules & instructions that agent may or may not read/follow, good for progressive disclosure, examples, thorough guidance, and something you want to offload from `AGENTS.md` (and cite from it), and has to be well-defined in frontmatter to increase likelihood of success, example: https://www.skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
|
|
20
|
+
- `.agents/commands` — one-off commands, usually simpler than skills
|
|
21
|
+
- `openspec/specs` - SDD specifications, should define user facing behavior or API contracts, not coding instructions / best practices / etc.
|
|
22
|
+
- `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
|
|
23
|
+
- `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
24
|
+
- `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
25
|
+
|
|
26
|
+
# Placement Decision
|
|
27
|
+
|
|
28
|
+
When deciding where information belongs, use this order:
|
|
29
|
+
|
|
30
|
+
1. Is it durable observable system/component behavior?
|
|
31
|
+
- **→ `openspec/specs`**
|
|
32
|
+
2. Must the agent always know it when touching a deterministically identifiable set of files?
|
|
33
|
+
- **→ scoped `.agents/rules`**
|
|
34
|
+
3. Is it mandatory repo-wide or directory-wide context/routing?
|
|
35
|
+
- **→ `AGENTS.md`**
|
|
36
|
+
4. Is it detailed knowledge, guidance, examples, best practices, or a reusable procedure that should be progressively disclosed?
|
|
37
|
+
- **→ skill**
|
|
38
|
+
5. Is it merely supporting material extracted from `AGENTS.md` to reduce default context?
|
|
39
|
+
- **→ skill**, referenced explicitly from `AGENTS.md`
|
|
40
|
+
6. Is it primarily documentation for humans?
|
|
41
|
+
- **→ `README.md`**
|
|
42
|
+
|
|
43
|
+
When correctness depends on an instruction being observed, do NOT rely solely on skill discovery.
|
|
44
|
+
|
|
45
|
+
Prefer one authoritative location for each concern. Reference it elsewhere instead of duplicating it.
|
|
46
|
+
|
|
47
|
+
# `README.md`
|
|
48
|
+
|
|
49
|
+
- Should be targeted to be read by humans
|
|
50
|
+
- First file that's visible to humans
|
|
51
|
+
|
|
52
|
+
# `AGENTS.md`
|
|
53
|
+
|
|
54
|
+
- Root `AGENTS.md`
|
|
55
|
+
- Should be minimalistic
|
|
56
|
+
- Can be decomposed as `skills` & `rules` (with references to them)
|
|
57
|
+
- Such references to skills should be referred conditional, e.g. with minimal explanation when to use so agent has better chances of reaching them
|
|
58
|
+
- Decomposition should be used when
|
|
59
|
+
- Section is narrowly scoped (installation instructions / testing / particular framework or technology) and not always applicable
|
|
60
|
+
- Section is large
|
|
61
|
+
- `AGENTS.md` can refer to `README.md` in order not to restate things
|
|
62
|
+
- Repo-wide convention to use SDD should be defined here to be always visible
|
|
63
|
+
- Focus on mandatory routing and instructions
|
|
64
|
+
- Sub-directory `AGENTS.md`
|
|
65
|
+
- Directory-specific rules & instructions should be in `AGENTS.md` of that folder
|
|
66
|
+
- Lift rules & instructions up the tree to higher `AGENTS.md` if multiple dirs must adhere to them, don't copy-paste them
|
|
67
|
+
- All `AGENTS.md` files should be accompanied by a symlink `CLAUDE.md`
|
|
68
|
+
|
|
69
|
+
# `.agents/rules`
|
|
70
|
+
|
|
71
|
+
- `.agents/rules` must be accompanied by symlinks in `.claude/rules` and `.codex/rules`
|
|
72
|
+
- Files should be scoped to certain paths
|
|
73
|
+
- Files should be small,
|
|
74
|
+
- Examples not allowed in general
|
|
75
|
+
- Should describe only coding conventions, recommendations, forced contextual instructions / automatic guardrails
|
|
76
|
+
- As bullet points
|
|
77
|
+
- Concise, terse and to the point
|
|
78
|
+
- Hard constraints
|
|
79
|
+
- That must appear in scope by `paths` glob
|
|
80
|
+
- Should be cited in `AGENTS.md` to ensure they're discoverable by harnesses that don't support `.xxx/rules` natively
|
|
81
|
+
|
|
82
|
+
# `.agents/skills`
|
|
83
|
+
|
|
84
|
+
- `.agents/skills` must be accompanied by symlinks in `.claude/skills` and `.codex/skills`
|
|
85
|
+
- May define either
|
|
86
|
+
- A workflow
|
|
87
|
+
- A process
|
|
88
|
+
- A set of rules
|
|
89
|
+
- Best practices
|
|
90
|
+
- Examples
|
|
91
|
+
- Engineering knowledge
|
|
92
|
+
- Agent decides to discover it or not, use it or not, so no guarantee of honoring
|
|
93
|
+
- A requirement/rule MUST NOT exist only in a skill if correctness depends on the agent always observing it
|
|
94
|
+
|
|
95
|
+
# `.agents/commands`
|
|
96
|
+
|
|
97
|
+
- `.agents/commands` must be accompanied by symlinks in `.claude/commands` and `.codex/commands`
|
|
98
|
+
- Smaller and simpler than skills
|
|
99
|
+
- One-off commands, not flows
|
|
100
|
+
|
|
101
|
+
# `openspec`
|
|
102
|
+
|
|
103
|
+
- `OpenSpec` / `SpecKit` and similar SDD specifications should define
|
|
104
|
+
- User facing or externally observable behavior
|
|
105
|
+
- Durable component/system/API contracts & invariants
|
|
106
|
+
- Not general coding instructions
|
|
107
|
+
- Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.agents|.claude|.codex]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
|
|
108
|
+
- `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
|
|
109
|
+
- Context will already contain root `AGENTS.md`, no duplication needed
|
|
110
|
+
- `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
|
|
111
|
+
- `openspec/config.yml#operation.[apply|archive].guidance` - very narrow sets of instructions specifically for defined part of the flow when it's entered
|
|
112
|
+
- The two litmus questions:
|
|
113
|
+
- Could the implementation be rewritten substantially and the statement still hold? Then it is SPEC.
|
|
114
|
+
- Could the detail change while the contract stays the same? Then it is not SPEC.
|
|
115
|
+
- Requirements and scenarios should (preferrably) be proven by tests, and may be cited in tests for stronger connection
|
|
116
|
+
- Tests should be validated that they do what spec says (optional, unless project mandates this in root `AGENTS.md`)
|
|
117
|
+
- Code citations must resolve, not checked for validity
|
|
118
|
+
|
|
119
|
+
# Common for `AGENTS.md` `.agents/rules` `.agents/skills`
|
|
120
|
+
|
|
121
|
+
- If project uses Spec Driven Development framework like OpenSpec, these files should be free from product specifications / external behavior, and only focused on general coding instructions
|
|
122
|
+
- Preferred instructions/rules syntax how to structure plain human language: `EARS` for requirements and `BDD` (Given/When/Then) for scenarios
|
|
123
|
+
- Rules & instructions in these files can't be cited from tests or code, so their proof is tooling, never a citation
|
package/rules/auth.md
CHANGED
package/rules/code-style.md
CHANGED
package/rules/db.md
CHANGED
|
@@ -10,8 +10,7 @@ description: Database persistence and migration rules
|
|
|
10
10
|
|
|
11
11
|
# Postgres
|
|
12
12
|
|
|
13
|
-
- Use
|
|
14
|
-
- Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
|
|
13
|
+
- Use Drizzle as ORM if user asks to add ORM
|
|
15
14
|
- Keep schemas, repositories, tenancy, and authorization app-owned; keep reusable driver plumbing in `@kirill.konshin/db`.
|
|
16
15
|
- Import `@kirill.konshin/db` through focused driver, migration, URL, and type subpaths so unrelated drivers are not loaded.
|
|
17
16
|
- Keep database access server-only and separate the database/repository layer from API, UI, and state-management layers.
|
|
@@ -20,9 +19,16 @@ description: Database persistence and migration rules
|
|
|
20
19
|
- Validate inputs at the application boundary and enforce critical invariants again in Postgres.
|
|
21
20
|
- Use `DATABASE_URL` at runtime; prefer `DATABASE_URL_UNPOOLED` for migrations and maintenance when available.
|
|
22
21
|
- Close owned pools in `finally`; do not leak clients or hide ownership of long-lived connections.
|
|
23
|
-
- Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
|
|
24
22
|
- Enforce user and tenant scope on every read and mutation; authentication alone is not authorization.
|
|
25
23
|
- For LocalStorage or IndexedDB migrations, preserve behavior but improve the schema when normalization or consolidation is clearly safer.
|
|
26
24
|
- Make importers transactional, validated, idempotent, and count-verifiable; never delete server data merely because a mutable export became smaller.
|
|
27
25
|
- Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
|
|
28
26
|
- After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
|
|
27
|
+
|
|
28
|
+
# Neon
|
|
29
|
+
|
|
30
|
+
Only applies if user specifically asked to add Neon as DB, or project already uses Neon as DB.
|
|
31
|
+
|
|
32
|
+
- Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
|
|
33
|
+
- Use Neon Postgres with Drizzle and checked-in generated migrations.
|
|
34
|
+
- Fold Neon Auth into [Iron Session](./auth.md): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
|
package/rules/electron.md
CHANGED
package/rules/i18n.md
CHANGED
package/rules/jest.md
CHANGED
|
@@ -7,3 +7,4 @@ paths:
|
|
|
7
7
|
|
|
8
8
|
- Always prefer TS-based config. Choice of loader is dictated by other installed packages, https://jestjs.io/docs/configuration (first tip about loaders)
|
|
9
9
|
- In monorepo define root jest project https://jestjs.io/docs/configuration#projects-arraystring--projectconfig
|
|
10
|
+
- Prefer Vitest instead of Jest
|
package/rules/nx.md
CHANGED
package/rules/turbo.md
CHANGED
package/rules/typescript.md
CHANGED
package/skills/lint-repo.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-repo
|
|
3
|
-
description: Set up/update this repo's ESLint + Prettier + lint-staged + Husky tooling (@kirill.konshin/lint), and/or audit the codebase against the packaged agent rules. Rules are discovered from .
|
|
3
|
+
description: Set up/update this repo's ESLint + Prettier + lint-staged + Husky tooling (@kirill.konshin/lint), and/or audit the codebase against the packaged agent rules. Rules are discovered from .agents/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Lint Repo
|
|
@@ -27,7 +27,7 @@ Check the README's "Issues" section before debugging a lint crash.
|
|
|
27
27
|
|
|
28
28
|
## B. Audit code against rules
|
|
29
29
|
|
|
30
|
-
Rules: `.
|
|
30
|
+
Rules: `.agents/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.md`; plus overrides in `AGENTS.md # Custom Rules` / `CLAUDE.md` (override wins on conflict). Treat rule files as normative — read them directly.
|
|
31
31
|
|
|
32
32
|
### 1. Mechanical pass first
|
|
33
33
|
|