@kirill.konshin/lint 0.7.3 → 0.8.0
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 +160 -113
- package/dist/config.d.ts +103 -0
- package/dist/config.js +112 -0
- package/dist/configs/base.d.ts +1 -1
- package/dist/configs/nx.d.ts +1 -1
- package/dist/configs/nx.js +3 -8
- package/dist/configs/react.d.ts +3 -3
- package/dist/configs/react.js +6 -16
- package/dist/configs/storybook.d.ts +3 -3
- package/dist/configs/storybook.js +4 -9
- package/dist/configs/tailwind.d.ts +6 -25
- package/dist/configs/tailwind.js +3 -64
- package/dist/configs/testing.d.ts +1 -1
- package/dist/configs/testing.js +3 -15
- package/dist/configs/turbo.d.ts +2 -2
- package/dist/configs/turbo.js +4 -6
- package/dist/configs/typescriptTypeAware.d.ts +1 -1
- package/dist/gates.d.ts +72 -0
- package/dist/gates.js +132 -0
- package/dist/index.d.ts +15 -51
- package/dist/index.js +16 -14
- package/dist/lib.d.ts +1 -1
- package/dist/lib.js +1 -1
- package/dist/lintPrepare.d.ts +75 -28
- package/dist/lintPrepare.js +243 -35
- package/dist/testColocation.js +1 -1
- package/dist/vitePlus.d.ts +8 -18
- package/dist/vitePlus.js +40 -47
- package/package.json +7 -4
- package/rules/agent.md +1 -0
- package/rules/auth.md +3 -3
- package/rules/db.md +6 -9
- package/rules/expo.md +2 -0
- package/rules/github.md +1 -1
- package/rules/gitlab.md +1 -1
- package/rules/i18n.md +3 -0
- package/rules/monorepo-turbo-nx.md +38 -4
- package/rules/mui.md +8 -18
- package/rules/nextjs.md +13 -13
- package/rules/npm-yarn.md +28 -118
- package/rules/nx.md +1 -1
- package/rules/playwright.md +1 -1
- package/rules/react.md +7 -32
- package/rules/tailwind.md +9 -47
- package/rules/testing.md +2 -2
- package/rules/turbo.md +1 -1
- package/rules/typescript.md +6 -2
- package/rules/ui-kit.md +6 -0
- package/rules/vite.md +1 -1
- package/skills/lint-db/SKILL.md +23 -0
- package/skills/lint-electron/SKILL.md +9 -6
- package/skills/lint-github/SKILL.md +15 -8
- package/skills/lint-gitlab/SKILL.md +20 -5
- package/skills/lint-migrate/SKILL.md +18 -2
- package/skills/lint-mui/SKILL.md +28 -0
- package/skills/lint-nextjs/SKILL.md +53 -16
- package/skills/lint-npm-yarn/SKILL.md +126 -0
- package/skills/lint-repo/SKILL.md +12 -12
- package/skills/lint-tailwind/SKILL.md +53 -0
- package/skills/lint-webstorm/SKILL.md +3 -3
- package/skills/lint-worktree/SKILL.md +25 -9
- package/skills/spec-author/SKILL.md +2 -2
- package/skills/spec-steward/SKILL.md +1 -1
- package/skills/spec-steward/references/apply.md +1 -1
- package/skills/spec-steward/references/contract.md +2 -2
- package/skills/spec-steward/references/model.md +2 -2
- package/skills/spec-steward/references/review-format.md +4 -4
- package/skills/spec-steward/references/wiring.md +2 -2
- package/skills/spec-steward/references/worker.md +1 -1
- package/skills/spec-tools/SKILL.md +2 -2
- package/skills/spec-tools/references/rules/common.md +1 -1
- package/skills/spec-tools/references/rules/spec-steward.md +1 -1
- package/skills/spec-tools/scripts/cli.js +2 -2
- package/skills/spec-verify/SKILL.md +1 -1
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lint-tailwind
|
|
3
|
+
description: Tailwind details for the tailwind rule - the safe-area `@utility` template and the eslint-plugin-tailwindcss / Oxlint setup (entry CSS detection, `cssConfigPath`, scoping, resolution errors). Use when adding safe-area utilities, or when Tailwind lint is set up, crashes or skips.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The binding rules are in [rules/tailwind.md](../../rules/tailwind.md). This skill holds the details.
|
|
7
|
+
|
|
8
|
+
# Safe-Area Utilities
|
|
9
|
+
|
|
10
|
+
```css
|
|
11
|
+
@utility top-safe {
|
|
12
|
+
top: 1.5rem;
|
|
13
|
+
top: max(1.5rem, env(safe-area-inset-top, 0px));
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
@utility right-safe {
|
|
17
|
+
right: 1.5rem;
|
|
18
|
+
right: max(1.5rem, env(safe-area-inset-right, 0px));
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
@utility bottom-safe {
|
|
22
|
+
bottom: 1.5rem;
|
|
23
|
+
bottom: max(1.5rem, env(safe-area-inset-bottom, 0px));
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
@utility left-safe {
|
|
27
|
+
left: 1.5rem;
|
|
28
|
+
left: max(1.5rem, env(safe-area-inset-left, 0px));
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
# ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
|
|
33
|
+
|
|
34
|
+
- With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; both read `tailwind` from `lint.config.ts`
|
|
35
|
+
- The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
|
|
36
|
+
- Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned across the root + every workspace package, `.gitignore`-aware), rules auto-enable with that entry
|
|
37
|
+
- Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
|
|
38
|
+
- `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see the `lint-npm-yarn` skill, "Hoisting") or add it to root `devDependencies`; trace detection with `LINT_DEBUG=1 vp lint` (or `LINT_DEBUG=1 eslint .`)
|
|
39
|
+
- Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
|
|
40
|
+
- pass `cssConfigPath` in `lint.config.ts` to pick one (Vite+: the only fix, it ignores nested `lint` blocks) OR
|
|
41
|
+
- ESLint only: create a leaf `eslint.config.mjs` per app with its own `cssConfigPath` (if ALL need to be linted)
|
|
42
|
+
- When detection can't see `tailwindcss` (e.g. it lives only in leaf packages of a monorepo), force it with `tailwind: true` — then a missing entry CSS is a HARD ERROR instead of a silent skip
|
|
43
|
+
- ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `lint.config.ts`:
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import { defineLintConfig } from '@kirill.konshin/lint/config';
|
|
47
|
+
|
|
48
|
+
export default defineLintConfig({
|
|
49
|
+
tailwind: {
|
|
50
|
+
cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the workspace root
|
|
51
|
+
},
|
|
52
|
+
});
|
|
53
|
+
```
|
|
@@ -5,7 +5,7 @@ description: Templates and checks for JetBrains IDEA / WebStorm `.idea` project
|
|
|
5
5
|
|
|
6
6
|
# Check
|
|
7
7
|
|
|
8
|
-
Compare the project's `.idea` files with the templates below and
|
|
8
|
+
Compare the project's `.idea` files with the templates below and [rules/webstorm.md](../../rules/webstorm.md), list every discrepancy, ask before fixing:
|
|
9
9
|
|
|
10
10
|
- Template settings missing or different in the project's files
|
|
11
11
|
- Excluded folders out of sync between `.gitignore`, `.idea/%projectName%.iml` (usually only one IML file) and `.idea/indexLayout.xml` - look only in these files, infer nothing else
|
|
@@ -44,7 +44,7 @@ Compare the project's `.idea` files with the templates below and the `webstorm`
|
|
|
44
44
|
|
|
45
45
|
# Vite+: Oxc plugin
|
|
46
46
|
|
|
47
|
-
When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.com/plugin/27061-oxc) runs `vp lint --lsp` / `vp fmt --lsp` (AUTOMATIC mode finds `vite-plus`), so the `vite.config.ts
|
|
47
|
+
When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.com/plugin/27061-oxc) runs `vp lint --lsp` / `vp fmt --lsp` (AUTOMATIC mode finds `vite-plus`), so the Vite+ config applies (`vite.config.ts`, with the blocks from the `vitePlus` key of `lint.config.ts`). Prettier is disabled and `.idea/jsLinters/eslint.xml` deleted. The plugin stores booleans as attributes while the Vite+ docs write `<option>` - keep both; the IDE rewrites the file in its own form on save. Ask the user to confirm Settings → Tools → Oxc after reopening.
|
|
48
48
|
|
|
49
49
|
`.idea/externalDependencies.xml` (required plugin; un-ignore it if `.idea` is gitignored: `!.idea/externalDependencies.xml`):
|
|
50
50
|
|
|
@@ -149,7 +149,7 @@ When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.co
|
|
|
149
149
|
|
|
150
150
|
# GitIgnore
|
|
151
151
|
|
|
152
|
-
Excluded folders follow the baseline of
|
|
152
|
+
Excluded folders follow the baseline of [rules/webstorm.md](../../rules/webstorm.md).
|
|
153
153
|
|
|
154
154
|
## Configure `.idea/.gitignore`:
|
|
155
155
|
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-worktree
|
|
3
|
-
description:
|
|
3
|
+
description: Git worktrees inside the main checkout (`.worktrees`, Claude Code's `.claude/worktrees`) and the JetBrains IDEA / WebStorm module-name clash they cause. Use when creating, attaching or removing a git worktree.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
- Prefer creating worktrees inside the main repo in `.worktrees` directory
|
|
7
|
-
-
|
|
6
|
+
- Prefer creating worktrees inside the main repo in `.worktrees` directory; Claude Code creates its worktrees in `.claude/worktrees`
|
|
7
|
+
- Each worktree folder has to be gitignored (`.gitignore` or the shared `.git/info/exclude`) and marked as excluded in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.claude/worktrees" />`)
|
|
8
|
+
- Without the exclusion, the main project indexes a second copy of every source and `node_modules`, and its save actions reformat the worktree's files
|
|
8
9
|
|
|
9
10
|
# Git Worktrees & JetBrains IDEA / WebStorm
|
|
10
11
|
|
|
@@ -14,15 +15,30 @@ description: Describes how to work with GIT Worktrees
|
|
|
14
15
|
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%`.
|
|
15
16
|
2. Point `.idea/modules.xml` at the renamed file.
|
|
16
17
|
3. Write the same name into `.idea/.name`.
|
|
17
|
-
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.
|
|
18
18
|
- Keep the rename local, and NEVER commit it or merge it back:
|
|
19
19
|
- 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.
|
|
20
20
|
- Ignore the renamed file in the shared `.git/info/exclude` with the pattern `.idea/%projectName% *.iml`.
|
|
21
21
|
- A **tracked** `.idea/modules.xml` or `.idea/.name`: run `git update-index --skip-worktree` on it.
|
|
22
22
|
- 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`).
|
|
23
|
+
- A worktree that has both the original `.iml` and a renamed copy: do the `skip-worktree` step on the original, then delete it.
|
|
23
24
|
- Verify with `git status --short .idea`: nothing from the rename is listed, only the staged edits.
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
-
|
|
25
|
+
|
|
26
|
+
# Attaching a Worktree to the Main Project
|
|
27
|
+
|
|
28
|
+
- Attaching edits tracked files of the main checkout:
|
|
29
|
+
- `.idea/modules.xml` gets an entry for the worktree's `.iml`; attaching can replace the main checkout's own entry: keep both, then reload the project
|
|
30
|
+
- `.idea/%projectName%.iml` gets `<orderEntry type="module" module-name="%projectName% %Branch Title%" />`
|
|
31
|
+
- `.idea/vcs.xml` can get `<mapping directory="" vcs="Git" />` instead of `$PROJECT_DIR$`
|
|
32
|
+
- Keep these edits local, the same as the rename: stage only the real edits to these files (e.g. a new `excludeFolder`), then `git update-index --skip-worktree` them
|
|
33
|
+
- To stage part of a file without `git add -p`: `git hash-object -w` the wanted content, then `git update-index --cacheinfo 100644,<blob>,<path>`
|
|
34
|
+
- Verify with `git status --short .idea` in the main checkout: only the staged edits are listed
|
|
35
|
+
- A worktree inside the main checkout shows as a module node inside the main tree, under its excluded folder, never as a top-level tree; for a top-level tree, create the worktree outside the main checkout (for Claude Code: its "Worktree location" setting; do not change it without the user's approval)
|
|
36
|
+
- After the worktree is detached or removed: `git update-index --no-skip-worktree` the main checkout's files, then `git checkout -- <files>`
|
|
37
|
+
|
|
38
|
+
# Before a Rebase, Merge or Checkout
|
|
39
|
+
|
|
40
|
+
In each checkout, for tracked files marked above that the operation updates:
|
|
41
|
+
|
|
42
|
+
1. Rename the `.iml` back and run `git update-index --no-skip-worktree` on every marked file.
|
|
43
|
+
2. Restore them with `git checkout -- <files>`.
|
|
44
|
+
3. Redo the rename and the marks afterwards.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-author
|
|
3
|
-
description: Write or edit a capability specification in openspec/specs — the default direct-edit path
|
|
4
|
-
allowed-tools: Bash(openspec:*), Bash(spec-tools:*), Bash(
|
|
3
|
+
description: Write or edit a capability specification in openspec/specs — the default direct-edit path. Use when adding or changing a requirement or scenario, unless the user asks for the /opsx delta flow.
|
|
4
|
+
allowed-tools: Bash(openspec:*), Bash(spec-tools:*), Bash(yarn openspec:*), Bash(yarn spec-tools:*), Bash(npx openspec:*), Bash(npx spec-tools:*), Bash(node:*), 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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-steward
|
|
3
|
-
description: Guard, audit and repair an OpenSpec specification corpus
|
|
3
|
+
description: Guard, audit and repair an OpenSpec specification corpus - are these the right rules, in the right place, with the right evidence; it proposes spec changes and never fails a build. Use when auditing spec corpus quality, processing a spec review file (`.spec-audit/spec-review.yaml`), aligning rules shared by several repositories, wiring the spec guard into a repository, or when `spec-tools steward check` or the edit hook reports a finding. Not for code conformance (the `spec-verify` skill) or for writing a rule (the `spec-author` skill).
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Spec steward
|
|
@@ -6,7 +6,7 @@ The owner has answered a review file ([review-format.md](review-format.md)). Pro
|
|
|
6
6
|
2. **Accepted (`✅`, `✅ <comment>`).** Apply the proposal, changed as the comment tells.
|
|
7
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
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
|
|
9
|
+
- When a change moves guidance to a new place, put it where [rules/agent.md](../../../rules/agent.md) tells, remove each copy, and reference it from its old place.
|
|
10
10
|
- Add `applied: "R<round> — <what changed, with paths>"` to the item. A second application makes `applied` a list.
|
|
11
11
|
3. **Rejected (`❌`, `❌ <comment>`).** Keep the rule as it is, or follow the owner's other instruction. Record what you did in `applied`.
|
|
12
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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The spec-steward contract
|
|
2
2
|
|
|
3
|
-
What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `steward.test.
|
|
3
|
+
What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `spec-tools/src/steward/steward.test.ts` proves the cases below.
|
|
4
4
|
|
|
5
5
|
Terms used throughout:
|
|
6
6
|
|
|
@@ -35,7 +35,7 @@ A citation of a scenario's anchor binds the scenario only where it sits in one o
|
|
|
35
35
|
| In a test file (a JavaScript or TypeScript `*.test.*`, `*.spec.*` or `*.test-d.*` file, a file under `__tests__/` or `e2e/`, or a Python or Go test file), inside a `describe`, `it`, `test`, `suite` or `bench` call, with any `.only`, `.skip`, `.concurrent`, `.sequential`, `.todo`, `.each(…)`, `.for(…)`, `.runIf(…)`, `.skipIf(…)` or `.fails` chain, and Playwright's `test.describe`, `test.step`, `.serial`, `.parallel`, `.fixme` and `.fail`; in a Python test file, inside a `test_…` function or a `Test…` class; in a Go test file, inside a `Test…` function | yes |
|
|
36
36
|
| In a test file, in the comment run directly above such a call or function (in Python, its decorators too), with no blank line between | yes |
|
|
37
37
|
| In a test file, on a type assertion — an `Expect<…>` type alias, or an `expectTypeOf(…)` or `assertType(…)` call — at the top level or inside a block | yes |
|
|
38
|
-
| In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}`, `vite.config.{js,mjs,cjs,ts,mts,cts}` (Vite+) or `yarn.config.cjs` — anywhere | yes |
|
|
38
|
+
| In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}`, `vite.config.{js,mjs,cjs,ts,mts,cts}` (Vite+), `lint.config.{js,mjs,cjs,ts,mts,cts}` (`@kirill.konshin/lint`) or `yarn.config.cjs` — anywhere | yes |
|
|
39
39
|
| In a file matching a `binds` glob the repository declares — `"spec-steward": { "binds": [...] }` in its root `package.json`, or `--binds <glob>` — (a check script, a Dockerfile, a CI configuration), anywhere | yes |
|
|
40
40
|
| Anywhere else in a test file: its header, a fixture, a helper | no — it binds nothing and fails nothing |
|
|
41
41
|
| Code, configuration, YAML, a Dockerfile or a document that no `--binds` glob matches | no — it is a pointer |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The specification model
|
|
2
2
|
|
|
3
|
-
Where a piece of guidance lives is decided by
|
|
3
|
+
Where a piece of guidance lives is decided by [rules/agent.md](../../../rules/agent.md), shipped by `@kirill.konshin/lint`; in a repository it is `.agents/rules/agent.md`. Read it there; this file covers only what is specific to the specifications themselves. What the gate checks mechanically — citations, binding, markers, size lines, the scenario ratchet — is [contract.md](contract.md).
|
|
4
4
|
|
|
5
5
|
## A rule in `openspec/specs` is a contract
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ Normative force is carried by the RFC 2119 keywords — MUST, MUST NOT, REQUIRED
|
|
|
10
10
|
|
|
11
11
|
A specification describes only real, existing behaviour. What is knowingly absent or incomplete is recorded as a [Known gap](#advisory-known-gap-or-neither), never written as though implemented and never left as unmarked silence.
|
|
12
12
|
|
|
13
|
-
Apply the two litmus questions from
|
|
13
|
+
Apply the two litmus questions from [rules/agent.md](../../../rules/agent.md); then the decision test:
|
|
14
14
|
|
|
15
15
|
> **Name the observable failure this rule prevents, and the cheapest evidence that would catch it.**
|
|
16
16
|
|
|
@@ -16,8 +16,8 @@ R-001:
|
|
|
16
16
|
confidence: 85
|
|
17
17
|
rule:
|
|
18
18
|
text: |-
|
|
19
|
-
The server SHALL promote
|
|
20
|
-
location: '
|
|
19
|
+
The server SHALL promote Xxx…
|
|
20
|
+
location: 'APP openspec/specs/system-overview/logging/spec.md:47'
|
|
21
21
|
wrong: |
|
|
22
22
|
The rule names the exact log fields. A field change breaks the rule with no effect in production.
|
|
23
23
|
proposal: |
|
|
@@ -37,10 +37,10 @@ R-002:
|
|
|
37
37
|
rules:
|
|
38
38
|
- text: |-
|
|
39
39
|
WHEN the dev server starts THEN it seeds the demo account
|
|
40
|
-
location: '
|
|
40
|
+
location: 'APP openspec/specs/apps/runtime/spec.md:88'
|
|
41
41
|
- text: |-
|
|
42
42
|
The local database SHALL reset on each start
|
|
43
|
-
location: '
|
|
43
|
+
location: 'APP openspec/specs/apps/db/spec.md:12'
|
|
44
44
|
note: 'the reset is also in the README'
|
|
45
45
|
wrong: |
|
|
46
46
|
Both rules apply only on a developer machine. A violation has no effect in production.
|
|
@@ -5,14 +5,14 @@ A skill is discovered at the agent's discretion, so it cannot be the only thing
|
|
|
5
5
|
| Point | What it does | Placed by |
|
|
6
6
|
| --- | --- | --- |
|
|
7
7
|
| Scoped rule `.agents/rules/openspec.md` (+ `.claude/rules`) | Hard constraints, loaded when the agent touches `openspec/**`. | `lint-prepare` (`@kirill.konshin/lint`) |
|
|
8
|
-
| Skill `.agents/skills/spec-steward` (+ `.claude/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` |
|
|
8
|
+
| Skill `.agents/skills/spec-steward` (+ `.claude/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` (through the `skills` CLI) |
|
|
9
9
|
| Edit hook in `.claude/settings.json` | Runs `steward hook` after every Edit/Write/MultiEdit and feeds findings back to the agent at once — only for what the edit changed, with no ratchet. | `steward wire --fix` |
|
|
10
10
|
| Routing line in `AGENTS.md` | Tells every agent, Codex included, where the guard lives, and that corpus-quality audits use this skill while code conformance is the `spec-verify` audit. | You, beside the specification-driven convention; `wire --fix` prints the line. |
|
|
11
11
|
| OPSX operation guidance in `openspec/config.yaml` | One narrow line each for `apply` and `archive`: run the repository's spec gate (AGENTS.md → Checks); a `weakened` finding stops the flow. | `steward wire --fix`, when the file has OpenSpec's standard shape |
|
|
12
12
|
|
|
13
13
|
These five points keep to the placement rules:
|
|
14
14
|
|
|
15
|
-
- Nothing restates
|
|
15
|
+
- Nothing restates [rules/agent.md](../../../rules/agent.md) or the repository's own rules.
|
|
16
16
|
- The OPSX `context` stays untouched: it already carries `AGENTS.md`.
|
|
17
17
|
- The hook is a no-op where the skill is not installed, so teammates without it are not blocked.
|
|
18
18
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
This file tells how one worker of the corpus-quality audit runs. `spec-tools workers --audit spec-steward` starts one worker per unit of the scope. Its brief names the unit, the files to read and the findings file to write. The procedure around the workers is [audit.md](audit.md).
|
|
4
4
|
|
|
5
|
-
What to judge is in the judging rules: [`common.md`](../../spec-tools/references/rules/common.md), then [`spec-steward.md`](../../spec-tools/references/rules/spec-steward.md). How a specification is written is [model.md](model.md). Where guidance belongs is the placement guide,
|
|
5
|
+
What to judge is in the judging rules: [`common.md`](../../spec-tools/references/rules/common.md), then [`spec-steward.md`](../../spec-tools/references/rules/spec-steward.md). How a specification is written is [model.md](model.md). Where guidance belongs is the placement guide, [rules/agent.md](../../../rules/agent.md) of this package. Read them before you judge.
|
|
6
6
|
|
|
7
7
|
The audit is read-only. You write your findings file and nothing else. Your tools are Read, Glob, Grep, Write and the read-only git commands. Other commands are denied and only cost a turn.
|
|
8
8
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-tools
|
|
3
|
-
description:
|
|
3
|
+
description: Set up and run the `spec-tools` CLI of `@kirill.konshin/lint` in an OpenSpec repository - change gates, workflow-evidence gate, specification diff, runs of the `spec-verify` audit, and the CI glue around a headless AI review. Use when wiring spec-tools into a repository or its pipeline, when a `spec-tools` command fails or its output needs reading, or when choosing the run class of an audit.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# spec-tools
|
|
@@ -35,7 +35,7 @@ Run them through the package manager (`yarn spec-tools gates`), the bin (`node_m
|
|
|
35
35
|
|
|
36
36
|
## Setting a repository up
|
|
37
37
|
|
|
38
|
-
1. Pin `@kirill.konshin/lint`; `lint-prepare`
|
|
38
|
+
1. Pin `@kirill.konshin/lint`; `lint-prepare` installs the `spec-steward`, `spec-tools` and `spec-verify` skills.
|
|
39
39
|
2. Declare what binds beyond spec-steward's defaults once, in the root `package.json`: `"spec-steward": { "binds": ["scripts/checks/**", "**/*.Dockerfile", ".gitlab-ci.yml"] }`.
|
|
40
40
|
3. List the gates in the repository's `AGENTS.md` checks: `openspec validate --strict --all`, `spec-tools gates`, and after a requirement changes `spec-tools changed` with `/spec-verify changed` and `spec-tools diff`.
|
|
41
41
|
4. Ignore the generated files with one `.gitignore` line, `.spec-audit/`: every file the tools and the audits write is under it — YAML data, the Markdown and HTML reports, `claude.jsonl`, the job logs. In CI, publish `.spec-audit/` as each audit job's artifacts path.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Judging rules: common
|
|
2
2
|
|
|
3
|
-
These rules tell what a finding is, how severe it is, and how sure you are of it. They apply to every audit that spec-tools runs: spec-verify, its judge
|
|
3
|
+
These rules tell what a finding is, how severe it is, and how sure you are of it. They apply to every audit that spec-tools runs: spec-verify, its judge and spec-steward. The skill and the tool tell how a run works.
|
|
4
4
|
|
|
5
5
|
## Evidence
|
|
6
6
|
|
|
@@ -7,7 +7,7 @@ This audit judges if the specification holds the correct rules with the correct
|
|
|
7
7
|
## Items to report
|
|
8
8
|
|
|
9
9
|
1. A REQUIRED rule that must be ⚠️ Advisory (see Severity).
|
|
10
|
-
2. A rule that belongs in `AGENTS.md`, a scoped rule, a skill, a command, the OpenSpec configuration or a README. The placement guide is
|
|
10
|
+
2. A rule that belongs in `AGENTS.md`, a scoped rule, a skill, a command, the OpenSpec configuration or a README. The placement guide is [rules/agent.md](../../../../rules/agent.md).
|
|
11
11
|
3. A rule that a deterministic tool can enforce better than an AI audit.
|
|
12
12
|
4. A rule that causes tests of low value or artificial tests.
|
|
13
13
|
5. A rule whose tests satisfy the wording while failing to protect the intent.
|
|
@@ -7689,7 +7689,7 @@ var init_citations = __esmMin((() => {
|
|
|
7689
7689
|
CITE = /((?:\.{1,2}\/)*(?:[\w@.-]+\/)*?openspec\/specs\/[\w./-]*?spec\.md)(?:#([\w-]+))?/g;
|
|
7690
7690
|
SKIP = /(?:^|\/)(?:node_modules|dist|build|coverage|\.git|\.nx|\.yarn|\.yalc|\.turbo|\.next|\.docusaurus|\.eve)(?:\/|$)|^openspec\/changes\/|(?:^|\/)spec\.md$/;
|
|
7691
7691
|
TEST_FILE = /(?:^|\/)(?:__tests__|e2e)\/|\.(?:test|spec|test-d)\.[cm]?[jt]sx?$|(?:^|\/)test_[^/]+\.py$|_test\.(?:py|go)$/;
|
|
7692
|
-
LINT_CONFIG = /(?:^|\/)(?:(?:eslint|vite)\.config\.[cm]?[jt]s|yarn\.config\.cjs)$/;
|
|
7692
|
+
LINT_CONFIG = /(?:^|\/)(?:(?:eslint|vite|lint)\.config\.[cm]?[jt]s|yarn\.config\.cjs)$/;
|
|
7693
7693
|
isTestFile = (file) => TEST_FILE.test(file) && !isDoc(file);
|
|
7694
7694
|
isLintConfig = (file) => LINT_CONFIG.test(file);
|
|
7695
7695
|
anchorCache = /* @__PURE__ */ new Map();
|
|
@@ -9184,7 +9184,7 @@ function wireCli(opts, root) {
|
|
|
9184
9184
|
const labels = {
|
|
9185
9185
|
agents: "AGENTS.md routes to spec-steward",
|
|
9186
9186
|
rule: ".agents/rules/openspec.md (or .claude/rules) is linked by lint-prepare",
|
|
9187
|
-
skill: ".agents/skills/spec-steward (or .claude/skills) is
|
|
9187
|
+
skill: ".agents/skills/spec-steward (or .claude/skills) is installed by lint-prepare",
|
|
9188
9188
|
hook: ".claude/settings.json runs the edit hook",
|
|
9189
9189
|
opsx: `openspec/config apply/archive guidance points at the repository's spec gate (${GATE_POINTER})`
|
|
9190
9190
|
};
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-verify
|
|
3
|
-
description: Audit whether the code satisfies the intent of the OpenSpec specifications; its verdict gates CI.
|
|
3
|
+
description: Audit whether the code satisfies the intent of the OpenSpec specifications; its verdict gates CI. Finds what no tool can - cross-capability contradictions, code that misses a requirement's intent, bound tests that do not assert their scenario, gaps nobody recorded. Use for a code-conformance audit (`spec-tools audit`) or after changing a capability (`/spec-verify changed`). Not for corpus quality (the `spec-steward` skill).
|
|
4
4
|
model: claude-haiku-5-5
|
|
5
5
|
effort: high
|
|
6
6
|
---
|