@theholocron/skills 1.3.3 → 1.12.1-alpha.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.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: discuss
3
+ description: Discussion / RFC Agent. INVOKE WHEN: an architectural decision needs engineering review before being finalized. Converts design analysis into a structured GitHub Discussion.
4
+ ---
5
+
6
+ # Discussion / RFC Agent
7
+
8
+ Convert the design analysis into a GitHub Discussion suitable for engineering
9
+ review.
10
+
11
+ Include:
12
+
13
+ # Problem
14
+
15
+ # Context
16
+
17
+ # Constraints
18
+
19
+ # Options
20
+
21
+ For each option:
22
+
23
+ - description
24
+ - advantages
25
+ - disadvantages
26
+ - operational consequences
27
+ - implementation complexity
28
+
29
+ # Recommended Direction
30
+
31
+ State the recommendation as a proposal, not a decision.
32
+
33
+ # Open Questions
34
+
35
+ # Decision Requested
36
+
37
+ Avoid implementation-level details unless they materially affect the
38
+ architectural choice.
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  name: git-safety
3
+ title: Git Safety
3
4
  description: Git safety rules. INVOKE WHEN: git push, force push, git reset, git clean, destructive git operations. NEVER force push or do destructive git operations without explicit permission.
4
5
  ---
5
6
 
@@ -30,14 +31,17 @@ If you find yourself about to run one of these, stop and ask the user first.
30
31
  ## safe alternatives
31
32
 
32
33
  **Instead of `git reset --hard`:**
34
+
33
35
  - `git stash` to save changes temporarily
34
36
  - `git stash pop` to restore them later
35
37
 
36
38
  **Instead of force push:**
39
+
37
40
  - `git pull --rebase` then normal push to reconcile diverged history
38
41
  - If history is intentionally diverged, stop and ask the user how they want to proceed
39
42
 
40
43
  **Instead of `git clean -fd`:**
44
+
41
45
  - `git stash --include-untracked` to preserve files
42
46
  - Review untracked files with `git status` before deciding to delete
43
47
 
