Skip to content

Commit c242a01

Browse files
maiieulmaiieul
authored
Merge pull request #8776 from QwikDev/update-ruler
Update ruler
2 parents c3b933c + 50e146d commit c242a01

6 files changed

Lines changed: 213 additions & 141 deletions

File tree

‎.claude/skills/qwik-docs-development/SKILL.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,3 +94,25 @@ Set `QWIK_LLMS_BASE_URL` only when intentionally testing alternate generated lin
9494
changed.
9595
- If docs source or scripts contradict this skill, update the skill before finishing or record why
9696
guidance edits were out of scope.
97+
98+
## No Hydration Terminology
99+
100+
Never describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is
101+
resumable: the server serializes application state and listeners into the HTML, and the client
102+
resumes execution exactly where the server left off, without re-running component code or
103+
rebuilding the framework state.
104+
105+
- Do not call any Qwik mechanism "hydration", "hydrating", "rehydration", "partial hydration",
106+
"progressive hydration", "selective hydration", or "island hydration".
107+
- Do not describe Qwik components, containers, or apps as "hydrated" or "needing to hydrate".
108+
- Use the Qwik terminilogy instead: "javascript streaming", "JIT preloading", "resumability", "resume", "resuming", "serialization", "deserialization", and "lazy execution".
109+
- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,
110+
or hydrating the app.
111+
112+
### Allowed Mentions
113+
114+
The word "hydration" may appear only when explicitly contrasting Qwik with hydration-based
115+
frameworks, and the sentence must make clear that hydration is what other frameworks do and what
116+
Qwik avoids. For example: "Unlike frameworks that hydrate on the client, Qwik resumes from
117+
serialized state." Never use hydration vocabulary, even casually or by analogy, to explain what
118+
Qwik itself does.

‎.codex/skills/qwik-docs-development/SKILL.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,3 +94,25 @@ Set `QWIK_LLMS_BASE_URL` only when intentionally testing alternate generated lin
9494
changed.
9595
- If docs source or scripts contradict this skill, update the skill before finishing or record why
9696
guidance edits were out of scope.
97+
98+
## No Hydration Terminology
99+
100+
Never describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is
101+
resumable: the server serializes application state and listeners into the HTML, and the client
102+
resumes execution exactly where the server left off, without re-running component code or
103+
rebuilding the framework state.
104+
105+
- Do not call any Qwik mechanism "hydration", "hydrating", "rehydration", "partial hydration",
106+
"progressive hydration", "selective hydration", or "island hydration".
107+
- Do not describe Qwik components, containers, or apps as "hydrated" or "needing to hydrate".
108+
- Use the Qwik terminilogy instead: "javascript streaming", "JIT preloading", "resumability", "resume", "resuming", "serialization", "deserialization", and "lazy execution".
109+
- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,
110+
or hydrating the app.
111+
112+
### Allowed Mentions
113+
114+
The word "hydration" may appear only when explicitly contrasting Qwik with hydration-based
115+
frameworks, and the sentence must make clear that hydration is what other frameworks do and what
116+
Qwik avoids. For example: "Unlike frameworks that hydrate on the client, Qwik resumes from
117+
serialized state." Never use hydration vocabulary, even casually or by analogy, to explain what
118+
Qwik itself does.

‎.ruler/AGENTS.md‎

Lines changed: 49 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,12 @@ commands:
5050
### getting started
5151

5252
```bash
53-
# Setup — once per checkout, and again after dependency changes
54-
pnpm install && pnpm build.core
53+
pnpm i
54+
```
55+
56+
```bash
57+
pnpm build.core # for a fresh start
58+
pnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)
5559
```
5660
### Iterating
5761

@@ -73,7 +77,7 @@ pnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --confi
7377

7478
For Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.
7579

76-
Run `pnpm build.full` only when you are touching the optimizer rust code.
80+
Re-run `pnpm build.full` when you are touching the optimizer rust code.
7781

7882
### When making a PR
7983

@@ -118,27 +122,10 @@ Follow that bias:
118122
- Keep new durable lessons in the most specific skill or reference that future agents are likely to
119123
load. Do not add package-specific details to these always-on rules unless they affect most tasks.
120124
- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,
121-
where things live, and how to verify — rather than describing how the code currently works (the
122-
source already does that). Omit "don't do X" prohibitions for anything a test already enforces; the
125+
where things live, and how to verify — rather than describing how the code currently works. Omit "don't do X" prohibitions for anything a test already enforces; the
123126
suite is the guardrail, so reserve notes for what it can't self-enforce.
124127
- When updating guidance, load the `qwik-guidance-maintenance` skill.
125128

