@kirill.konshin/lint 0.5.2 → 0.5.4

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 (40) hide show
  1. package/README.md +1 -1
  2. package/dist/lintPrepare.d.ts +9 -8
  3. package/dist/lintPrepare.d.ts.map +1 -1
  4. package/dist/lintPrepare.js +20 -14
  5. package/package.json +5 -3
  6. package/rules/github.md +0 -76
  7. package/rules/gitlab.md +0 -72
  8. package/rules/nextjs.md +2 -55
  9. package/rules/openspec.md +12 -0
  10. package/rules/storybook.md +2 -0
  11. package/rules/tailwind.md +1 -1
  12. package/rules/testing.md +1 -0
  13. package/rules/webstorm.md +6 -214
  14. package/skills/lint-github/SKILL.md +78 -0
  15. package/skills/lint-gitlab/SKILL.md +76 -0
  16. package/skills/lint-nextjs/SKILL.md +59 -0
  17. package/skills/{lint-repo.md → lint-repo/SKILL.md} +1 -1
  18. package/skills/lint-webstorm/SKILL.md +201 -0
  19. package/skills/lint-worktree/SKILL.md +28 -0
  20. package/skills/spec-steward/SKILL.md +76 -0
  21. package/skills/spec-steward/references/apply.md +18 -0
  22. package/skills/spec-steward/references/audit.md +57 -0
  23. package/skills/spec-steward/references/contract.md +186 -0
  24. package/skills/spec-steward/references/criteria.md +59 -0
  25. package/skills/spec-steward/references/model.md +71 -0
  26. package/skills/spec-steward/references/review-format.md +61 -0
  27. package/skills/spec-steward/references/wiring.md +19 -0
  28. package/skills/spec-steward/scripts/lib/align.mjs +126 -0
  29. package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
  30. package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
  31. package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
  32. package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
  33. package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
  34. package/skills/spec-steward/scripts/lib/git.mjs +138 -0
  35. package/skills/spec-steward/scripts/lib/review.mjs +347 -0
  36. package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
  37. package/skills/spec-steward/scripts/lib/util.mjs +161 -0
  38. package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
  39. package/skills/spec-steward/scripts/steward.mjs +350 -0
  40. package/skills/spec-steward/workflows/audit.js +539 -0
package/README.md CHANGED
@@ -330,7 +330,7 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
330
330
  In the project root, `lint-prepare`:
331
331
 
332
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).
333
+ - Links every `rules/*.md` and every skill folder (`skills/<name>/` with all its files, plus this `README.md` next to `SKILL.md` unless the skill ships one, so a skill can reference `@README.md`) into all three — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules. Links point straight at the installed package's real location (`node_modules/@kirill.konshin/lint`, or the workspace package).
334
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
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
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.
@@ -4,9 +4,10 @@
4
4
  *