@@ -0,0 +1,278 @@
1
+ ---
2
+ name: holocron-skill-client
3
+ title: "Holocron: New Client"
4
+ description: Scaffold a new @theholocron/<slug>-client package in the clients folder of theholocron/holocron. INVOKE WHEN: user asks to add a new HTTP client package to the clients group. Invoked as /holocron-skill-client.
5
+ ---
6
+
7
+ <!-- editorconfig-checker-disable-file -->
8
+
9
+ # Scaffold a new client package
10
+
11
+ Scaffold a new `@theholocron/<slug>-client` package in `clients/` of `theholocron/holocron`.
12
+ The standalone `theholocron/clients` repo is archived; do not scaffold there.
13
+
14
+ Replace `<slug>` with the vendor name in kebab-case (e.g. `slack`, `stripe`),
15
+ `<Vendor>` with PascalCase (e.g. `Slack`, `Stripe`), and `<BASE_URL>` with
16
+ the API root (e.g. `https://api.stripe.com`).
17
+
18
+ Reference implementations: `clients/axiom-client` (smallest current example —
19
+ `createRestClient`, `stubFetch`, DI fetch, optional `logger` / `errors` sinks)
20
+ and `clients/http-client` (the shared primitives every client builds on).
21
+ Read `clients/axiom-client/package.json` and copy its shape rather than
22
+ trusting this template if they ever disagree.
23
+
24
+ ---
25
+
26
+ ## 1. Create the package directory
27
+
28
+ ```
29
+ clients/<slug>-client/
30
+ ├── src/
31
+ │ ├── index.ts
32
+ │ ├── index.test.ts
33
+ │ ├── utils.ts
34
+ │ └── <resource>/<resource>.ts
35
+ ├── package.json
36
+ ├── tsconfig.json
37
+ ├── tsdown.config.ts
38
+ ├── vitest.config.ts
39
+ └── README.md
40
+ ```
41
+
42
+ The workspace glob `clients/*` in `pnpm-workspace.yaml` already covers the new
43
+ folder, and knip's `clients/*` entry covers `src/index.ts` and `src/**/*.test.ts`,
44
+ so neither file needs editing. Tests live beside the module they cover
45
+ (`foo.test.ts`); there is no `__tests__` directory. There is no per-package
46
+ `LICENSE`, `CHANGELOG.md`, `eslint.config.ts` (the root config applies) or
47
+ `.releaserc`.
48
+
49
+ ---
50
+
51
+ ## 2. Config files
52
+
53
+ **`clients/<slug>-client/package.json`**
54
+
55
+ ```json
56
+ {
57
+ "name": "@theholocron/<slug>-client",
58
+ "version": "<current clients version>",
59
+ "description": "A TypeScript client for the <Vendor> API",
60
+ "keywords": ["<slug>", "typescript", "http-client", "api"],
61
+ "homepage": "https://docs.theholocron.dev/holocron/clients/<slug>/",
62
+ "bugs": "https://github.com/theholocron/holocron/issues",
63
+ "repository": {
64
+ "type": "git",
65
+ "url": "git+https://github.com/theholocron/holocron.git",
66
+ "directory": "clients/<slug>-client"
67
+ },
68
+ "license": "MIT",
69
+ "author": "Newton Koumantzelis",
70
+ "sideEffects": false,
71
+ "type": "module",
72
+ "exports": {
73
+ ".": {
74
+ "types": "./dist/index.d.mts",
75
+ "import": "./dist/index.mjs",
76
+ "default": "./dist/index.mjs"
77
+ }
78
+ },
79
+ "files": ["dist"],
80
+ "scripts": {
81
+ "build": "tsdown && node ../scripts/check-bundle-size.mjs",
82
+ "lint:code": "eslint .",
83
+ "test:watch": "vitest",
84
+ "typecheck": "tsc --noEmit",
85
+ "test:unit": "vitest run"
86
+ },
87
+ "dependencies": {
88
+ "@theholocron/http-client": "workspace:^",
89
+ "@theholocron/observability": "catalog:"
90
+ },
91
+ "devDependencies": {
92
+ "@theholocron/eslint-config": "catalog:configs",
93
+ "@theholocron/tsconfig": "catalog:configs",
94
+ "@theholocron/tsdown-config": "catalog:configs",
95
+ "@theholocron/vitest-config": "catalog:configs",
96
+ "@types/node": "catalog:",
97
+ "@vitest/coverage-v8": "catalog:",
98
+ "@vitest/eslint-plugin": "catalog:",
99
+ "eslint": "catalog:",
100
+ "eslint-plugin-n": "catalog:",
101
+ "globals": "catalog:",
102
+ "tsdown": "catalog:",
103
+ "typescript": "catalog:",
104
+ "vitest": "catalog:"
105
+ },
106
+ "engines": { "node": ">=22.0.0" },
107
+ "publishConfig": { "access": "public" }
108
+ }
109
+ ```
110
+
111
+ - **`version`**: read it from any sibling (`clients/http-client/package.json`);
112
+ the whole `clients/` folder is one version group (tags `clients-vX.Y.Z`, one
113
+ `clients/CHANGELOG.md`). `holocron publish bump-versions --group clients`
114
+ moves every package in the group together at release.
115
+ - **License is MIT** (ADR-0016). No `releases` or `wiki` fields.
116
+ - `homepage` uses the slug **without** `-client` (`.../clients/axiom/`),
117
+ matching the docs page you add in step 5.
118
+ - Inside the group, `@theholocron/http-client` is `workspace:^`. Everything
119
+ from `configs/` is `catalog:configs`; `@theholocron/*-utils` would be
120
+ `catalog:utils`; third-party deps are `catalog:`. Never pin exact versions.
121
+ - Drop `@theholocron/observability` and the `logger` / `errors` options in
122
+ step 3 only if you deliberately do not want diagnostics hooks.
123
+
124
+ **`tsdown.config.ts`** and **`vitest.config.ts`** are one line each:
125
+
126
+ ```ts
127
+ export { default } from "@theholocron/tsdown-config/presets/library";
128
+ ```
129
+
130
+ ```ts
131
+ export { default } from "@theholocron/vitest-config/bundles/library";
132
+ ```
133
+
134
+ **`tsconfig.json`**
135
+
136
+ ```json
137
+ {
138
+ "display": "<Vendor> API Client",
139
+ "extends": "@theholocron/tsconfig/node-lts",
140
+ "compilerOptions": { "baseUrl": "./", "outDir": "./dist" },
141
+ "include": ["src/**/*.ts"],
142
+ "exclude": ["node_modules", "dist"]
143
+ }
144
+ ```
145
+
146
+ ## 3. Source files
147
+
148
+ ### `src/utils.ts` — REST client factory
149
+
150
+ ```ts
151
+ import { createRestClient, type RestClient } from "@theholocron/http-client";
152
+ import type { ErrorSink, Logger } from "@theholocron/observability/core";
153
+
154
+ export type { RestClient };
155
+
156
+ export interface <Vendor>ClientOptions {
157
+ /** <Vendor> API token. */
158
+ token: string;
159
+ /** Override base URL for testing. Defaults to <BASE_URL>. */
160
+ baseUrl?: string;
161
+ /** Override fetch for testing. Defaults to globalThis.fetch. */
162
+ fetch?: typeof fetch;
163
+ /** Structured logger for request/response diagnostics. Defaults to a no-op. */
164
+ logger?: Logger;
165
+ /** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
166
+ errors?: ErrorSink;
167
+ }
168
+
169
+ export function create<Vendor>RestClient(opts: <Vendor>ClientOptions): RestClient {
170
+ return createRestClient({
171
+ baseUrl: opts.baseUrl ?? "<BASE_URL>",
172
+ token: opts.token,
173
+ vendor: "<Vendor>",
174
+ fetch: opts.fetch,
175
+ logger: opts.logger,
176
+ errors: opts.errors,
177
+ });
178
+ }
179
+ ```
180
+
181
+ ### `src/<resource>/<resource>.ts` — one file per API resource
182
+
183
+ Each takes the `RestClient` and returns its methods (see
184
+ `clients/axiom-client/src/datasets/datasets.ts`).
185
+
186
+ ### `src/index.ts` — factory and public API
187
+
188
+ ```ts
189
+ import { <resource> } from "./<resource>/<resource>.js";
190
+ import { type <Vendor>ClientOptions, create<Vendor>RestClient } from "./utils.js";
191
+
192
+ export type { <Vendor>ClientOptions } from "./utils.js";
193
+
194
+ export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
195
+ const rest = create<Vendor>RestClient(opts);
196
+ return { <resource>: <resource>(rest) };
197
+ }
198
+
199
+ export type <Vendor>Client = ReturnType<typeof create<Vendor>Client>;
200
+ ```
201
+
202
+ ### `src/index.test.ts` — use `stubFetch`
203
+
204
+ ```ts
205
+ import { stubFetch } from "@theholocron/http-client/testing";
206
+ import { describe, expect, it } from "vitest";
207
+
208
+ import { create<Vendor>Client } from "./index.js";
209
+
210
+ describe("create<Vendor>Client", () => {
211
+ it("sends Bearer authorization header", async () => {
212
+ const { fetch, calls } = stubFetch([{ body: {} }]);
213
+ const client = create<Vendor>Client({ token: "t", fetch });
214
+ await client.<resource>.<method>();
215
+ expect(calls[0]?.headers.authorization).toBe("Bearer t");
216
+ });
217
+ });
218
+ ```
219
+
220
+ Tests use `stubFetch` (dependency-injected fetch), never `vi.stubGlobal`.
221
+ Cover every public method and the error path.
222
+
223
+ ### `README.md`
224
+
225
+ Same shape as `clients/axiom-client/README.md`: title, one-line description,
226
+ Installation (`pnpm add @theholocron/<slug>-client`), Usage, API tables, License.
227
+
228
+ ## 4. Monorepo registration
229
+
230
+ 1. **Install**: run `pnpm install` from the repo root. It links the new
231
+ workspace package and updates `pnpm-lock.yaml`; commit the lockfile.
232
+ 2. **Codecov**: `codecov.yml` has one component per package under the
233
+ `# clients` heading (`component_id: <slug>-client`, `paths: clients/<slug>-client/**`).
234
+ The file is generated by `holocron setup` (the "write codecov.yml" step,
235
+ `codecovConfig()` in `cli/astromech/src/generators/codecov`), which needs
236
+ tokens for its other steps, so in practice add the block by hand in exactly
237
+ that format, keeping the list alphabetical.
238
+ 3. **Release**: nothing to edit. `release.config.ts` and the `release`
239
+ task in `astromech.config.ts` release the whole `clients` group by folder.
240
+ 4. **Dependency catalog**: only if something outside `clients/` (a plugin, the
241
+ CLI) will consume the package, add it to `catalogs.clients` in
242
+ `pnpm-workspace.yaml` after it has been published, and reference it as
243
+ `catalog:clients`.
244
+
245
+ ## 5. Docs
246
+
247
+ - Add `docs/src/content/docs/clients/<slug>.mdx` (frontmatter `title`,
248
+ `description`; copy `axiom.mdx`).
249
+ - Add a row to the table in `docs/src/content/docs/clients/index.mdx`.
250
+ - Add `{ label: "<slug>-client", slug: "clients/<slug>" }` to the Clients
251
+ group of the sidebar in the root `astro.config.ts` (alphabetical).
252
+
253
+ ## 6. Non-negotiables
254
+
255
+ 1. `version` matches the current `clients/` group version.
256
+ 2. `repository.directory` is `clients/<slug>-client`; license `MIT`.
257
+ 3. `@theholocron/http-client` is `workspace:^`, never a pinned version.
258
+ 4. Tests use `stubFetch` beside the source; no `__tests__` directory.
259
+ 5. Docs page, index row, sidebar entry and codecov component ship in the same PR.
260
+
261
+ ## 7. Checklist before opening a PR
262
+
263
+ - [ ] Issue filed first; feature branch created from `origin/alpha` before any code
264
+ - [ ] `pnpm install` — workspace symlink created, lockfile updated
265
+ - [ ] `pnpm --filter @theholocron/<slug>-client typecheck` passes
266
+ - [ ] `pnpm --filter @theholocron/<slug>-client lint:code` passes
267
+ - [ ] `pnpm --filter @theholocron/<slug>-client test:unit` passes
268
+ - [ ] `pnpm --filter @theholocron/<slug>-client build` — `dist/` emitted
269
+ - [ ] `version` in `package.json` matches the clients group
270
+ - [ ] `codecov.yml` component added
271
+ - [ ] Docs page, `clients/index.mdx` row and `astro.config.ts` sidebar entry added
272
+ - [ ] `holocron run ci` passes
273
+ - [ ] PR title is a Conventional Commit (`feat(clients): ...`); commits signed (`-s`)
274
+ - [ ] CI green before requesting review
275
+
276
+ After merge, the first publish of a brand-new package needs
277
+ `holocron publish package --initial --group clients` run by a maintainer
278
+ (npm Trusted Publishing needs the package to exist first); do not run it yourself.
@@ -0,0 +1,246 @@
1
+ ---
2
+ name: holocron-skill-config
3
+ title: "Holocron: New Config"
4
+ description: Scaffold a new shareable config package in the configs folder of theholocron/holocron. INVOKE WHEN: user asks to add a new @theholocron/<tool>-config package to the configs group. Invoked as /holocron-skill-config.
5
+ ---
6
+
7
+ <!-- editorconfig-checker-disable-file -->
8
+
9
+ # Scaffold a new config package
10
+
11
+ Scaffold a new shareable config package in `configs/` of `theholocron/holocron`.
12
+ The standalone `theholocron/configs` repo is archived; do not scaffold there.
13
+
14
+ ## When to use
15
+
16
+ When the user asks to add a new `@theholocron/<tool>-config` package.
17
+
18
+ Reference implementations: `configs/prettier-config` (single default export),
19
+ `configs/commitlint-config` (same, with peers), and `configs/vitest-config` /
20
+ `configs/tsdown-config` (multi-preset, with `presets/` and `bundles/`). Read
21
+ the sibling's `package.json` and copy its shape if this template ever disagrees.
22
+
23
+ ## What to produce
24
+
25
+ Unlike clients and utils, a config package keeps its sources at the package
26
+ root (no `src/`), and its test sits beside `index.ts`:
27
+
28
+ ```
29
+ configs/<tool>-config/
30
+ ├── package.json
31
+ ├── index.ts (or named-export entry; use presets/ for multi-preset)
32
+ ├── index.test.ts
33
+ ├── tsdown.config.ts
34
+ ├── tsconfig.json
35
+ ├── vitest.config.ts
36
+ └── README.md
37
+ ```
38
+
39
+ Multi-preset packages add `presets/*.ts` (and optionally `bundles/*.ts`, a
40
+ preset plus opinionated settings) and re-export them from `index.ts`.
41
+
42
+ There is no per-package `LICENSE` or `.releaserc`, and you do not create a
43
+ `CHANGELOG.md`: the whole `configs/` folder is one version group with a single
44
+ `configs/CHANGELOG.md`. The workspace glob `configs/*` in `pnpm-workspace.yaml`
45
+ already covers the new folder.
46
+
47
+ ## File templates
48
+
49
+ ### `package.json`
50
+
51
+ ```json
52
+ {
53
+ "name": "@theholocron/<tool>-config",
54
+ "version": "<current configs version>",
55
+ "description": "A <Tool> configuration for <purpose>.",
56
+ "keywords": ["<tool>", "config", "theholocron"],
57
+ "homepage": "https://docs.theholocron.dev/holocron/configs/<tool>-config/",
58
+ "bugs": "https://github.com/theholocron/holocron/issues",
59
+ "repository": {
60
+ "type": "git",
61
+ "url": "git+https://github.com/theholocron/holocron.git",
62
+ "directory": "configs/<tool>-config"
63
+ },
64
+ "license": "MIT",
65
+ "author": "Newton Koumantzelis",
66
+ "sideEffects": false,
67
+ "type": "module",
68
+ "exports": {
69
+ ".": {
70
+ "types": "./dist/index.d.ts",
71
+ "import": "./dist/index.js",
72
+ "default": "./dist/index.js"
73
+ },
74
+ "./package.json": "./package.json"
75
+ },
76
+ "files": ["dist/"],
77
+ "scripts": {
78
+ "build": "tsdown",
79
+ "lint:code": "eslint .",
80
+ "test:watch": "vitest",
81
+ "typecheck": "tsc --noEmit",
82
+ "test:unit": "vitest run"
83
+ },
84
+ "devDependencies": {
85
+ "@theholocron/tsconfig": "workspace:*",
86
+ "@theholocron/vitest-config": "workspace:*",
87
+ "@vitest/coverage-v8": "catalog:",
88
+ "tsdown": "catalog:",
89
+ "typescript": "catalog:",
90
+ "vitest": "catalog:"
91
+ },
92
+ "peerDependencies": {
93
+ "<tool>": "^<major>"
94
+ },
95
+ "engines": { "node": ">=22.0.0" },
96
+ "publishConfig": { "access": "public" }
97
+ }
98
+ ```
99
+
100
+ - **`version`**: copy it from any sibling (`configs/prettier-config/package.json`).
101
+ The `configs/` folder is a version group (tags `configs-vX.Y.Z`);
102
+ `holocron publish bump-versions --group configs` moves every package together.
103
+ - **License is MIT** (ADR-0016). No `releases` or `wiki` fields.
104
+ - Packages inside the group reference each other as `workspace:*`; third-party
105
+ dev tooling is `catalog:`. Never pin exact versions for those.
106
+ - The tool being configured goes in `peerDependencies`. Optional-per-preset
107
+ peers also go under `peerDependenciesMeta`:
108
+ `"peerDependenciesMeta": { "<tool>": { "optional": true } }`.
109
+ - Export each preset/bundle as a subpath (`"./presets/node"`,
110
+ `"./bundles/library"`, …) with `types` / `import` / `default` pointing at `dist/`.
111
+ `files: ["dist/"]` covers them.
112
+
113
+ ### `tsdown.config.ts`
114
+
115
+ Config packages build with a plain tsdown config, not the shared `library`
116
+ preset: the preset lives in `@theholocron/tsdown-config`, which is itself a
117
+ config package, and these packages must not depend on the one they bootstrap.
118
+
119
+ ```ts
120
+ import { defineConfig } from "tsdown";
121
+ export default defineConfig({
122
+ entry: ["index.ts"],
123
+ format: "esm",
124
+ fixedExtension: false,
125
+ dts: true,
126
+ clean: true,
127
+ });
128
+ ```
129
+
130
+ For multi-preset packages list every entry point:
131
+
132
+ ```ts
133
+ entry: ["index.ts", "presets/node.ts", "presets/react.ts", "bundles/library.ts"],
134
+ ```
135
+
136
+ ### `tsconfig.json`
137
+
138
+ ```json
139
+ {
140
+ "extends": "@theholocron/tsconfig/node-lts",
141
+ "compilerOptions": { "rootDir": ".", "outDir": "dist" },
142
+ "include": ["**/*.ts"],
143
+ "exclude": ["dist", "node_modules", "tsdown.config.ts"]
144
+ }
145
+ ```
146
+
147
+ ### `vitest.config.ts`
148
+
149
+ ```ts
150
+ import { node } from "@theholocron/vitest-config";
151
+ import { defineConfig } from "vitest/config";
152
+ export default defineConfig(node());
153
+ ```
154
+
155
+ ### `index.ts` (single default export)
156
+
157
+ ```ts
158
+ import type { Config } from "<tool>";
159
+
160
+ const config = {
161
+ // ...
162
+ } satisfies Config;
163
+
164
+ export default config;
165
+ ```
166
+
167
+ ### `index.ts` (named presets / multi-export)
168
+
169
+ ```ts
170
+ export { node } from "./presets/node.js";
171
+ export { react } from "./presets/react.js";
172
+ ```
173
+
174
+ Relative imports in config sources use `.js` extensions (TypeScript's ESM
175
+ convention); the resolver finds the `.ts` file at build time.
176
+
177
+ ### `index.test.ts` (beside `index.ts`, no `__tests__` directory)
178
+
179
+ ```ts
180
+ import { describe, it, expect } from "vitest";
181
+ import config from "./index.js";
182
+
183
+ describe("<tool>-config", () => {
184
+ it("exports a non-empty config object", () => {
185
+ expect(typeof config).toBe("object");
186
+ expect(Object.keys(config).length).toBeGreaterThan(0);
187
+ });
188
+ });
189
+ ```
190
+
191
+ ### `README.md`
192
+
193
+ Follow `configs/prettier-config/README.md`: title, one-line description linking
194
+ the tool's own docs, Installation (`pnpm add -D @theholocron/<tool>-config <tool>`),
195
+ Usage with the exact file the user creates, then optional presets/bundles.
196
+ Keep it short; link to official docs rather than duplicating them.
197
+
198
+ ## Monorepo registration
199
+
200
+ 1. Run `pnpm install` from the repo root (links the workspace package, updates
201
+ `pnpm-lock.yaml`; commit the lockfile).
202
+ 2. **Codecov**: add a component under the `# configs` heading of `codecov.yml`
203
+ (`component_id: <tool>-config`, `paths: configs/<tool>-config/**`), alphabetical.
204
+ The file is generated by `holocron setup` ("write codecov.yml" step,
205
+ `cli/astromech/src/generators/codecov`); that command needs tokens for its
206
+ other steps, so add the block by hand in exactly that format.
207
+ 3. **knip**: `knip.config.ts` has a `configs/*` workspace entry (`configPackage()`).
208
+ Add a dedicated entry only if the package lists optional peers knip should
209
+ ignore (see `configs/eslint-config` there).
210
+ 4. **Release**: nothing to edit; the `configs` group releases by folder.
211
+ 5. **Dependency catalog**: if other workspaces (packages in `clients/`, `utils/`,
212
+ plugins, the CLI) will consume it, add it to `catalogs.configs` in
213
+ `pnpm-workspace.yaml` once it has been published and use `catalog:configs`.
214
+ 6. **Docs**: add `docs/src/content/docs/configs/<tool>-config.mdx`
215
+ (frontmatter `title`, `description`; copy `prettier-config.mdx`), a row in
216
+ `docs/src/content/docs/configs/index.mdx`, and
217
+ `{ label: "<tool>-config", slug: "configs/<tool>-config" }` to the Configs
218
+ group of the sidebar in the root `astro.config.ts` (alphabetical).
219
+
220
+ ## Non-negotiables
221
+
222
+ - **TypeScript source, compiled to `dist/` via tsdown.** Never publish raw `.ts`
223
+ or add plain `.js` source. `"files"` must be `["dist/"]`.
224
+ - **Match `version` to the configs group** — read a sibling's `package.json`.
225
+ - **Peer deps, not regular deps.** The tool being configured is a peer.
226
+ - **Deprecation notice** if replacing an existing package — add a banner at the
227
+ top of the old package's `README.md` pointing to the replacement.
228
+ - Tests live beside the source (`index.test.ts`); no `__tests__` directory.
229
+
230
+ ## Checklist
231
+
232
+ 1. Create `configs/<tool>-config/` with the files above.
233
+ 2. `devDependencies` include `@theholocron/tsconfig` and
234
+ `@theholocron/vitest-config` (`workspace:*`), plus `@vitest/coverage-v8`,
235
+ `tsdown`, `typescript`, `vitest` (`catalog:`).
236
+ 3. `scripts` use the task names `build`, `test:unit`,
237
+ `typecheck`, `lint:code`.
238
+ 4. `pnpm install`, then `pnpm --filter @theholocron/<tool>-config` run
239
+ `build`, `test:unit`, `typecheck` and
240
+ `lint:code` — all must pass.
241
+ 5. `codecov.yml` component, docs page, `configs/index.mdx` row and sidebar entry added.
242
+ 6. `holocron run ci` passes.
243
+ 7. Open a PR with a `feat(configs):` commit, signed with `-s` — semantic-release
244
+ computes the next `configs-v*` version and publishes the group in lockstep.
245
+ The first publish of a brand-new package needs
246
+ `holocron publish package --initial --group configs` run by a maintainer.
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  name: holocron-skill-plugin
3
+ title: "Holocron: New Plugin"
3
4
  description: Scaffold a new @theholocron/holocron-plugin-<slug> package. INVOKE WHEN: user asks to add a new provider plugin to theholocron/holocron. Since v2.0.0-alpha, use the CLI command instead. Invoked as /holocron-skill-plugin.