126-
### Code Style
127-
128-
Prettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing
129-
commas where configured, and always use braces for control flow.
130-
131-
Naming conventions:
132-
133-
| Pattern | Usage |
134-
| --- | --- |
135-
| `use*` | Hooks called in component/task scope |
136-
| `*$` | QRL boundary extracted by the optimizer |
137-
| `create*` | Factory functions |
138-
| `*.unit.ts(x)` | Vitest unit files |
139-
| `*.spec.ts(x)` | Vitest spec files |
140-
| `*.e2e.ts` | Playwright e2e files |
141-
142129
### Skill Selection
143130

144131
Load the relevant skill before non-trivial work in that area:
@@ -162,22 +149,21 @@ the skill list unambiguous outside the repo-local `.ruler` tree.
162149

163150
When a change affects published packages, add a changeset under `.changeset/`.
164151

165-
- Use `patch` for bug fixes, `minor` for new features and `major` for API removal. A `major` may also include a new feature, but it must remove or break a public API.
152+
- Use `patch` for bug fixes: focus on the issue rather than the solution.
153+
- `minor` for new features: explain the new feature.
154+
- `major` for API removal: may also include a new feature, but it must remove or break a public API.
166155
- Enforce 1 changeset per change.
167156
- Write the changeset summary in lowercase (e.g. `fix:`)
168-
- 1 sentence focused on the bug fix or feature. Don't include implementation details.
157+
- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.
169158

170159
### Code Quality
171160

172-
Write code that junior developers and AI agents can understand during review and future changes.
173161

174162
#### Sanity
175163

176-
- Prefer local semantic helpers over broad rewrites when they make state, ordering, or ownership
177-
clearer.
178-
- Do not leave debug logging, temporary names, "fixup" code, or unexplained broad fallbacks in the
179-
final diff.
180-
- Only add explanatory comments where absolutely necessary, only to warn and crucial information that is not self-explanatory. Write comments for humans: keep your comments constrained to 1 short sentence or 2 maximum; be mindful of character count; focus on explaning the crux of the issue rather than implementation details.
164+
- Remember to keep your code DRY.
165+
- Do not leave debug logging or temporary names in the final diff.
166+
- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.
181167
- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.
182168

183169
#### Naming
@@ -218,27 +204,21 @@ Before finishing, read the changed code as if you are new to the package:
218204

219205
If the answer is no, simplify the code before calling the task complete.
220206

221-
### No Hydration Terminology
222-
223-
Never describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is
224-
resumable: the server serializes application state and listeners into the HTML, and the client
225-
resumes execution exactly where the server left off, without re-running component code or
226-
rebuilding the framework state.
207+
### Code Style
227208

228-
- Do not call any Qwik mechanism "hydration", "hydrating", "rehydration", "partial hydration",
229-
"progressive hydration", "selective hydration", or "island hydration".
230-
- Do not describe Qwik components, containers, or apps as "hydrated" or "needing to hydrate".
231-
- Use the Qwik terminilogy instead: "javascript streaming", "JIT preloading", "resumability", "resume", "resuming", "serialization", "deserialization", and "lazy execution".
232-
- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,
233-
or hydrating the app.
209+
Prettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing
210+
commas where configured, and always use braces for control flow.
234211

235-
#### Allowed Mentions
212+
Naming conventions:
236213

237-
The word "hydration" may appear only when explicitly contrasting Qwik with hydration-based
238-
frameworks, and the sentence must make clear that hydration is what other frameworks do and what
239-
Qwik avoids. For example: "Unlike frameworks that hydrate on the client, Qwik resumes from
240-
serialized state." Never use hydration vocabulary, even casually or by analogy, to explain what
241-
Qwik itself does.
214+
| Pattern | Usage |
215+
| --- | --- |
216+
| `use*` | Hooks called in component/task scope |
217+
| `*$` | QRL boundary extracted by the optimizer |
218+
| `create*` | Factory functions |
219+
| `*.unit.ts(x)` | Vitest unit files |
220+
| `*.spec.ts(x)` | Vitest spec files |
221+
| `*.e2e.ts` | Playwright e2e files |
242222

243223
### Security And Supply Chain
244224