5
5
  * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
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
7
+ * file symlinks only: package rules and skills (every file a skill folder ships, plus the package
8
+ * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into all three, pointing
9
+ * straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`
10
+ * and `.codex`. It also
10
11
  * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
11
12
  *
12
13
  * Usage:
@@ -24,7 +25,6 @@ type Rule = {
24
25
  content: string;
25
26
  };
26
27
  type Skill = {
27
- file: string;
28
28
  name: string;
29
29
  };
30
30
  type ExistingFile = {
@@ -37,13 +37,14 @@ type ExistingFile = {
37
37
  */
38
38
  export declare function readRules(): Rule[];
39
39
  /**
40
- * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
41
- * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
40
+ * Read the package skills directory: every directory holding a `SKILL.md` is a skill named after the directory,
41
+ * shipped with all its files (scripts, references, ...).
42
42
  */
43
43
  export declare function readSkills(): Skill[];
44
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
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and every file of a skill at its
46
+ * own relative path, plus the package README.md next to its `SKILL.md` (unless the skill ships one), so a skill can
47
+ * reference `@README.md`.
47
48
  */
48
49
  export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string, string>;
49
50
  /**
@@ -1 +1 @@
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"}
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,CAAA;CAAE,CAAC;AAC9B,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;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBhF;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"}
@@ -4,9 +4,10 @@
4
4
  *
5
5
  * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
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
7
+ * file symlinks only: package rules and skills (every file a skill folder ships, plus the package
8
+ * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into all three, pointing
9
+ * straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`
10
+ * and `.codex`. It also
10
11
  * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
11
12
  *
12
13
  * Usage:
@@ -218,21 +219,22 @@ export function readRules() {
218
219
  return rules;
219
220
  }
220
221
  /**
221
- * Read all markdown files from the package skills directory. Each file becomes its own skill, named after the file
222
- * (without extension) - e.g. `lint-repo.md` becomes the `lint-repo` skill.
222
+ * Read the package skills directory: every directory holding a `SKILL.md` is a skill named after the directory,
223
+ * shipped with all its files (scripts, references, ...).
223
224
  */
224
225
  export function readSkills() {
225
226
  if (!fs.existsSync(SKILLS_DIR))
226
227
  return [];
227
228
  return fs
228
- .readdirSync(SKILLS_DIR)
229
- .filter((f) => f.endsWith('.md'))
230
- .sort()
231
- .map((file) => ({ file, name: file.replace('.md', '') }));
229
+ .readdirSync(SKILLS_DIR, { withFileTypes: true })
230
+ .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md')))
231
+ .map((entry) => ({ name: entry.name }))
232
+ .sort((a, b) => a.name.localeCompare(b.name));
232
233
  }
233
234
  /**
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`.
235
+ * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and every file of a skill at its
236
+ * own relative path, plus the package README.md next to its `SKILL.md` (unless the skill ships one), so a skill can
237
+ * reference `@README.md`.
236
238
  */
237
239
  export function packageFiles(rules, skills) {
238
240
  const files = new Map();
@@ -241,9 +243,13 @@ export function packageFiles(rules, skills) {
241
243
  files.set(path.join('rules', rule.file), path.join(RULES_DIR, rule.file));
242
244
  }
243
245
  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);
246
+ const root = path.join(SKILLS_DIR, skill.name);
247
+ const readme = path.join('skills', skill.name, 'README.md');
248
+ for (const file of listRealFiles(root)) {
249
+ files.set(path.join('skills', skill.name, file), path.join(root, file));
250
+ }
251
+ if (hasReadme && !files.has(readme))
252
+ files.set(readme, README_FILE);
247
253
  }
248
254
  return files;
249
255
  }
package/package.json CHANGED
@@ -1,11 +1,12 @@
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.2",
4
+ "version": "0.5.4",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
8
- "lint-prepare": "./dist/lintPrepare.js"
8
+ "lint-prepare": "./dist/lintPrepare.js",
9
+ "spec-steward": "./skills/spec-steward/scripts/steward.mjs"
9
10
  },
10
11
  "main": "./dist/index.js",
11
12
  "module": "./dist/index.js",
@@ -41,7 +42,8 @@
41
42
  "files": [
42
43
  "dist",
43
44
  "rules",
44
- "skills"
45
+ "skills",
46
+ "!skills/**/*.test.mjs"
45
47
  ],
