@kirill.konshin/lint 0.5.1 → 0.5.3

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.
Files changed (30) hide show
  1. package/README.md +6 -4
  2. package/dist/lintPrepare.d.ts +32 -31
  3. package/dist/lintPrepare.d.ts.map +1 -1
  4. package/dist/lintPrepare.js +261 -125
  5. package/package.json +5 -3
  6. package/rules/agent.md +42 -36
  7. package/rules/openspec.md +12 -0
  8. package/rules/testing.md +1 -0
  9. package/skills/lint-repo.md +2 -2
  10. package/skills/spec-steward/SKILL.md +76 -0
  11. package/skills/spec-steward/references/apply.md +18 -0
  12. package/skills/spec-steward/references/audit.md +57 -0
  13. package/skills/spec-steward/references/contract.md +186 -0
  14. package/skills/spec-steward/references/criteria.md +59 -0
  15. package/skills/spec-steward/references/model.md +71 -0
  16. package/skills/spec-steward/references/review-format.md +61 -0
  17. package/skills/spec-steward/references/wiring.md +19 -0
  18. package/skills/spec-steward/scripts/lib/align.mjs +126 -0
  19. package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
  20. package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
  21. package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
  22. package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
  23. package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
  24. package/skills/spec-steward/scripts/lib/git.mjs +138 -0
  25. package/skills/spec-steward/scripts/lib/review.mjs +347 -0
  26. package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
  27. package/skills/spec-steward/scripts/lib/util.mjs +161 -0
  28. package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
  29. package/skills/spec-steward/scripts/steward.mjs +350 -0
  30. package/skills/spec-steward/workflows/audit.js +539 -0
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
- - Symlinks every `rules/*.md` into `.claude/rules/` (auto-discovered by Claude Code) and `.codex/rules/`.
333
- - Symlinks every skill into `.claude/skills/<name>/` and `.codex/skills/<name>/` (`SKILL.md` plus this `README.md` alongside it, so a skill can reference `@README.md`) — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules.
334
- - Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — per rule a `## <Title>` (from the file name), its frontmatter `description` and an `@path` to the rule file, relative to the project root from the package's real (symlink-resolved) location — and symlinks `CLAUDE.md` to it.
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
- `init`/`update` refuse to run if `.claude/rules`, `.codex/rules`, a skill target dir, or `CLAUDE.md` contains anything that isn't a symlink — this avoids silently overwriting files you created by hand. Codex command policies (`.codex/rules/*.rules`) are left alone. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
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
 
@@ -2,11 +2,13 @@
2
2
  /**
3
3
  * @kirill.konshin/lint
4
4
  *
5
- * This script symlinks all markdown rule files from the package into the consuming
6
- * project's `.claude/rules` (auto-discovered by Claude Code) and `.codex/rules` directories,
7
- * symlinks every package skill into `.claude/skills/<name>/` and `.codex/skills/<name>/`
8
- * (SKILL.md plus the package README.md alongside it, so a skill can reference `@README.md`),
9
- * and generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
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`; a folder skill with every file it ships) go into all three, pointing straight
9
+ * at the installed
10
+ * package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
11
+ * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
10
12
  *
11
13
  * Usage:
12
14
  * lint-prepare init - Initialize AGENTS.md in the current directory (default)
@@ -25,6 +27,7 @@ type Rule = {
25
27
  type Skill = {
26
28
  file: string;
27
29
  name: string;
30
+ folder?: boolean;
28
31
  };
29
32
  type ExistingFile = {
30
33
  exists: boolean;
@@ -36,24 +39,28 @@ type ExistingFile = {
36
39
  */
37
40
  export declare function readRules(): Rule[];
38
41
  /**
39
- * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
40
- * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
42
+ * Read the package skills directory. A markdown file becomes its own skill, named after the file (without extension)
43
+ * - e.g. `lint-repo.md` becomes the `lint-repo` skill; a directory holding a `SKILL.md` is a folder skill named after
44
+ * the directory, shipped with its scripts and references.
41
45
  */