@@ -340,3 +320,25 @@ is resolved.
340320
task.
341321
- Do not commit `.only` tests.
342322
- Do not skip tests for behavior changes; use the closest focused test first.
323+
324+
### No Hydration Terminology
325+
326+
Never describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is
327+
resumable: the server serializes application state and listeners into the HTML, and the client
328+
resumes execution exactly where the server left off, without re-running component code or
329+
rebuilding the framework state.
330+
331+
- Do not call any Qwik mechanism "hydration", "hydrating", "rehydration", "partial hydration",
332+
"progressive hydration", "selective hydration", or "island hydration".
333+
- Do not describe Qwik components, containers, or apps as "hydrated" or "needing to hydrate".
334+
- Use the Qwik terminilogy instead: "javascript streaming", "JIT preloading", "resumability", "resume", "resuming", "serialization", "deserialization", and "lazy execution".
335+
- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,
336+
or hydrating the app.
337+
338+
#### Allowed Mentions
339+
340+
The word "hydration" may appear only when explicitly contrasting Qwik with hydration-based
341+
frameworks, and the sentence must make clear that hydration is what other frameworks do and what
342+
Qwik avoids. For example: "Unlike frameworks that hydrate on the client, Qwik resumes from
343+
serialized state." Never use hydration vocabulary, even casually or by analogy, to explain what
344+
Qwik itself does.

‎.ruler/skills/qwik-docs-development/SKILL.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,3 +94,25 @@ Set `QWIK_LLMS_BASE_URL` only when intentionally testing alternate generated lin
9494
changed.
9595
- If docs source or scripts contradict this skill, update the skill before finishing or record why
9696
guidance edits were out of scope.
97+
98+
## No Hydration Terminology
99+
100+
Never describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is
101+
resumable: the server serializes application state and listeners into the HTML, and the client
102+
resumes execution exactly where the server left off, without re-running component code or
103+
rebuilding the framework state.
104+
105+
- Do not call any Qwik mechanism "hydration", "hydrating", "rehydration", "partial hydration",
106+
"progressive hydration", "selective hydration", or "island hydration".
107+
- Do not describe Qwik components, containers, or apps as "hydrated" or "needing to hydrate".
108+
- Use the Qwik terminilogy instead: "javascript streaming", "JIT preloading", "resumability", "resume", "resuming", "serialization", "deserialization", and "lazy execution".
109+
- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,
110+
or hydrating the app.
111+
112+
### Allowed Mentions
113+
114+
The word "hydration" may appear only when explicitly contrasting Qwik with hydration-based
115+
frameworks, and the sentence must make clear that hydration is what other frameworks do and what
116+
Qwik avoids. For example: "Unlike frameworks that hydrate on the client, Qwik resumes from
117+
serialized state." Never use hydration vocabulary, even casually or by analogy, to explain what
118+
Qwik itself does.

‎AGENTS.md‎

Lines changed: 49 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,12 @@ commands:
5555
### getting started
5656

5757
```bash
58-
# Setup — once per checkout, and again after dependency changes
59-
pnpm install && pnpm build.core
58+
pnpm i
59+
```
60+
61+
```bash
62+
pnpm build.core # for a fresh start
63+
pnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)
6064
```
6165
### Iterating
6266

@@ -78,7 +82,7 @@ pnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --confi
7882

7983
For Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.
8084

81-
Run `pnpm build.full` only when you are touching the optimizer rust code.
85+
Re-run `pnpm build.full` when you are touching the optimizer rust code.
8286

8387
### When making a PR
8488

@@ -123,27 +127,10 @@ Follow that bias:
123127
- Keep new durable lessons in the most specific skill or reference that future agents are likely to
124128
load. Do not add package-specific details to these always-on rules unless they affect most tasks.
125129
- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,
126-
where things live, and how to verify — rather than describing how the code currently works (the
127-
source already does that). Omit "don't do X" prohibitions for anything a test already enforces; the
130+
where things live, and how to verify — rather than describing how the code currently works. Omit "don't do X" prohibitions for anything a test already enforces; the
128131
suite is the guardrail, so reserve notes for what it can't self-enforce.
129132
- When updating guidance, load the `qwik-guidance-maintenance` skill.
130133

131-
### Code Style
132-
133-
Prettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing
134-
commas where configured, and always use braces for control flow.
135-
136-
Naming conventions:
137-
138-
| Pattern | Usage |
139-
| --- | --- |
140-
| `use*` | Hooks called in component/task scope |
141-
| `*$` | QRL boundary extracted by the optimizer |
142-
| `create*` | Factory functions |
143-
| `*.unit.ts(x)` | Vitest unit files |
144-
| `*.spec.ts(x)` | Vitest spec files |
145-
| `*.e2e.ts` | Playwright e2e files |
146-
147134
### Skill Selection
148135

149136
Load the relevant skill before non-trivial work in that area:
@@ -167,22 +154,21 @@ the skill list unambiguous outside the repo-local `.ruler` tree.
167154

168155
When a change affects published packages, add a changeset under `.changeset/`.
169156