46
48
  "dependencies": {
47
49
  "@eslint/config-helpers": "^0.7.0",
package/rules/github.md CHANGED
@@ -9,79 +9,3 @@ paths:
9
9
 
10
10
  - Agentic review MUST verify this effective CI order: checkout -> enable Corepack -> setup Node with Yarn cache -> restore build caches -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
11
11
  - In multi-job workflows, use job-specific build-cache keys with a same-run fallback so downstream jobs reuse upstream results without immutable-key collisions.
12
-
13
- # Example Workflow
14
-
15
- ```yml
16
- name: Release
17
-
18
- on:
19
- push:
20
- branches:
21
- - main
22
-
23
- # If project publishes to NPM
24
- permissions:
25
- id-token: write # Required for OIDC
26
- contents: read
27
-
28
- concurrency: ${{ github.workflow }}-${{ github.ref }}
29
-
30
- jobs:
31
- release:
32
- name: Release
33
- runs-on: ubuntu-latest
34
- env:
35
- TURBO_CACHE_DIR: .turbo # if project uses Turbo
36
- YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
37
-
38
- # If project publishes to NPM
39
- # https://davistobias.com/articles/adding-changeset/#2.1.b-adding-changeset-to-github-workflows
40
- if: github.repository == 'kirill-konshin/utils'
41
- permissions:
42
- id-token: write # Required for OIDC trusted publishing
43
- contents: write
44
- pull-requests: write
45
-
46
- steps:
47
- - name: Checkout Repo
48
- uses: actions/checkout@v4
49
-
50
- - name: Enable Corepack
51
- run: corepack enable
52
-
53
- - name: Setup Node.js
54
- uses: actions/setup-node@v6
55
- with:
56
- node-version: 24
57
- registry-url: 'https://registry.npmjs.org'
58
- cache: yarn
59
- cache-dependency-path: yarn.lock
60
-
61
- #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
62
- #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
63
- - name: Cache Turbo
64
- uses: actions/cache@v6
65
- with:
66
- path: .turbo
67
- key: ${{ runner.os }}-turbo-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
68
- restore-keys: |
69
- ${{ runner.os }}-turbo-${{ github.run_id }}-${{ github.run_attempt }}-
70
- ${{ runner.os }}-turbo-
71
-
72
- - name: Cache Nx
73
- uses: actions/cache@v6
74
- with:
75
- path: .nx/cache
76
- key: ${{ runner.os }}-nx-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
77
- restore-keys: |
78
- ${{ runner.os }}-nx-${{ github.run_id }}-${{ github.run_attempt }}-
79
- ${{ runner.os }}-nx-
80
-
81
- - name: Install dependencies
82
- run: yarn install --immutable
83
-
84
- # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this block skipped
85
- - name: Prepare
86
- run: yarn prepare
87
- ```
package/rules/gitlab.md CHANGED
@@ -14,76 +14,4 @@ paths:
14
14
 
15
15
  # Example
16
16
 
17
- ```yml
18
- image: node:lts
19
-
20
- variables:
21
- YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
22
-
23
- cache:
24
- - key:
25
- prefix: yarn
26
- files:
27
- - yarn.lock # dependencies cached based on lockfile
28
- paths:
29
- - .yarn/cache
30
- policy: pull-push
31
- # Job-specific keys prevent parallel jobs from replacing each other's local build cache.
32
- - key: build-$CI_JOB_NAME_SLUG-$CI_COMMIT_REF_SLUG
33
- fallback_keys:
34
- - build-$CI_JOB_NAME_SLUG-$CI_DEFAULT_BRANCH
35
- paths:
36
- - .turbo
37
- - .nx/cache
38
- - '**/.tscache'
39
- - '**/.tsbuildinfo'
40
- - '**/.next/cache'
41
- policy: pull-push
42
-
43
- stages:
44
- - install
45
- - test
46
- - build
47
-
48
- # separate so that cache can pre-populate if other steps would fail, it speeds things up
49
- before_script:
50
- - corepack enable
51
- - yarn install --immutable
52
- - yarn prepare # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this line skipped
53
-
54
- install:
55
- stage: install
56
- script:
57
- - echo Done
58
-
59
- lint:
60
- stage: test
61
- script:
62
- - yarn lint
63
-
64
- test:
65
- stage: test
66
- image: mcr.microsoft.com/playwright:v1.50.0-noble # keep in sync with installed Playwright version
67
- artifacts:
68
- when: always
69
- paths:
70
- - test-results
71
- - test-results-html
72
- reports:
73
- junit: test-results/junit.xml
74
- script:
75
- - yarn test:playwright # https://playwright.dev/docs/ci#running-headed xvfb-run yarn test:playwright
76
-
77
- # Not needed for Vercel-hosted projects
78
- build:
79
- stage: build
80
- script:
81
- - yarn build
82
- only:
83
- - master
84
- artifacts:
85
- paths:
86
- - web/build
87
- ```
88
-
89
17
  - Use Nx Cloud or Turbo Remote Cache when build results must be shared safely across parallel jobs.
package/rules/nextjs.md CHANGED
@@ -5,6 +5,8 @@ description: Set of rules for projects which use Next.js
5
5
 
6
6
  _EVERY_ Next.js page, layout, route handler or component must adhere to policy unless explicitly prohibited in comment before the component definition.
7
7
 
8
+ Use `lint-nextjs` skill when working with Next.js projet.
9
+
8
10
  # General Guidelines
9
11
 
10
12
  - Prefer Route Handlers for redirects
@@ -26,58 +28,3 @@ _EVERY_ Next.js page, layout, route handler or component must adhere to policy u
26
28
  - ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) — encapsulates the Toolpad boilerplate and wires `@kirill.konshin/auth`, see mui.md
