@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,52 @@
1
+ ---
2
+ name: spec
3
+ description: Specification Agent. INVOKE WHEN: design decisions are accepted and a formal spec is needed. Describes WHAT the system must do — not how to implement it.
4
+ ---
5
+
6
+ # Specification Agent
7
+
8
+ You are acting as a technical specification author.
9
+
10
+ Create a specification for the requested capability using:
11
+
12
+ - the GitHub issue
13
+ - accepted design decisions
14
+ - accepted ADRs
15
+ - existing system behavior
16
+ - relevant repository documentation
17
+
18
+ Treat accepted ADRs as architectural constraints.
19
+
20
+ The specification should describe WHAT the system must do, not how to implement it.
21
+
22
+ Include:
23
+
24
+ - Objective
25
+ - Background
26
+ - Goals / Non-goals
27
+ - Existing behavior
28
+ - Required behavior
29
+ - Interfaces
30
+ - Data model
31
+ - Validation
32
+ - State transitions
33
+ - Error handling
34
+ - Authorization / security
35
+ - Observability
36
+ - Compatibility requirements
37
+ - Edge cases
38
+ - Testing requirements
39
+ - Acceptance criteria
40
+ - Related ADRs and issues
41
+
42
+ The specification should be detailed enough that another engineer or AI agent
43
+ could implement the feature without seeing the original planning conversation.
44
+
45
+ IMPORTANT: Do not silently make new architectural decisions. If the specification
46
+ requires a decision that has not been established, mark it as an unresolved
47
+ design question and surface it for discussion.
48
+
49
+ ## Process rule
50
+
51
+ File a GitHub issue BEFORE writing the spec. The spec's frontmatter `issue:`
52
+ field must reference it. Order: Issue → Spec → PR → Review → merge.
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: verify
3
+ description: Verification Agent. INVOKE WHEN: implementation review is complete and a final acceptance-criteria check is needed. Creates a requirement matrix against the spec.
4
+ ---
5
+
6
+ # Verification Agent
7
+
8
+ Verify this implementation against the accepted specification.
9
+
10
+ Treat each acceptance criterion as independently testable.
11
+
12
+ Create a requirement matrix containing:
13
+
14
+ - requirement
15
+ - implementation location
16
+ - test coverage
17
+ - status (PASS | PARTIAL | FAIL | NOT TESTED)
18
+ - notes
19
+
20
+ Do not infer compliance merely because related code exists.
21
+ Verify the actual behavior where possible.
22
+ Identify any specification language that is ambiguous or impossible to verify.
@@ -1,88 +0,0 @@
1
- ---
2
- name: commit-standards
3
- description: Commit message standards. INVOKE WHEN: writing a commit message, reviewing a commit, opening a PR. Always use Conventional Commits and sign commits with -s (DCO).
4
- ---
5
-
6
- # commit standards
7
-
8
- ## Conventional Commits
9
-
10
- All commit subjects must follow the Conventional Commits format:
11
-
12
- ```
13
- <type>[optional scope]: <description>
14
- ```
15
-
16
- ### Types
17
-
18
- | Type | Use for |
19
- |------|---------|
20
- | `feat` | New feature (triggers minor version bump) |
21
- | `fix` | Bug fix (triggers patch bump) |
22
- | `chore` | Maintenance that doesn't affect published artifacts |
23
- | `docs` | Documentation-only changes |
24
- | `ci` | CI/workflow changes (won't appear in changelog) |
25
- | `test` | Test additions or changes |
26
- | `refactor` | Code restructuring with no behavior change |
27
- | `perf` | Performance improvement |
28
-
29
- ### Breaking changes
30
-
31
- Append `!` after the type/scope, or add `BREAKING CHANGE:` in the footer:
32
-
33
- ```
34
- feat!: remove deprecated auth endpoint
35
-
36
- BREAKING CHANGE: the /v1/auth endpoint has been removed; use /v2/auth
37
- ```
38
-
39
- ## Gitmoji
40
-
41
- Prefix commit descriptions with the appropriate emoji so intent is visible at a glance in git log. Place the emoji after the colon so the type is still the first token (semantic-release and commitlint parse from the start of the subject):
42
-
43
- ```
44
- feat: ✨ add OAuth2 login flow
45
- fix: 🐛 handle null session on logout
46
- docs: 📝 update deploy prerequisites
47
- ```
48
-
49
- | Type | Emoji |
50
- |------|-------|
51
- | `feat` | ✨ |
52
- | `fix` | 🐛 |
53
- | `docs` | 📝 |
54
- | `chore` | 🔧 |
55
- | `ci` | 👷 |
56
- | `refactor` | ♻️ |
57
- | `test` | 🧪 |
58
- | `perf` | ⚡️ |
59
- | `style` | 💄 |
60
- | `revert` | ⏪ |
61
-
62
- ## DCO — always `git commit -s`
63
-
64
- The `Signed-off-by:` trailer is required on every commit in theholocron repos.
65
- The `-s` flag generates it automatically from your git config:
66
-
67
- ```sh
68
- git commit -s -m "feat: add new thing"
69
- ```
70
-
71
- Result:
72
- ```
73
- feat: add new thing
74
-
75
- Signed-off-by: Your Name <you@example.com>
76
- ```
77
-
78
- Never skip `-s`. Branch protection and CI enforce DCO.
79
-
80
- ## No agent attribution
81
-
82
- Do not add `Co-Authored-By: Claude` or any agent attribution in commits, PRs,
83
- issues, or docs. The author is always the user.
84
-
85
- ## Commit scope
86
-
87
- Keep commits focused. One logical change per commit makes history bisectable and
88
- makes semantic-release versioning accurate.
@@ -1,151 +0,0 @@
1
- ---
2
- name: holocron-skill-client
3
- description: Scaffold a new @theholocron/<slug>-client package in theholocron/clients. INVOKE WHEN: user asks to add a new HTTP client package to the clients monorepo. Invoked as /holocron-skill-client.
4
- ---
5
-
6
- <!-- editorconfig-checker-disable-file -->
7
-
8
- # Scaffold a new client package
9
-
10
- Replace `<slug>` with the vendor name in kebab-case (e.g. `slack`, `stripe`),
11
- `<Vendor>` with PascalCase (e.g. `Slack`, `Stripe`), and `<BASE_URL>` with
12
- the API root (e.g. `https://api.stripe.com`).
13
-
14
- Reference implementation: `packages/zendesk-client` (the canonical example
15
- of the current patterns — `createRestClient`, `stubFetch`, DI fetch).
16
-
17
- ---
18
-
19
- ## 1. Register in the workspace
20
-
21
- Add to `pnpm-workspace.yaml`:
22
-
23
- ```yaml
24
- packages:
25
- - packages/<slug>-client
26
- ```
27
-
28
- Then run `pnpm install` from the repo root.
29
-
30
- ---
31
-
32
- ## 2. Config files (identical across all clients)
33
-
34
- **`packages/<slug>-client/package.json`**
35
-
36
- ```json
37
- {
38
- "name": "@theholocron/<slug>-client",
39
- "version": "0.0.0",
40
- "description": "A TypeScript client for the <Vendor> API",
41
- "homepage": "https://github.com/theholocron/clients/tree/main/packages/<slug>-client#readme",
42
- "bugs": "https://github.com/theholocron/clients/issues",
43
- "repository": {
44
- "type": "git",
45
- "url": "git+https://github.com/theholocron/clients.git",
46
- "directory": "packages/<slug>-client"
47
- },
48
- "license": "GPL-3.0",
49
- "author": "Newton Koumantzelis",
50
- "type": "module",
51
- "main": "./src/index.ts",
52
- "exports": { ".": "./src/index.ts" },
53
- "scripts": {
54
- "build": "tsdown",
55
- "lint": "eslint .",
56
- "test": "vitest run",
57
- "test:watch": "vitest",
58
- "test:coverage": "vitest run --coverage",
59
- "typecheck": "tsc --noEmit"
60
- },
61
- "dependencies": {
62
- "@theholocron/http-client": "<current-lockstep-version>"
63
- },
64
- "devDependencies": {
65
- "@types/node": "^22.0.0",
66
- "@theholocron/eslint-config": "catalog:",
67
- "@theholocron/tsconfig": "catalog:",
68
- "@theholocron/tsdown-config": "catalog:",
69
- "@theholocron/vitest-config": "catalog:",
70
- "@vitest/coverage-v8": "catalog:",
71
- "@vitest/eslint-plugin": "catalog:",
72
- "eslint": "catalog:",
73
- "eslint-plugin-n": "catalog:",
74
- "globals": "catalog:",
75
- "tsdown": "catalog:",
76
- "typescript": "catalog:",
77
- "vitest": "catalog:"
78
- },
79
- "publishConfig": {
80
- "access": "public",
81
- "main": "./dist/index.mjs",
82
- "types": "./dist/index.d.mts",
83
- "exports": {
84
- ".": {
85
- "types": "./dist/index.d.mts",
86
- "import": "./dist/index.mjs",
87
- "default": "./dist/index.mjs"
88
- }
89
- }
90
- },
91
- "files": ["dist", "README.md"],
92
- "engines": { "node": ">=22.0.0" },
93
- "releases": "https://github.com/theholocron/clients/releases"
94
- }
95
- ```
96
-
97
- ## 3. Source files
98
-
99
- ### `src/client.ts` — REST client factory
100
-
101
- ```ts
102
- import { createRestClient, type RestClient } from "@theholocron/http-client";
103
-
104
- export interface <Vendor>ClientOptions {
105
- token: string;
106
- fetch?: typeof fetch;
107
- }
108
-
109
- export function create<Vendor>RestClient(opts: <Vendor>ClientOptions): RestClient {
110
- return createRestClient({
111
- baseUrl: "<BASE_URL>",
112
- token: opts.token,
113
- vendor: "<Vendor>",
114
- fetch: opts.fetch,
115
- });
116
- }
117
- ```
118
-
119
- ### `src/index.ts` — factory + public API
120
-
121
- ```ts
122
- import { create<Vendor>RestClient } from "./client.js";
123
- import { <resources> } from "./<resources>.js";
124
-
125
- export type { <Vendor>ClientOptions } from "./client.js";
126
- export type * from "./types.js";
127
-
128
- export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
129
- const rest = create<Vendor>RestClient(opts);
130
- return { <resources>: <resources>(rest) };
131
- }
132
- ```
133
-
134
- ## 4. Non-negotiables
135
-
136
- 1. **Add to `.releaserc.json` `prepareCmd`** — alphabetical order. Omitting this leaves
137
- the package frozen at its initial version while all others advance.
138
- 2. **Set initial `version`** in `package.json` to match the current lockstep version.
139
- 3. **Add entry to `codecov.yml`** under `component_management.individual_components`.
140
- 4. **Use `stubFetch`** in tests — DI pattern, no `vi.stubGlobal`.
141
-
142
- ## 5. Checklist before opening a PR
143
-
144
- - [ ] `pnpm install` — workspace symlink created
145
- - [ ] `pnpm --filter @theholocron/<slug>-client typecheck` passes
146
- - [ ] `pnpm --filter @theholocron/<slug>-client lint` passes
147
- - [ ] `pnpm --filter @theholocron/<slug>-client test` passes
148
- - [ ] `pnpm --filter @theholocron/<slug>-client build` — `dist/` emitted
149
- - [ ] `packages/<slug>-client` added to `prepareCmd` in `.releaserc.json`
150
- - [ ] `version` in `package.json` set to current lockstep version
151
- - [ ] `codecov.yml` entry added
@@ -1,236 +0,0 @@
1
- ---
2
- name: holocron-skill-config
3
- description: Scaffold a new shareable config package in theholocron/configs. INVOKE WHEN: user asks to add a new @theholocron/<tool>-config package to the configs monorepo. Invoked as /holocron-skill-config.
4
- ---
5
-
6
- <!-- editorconfig-checker-disable-file -->
7
-
8
- # Scaffold a new config package
9
-
10
- Scaffold a new shareable config package in `theholocron/configs`.
11
-
12
- ## When to use
13
-
14
- When the user asks to add a new `@theholocron/<tool>-config` package to this monorepo.
15
-
16
- ## What to produce
17
-
18
- Seven files in `packages/<tool>-config/`:
19
-
20
- ```
21
- packages/<tool>-config/
22
- ├── package.json
23
- ├── index.ts (or named-export entry; use presets/ for multi-preset)
24
- ├── tsdown.config.ts
25
- ├── tsconfig.json
26
- ├── vitest.config.ts
27
- ├── index.test.ts
28
- └── README.md
29
- ```
30
-
31
- Optionally, if the config needs multiple presets:
32
-
33
- ```
34
- packages/<tool>-config/
35
- ├── package.json
36
- ├── index.ts (re-exports all named presets)
37
- ├── presets/
38
- │ ├── node.ts
39
- │ └── react.ts
40
- ├── bundles/ (preset + opinionated settings combined)
41
- │ └── library.ts
42
- ├── tsdown.config.ts
43
- ├── tsconfig.json
44
- ├── vitest.config.ts
45
- ├── index.test.ts
46
- └── README.md
47
- ```
48
-
49
- ## File templates
50
-
51
- ### `package.json`
52
-
53
- Copy the shape from an existing package (e.g. `packages/prettier-config/package.json`).
54
- Key fields:
55
-
56
- ```json
57
- {
58
- "name": "@theholocron/<tool>-config",
59
- "version": "<current monorepo version>",
60
- "description": "A <Tool> configuration for <purpose>.",
61
- "homepage": "https://github.com/theholocron/configs/tree/main/packages/<tool>-config#readme",
62
- "bugs": "https://github.com/theholocron/configs/issues",
63
- "repository": {
64
- "type": "git",
65
- "url": "git+https://github.com/theholocron/configs.git"
66
- },
67
- "license": "GPL-3.0",
68
- "author": "Newton Koumantzelis",
69
- "keywords": ["<tool>", "config", "theholocron"],
70
- "type": "module",
71
- "main": "dist/index.js",
72
- "scripts": {
73
- "build": "tsdown",
74
- "typecheck": "tsc --noEmit",
75
- "test": "vitest run"
76
- },
77
- "devDependencies": {
78
- "@theholocron/tsconfig": "workspace:*",
79
- "@theholocron/vitest-config": "workspace:*",
80
- "@vitest/coverage-v8": "catalog:",
81
- "tsdown": "catalog:",
82
- "typescript": "catalog:",
83
- "vitest": "catalog:"
84
- },
85
- "exports": {
86
- ".": {
87
- "types": "./dist/index.d.ts",
88
- "import": "./dist/index.js",
89
- "default": "./dist/index.js"
90
- },
91
- "./package.json": "./package.json"
92
- },
93
- "files": ["dist/"],
94
- "peerDependencies": {
95
- "<tool>": "^<major>"
96
- },
97
- "engines": {
98
- "node": ">=22.0.0"
99
- },
100
- "publishConfig": { "access": "public" }
101
- }
102
- ```
103
-
104
- - **Match `version` to the current monorepo version** — check the root `package.json`.
105
- - All peer deps that are optional per-preset go under `peerDependenciesMeta`:
106
- ```json
107
- "peerDependenciesMeta": { "<tool>": { "optional": true } }
108
- ```
109
- - Export each preset/bundle as a subpath (`"./presets/node"`, `"./bundles/library"`, …),
110
- add the corresponding `"types"` / `"import"` / `"default"` keys pointing to `dist/`,
111
- and ensure they are listed under `"files": ["dist/"]`.
112
-
113
- ### `tsdown.config.ts`
114
-
115
- ```ts
116
- import { defineConfig } from "tsdown";
117
- export default defineConfig({
118
- entry: ["index.ts"],
119
- format: "esm",
120
- fixedExtension: false,
121
- dts: true,
122
- clean: true,
123
- });
124
- ```
125
-
126
- For multi-preset packages list every entry point:
127
-
128
- ```ts
129
- entry: ["index.ts", "presets/node.ts", "presets/react.ts", "bundles/library.ts"],
130
- ```
131
-
132
- ### `tsconfig.json`
133
-
134
- ```json
135
- {
136
- "extends": "@theholocron/tsconfig/node-lts",
137
- "compilerOptions": { "rootDir": ".", "outDir": "dist" },
138
- "include": ["**/*.ts"],
139
- "exclude": ["dist", "node_modules", "tsdown.config.ts"]
140
- }
141
- ```
142
-
143
- ### `vitest.config.ts`
144
-
145
- ```ts
146
- import { node } from "@theholocron/vitest-config";
147
- import { defineConfig } from "vitest/config";
148
- export default defineConfig(node());
149
- ```
150
-
151
- ### `index.ts` (single default export)
152
-
153
- ```ts
154
- import type { Config } from "<tool>";
155
-
156
- const config = {
157
- // ...
158
- } satisfies Config;
159
-
160
- export default config;
161
- ```
162
-
163
- ### `index.ts` (named presets / multi-export)
164
-
165
- ```ts
166
- export { node } from "./presets/node.js";
167
- export { react } from "./presets/react.js";
168
- ```
169
-
170
- Note: source files use `.js` extensions on relative imports — TypeScript's ESM
171
- convention; the TS resolver finds the `.ts` file at build time.
172
-
173
- ### `index.test.ts`
174
-
175
- ```ts
176
- import { describe, it, expect } from "vitest";
177
- import config from "./index.js";
178
-
179
- describe("<tool>-config", () => {
180
- it("exports a non-empty config object", () => {
181
- expect(typeof config).toBe("object");
182
- expect(Object.keys(config).length).toBeGreaterThan(0);
183
- });
184
- });
185
- ```
186
-
187
- ### `README.md`
188
-
189
- Follow this structure (see existing READMEs for tone):
190
-
191
- ```markdown
192
- # <Tool> Config
193
-
194
- A [<Tool> configuration](official-docs-url) for <one-line description>.
195
-
196
- ## Installation
197
-
198
- \`\`\`bash
199
- npm install --save-dev @theholocron/<tool>-config
200
- \`\`\`
201
-
202
- ## Usage
203
-
204
- <minimal working example — show the exact file name the user creates and its contents>
205
-
206
- ## <Optional: named presets or bundles section>
207
- ```
208
-
209
- Keep it short. Link to official docs rather than duplicating them.
210
-
211
- ## Non-negotiables
212
-
213
- - **TypeScript source, compiled to `dist/` via tsdown.** Never publish raw `.ts`
214
- files or add plain `.js` source. The `"files"` field must be `["dist/"]`.
215
- - **Match version to current monorepo version** — check root `package.json`.
216
- - **Peer deps, not regular deps.** The tool being configured belongs in
217
- `peerDependencies`.
218
- - **Deprecation notice** if replacing an existing package — add a banner at the
219
- top of the old package's `README.md` pointing to the replacement.
220
- - Run `pnpm install` after adding the package to pick up workspace resolution.
221
- - Run `pnpm build` to verify tsdown compiles successfully.
222
- - Run `pnpm lint` to verify the new files pass ESLint.
223
-
224
- ## Checklist
225
-
226
- 1. Create `packages/<tool>-config/` with all seven files listed above.
227
- 2. Set `devDependencies` to include `@theholocron/tsconfig`, `@theholocron/vitest-config`,
228
- `@vitest/coverage-v8`, `tsdown`, `typescript`, and `vitest` (use `catalog:` /
229
- `workspace:*` specifiers — never pin exact versions).
230
- 3. Confirm `scripts` has `"build": "tsdown"`, `"test": "vitest run"`, and
231
- `"typecheck": "tsc --noEmit"`.
232
- 4. Add entry to `codecov.yml` under `component_management.individual_components`
233
- with `component_id: <slug>`, `name: "<slug>"`, and `paths: [packages/<slug>/**]`.
234
- 5. Run `pnpm install`, `pnpm build`, `pnpm test`, `pnpm typecheck` — all must pass.
235
- 6. Open a PR with a `feat:` commit — semantic-release will compute a minor bump
236
- and publish all packages in lockstep.
@@ -1,134 +0,0 @@
1
- ---
2
- name: holocron-skill-skill
3
- description: Add a new owned skill to theholocron/skills. INVOKE WHEN: user asks to create or add a new skill to the skills repo. Invoked as /holocron-skill-skill.
4
- ---
5
-
6
- <!-- editorconfig-checker-disable-file -->
7
-
8
- # Add a new skill
9
-
10
- Add a new owned skill to `theholocron/skills`.
11
-
12
- Replace `<name>` with the skill's kebab-case identifier (e.g. `git-safety`, `holocron-skill-config`).
13
-
14
- ---
15
-
16
- ## 1. Decide the skill category
17
-
18
- **Workflow & safety** — generic skills applicable to any repo (e.g. `git-safety`, `commit-standards`).
19
- **Project-specific** — skills scoped to a particular theholocron repo or task (e.g. `holocron-skill-config`).
20
-
21
- The category determines which section of `README.md` the skill is listed in.
22
-
23
- ---
24
-
25
- ## 2. Create the skill file
26
-
27
- ```
28
- skills/<name>/
29
- └── SKILL.md
30
- ```
31
-
32
- ### `SKILL.md` frontmatter
33
-
34
- ```markdown
35
- ---
36
- name: <name>
37
- description: <One-line description>. INVOKE WHEN: <trigger conditions>. Invoked as /<name>.
38
- ---
39
- ```
40
-
41
- - `name` must match the directory name exactly.
42
- - `description` is what Claude reads to decide whether to invoke the skill — make the "INVOKE WHEN" clause specific and unambiguous.
43
- - "Invoked as `/<name>`" is the slash-command the user types.
44
-
45
- ### Body structure
46
-
47
- Follow the pattern used by existing skills:
48
-
49
- ```markdown
50
- # <Skill title>
51
-
52
- <One-paragraph summary of what this skill does and when to use it.>
53
-
54
- ## When to use
55
-
56
- <Bullet list of specific trigger scenarios.>
57
-
58
- ## <Main content section(s)>
59
-
60
- <Rules, checklists, file templates, etc.>
61
-
62
- ## Non-negotiables (if applicable)
63
-
64
- <Hard rules the agent must never violate.>
65
-
66
- ## Checklist
67
-
68
- <Numbered steps — the agent works through these in order.>
69
- ```
70
-
71
- Keep it concise. The agent reads this at invocation time; every sentence should earn its place.
72
-
73
- ---
74
-
75
- ## 3. Validate
76
-
77
- ```bash
78
- pnpm test
79
- ```
80
-
81
- The smoke test checks that every `skills/*/SKILL.md` exists. It will fail if the frontmatter is missing or the file is empty.
82
-
83
- ---
84
-
85
- ## 4. Update `README.md`
86
-
87
- Add a row to the **Owned skills** table in the appropriate section:
88
-
89
- ```markdown
90
- | [`<name>`](./skills/<name>/SKILL.md) | <Short description — match the "description" frontmatter field> |
91
- ```
92
-
93
- - Workflow & safety skills → "Workflow & safety" table
94
- - Repo-specific skills → "Project-specific (theholocron)" table
95
-
96
- ---
97
-
98
- ## 5. Update `AGENTS.md`
99
-
100
- Add a row to the **Available skills** table in the matching section:
101
-
102
- ```markdown
103
- | `<name>` | <trigger phrase — a few words> |
104
- ```
105
-
106
- ---
107
-
108
- ## 6. Open a PR
109
-
110
- ```bash
111
- git add skills/<name>/SKILL.md README.md AGENTS.md
112
- git commit -s -m "feat: add <name> skill"
113
- ```
114
-
115
- Semantic-release handles versioning. The `pnpm test` smoke test runs in CI.
116
-
117
- ---
118
-
119
- ## Non-negotiables
120
-
121
- - **`name` in frontmatter must match the directory name** — the smoke test and install tooling rely on this.
122
- - **`INVOKE WHEN:` clause is required in `description`** — without it, the agent won't know when to invoke the skill automatically.
123
- - **Both `README.md` and `AGENTS.md` must be updated** — `README.md` is the public-facing table; `AGENTS.md` is what agents read in consuming repos.
124
- - **`pnpm test` must pass** before opening a PR.
125
-
126
- ---
127
-
128
- ## Checklist
129
-
130
- 1. Create `skills/<name>/SKILL.md` with correct frontmatter and body.
131
- 2. Run `pnpm test` — smoke test must pass.
132
- 3. Add row to `README.md` owned skills table (correct section).
133
- 4. Add row to `AGENTS.md` Available skills table (correct section).
134
- 5. Open a PR with a `feat:` commit signed with `-s`.