4
5
  ---
5
6
 
@@ -41,10 +42,21 @@ Then follow the "Next" steps printed by the command:
41
42
  5. Commit + push when the capability is functionally complete.
42
43
  6. **Wire a typed client** once `@theholocron/<slug>-client` exists.
43
44
 
45
+ ## Checklist before opening a PR
46
+
47
+ - [ ] Feature branch created before any code was written
48
+ - [ ] `pnpm --filter @theholocron/holocron-plugin-<slug> typecheck` passes
49
+ - [ ] `pnpm --filter @theholocron/holocron-plugin-<slug> lint` passes
50
+ - [ ] `pnpm --filter @theholocron/holocron-plugin-<slug> test` passes
51
+ - [ ] Plugin entry added to the docs-theme registry
52
+ - [ ] Docs page added under `docs/` in the same PR
53
+ - [ ] PR title follows Conventional Commits
54
+ - [ ] CI green before requesting review
55
+
44
56
  ## Step 6: migrate to a typed client
45
57
 
46
58
  The scaffolded `rest.ts` uses the raw `createRestClient` from `@theholocron/cli`.
47
- Once a typed client package exists in `theholocron/clients`, replace it:
59
+ Once a typed client package exists in `clients/` of this repo (`@theholocron/<slug>-client`), replace it:
48
60
 
49
61
  **`src/rest.ts`** — swap to a re-export:
50
62
 
@@ -61,7 +73,7 @@ export {
61
73
  ```yaml
62
74
  # pnpm-workspace.yaml
63
75
  catalog:
64
- "@theholocron/<slug>-client": ^<version>
76
+ "@theholocron/<slug>-client": ^<version>
65
77
  ```
66
78
 
67
79
  ```json
@@ -73,6 +85,7 @@ catalog:
73
85
  ## Auth pattern (4-step precedence)
74
86
 
75
87
  Every plugin's `auth.ts` follows this order:
88
+
76
89
  1. `--token` CLI flag (`RuntimeContext.cliToken`)
77
90
  2. `HOLOCRON_<VENDOR>_TOKEN` env var
78
91
  3. `<VENDOR_NATIVE_ENV_VAR>` env var