27
29
  - Use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
28
30
  - Tailwind is ONLY for user-facing sites, NEVER for admin (see tailwind.md)
29
-
30
- # Layouts
31
-
32
- Always use https://nextjs.org/docs/app/api-reference/file-conventions/layout#layout-props-helper:
33
-
34
- ```tsx
35
- import React from 'react';
36
-
37
- export default function Layout({ children, analytics }: LayoutProps<'/dashboard'>) {
38
- return (
39
- <>
40
- {children}
41
- {/* If you have app/dashboard/@analytics, it appears as a typed slot: */}
42
- {analytics}
43
- </>
44
- );
45
- }
46
- ```
47
-
48
- ## Check auth in layouts pattern
49
-
50
- Prefer `/app/(auth)/layout.tsx` as root layout for auth protection. This won't create path segment, but will protect all routes under it.
51
-
52
- Route Handlers are not protected by layouts, so add auth check there too.
53
-
54
- ```tsx
55
- import React from 'react';
56
- import { redirect } from 'next/navigation';
57
- import { getToken } from '@/lib/auth';
58
-
59
- export default async function Layout({ children }: LayoutProps<'/dashboard'>) {
60
- if (!(await getToken())) {
61
- redirect('/login');
62
- }
63
- return <>{children}</>;
64
- }
65
- ```
66
-
67
- # Pages
68
-
69
- - https://nextjs.org/docs/app/api-reference/file-conventions/dynamic-routes
70
- - https://nextjs.org/docs/app/getting-started/layouts-and-pages#rendering-with-search-params
71
- - https://nextjs.org/docs/app/getting-started/layouts-and-pages#creating-a-dynamic-segment
72
-
73
- Always use https://nextjs.org/docs/app/api-reference/file-conventions/page#page-props-helper.
74
-
75
- Always use the following pattern for all pages:
76
-
77
- ```tsx
78
- export default async function Page({ params, searchParams }: PageProps<'/blog/[slug]'>) {
79
- const { slug } = await params;
80
- const { filter } = await searchParams;
81
- return <h1>Blog post: {slug}</h1>;
82
- }
83
- ```
@@ -0,0 +1,12 @@
1
+ ---
2
+ type: always_apply
3
+ description: Hard constraints while editing an OpenSpec corpus
4
+ paths:
5
+ - 'openspec/**'
6
+ ---
7
+
8
+ - NEVER weaken, narrow, delete or reclassify a rule to make code pass — a divergence is the owner's call, ask
9
+ - A scenario adds one concrete case beyond its requirement, or it is not written
10
+ - A rule shared by several repositories is worded identically in each
11
+ - Before handing back a spec change run the repository's spec gate (AGENTS.md → Checks) and surface every `weakened` finding to the owner
12
+ - Corpus-quality audits, review rounds and cross-repository alignment follow the `spec-steward` skill; a code-conformance audit is the repository's own, named in its AGENTS.md
@@ -7,6 +7,8 @@ paths:
7
7
 