170-
- Use `patch` for bug fixes, `minor` for new features and `major` for API removal. A `major` may also include a new feature, but it must remove or break a public API.
157+
- Use `patch` for bug fixes: focus on the issue rather than the solution.
158+
- `minor` for new features: explain the new feature.
159+
- `major` for API removal: may also include a new feature, but it must remove or break a public API.
171160
- Enforce 1 changeset per change.
172161
- Write the changeset summary in lowercase (e.g. `fix:`)
173-
- 1 sentence focused on the bug fix or feature. Don't include implementation details.
162+
- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.
174163

175164
### Code Quality
176165

177-
Write code that junior developers and AI agents can understand during review and future changes.
178166

179167
#### Sanity
180168

181-
- Prefer local semantic helpers over broad rewrites when they make state, ordering, or ownership
182-
clearer.
183-
- Do not leave debug logging, temporary names, "fixup" code, or unexplained broad fallbacks in the
184-
final diff.
185-
- Only add explanatory comments where absolutely necessary, only to warn and crucial information that is not self-explanatory. Write comments for humans: keep your comments constrained to 1 short sentence or 2 maximum; be mindful of character count; focus on explaning the crux of the issue rather than implementation details.
169+
- Remember to keep your code DRY.
170+
- Do not leave debug logging or temporary names in the final diff.
171+
- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.
186172
- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.
187173

188174
#### Naming
@@ -223,27 +209,21 @@ Before finishing, read the changed code as if you are new to the package:
223209

224210
If the answer is no, simplify the code before calling the task complete.
225211

226-
### No Hydration Terminology
227-
228-
Never describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is
229-
resumable: the server serializes application state and listeners into the HTML, and the client
230-
resumes execution exactly where the server left off, without re-running component code or
231-
rebuilding the framework state.
212+
### Code Style
232213

233-
- Do not call any Qwik mechanism "hydration", "hydrating", "rehydration", "partial hydration",
234-
"progressive hydration", "selective hydration", or "island hydration".
235-
- Do not describe Qwik components, containers, or apps as "hydrated" or "needing to hydrate".
236-
- Use the Qwik terminilogy instead: "javascript streaming", "JIT preloading", "resumability", "resume", "resuming", "serialization", "deserialization", and "lazy execution".
237-
- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,
238-
or hydrating the app.
214+
Prettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing
215+
commas where configured, and always use braces for control flow.
239216

240-
#### Allowed Mentions
217+
Naming conventions:
241218

242-
The word "hydration" may appear only when explicitly contrasting Qwik with hydration-based
243-
frameworks, and the sentence must make clear that hydration is what other frameworks do and what
244-
Qwik avoids. For example: "Unlike frameworks that hydrate on the client, Qwik resumes from
245-
serialized state." Never use hydration vocabulary, even casually or by analogy, to explain what
246-
Qwik itself does.
219+
| Pattern | Usage |
220+
| --- | --- |
221+
| `use*` | Hooks called in component/task scope |
222+
| `*$` | QRL boundary extracted by the optimizer |
223+
| `create*` | Factory functions |
224+
| `*.unit.ts(x)` | Vitest unit files |
225+
| `*.spec.ts(x)` | Vitest spec files |
226+
| `*.e2e.ts` | Playwright e2e files |
247227

248228
### Security And Supply Chain
249229

@@ -346,6 +326,28 @@ is resolved.
346326
- Do not commit `.only` tests.
347327
- Do not skip tests for behavior changes; use the closest focused test first.
348328

329+
### No Hydration Terminology
330+
331+
Never describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is
332+
resumable: the server serializes application state and listeners into the HTML, and the client
333+
resumes execution exactly where the server left off, without re-running component code or
334+
rebuilding the framework state.
335+
336+
- Do not call any Qwik mechanism "hydration", "hydrating", "rehydration", "partial hydration",
337+
"progressive hydration", "selective hydration", or "island hydration".
338+
- Do not describe Qwik components, containers, or apps as "hydrated" or "needing to hydrate".
339+
- Use the Qwik terminilogy instead: "javascript streaming", "JIT preloading", "resumability", "resume", "resuming", "serialization", "deserialization", and "lazy execution".
340+
- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,
341+
or hydrating the app.
342+
343+
#### Allowed Mentions
344+
345+
The word "hydration" may appear only when explicitly contrasting Qwik with hydration-based
346+
frameworks, and the sentence must make clear that hydration is what other frameworks do and what
347+
Qwik avoids. For example: "Unlike frameworks that hydrate on the client, Qwik resumes from
348+
serialized state." Never use hydration vocabulary, even casually or by analogy, to explain what
349+
Qwik itself does.
350+
349351

350352

351353
<!-- Source: .ruler/README.md -->

0 commit comments

Comments
 (0)