Skip to content

Commit e3f1405

Browse files
chore: add vendored reference repo subtree sync tooling (pingdotgg#2902)
Co-authored-by: codex <[email protected]>
1 parent b3e8c03 commit e3f1405

1,925 files changed

Lines changed: 657533 additions & 3 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.oxfmtrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
"$schema": "./node_modules/oxfmt/configuration_schema.json",
33
"ignorePatterns": [
44
".reference",
5+
".repos/**",
56
".plans",
67
"dist",
78
"dist-electron",

‎.oxlintrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
"ignorePatterns": [
44
"dist",
55
"dist-electron",
6+
".repos/**",
67
"node_modules",
78
"bun.lock",
89
"*.tsbuildinfo",
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: grill-me
3+
description: Interview the user about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
4+
---
5+
6+
Interview me about every aspect of this plan until we reach a shared understanding and a defensible design.
7+
8+
Ask exactly one question at a time, then wait for my answer before asking the next question.
9+
10+
Use each answer to choose the next highest-leverage unresolved question. Maintain an implicit decision tree of resolved decisions, open questions, assumptions, dependencies, risks, and rejected alternatives.
11+
12+
For each question, include:
13+
14+
- clear answer options when appropriate
15+
- your recommended answer, marked as recommended
16+
- a brief reason for the recommendation
17+
18+
Use open-ended questions when fixed options would prematurely constrain the design space.
19+
20+
Challenge vague, inconsistent, risky, or unsupported assumptions. If an answer creates a contradiction or unresolved dependency, ask a follow-up before moving on.
21+
22+
Cover, as relevant:
23+
24+
- goals and non-goals
25+
- users and stakeholders
26+
- constraints
27+
- alternatives
28+
- APIs and interfaces
29+
- data model
30+
- error handling
31+
- security
32+
- observability
33+
- testing
34+
- migration and rollout
35+
- failure modes
36+
- operational ownership
37+
- success criteria
38+
39+
If repository facts are needed, inspect the codebase instead of asking the user. Do not ask me to provide information that can be determined locally.
40+
41+
When an available user-input tool such as `request_user_input` fits the question, use it to ask one short question with a small set of mutually exclusive options. Otherwise, ask in plain text and present clear possible answers as a numbered list when that helps me answer quickly. Include your recommended option and mark it as recommended.
42+
43+
Stop when the major branches of the design tree have been resolved. Then summarize the agreed design, remaining risks, assumptions, rejected alternatives, and next steps.
Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
name: jsdocs
3+
description: Write, insert, or update Effect public API JSDoc so it satisfies the jsdocs oxlint rule. Use when adding or fixing JSDoc comments, resolving jsdocs diagnostics, preparing docs for JSON extraction, or reviewing public API documentation.
4+
---
5+
6+
Use this skill to write well-formed JSDoc for Effect public APIs.
7+
8+
## Workflow
9+
10+
When updating public API JSDoc:
11+
12+
1. Inspect the declaration, implementation, nearby tests, and nearby JSDoc before editing.
13+
2. Decide whether the task is a single API fix or a module refinement pass.
14+
3. Rewrite comments into the required documentation shape while preserving correct facts and examples.
15+
4. For module refinements, complex APIs, or APIs with related alternatives, run the `@see` and `**Gotchas**` audits.
16+
5. Run the narrowest relevant validation.
17+
18+
## Required documentation shape
19+
20+
Use a normal multiline JSDoc comment in TypeScript source:
21+
22+
```ts
23+
/**
24+
* Short description as one paragraph.
25+
*
26+
* **When to use**
27+
*
28+
* Optional practical usage guidance.
29+
*
30+
* **Details**
31+
*
32+
* Optional details for complex APIs, options, overloads, or behavior.
33+
*
34+
* **Gotchas**
35+
*
36+
* Optional edge cases, footguns, or surprising behavior.
37+
*
38+
* **Example** (Short title)
39+
*
40+
* Optional prose explaining the example.
41+
*
42+
* ```ts
43+
* const result = example()
44+
* ```
45+
*
46+
* @category constructors
47+
* @since 1.0.0
48+
*/
49+
```
50+
51+
## Prose Rules
52+
53+
- Use sober, practical prose.
54+
- Write all public JSDoc prose in English.
55+
- Do not use jargon when a plain word works.
56+
- Do not be clever.
57+
- Do not add filler sections.
58+
- The short description is required and must be exactly one paragraph.
59+
- Make the short description stand on its own. Do not rely on `**When to use**`
60+
to make the API understandable.
61+
- For functions and methods, prefer present-tense, action-first prose such as
62+
`Creates`, `Returns`, `Checks`, `Provides`, `Represents`, `Converts`,
63+
`Decodes`, or `Formats`.
64+
- For technical value exports, use consistent noun forms such as `Schema for`,
65+
`Layer that`, `Service that`, `Context reference that`, or
66+
`Constructors and matchers for`.
67+
- Avoid leading `A` or `An` for canonical technical nouns when the surrounding
68+
module uses a standard noun family, for example prefer `Schema for ...` over
69+
`A schema for ...`.
70+
- Do not describe implementation mechanics when a public concept is clearer.
71+
For example, prefer `Constructors and matchers for ...` over wording that
72+
only says an API uses `Data.taggedEnum`.
73+
- Avoid generic purity or non-mutation remarks unless they document a real
74+
surprise, caveat, or meaningful contrast with a mutating-looking API.
75+
- Optional sections must appear in this order:
76+
1. `**When to use**`
77+
2. `**Details**`
78+
3. `**Gotchas**`
79+
- Include an optional section only when it has useful, non-empty content.
80+
- Prefer prose over bullet lists for single-item `**Details**`, `**When to use**`, or `**Gotchas**` sections. Use bullets only when there are two or more parallel facts, options, cases, or caveats.
81+
- `**When to use**` describes the positive use case for the documented API. Do not use it as a routing section for sibling APIs. If neighboring APIs need to be mentioned, put that boundary in `@see` tag text instead.
82+
- `**When to use**` is important when the API has close alternatives, trade-offs, or `@see` tags. If `@see` tags are present, inspect the referenced APIs and add `**When to use**` when it clarifies the documented API's own use case.
83+
- `**When to use**` must start with one of these practical guidance forms: `Use to`, `Use when`, `Use as`, or `Use with`. Avoid bullet lists and vague openers such as `Use this...` or `Useful for...`.
84+
- Keep `short` and `**When to use**` distinct: the short description says what
85+
the API is or does; `**When to use**` says when to choose it.
86+
- Add internal `@see` tags only for semantically useful related public APIs.
87+
- Write `@see` tag text as normal prose after the link; no special separator is required. Prefer forms like `@see {@link otherApi} for ...` when a short explanation helps.
88+
- Use exactly one blank line between the short description, sections, examples, and tags.
89+
- Do not use Markdown headings such as `# Heading` or ad hoc bold headings such as `**Notes**`; only the standard headings are allowed.
90+
- Examples must use `**Example** (Title)`, optional prose, and exactly one non-empty `ts` code fence.
91+
- Example titles must be unique after trimming and lowercasing.
92+
- Prefer examples with stable, deterministic output. Avoid assertions or
93+
`console.log` comments that depend on stack traces, object inspection,
94+
`Error` formatting, concurrency order, timing, randomness, or
95+
environment-specific formatting. Examples may assume Node.js console
96+
formatting. Direct `Set` / `Map` output is acceptable when insertion order is
97+
deterministic and the expected output uses Node's format; otherwise
98+
demonstrate a stable property instead.
99+
- Do not use `@example`.
100+
- Do not put TypeScript code fences outside `**Example** (Title)` sections.
101+
- Inline `{@link Symbol}` targets must resolve to TypeScript symbols; do not link to URLs with `{@link}`.
102+
- Avoid overlinking in prose. Use `{@link Symbol}` only when navigation to
103+
that symbol helps the reader choose or understand the API. For the API being
104+
documented, the module's central type, nearby obvious names, or repeated
105+
mentions, prefer plain code formatting such as `Cause`, `Effect`, or
106+
`Context`.
107+
- Do not document module-level comments; module JSDoc is ignored by this rule.
108+
- `@internal` means the item is ignored; do not rewrite it as public docs.
109+
- Default exports are ignored by this rule and do not need JSDoc.
110+
- Do not add unsupported constructs such as enums or empty exports in checked files.
111+
- For low-level public values, prefer accurate categories such as `symbols`,
112+
`type IDs`, or `prototypes` over compensating with verbose descriptions.
113+
114+
## Tag rules
115+
116+
When multiple tags are present, keep them in this order:
117+
118+
1. `@deprecated`
119+
2. `@default`
120+
3. `@see`
121+
4. `@category`
122+
5. `@since`
123+
124+
Tag requirements by declaration kind:
125+
126+
- Root declarations require `@category` and stable-semver `@since`, and must
127+
not use `@default`.
128+
- Namespaces and declarations inside namespaces require stable-semver `@since`,
129+
may use `@category`, and must not use `@default`.
130+
- Member JSDoc is optional. When present, it follows the same prose and layout
131+
rules, may use optional stable-semver `@since`, may use non-empty `@default`,
132+
and must not use `@category`.
133+
- Any declaration may use `@deprecated` with a non-empty message and repeated
134+
non-empty `@see` tags for semantically useful related public APIs.
135+
136+
## Updating existing JSDoc
137+
138+
When fixing or updating existing docs:
139+
140+
1. Preserve correct facts and examples.
141+
2. Rewrite the layout into the standard template.
142+
3. Move usage guidance into `**When to use**`, behavior details into `**Details**`, and real caveats into `**Gotchas**`.
143+
4. Convert `@example` tags and loose `ts` fences into `**Example** (Title)` sections.
144+
5. Preserve valid `@see`, `@deprecated`, `@default`, `@category`, and `@since` tags.
145+
6. Remove `@see` tags that do not point to semantically useful related public APIs.
146+
7. Replace redundant inline `{@link ...}` tags with plain code formatting when
147+
the link target is already obvious from the current declaration or module.
148+
8. Remove sections that would be empty.
149+
150+
## Module refinement
151+
152+
When asked to refine an existing module:
153+
154+
1. First scan the module for local documentation patterns, repeated API families, and category conventions.
155+
2. Keep the change focused on documentation quality unless the user also asked for rule or source changes.
156+
3. Prefer improving existing comments over rewriting every comment into a new voice.
157+
4. Preserve examples unless they are wrong, stale, nondeterministic, or fail
158+
the required documentation shape.
159+
5. Apply the `@see` and `**Gotchas**` audits across the module before finishing.
160+
161+
## See audit
162+
163+
When refining an existing public API module, always do a dedicated `@see` pass:
164+
165+
1. Inspect existing `@see` tags and referenced APIs before keeping, changing, or removing them.
166+
2. Look for close alternatives in the same module or API family when the documented API is one of several ways to do similar work.
167+
3. Keep or add `@see` only when the linked API is semantically useful to understand the documented API.
168+
4. Good `@see` targets include sibling APIs, alternatives, inverse operations, lower-level or higher-level variants, complementary operations, and closely returned, consumed, or configured types/values.
169+
5. Do not use `@see` for implementation dependencies, broad concepts, external background links, APIs that merely share a word or name, helper APIs used only inside examples, undocumented/private members, or APIs that are only generally compatible.
170+
6. When `@see` tags are kept or added, include `**When to use**` guidance if the documented API's own use case is not obvious from the short description. Keep comparisons with sibling APIs in the `@see` tag text.
171+
172+
## Gotchas audit
173+
174+
When refining an existing public API module, always do a dedicated `**Gotchas**` pass:
175+
176+
1. Scan existing prose for caveat language: warnings, exceptions, limitations, preconditions, special cases, or behavior that is easy to misuse.
177+
2. Inspect the implementation and nearby tests for behavior that is not obvious from the type signature or short description.
178+
3. Move real caveats from `**Details**` into `**Gotchas**` when they describe edge cases, footguns, preconditions, surprising behavior, or important failure modes.
179+
4. Add `**Gotchas**` only when the caveat is concrete and useful to a reader choosing or using the API.
180+
5. If no gotchas are added during a refinement pass, state that a gotchas audit was performed and why no caveats were worth documenting.
181+
182+
## Validation
183+
184+
Run the narrowest validation that matches the change:
185+
186+
- For JSDoc or example changes in a package with generated docs, run `pnpm docgen` from that package directory.
187+
- Run `pnpm lint` because the linter includes the custom rule that checks public API JSDoc.
188+
- Do not run broad validation for prose-only skill edits.
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: scratchpad
3+
description: Extract the JSDoc example nearest the active source selection or cursor into ./scratchpad as a TypeScript file. Use when the user asks to dump, copy, open, or try a source example in scratchpad.
4+
---
5+
6+
Use this skill to create a scratchpad TypeScript file from the JSDoc `**Example**`
7+
nearest the user's active source cursor or selection.
8+
9+
## Workflow
10+
11+
1. Determine the source path and line:
12+
- Use the IDE active file and selection/cursor line when present.
13+
- Use an explicit file and line when the user provides them.
14+
- If no line or selection is available, ask for it.
15+
2. Run:
16+
17+
```sh
18+
node .agents/skills/scratchpad/scripts/extract-example.mjs <source-path> <line>
19+
```
20+
21+
3. If the script exits with code 2 because there is no obvious runner, ask the
22+
user whether to preserve the example exactly, name an Effect value to run, or
23+
cancel.
24+
- To preserve exactly, rerun with `--mode preserve`.
25+
- To run a specific Effect value, rerun with `--runner <identifier>`.
26+
4. Report the created path as a clickable file link. This is the deterministic
27+
way to open it in the code pane.
28+
5. Do not run the scratchpad file unless the user explicitly asks.
29+
30+
## Behavior
31+
32+
- The script chooses the example whose `**Example**` section contains the line;
33+
otherwise it chooses the first following example; otherwise the nearest
34+
previous example.
35+
- Filenames are derived from the source file and example title, for example
36+
`scratchpad/Schedule-retrying-and-repeating-effects.ts`.
37+
- Existing files are not overwritten. The script appends a numeric suffix.
38+
- In auto mode, if a top-level `program` binding exists, the script appends:
39+
40+
```ts
41+
Effect.runPromise(program).then(console.log, console.error)
42+
```
43+
44+
- If the example already contains an Effect runner, the script preserves it.
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
interface:
2+
display_name: "Scratchpad"
3+
short_description: "Extract examples into scratchpad"
4+
default_prompt: "Use $scratchpad to extract the active JSDoc example into scratchpad."
5+
6+
policy:
7+
allow_implicit_invocation: true

0 commit comments

Comments
 (0)