8
8
  - Story files: `*.stories.tsx`
9
9
 
10
+ # Suggested basic template
11
+
10
12
  ```tsx
11
13
  import type { Meta, StoryObj } from '@storybook/react-vite';
12
14
  import { ComponentName } from './componentName';
package/rules/tailwind.md CHANGED
@@ -61,4 +61,4 @@ export default defineLintConfig({
61
61
 
62
62
  # Webstorm
63
63
 
64
- See [specific webstorm instructions](webstorm.md) if project uses Tailwind.
64
+ See the `lint-webstorm` skill (`.idea/tailwindcss.xml`) if project uses WebStorm.
package/rules/testing.md CHANGED
@@ -24,3 +24,4 @@ paths:
24
24
  - Mock class methods/values or wrap originals in mocks for visibility
25
25
  - Create helper/factory functions for repeated setup, keep tests DRY
26
26
  - Prefer tests to be logic-free
27
+ - Write a test because it catches a regression, NEVER so that spec text counts as covered
package/rules/webstorm.md CHANGED
@@ -2,219 +2,11 @@
2
2
  type: always_apply
3
3
  description: IDEA / WebStorm patterns
4
4
  paths:
5
- - '**/.idea/**/*.xml'
6
- - '**/.idea/**/*.iml'
5
+ - '**/.idea/**/*.*'
6
+ - '**/.gitignore'
7
7
  ---
8
8
 
9
- **ALL** IDEA / WebStorm projects must adhere to policy unless explicitly prohibited.
10
-
11
- Preserve already existing settings, add what's safe, ask user how to merge if there are conflicts.
12
-
13
- # Configure `.idea/%projectName%.iml`
14
-
15
- ```xml
16
- <?xml version="1.0" encoding="UTF-8"?>
17
- <module type="WEB_MODULE" version="4">
18
- <component name="NewModuleRootManager">
19
- <content url="file://$MODULE_DIR$">
20
- <excludeFolder url="file://$MODULE_DIR$/.yarn" />
21
- <excludePattern pattern=".turbo" />
22
- <excludePattern pattern=".nx" />
23
- <excludePattern pattern="build" />
24
- <excludePattern pattern="coverage" />
25
- <excludePattern pattern="dist" />
26
- </content>
27
- <orderEntry type="inheritedJdk" />
28
- <orderEntry type="sourceFolder" forTests="false" />
29
- </component>
30
- </module>
31
- ```
32
-
33
- # Configure `.idea/jsLibraryMappings.xml`
34
-
35
- ```xml
36
- <?xml version="1.0" encoding="UTF-8"?>
37
- <project version="4">
38
- <component name="JavaScriptLibraryMappings">
39
- <includedPredefinedLibrary name="Node.js Core" />
40
- </component>
41
- </project>
42
- ```
43
-
44
- # Configure `.idea/prettier.xml`
45
-
46
- ```xml
47
- <?xml version="1.0" encoding="UTF-8"?>
48
- <project version="4">
49
- <component name="PrettierConfiguration">
50
- <option name="myConfigurationMode" value="AUTOMATIC" />
51
- <option name="myRunOnSave" value="true" />
52
- <option name="myRunOnReformat" value="true" />
53
- <option name="myFilesPattern" value="{**/*,*}.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue,css,scss,sass,less,yml,yaml,json,json5,graphql,graphqls,xml}" />
54
- </component>
55
- </project>
56
- ```
57
-
58
- # Configure `.idea/jsLinters/eslint.xml`
59
-
60
- ```xml
61
- <?xml version="1.0" encoding="UTF-8"?>
62
- <project version="4">
63
- <component name="EslintConfiguration">
64
- <files-pattern value="**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}" />
65
- <option name="fix-on-save" value="true" />
66
- </component>
67
- </project>
68
- ```
69
-
70
- # Configure `.idea/vcs.xml`
71
-
72
- ```xml
73
- <?xml version="1.0" encoding="UTF-8"?>
74
- <project version="4">
75
- <component name="CommitMessageInspectionProfile">
76
- <profile version="1.0">
77
- <inspection_tool class="BodyLimit" enabled="true" level="WARNING" enabled_by_default="true">
78
- <option name="RIGHT_MARGIN" value="100" />
79
- </inspection_tool>
80
- <inspection_tool class="SubjectBodySeparation" enabled="true" level="WARNING" enabled_by_default="true" />
81
- <inspection_tool class="SubjectLimit" enabled="true" level="WARNING" enabled_by_default="true">
82
- <option name="RIGHT_MARGIN" value="100" />
83
- </inspection_tool>
84
- </profile>
85
- </component>
86
- <component name="GitSharedSettings">
87
- <option name="FORCE_PUSH_PROHIBITED_PATTERNS">
88
- <list />
89
- </option>
90
- </component>
91
- <component name="VcsDirectoryMappings">
92
- <mapping directory="$PROJECT_DIR$" vcs="Git" />
93
- </component>
94
- </project>
95
- ```
96
-
97
- # GitIgnore
98
-
99
- Folders defined in `.gitignore` should match with `.idea/%project_name%.iml` (usually only one IML file).
100
-
101
- ## Configure `.idea/.gitignore`:
102
-
103
- ```gitignore
104
- # Default ignored files
105
- /shelf/
106
- /workspace.xml
107
- # Editor-based HTTP Client requests
108
- /httpRequests/
109
- AugmentWebviewStateStore.xml
110
- ```
111
-
112
- # Configure `.idea/codeStyles/codeStyleConfig.xml`
113
-
114
- ```xml
115
- <component name="ProjectCodeStyleConfiguration">
116
- <state>
117
- <option name="PREFERRED_PROJECT_CODE_STYLE" value="DiS" />
118
- </state>
119
- </component>
120
- ```
121
-
122
- # Configure `.idea/tailwindcss.xml`
123
-
124
- Applies if project is using Tailwind.
125
-
126
- ```xml
127
- <?xml version="1.0" encoding="UTF-8"?>
128
- <project version="4">
129
- <component name="TailwindSettings">
130
- <option name="lspConfiguration" value="{&#10; &quot;inspectPort&quot;: null,&#10; &quot;emmetCompletions&quot;: false,&#10; &quot;classAttributes&quot;: [&quot;class&quot;, &quot;className&quot;, &quot;activeClassName&quot;, &quot;disabledClassName&quot;, &quot;ngClass&quot;, &quot;class:list&quot;],&#10; &quot;classFunctions&quot;: [],&#10; &quot;codeActions&quot;: true,&#10; &quot;codeLens&quot;: true,&#10; &quot;hovers&quot;: true,&#10; &quot;suggestions&quot;: true,&#10; &quot;validate&quot;: true,&#10; &quot;colorDecorators&quot;: true,&#10; &quot;rootFontSize&quot;: 16,&#10; &quot;lint&quot;: {&#10; &quot;cssConflict&quot;: &quot;warning&quot;,&#10; &quot;invalidApply&quot;: &quot;error&quot;,&#10; &quot;invalidScreen&quot;: &quot;error&quot;,&#10; &quot;invalidVariant&quot;: &quot;error&quot;,&#10; &quot;invalidConfigPath&quot;: &quot;error&quot;,&#10; &quot;invalidTailwindDirective&quot;: &quot;error&quot;,&#10; &quot;invalidSourceDirective&quot;: &quot;error&quot;,&#10; &quot;recommendedVariantOrder&quot;: &quot;warning&quot;,&#10; &quot;usedBlocklistedClass&quot;: &quot;warning&quot;&#10; },&#10; &quot;showPixelEquivalents&quot;: true,&#10; &quot;includeLanguages&quot;: {&#10; &quot;ftl&quot;: &quot;html&quot;,&#10; &quot;jinja&quot;: &quot;html&quot;,&#10; &quot;jinja2&quot;: &quot;html&quot;,&#10; &quot;smarty&quot;: &quot;html&quot;,&#10; &quot;tmpl&quot;: &quot;gohtml&quot;,&#10; &quot;cshtml&quot;: &quot;html&quot;,&#10; &quot;vbhtml&quot;: &quot;html&quot;,&#10; &quot;razor&quot;: &quot;html&quot;&#10; },&#10; &quot;files&quot;: {&#10; &quot;exclude&quot;: [&#10; &quot;**/.git/**&quot;,&#10; &quot;**/.hg/**&quot;,&#10; &quot;**/.svn/**&quot;,&#10; &quot;**/node_modules/**&quot;,&#10; &quot;**/.yarn/**&quot;,&#10; &quot;**/.venv/**&quot;,&#10; &quot;**/venv/**&quot;,&#10; &quot;**/.next/**&quot;,&#10; &quot;**/.parcel-cache/**&quot;,&#10; &quot;**/.svelte-kit/**&quot;,&#10; &quot;**/.turbo/**&quot;,&#10; &quot;**/__pycache__/**&quot;&#10; ]&#10; },&#10; &quot;experimental&quot;: {&#10; &quot;configFile&quot;: null,&#10; &quot;classRegex&quot;: [&#10; &quot;Classes\\s*=\\s*['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;, &quot;['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;,&#10; &quot;Styles\\s*=\\s*['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;, &quot;['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;&#10; ]&#10; }&#10;}" />
131
- </component>
132
- </project>
133
- ```
134
-
135
- # Configure `.idea/jsonSchemas.xml`
136
-
137
- ```xml
138
- <?xml version="1.0" encoding="UTF-8"?>
139
- <project version="4">
140
- <component name="JsonSchemaMappingsProjectConfiguration">
141
- <state>
142
- <map>
143
- <entry key="Gemini CLI settings">
144
- <value>
145
- <SchemaInfo>
146
- <option name="name" value="Gemini CLI settings" />
147
- <option name="relativePathToSchema" value="https://raw.githubusercontent.com/google-gemini/gemini-cli/refs/heads/main/schemas/settings.schema.json" />
148
- <option name="applicationDefined" value="true" />
149
- <option name="patterns">
150
- <list>
151
- <Item>
152
- <option name="path" value=".gemini/settings.json" />
153
- </Item>
154
- </list>
155
- </option>
156
- </SchemaInfo>
157
- </value>
158
- </entry>
159
- <entry key="Yarn Config (.yarnrc.yml)">
160
- <value>
161
- <SchemaInfo>
162
- <option name="name" value="Yarn Config (.yarnrc.yml)" />
163
- <option name="relativePathToSchema" value="https://yarnpkg.com/configuration/yarnrc.json" />
164
- <option name="applicationDefined" value="true" />
165
- <option name="patterns">
166
- <list>
167
- <Item>
168
- <option name="path" value=".yarnrc.yml" />
169
- </Item>
170
- </list>
171
- </option>
172
- </SchemaInfo>
173
- </value>
174
- </entry>
175
- </map>
176
- </state>
177
- </component>
178
- </project>
179
- ```
180
-
181
- # Configure `indexLayout.xml`
182
-
183
- Ban build directories from search using examples:
184
-
185
- ```xml
186
- <?xml version="1.0" encoding="UTF-8"?>
187
- <project version="4">
188
- <component name="UserContentModel">
189
- <attachedFolders />
190
- <explicitIncludes>
191
- </explicitIncludes>
192
- <explicitExcludes>
193
- <Path>path-to-eve/.eve</Path>
194
- <Path>path-to-vite/dist</Path>
195
- <Path>path-to-next/.next</Path>
196
- </explicitExcludes>
197
- </component>
198
- </project>
199
- ```
200
-
201
- # Git Worktrees
202
-
203
- `.idea/%projectName%.iml`, `.idea/modules.xml` and `.idea/.name` are usually tracked. Every git worktree therefore checks out a module with the same name as the main checkout's, and WebStorm refuses to attach it: `Cannot attach project: Module name '%projectName%' already exists`.
204
-
205
- - When creating a worktree, ALWAYS give it a distinct module and project name derived from the branch, e.g. `Packing Travel App` for `travel-app`:
206
- 1. **Rename** — do not copy — `.idea/%projectName%.iml` to `.idea/%projectName% %Branch Title%.iml`. The module name is the file name, and attaching the worktree registers whichever `.iml` it finds: a copy beside the original still attaches as `%projectName%`.
207
- 2. Point `.idea/modules.xml` at the renamed file.
208
- 3. Write the same name into `.idea/.name`.
209
- 4. A main project the worktree is attached to lists it in its own `.idea/modules.xml`: point that entry at the renamed file too.
210
- - Keep the rename local, and NEVER commit it or merge it back:
211
- - The tracked `.iml` first: stage the branch's own edits to it (`git add .idea/%projectName%.iml`), then `git update-index --skip-worktree .idea/%projectName%.iml`, then rename. The staged content is what the branch commits; the rename never shows as a deletion. An edit the branch later makes to the renamed file has to be staged back the same way.
212
- - Ignore the renamed file in the shared `.git/info/exclude` with the pattern `.idea/%projectName% *.iml`.
213
- - A **tracked** `.idea/modules.xml` or `.idea/.name`: run `git update-index --skip-worktree` on it.
214
- - An **untracked** one (often `modules.xml` is in `.idea/.gitignore` and `.name` does not exist yet): `skip-worktree` fails on it, so leave it to `.idea/.gitignore` or add it to the shared `.git/info/exclude` as well (e.g. `.idea/.name`).
215
- - Verify with `git status --short .idea`: nothing from the rename is listed, only the staged edits.
216
- - Before a rebase, merge or checkout that updates those files (tracked ones only):
217
- 1. Rename the `.iml` back and run `git update-index --no-skip-worktree` on every file marked above.
218
- 2. Restore them with `git checkout -- <files>`.
219
- 3. Redo the rename afterwards.
220
- - A worktree created **inside** the main checkout (e.g. `.claude/worktrees/<name>`, where agents put theirs) is indexed by the main project as part of itself, a second copy of every source and `node_modules`, and the main project's save actions start reformatting the worktree's files. Exclude its folder in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.claude/worktrees" />`) and list it in `.gitignore`, so the folder rule under [GitIgnore](#gitignore) holds. Attaching such a worktree can replace the main checkout's own entry in its `.idea/modules.xml`: keep both — the main `.idea/%projectName%.iml` and the worktree's renamed one — then reload the project. A nested worktree shows as its own module node inside the tree, not as a separate top-level project; for a top-level entry, create the worktree outside the main checkout.
9
+ - **ALL** IDEA / WebStorm projects must adhere to the `lint-webstorm` skill templates unless explicitly prohibited - use the skill to set up or check `.idea` files
10
+ - Preserve already existing settings, add what's safe, ask user how to merge if there are conflicts
11
+ - Heavy folders nothing needs to search (`dist`, `build`, `coverage`, `.next`, `.nx`, `.turbo`, `.worktrees`, ...) are excluded in three places: `.gitignore`, "Mark as excluded" (`excludeFolder` / `excludePattern` in `.idea/%projectName%.iml`) and index exclusion (`.idea/indexLayout.xml`) - keep the three in sync, or at least on a shared baseline: some folders are only git-ignored, others only marked as excluded
12
+ - Git worktrees clash with IDEA module names - use the `lint-worktree` skill