42
46
  export declare function readSkills(): Skill[];
43
47
  /**
44
- * Fail if `.claude/rules` or `.codex/rules` contains anything that isn't a symlink - we don't want to
45
- * silently blow away a real file/directory a user placed there by hand. Codex command policies
46
- * (`*.rules`) are not ours and are left alone.
48
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `skills/<name>/SKILL.md` plus the
49
+ * package README.md next to it, so a skill can reference `@README.md`, and every file of a folder skill at its own
50
+ * relative path.
47
51
  */
48
- export declare function checkRulesDirSafety(rulesTargetDir: string): void;
52
+ export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string, string>;
49
53
  /**
50
- * Fail if `CLAUDE.md` exists and isn't a symlink - same reasoning as checkRulesDirSafety.
54
+ * The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
55
+ * except the package links (and dotfiles).
51
56
  */
52
- export declare function checkClaudeMdSafety(claudeMdPath: string): void;
57
+ export declare function readUserFiles(cwd: string): Map<string, string>;
53
58
  /**
54
- * Symlink rules into the consuming project's `.claude/rules` and `.codex/rules` directories.
55
- * Safe to clear and recreate: checkRulesDirSafety already guaranteed every existing
56
- * entry except Codex command policies (kept) is a symlink.
59
+ * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
60
+ * package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
61
+ * `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
62
+ * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
63
+ * records them (and keeps them out of git, so the user's own files there stay tracked).
57
64
  *
58
65
  * FIXME Codex Includes
59
66
  * https://github.com/openai/codex/issues/17401
@@ -64,35 +71,29 @@ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
64
71
  * (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
65
72
  * indexed anywhere).
66
73
  */
67
- export declare function symlinkRules(cwd: string, rules: Rule[]): string[];
74
+ export declare function syncAgentDirs(cwd: string, packageFiles: Map<string, string>, userFiles: Map<string, string>): void;
68
75
  /**
69
- * Fail if a skill's target directory (e.g. `.claude/skills/lint-repo`) contains anything
70
- * that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
71
- * own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
72
- * parent, since other packages (or the user) may keep unrelated skills there.
76
+ * Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
73
77
  */
74
- export declare function checkSkillDirSafety(skillDir: string): void;
78
+ export declare function installedRules(rules: Rule[], userFiles: Map<string, string>): Rule[];
75
79
  /**
76
- * Symlink each package skill into `<cwd>/.claude/skills/<name>/` and
77
- * `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
78
- * them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
79
- * via `@README.md` regardless of how the tool resolves relative mentions.
80
+ * Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
80
81
  */
81
- export declare function symlinkSkills(cwd: string, skills: Skill[]): string[];
82
+ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
82
83
  /**
83
84
  * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
84
85
  */
85
86
  export declare function symlinkClaudeMd(cwd: string): void;
86
87
  /**
87
- * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file with its
88
- * frontmatter `description` and a reference to the file.
88
+ * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
89
+ * and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
89
90
  *
90
- * `.claude/rules/*.md` are symlinked by symlinkRules() above and auto-discovered by
91
+ * `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
91
92
  * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
92
93
  * under `.claude/rules`, symlinks included) - no reference to them is needed here.
93
94
  * The sections below are for other tools that only read AGENTS.md.
94
95
  */
95
- export declare function generateAgentsFile(rules: Rule[], cwd: string, customSection: string | null): string;
96
+ export declare function generateAgentsFile(rules: Rule[], customSection: string | null): string;
96
97
  /**
97
98
  * Check if AGENTS.md exists and was generated by this tool. When it was, also return
98
99
  * 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;;;;;;;;;;;;;;;;GAgBG;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;AAiD1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAyBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAYhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAkBjE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAY1D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,CA2BpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAwBnG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CA0D3B"}
1
+ {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;GAkBG;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,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAC9D,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;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAcpC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqBhF;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"}