Skip to content

Commit fd96f03

Browse files
thibaudcolasthibaudcolas
committed
Add experimental agent skill for Stylelint upgrade
1 parent f9439e8 commit fd96f03

1 file changed

Lines changed: 204 additions & 0 deletions

File tree

  • .agents/skills/upgrading-stylelint-config

‎.agents/skills/upgrading-stylelint-config/SKILL.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
name: upgrading-stylelint-config
3+
description: Upgrades a Stylelint configuration to a new Stylelint major release
4+
license: MIT
5+
metadata:
6+
audience: maintainers
7+
# Hide the skill from discovery: https://github.com/vercel-labs/skills#optional-fields
8+
internal: true
9+
disable-model-invocation: true
10+
---
11+
12+
## Overview
13+
14+
Comprehensive project and dependencies review to identify needed changes to upgrade this project to a new Stylelint version, and potential opt-in improvements based on any changes in the release.
15+
16+
## Methodology
17+
18+
### Goals
19+
20+
- Upgrade the project to the target Stylelint release, including any needed dependencies upgrades.
21+
- Baseline QA that the upgrade works correctly - linting passes, test suite passes, all with no deprecation warnings if possible.
22+
- A thorough upgrade report for the user (upgrade methodology, what changed, what further tests to do, links to relevant information), ideally with guidance on opt-in changes to consider.
23+
24+
### Guardrails
25+
26+
- Prefer minimal, reviewable changes. Avoid introducing technical debt.
27+
- Make dependency updates explicit and reproducible (lockfile updates included).
28+
- No fixes unrelated to the upgrade (like linting/formatting), unless required for the QA checks to pass.
29+
- If a change is ambiguous, choose the option with the least technical debt. Ask for further input if needed.
30+
- When there are issues that seem like bugs in the dependencies, encourage the user to report back with feedback for maintainers.
31+
32+
### Input
33+
34+
To detect from the context or request from the user if unclear:
35+
36+
- Agent mode: whether we want to provide an audit of the needed work for an upgrade, or actually directly do the upgrade. Default: assume "direct update on current code".
37+
- Current versions of Node, Stylelint. Default: read from project configuration (`node --version`, `npm info . peerDependencies`)
38+
- Target version for Stylelint. Default: assume "latest", fetch the [CHANGELOG](https://raw.githubusercontent.com/stylelint/stylelint/refs/heads/main/CHANGELOG.md) and check which version is latest based on the current date.
39+
40+
### Reference data sources
41+
42+
Always fetch latest information from the official Stylelint docs if possible.
43+
44+
- [Official CHANGELOG](https://raw.githubusercontent.com/stylelint/stylelint/refs/heads/main/CHANGELOG.md)
45+
- Example: [Stylelint 17 migration guide (Markdown source)](https://raw.githubusercontent.com/stylelint/stylelint/refs/heads/main/docs/migration-guide/to-17.md)
46+
- Example: [Stylelint 17 migration guide (web page)](https://stylelint.io/migration-guide/to-17)
47+
48+
Combine it with project-specific information:
49+
50+
- Guidance for contributors in `CONTRIBUTING.md`.
51+
- Upgrade considerations / test plans / documentation on customizations.
52+
53+
### Reporting
54+
55+
Upgrades are sensitive tasks, it’s critical you provide clear information to the user throughout the upgrade tasks, with clear requests for any extra input. And as a comprehensive report at the end.
56+
57+
- Use text formatting if supported (tables, lists, Markdown links)
58+
- Link directly to release notes and other documentation pages where relevant.
59+
- When sharing docs references in reporting, make sure to link to the HTML pages.
60+
- Report on both your methodology, and the outcome.
61+
- Use artifacts in addition to messages if supported.
62+
63+
### Commit and pull request strategy
64+
65+
If the current task mode is to work directly on the project code, commit regularly on a new branch unless otherwise noted by project instructions.
66+
67+
Commit for:
68+
69+
- Version upgrades of dependencies
70+
- Fixes in the code
71+
- Fixes / additions in test suites
72+
- Documentation updates
73+
74+
Push if allowed from current permissions or after user confirmation, when:
75+
76+
- We want to see results from Continuous Integration tools.
77+
- We want human review.
78+
- We think the work is done.
79+
80+
### Quality Assurance
81+
82+
Options to check that the upgrade works correctly, to use as needed through upgrade steps:
83+
84+
- Linting passes: `npm run lint`
85+
- Test suite passes: `npm run test`
86+
- Rules tests passes: `npm run test:rules`
87+
- Docs updates work: `npm run build:docs`
88+
- Any other automated or manual checks documented for the project (test plans? upgrade considerations?)
89+
90+
Look for any deprecation warnings coming from Stylelint in particular.
91+
92+
### Definition of done
93+
94+
- Dependency files + lockfiles updated and consistent (`package.json` and `package-lock.json`)
95+
- Test suite / QA tools / CI all passing
96+
- No new deprecation warnings introduced (or explicitly documented)
97+
- CHANGELOG updated
98+
- Any relevant project doc is updated
99+
- Upgrade report created
100+
101+
## Steps
102+
103+
### Confirm upgrade path
104+
105+
- [ ] Confirm all input sources from the upgrade methodology.
106+
- [ ] Retrieve the current Node / Stylelint versions from context or user input
107+
- [ ] Determine the target Stylelint version ("latest" or a specific version number)
108+
- [ ] Fetch [Stylelint migration guides](https://github.com/stylelint/stylelint/tree/main/docs/migration-guide) and use the listing to confirm which releases are along the upgrade path, from current to target.
109+
- [ ] Report the upgrade path to the user.
110+
111+
At this stage, if there are multiple Stylelint versions on the upgrade path, make sure that all subsequent work is done in sequence for every one of those versions. For example, upgrading from Stylelint v14 to v16 should involve running through all the steps in this file with v15 as the target; then asking the user to confirm the successful v15 upgrade; then restarting this all from v15 to v16.
112+
113+
### Baseline setup and QA
114+
115+
- [ ] Check for project-specific information about quality assurance tools and methodologies, dependencies management, and upgrades considerations.
116+
- [ ] Create a branch for the upgrade (check any conventions for branch names, or `upgrade-stylelint-vX`)
117+
- [ ] Run the project’s QA tools / test suite to capture a baseline. At least tests and linting.
118+
119+
### Dependencies audit and upgrades
120+
121+
You may need to do this in a different order depending on whether dependency compatibility issues are reported when upgrading to the new Stylelint version.
122+
123+
- [ ] Use `npm info . devDependencies`, `npm info . dependencies`, `npm info . peerDependencies` to confirm the current versions of all of the project’s dependencies ahead of the upgrades.
124+
- [ ] Uninstall all of the project’s `dependencies` with npm (not dev or peer dependencies).
125+
- [ ] Fetch the [stylelint-find-new-rules CHANGELOG](https://raw.githubusercontent.com/Donov4n/stylelint-find-new-rules/refs/heads/master/CHANGELOG.md) to check which version of this package is compatible with our target Stylelint version.
126+
- [ ] Use `npm install --save-dev --save-exact stylelint@<version> stylelint-find-new-rules@<version>` to install the target Stylelint and stylelint-find-new-rules versions.
127+
- [ ] Fetch the CHANGELOGs of our dependencies, to check which versions of each package is compatible with our target Stylelint version, and any upgrade considerations we need to take into account.
128+
- [ ] Fetch the [stylelint-config-standard-scss CHANGELOG](https://raw.githubusercontent.com/stylelint-scss/stylelint-config-standard-scss/refs/heads/main/CHANGELOG.md).
129+
- [ ] Fetch the [stylelint-declaration-strict-value CHANGELOG](https://raw.githubusercontent.com/AndyOGo/stylelint-declaration-strict-value/refs/heads/master/CHANGELOG.md).
130+
- [ ] Fetch the [stylelint-order CHANGELOG](https://raw.githubusercontent.com/hudochenkov/stylelint-order/refs/heads/master/CHANGELOG.md).
131+
- [ ] Install the versions determined to be compatible with our Stylelint target. Move the `dependencies` definition in package.json to be in the same lines of the file it was before.
132+
- [ ] Report the needed dependencies upgrades to the user
133+
- [ ] Update the project’s documentation about dependencies to reflect any of those changes.
134+
- [ ] Use the project’s QA tools / test suite as needed when doing the upgrades.
135+
136+
Note any warnings or errors from npm or from the project’s QA tools. Those might indicate further actions needed for the upgrades to be successful. You may need to move to the subsequent steps to resolve them.
137+
138+
### Apply official upgrade guidance
139+
140+
- [ ] Fetch the Stylelint CHANGELOG and migration guide from the next version on the upgrade path, from the official docs.
141+
- [ ] Review the required actions and think about which ones are likely to affect this project.
142+
- [ ] Keep the project’s Node version as-is if it’s already higher than the Stylelint support.
143+
- [ ] Review the project’s implementation of Stylelint APIs, to identify possible code that needs changes.
144+
- [ ] Report your findings to the user. Consider providing a "Status" for every entry in the migration guide, even if just to report the current project is "Not affected"
145+
146+
### Rules updates
147+
148+
This is crucial for the success of the upgrade, and we have bespoke tools to facilitate this.
149+
150+
- [ ] Use `npm run test:rules` to determine which new rules have been introduced.
151+
- [ ] Update `src/unused.js`, making sure to add any new rules in the correct section (look at the guidance inside the file).
152+
- [ ] If in doubt, move the rules to a new section inside the `toReview` array so this can be further reviewed at a later date.
153+
- [ ] Use `npm run test -- -u` to update the project’s snapshots. This is crucial to understand which rule changes will affect users of this project.
154+
155+
### Update the CHANGELOG
156+
157+
Add a new entry in the CHANGELOG, following this set template, with examples replaced with the rules updates relevant for this release:
158+
159+
```markdown
160+
### Features
161+
162+
- Update stylelint to v<version> and up.
163+
- If relevant: Update all config dependencies to their latest releases, compatible with stylelint v<version>.
164+
- If relevant: Change enforced rules from Stylelint and `stylelint-config-standard-scss` (see list below).
165+
166+
### BREAKING CHANGES
167+
168+
The configuration now mandates stylelint v<version>. {Add commentary about the major highlights of the release if relevant}. See Stylelint’s official [Migrating to <version>](https://stylelint.io/migration-guide/to-<version>) documentation.
169+
170+
#### New rules configuration
171+
172+
| Rule | Purpose | Set to | Was set to |
173+
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------- |
174+
| [`at-rule-no-deprecated`](https://stylelint.io/user-guide/rules/at-rule-no-deprecated/) | Disallow deprecated at-rules | `true` | New rule |
175+
| [`scss/load-no-partial-leading-underscore`](https://github.com/stylelint-scss/stylelint-scss/blob/master/src/rules/load-no-partial-leading-underscore/README.md) | Replaces `scss/at-import-no-partial-leading-underscore` Disallow leading underscore in partial names in `@import`, `@use`, `@forward`, and [`meta.load-css`](https://sass-lang.com/documentation/modules/meta/#load-css) `$url` parameter | `true` | New rule |
176+
| [`scss/dollar-variable-colon-space-after`](https://github.com/stylelint-scss/stylelint-scss/blob/master/src/rules/dollar-variable-colon-space-after/README.md) | Require or disallow whitespace after the colon in `$`-variable declarations. | `always-single-line` | `always` |
177+
178+
#### New unused rules
179+
180+
- [`unit-allowed-list`](https://stylelint.io/user-guide/rules/unit-allowed-list/)
181+
- [`unit-disallowed-list`](https://stylelint.io/user-guide/rules/unit-disallowed-list/)
182+
```
183+
184+
For the key rules sections,
185+
186+
- [ ] Populate "New rules configuration" for newly-introduced rules, which will show as additions in the git diff of `src/__snapshots__/semver.test.js.snap`.
187+
- [ ] Populate "New rules configuration" for config changes on existing rules, which will show as additions + deletions inside `src/__snapshots__/semver.test.js.snap`.
188+
- [ ] Populate "New unused rules" based on the changes in the diff of `src/unused.js`.
189+
190+
### Update documentation
191+
192+
- [ ] Update the README to reflect the new target Stylelint version number in any examples.
193+
- [ ] If relevant, update the project’s README to reflect any improvements in Stylelint that users could benefit from.
194+
- [ ] Review whether there is any further project documentation to update, and make necessary changes if so.
195+
- [ ] If the project documents "upgrade considerations" for future updates, add information if necessary.
196+
197+
### Produce the upgrade report
198+
199+
- [ ] Check specific instructions from the user / coding harness on how to report information.
200+
- [ ] Report on any assumptions you took while interpreting the methodology for upgrades.
201+
- [ ] Add your reporting for every step in the upgrade process.
202+
- [ ] Report on any opt-in changes from the Stylelint release notes that haven’t been applied.
203+
- [ ] If it seems helpful, produce a manual test plan for the user.
204+
- [ ] If it seems helpful, produce a recap of relevant changes that can be shared with users of this project.

0 commit comments

Comments
 (0)