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