@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.
- package/LICENSE +1 -1
- package/README.md +136 -0
- package/package.json +12 -26
- package/skills-lock.json +30 -0
- package/src/adr/SKILL.md +53 -0
- package/src/adr/assets/template.md +64 -0
- package/src/commit-standards/SKILL.md +135 -0
- package/src/design/SKILL.md +38 -0
- package/src/destructive-command-guard/SKILL.md +51 -0
- package/src/discover/SKILL.md +44 -0
- package/src/discuss/SKILL.md +38 -0
- package/{git-safety → src/git-safety}/SKILL.md +4 -0
- package/src/holocron-skill-client/SKILL.md +278 -0
- package/src/holocron-skill-config/SKILL.md +246 -0
- package/{holocron-skill-plugin → src/holocron-skill-plugin}/SKILL.md +15 -2
- package/src/holocron-skill-skill/SKILL.md +155 -0
- package/src/holocron-skill-util/SKILL.md +286 -0
- package/src/implement/SKILL.md +54 -0
- package/src/plan/SKILL.md +40 -0
- package/{pr-workflow → src/pr-workflow}/SKILL.md +20 -1
- package/src/review/SKILL.md +78 -0
- package/{security-review → src/security-review}/SKILL.md +3 -0
- package/src/spec/SKILL.md +52 -0
- package/src/verify/SKILL.md +22 -0
- package/commit-standards/SKILL.md +0 -88
- package/holocron-skill-client/SKILL.md +0 -151
- package/holocron-skill-config/SKILL.md +0 -236
- package/holocron-skill-skill/SKILL.md +0 -134
- package/holocron-skill-util/SKILL.md +0 -274
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-skill
|
|
3
|
+
title: "Holocron: New Skill"
|
|
4
|
+
description: Add a new owned skill to the skills folder of theholocron/holocron. INVOKE WHEN: user asks to create or add a new skill to the skills registry. Invoked as /holocron-skill-skill.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- editorconfig-checker-disable-file -->
|
|
8
|
+
|
|
9
|
+
# Add a new skill
|
|
10
|
+
|
|
11
|
+
Add a new owned skill to `skills/` (the `@theholocron/skills` package) in `theholocron/holocron`.
|
|
12
|
+
The standalone `theholocron/skills` repo is archived; do not add skills there.
|
|
13
|
+
|
|
14
|
+
Replace `<name>` with the skill's kebab-case identifier (e.g. `git-safety`, `holocron-skill-config`).
|
|
15
|
+
|
|
16
|
+
There is no registry file or index to edit: the package ships everything under
|
|
17
|
+
`skills/src/`, `holocron setup` / `holocron install skills` copy `skills/src/<name>/`
|
|
18
|
+
by name into a consuming repo, and the smoke test discovers skills by listing
|
|
19
|
+
the directories. Creating the directory is the registration; the README row and
|
|
20
|
+
docs page keep the human-facing listings in sync.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 1. Decide the skill category
|
|
25
|
+
|
|
26
|
+
**Workflow & safety** — generic skills applicable to any repo (e.g. `git-safety`, `commit-standards`).
|
|
27
|
+
**Project-specific** — skills scoped to a particular theholocron repo or task (e.g. `holocron-skill-config`).
|
|
28
|
+
|
|
29
|
+
The category determines which table of `skills/README.md` the skill is listed in.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 2. Create the skill file
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
skills/src/<name>/
|
|
37
|
+
└── SKILL.md
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Optional supporting files (templates, examples) go in `skills/src/<name>/assets/`
|
|
41
|
+
(see `skills/src/adr/assets/`); they ship with the skill.
|
|
42
|
+
|
|
43
|
+
### `SKILL.md` frontmatter
|
|
44
|
+
|
|
45
|
+
```markdown
|
|
46
|
+
---
|
|
47
|
+
name: <name>
|
|
48
|
+
title: "<Short title>"
|
|
49
|
+
description: <One-line description>. INVOKE WHEN: <trigger conditions>. Invoked as /<name>.
|
|
50
|
+
---
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- `name` must match the directory name exactly.
|
|
54
|
+
- `description` is what Claude reads to decide whether to invoke the skill — make the "INVOKE WHEN" clause specific and unambiguous.
|
|
55
|
+
- "Invoked as `/<name>`" is the slash-command the user types.
|
|
56
|
+
- `title` is optional; most skills carry one (see `git-safety`).
|
|
57
|
+
|
|
58
|
+
### Body structure
|
|
59
|
+
|
|
60
|
+
Follow the pattern used by existing skills:
|
|
61
|
+
|
|
62
|
+
```markdown
|
|
63
|
+
# <Skill title>
|
|
64
|
+
|
|
65
|
+
<One-paragraph summary of what this skill does and when to use it.>
|
|
66
|
+
|
|
67
|
+
## When to use
|
|
68
|
+
|
|
69
|
+
<Bullet list of specific trigger scenarios.>
|
|
70
|
+
|
|
71
|
+
## <Main content section(s)>
|
|
72
|
+
|
|
73
|
+
<Rules, checklists, file templates, etc.>
|
|
74
|
+
|
|
75
|
+
## Non-negotiables (if applicable)
|
|
76
|
+
|
|
77
|
+
<Hard rules the agent must never violate.>
|
|
78
|
+
|
|
79
|
+
## Checklist
|
|
80
|
+
|
|
81
|
+
<Numbered steps — the agent works through these in order.>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Keep it concise. The agent reads this at invocation time; every sentence should earn its place.
|
|
85
|
+
Any path or command a skill names must exist in the repo — run it or `ls` it before writing it down.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## 3. Validate
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pnpm --filter @theholocron/skills test:unit
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The smoke test (`skills/test/index.mjs`, a `node:test` suite) checks that every
|
|
96
|
+
directory under `skills/src/` contains a `SKILL.md`. Also run
|
|
97
|
+
`pnpm exec prettier --check skills/` — the markdown is formatted.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 4. Update `skills/README.md`
|
|
102
|
+
|
|
103
|
+
Add a row to the **Owned skills** table in the matching section:
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
| [`<name>`](./src/<name>/SKILL.md) | <Short description — match the "description" frontmatter field> |
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
- Workflow & safety skills → "Workflow & safety" table
|
|
110
|
+
- Repo-specific skills → "Project-specific (theholocron)" table
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## 5. Update the docs site
|
|
115
|
+
|
|
116
|
+
- Add `docs/src/content/docs/skills/<name>.mdx` (frontmatter `title`, `description`;
|
|
117
|
+
copy a small sibling such as `git-safety.mdx`).
|
|
118
|
+
- Add a row to the Skills table in `docs/src/content/docs/skills/index.mdx`.
|
|
119
|
+
- Add `{ label: "<name>", slug: "skills/<name>" }` to the Skills group of the
|
|
120
|
+
sidebar in the root `astro.config.ts` (alphabetical).
|
|
121
|
+
- If it is a standard skill worth advertising, add a row to the registry table in
|
|
122
|
+
`docs/src/content/docs/commands/skills.mdx`.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 6. Open a PR
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
git add skills/src/<name>/SKILL.md skills/README.md docs/src/content/docs/skills astro.config.ts
|
|
130
|
+
git commit -s -m "feat(skills): ✨ add <name> skill"
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`@theholocron/skills` is its own version group (tags `skills-vX.Y.Z`, changelog in
|
|
134
|
+
`skills/CHANGELOG.md`); semantic-release computes the bump from the commit type.
|
|
135
|
+
There is no `AGENTS.md` skills table in this repo to update.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Non-negotiables
|
|
140
|
+
|
|
141
|
+
- **`name` in frontmatter must match the directory name** — the install tooling relies on it.
|
|
142
|
+
- **`INVOKE WHEN:` clause is required in `description`** — without it, the agent won't know when to invoke the skill automatically.
|
|
143
|
+
- **The `skills/README.md` row, docs page, docs index row and sidebar entry ship in the same PR.**
|
|
144
|
+
- **The skills unit test must pass** before opening a PR.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Checklist
|
|
149
|
+
|
|
150
|
+
1. Create `skills/src/<name>/SKILL.md` with correct frontmatter and body.
|
|
151
|
+
2. Run `pnpm --filter @theholocron/skills test:unit` — smoke test must pass.
|
|
152
|
+
3. Add the row to the `skills/README.md` owned-skills table (correct section).
|
|
153
|
+
4. Add the docs page, `skills/index.mdx` row and sidebar entry.
|
|
154
|
+
5. `pnpm exec prettier --check` on the changed files; `holocron run ci` passes.
|
|
155
|
+
6. Open a PR with a `feat(skills):` commit signed with `-s`.
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-util
|
|
3
|
+
title: "Holocron: New Util"
|
|
4
|
+
description: Scaffold a new @theholocron/<slug>-utils package in the utils folder of theholocron/holocron. INVOKE WHEN: user asks to add a new utility package to the utils group. Invoked as /holocron-skill-util.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- editorconfig-checker-disable-file -->
|
|
8
|
+
|
|
9
|
+
# Scaffold a new utility package
|
|
10
|
+
|
|
11
|
+
Scaffold a new `@theholocron/<name>-utils` package in `utils/` of `theholocron/holocron`.
|
|
12
|
+
The standalone `theholocron/utils` repo is archived; do not scaffold there.
|
|
13
|
+
|
|
14
|
+
Replace `<name>` with the utility domain in kebab-case (e.g. `color`, `math`, `format`).
|
|
15
|
+
|
|
16
|
+
Reference implementations (read their `package.json` and copy the shape if this
|
|
17
|
+
template ever disagrees):
|
|
18
|
+
|
|
19
|
+
- Node-only package: `utils/array-utils` (smallest) or `utils/string-utils` (has runtime deps)
|
|
20
|
+
- Browser-API package: `utils/location-utils` (DOM lib, happy-dom, eslint override)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 1. Create the package directory
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
utils/<name>-utils/
|
|
28
|
+
├── src/
|
|
29
|
+
│ ├── index.ts
|
|
30
|
+
│ ├── <module>.ts
|
|
31
|
+
│ └── <module>.test.ts
|
|
32
|
+
├── package.json
|
|
33
|
+
├── tsdown.config.ts
|
|
34
|
+
├── tsconfig.json
|
|
35
|
+
├── vitest.config.ts
|
|
36
|
+
└── README.md
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Tests live beside the module they cover (`<module>.test.ts` in `src/`); there is
|
|
40
|
+
no `__tests__` directory. There is no per-package `LICENSE`, `CHANGELOG.md`,
|
|
41
|
+
`eslint.config.ts` (the root config applies) or `.releaserc`. The workspace glob
|
|
42
|
+
`utils/*` in `pnpm-workspace.yaml` already covers the new folder, and knip's
|
|
43
|
+
`utils/*` entry covers `src/index.ts` and `src/**/*.test.ts`.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 2. File templates
|
|
48
|
+
|
|
49
|
+
### `package.json`
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"name": "@theholocron/<name>-utils",
|
|
54
|
+
"version": "<current utils version>",
|
|
55
|
+
"description": "<One-line description.>",
|
|
56
|
+
"keywords": ["<name>", "typescript", "utils"],
|
|
57
|
+
"homepage": "https://docs.theholocron.dev/holocron/utils/<name>-utils/",
|
|
58
|
+
"bugs": "https://github.com/theholocron/holocron/issues",
|
|
59
|
+
"repository": {
|
|
60
|
+
"type": "git",
|
|
61
|
+
"url": "git+https://github.com/theholocron/holocron.git",
|
|
62
|
+
"directory": "utils/<name>-utils"
|
|
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
|
+
},
|
|
75
|
+
"files": ["dist"],
|
|
76
|
+
"scripts": {
|
|
77
|
+
"build": "tsdown",
|
|
78
|
+
"lint:code": "eslint .",
|
|
79
|
+
"test:watch": "vitest",
|
|
80
|
+
"typecheck": "tsc --noEmit",
|
|
81
|
+
"test:unit": "vitest run"
|
|
82
|
+
},
|
|
83
|
+
"devDependencies": {
|
|
84
|
+
"@theholocron/eslint-config": "catalog:configs",
|
|
85
|
+
"@theholocron/tsdown-config": "catalog:configs",
|
|
86
|
+
"@theholocron/vitest-config": "catalog:configs",
|
|
87
|
+
"@tsconfig/node-lts": "catalog:",
|
|
88
|
+
"@types/node": "catalog:",
|
|
89
|
+
"@vitest/coverage-v8": "catalog:",
|
|
90
|
+
"@vitest/eslint-plugin": "catalog:",
|
|
91
|
+
"eslint": "catalog:",
|
|
92
|
+
"eslint-plugin-n": "catalog:",
|
|
93
|
+
"globals": "catalog:",
|
|
94
|
+
"tsdown": "catalog:",
|
|
95
|
+
"typescript": "catalog:",
|
|
96
|
+
"vitest": "catalog:"
|
|
97
|
+
},
|
|
98
|
+
"engines": { "node": ">=22" },
|
|
99
|
+
"publishConfig": { "access": "public" }
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- **`version`**: read it from any sibling (`utils/array-utils/package.json`). The
|
|
104
|
+
`utils/` folder is one version group (tags `utils-vX.Y.Z`, one
|
|
105
|
+
`utils/CHANGELOG.md`); `holocron publish bump-versions --group utils` moves
|
|
106
|
+
every package together at release.
|
|
107
|
+
- **License is MIT** (ADR-0016). No `releases`, `wiki` or `packageManager` fields.
|
|
108
|
+
- `homepage` keeps the full package name (`.../utils/<name>-utils/`).
|
|
109
|
+
- Runtime dependencies (if any) go in `"dependencies"` (`catalog:` for
|
|
110
|
+
third-party, `workspace:^` for another `utils/` package), not `devDependencies`.
|
|
111
|
+
- Browser-API packages add `"happy-dom": "catalog:"` to `devDependencies`.
|
|
112
|
+
|
|
113
|
+
### `tsdown.config.ts`
|
|
114
|
+
|
|
115
|
+
One line, re-exporting the shared preset:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
export { default } from "@theholocron/tsdown-config/presets/library";
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
If the package has runtime dependencies that must stay external, use the preset
|
|
122
|
+
as a function instead (see `utils/string-utils/tsdown.config.ts`):
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { library } from "@theholocron/tsdown-config/presets/library";
|
|
126
|
+
import type { UserConfig } from "tsdown";
|
|
127
|
+
|
|
128
|
+
const config: UserConfig = library({
|
|
129
|
+
deps: { neverBundle: [/^@theholocron\//, /^some-dependency$/] },
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
export default config;
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### `tsconfig.json` (Node-only)
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"display": "<Name> Utilities",
|
|
140
|
+
"extends": "@tsconfig/node-lts/tsconfig.json",
|
|
141
|
+
"compilerOptions": {
|
|
142
|
+
"allowImportingTsExtensions": true
|
|
143
|
+
},
|
|
144
|
+
"include": ["./src/**/*.ts"],
|
|
145
|
+
"exclude": ["./node_modules", "**/*.test.ts"]
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### `tsconfig.json` (Browser-API package)
|
|
150
|
+
|
|
151
|
+
Add `"lib"` to `compilerOptions`:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"display": "<Name> Utilities",
|
|
156
|
+
"extends": "@tsconfig/node-lts/tsconfig.json",
|
|
157
|
+
"compilerOptions": {
|
|
158
|
+
"allowImportingTsExtensions": true,
|
|
159
|
+
"lib": ["dom", "dom.iterable", "es2022"]
|
|
160
|
+
},
|
|
161
|
+
"include": ["./src/**/*.ts"],
|
|
162
|
+
"exclude": ["./node_modules", "**/*.test.ts"]
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### `vitest.config.ts`
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
import { library } from "@theholocron/vitest-config/bundles/library";
|
|
170
|
+
import { defineConfig } from "vitest/config";
|
|
171
|
+
|
|
172
|
+
export default defineConfig(library({ globals: true }) as never);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Browser-API packages pass `environment: "happy-dom"` too
|
|
176
|
+
(`library({ globals: true, environment: "happy-dom" })`).
|
|
177
|
+
|
|
178
|
+
### `src/index.ts`
|
|
179
|
+
|
|
180
|
+
```ts
|
|
181
|
+
// Named exports — no default export
|
|
182
|
+
export function myUtil(value: string): string {
|
|
183
|
+
return value;
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Use named exports throughout. Group related utilities into sibling files
|
|
188
|
+
(`src/casing.ts`, `src/casting.ts`, …) and re-export from `src/index.ts`:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
export * from "./casing.ts";
|
|
192
|
+
export * from "./casting.ts";
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Source imports use `.ts` extensions (`allowImportingTsExtensions`).
|
|
196
|
+
|
|
197
|
+
### Test files (`src/<module>.test.ts`)
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
import { describe, expect, test } from "vitest";
|
|
201
|
+
|
|
202
|
+
import * as util from "./index.ts";
|
|
203
|
+
|
|
204
|
+
describe("<Name>", () => {
|
|
205
|
+
test("does X", () => {
|
|
206
|
+
expect(util.myUtil("input")).toBe("expected");
|
|
207
|
+
});
|
|
208
|
+
});
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### `README.md`
|
|
212
|
+
|
|
213
|
+
```markdown
|
|
214
|
+
# `@theholocron/<name>-utils`
|
|
215
|
+
|
|
216
|
+
<One-line description of what the utilities do.>
|
|
217
|
+
|
|
218
|
+
## Installation
|
|
219
|
+
|
|
220
|
+
\`\`\`bash
|
|
221
|
+
pnpm add @theholocron/<name>-utils
|
|
222
|
+
\`\`\`
|
|
223
|
+
|
|
224
|
+
## Usage
|
|
225
|
+
|
|
226
|
+
\`\`\`typescript
|
|
227
|
+
import { myUtil } from "@theholocron/<name>-utils";
|
|
228
|
+
|
|
229
|
+
<minimal working example>
|
|
230
|
+
\`\`\`
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## 3. Monorepo registration
|
|
236
|
+
|
|
237
|
+
1. Run `pnpm install` from the repo root (links the workspace package, updates
|
|
238
|
+
`pnpm-lock.yaml`; commit the lockfile).
|
|
239
|
+
2. **Codecov**: add a component under the `# utils` heading of `codecov.yml`
|
|
240
|
+
(`component_id: <name>-utils`, `paths: utils/<name>-utils/**`), alphabetical.
|
|
241
|
+
The file is generated by `holocron setup` ("write codecov.yml" step,
|
|
242
|
+
`cli/astromech/src/generators/codecov`); that command needs tokens for its
|
|
243
|
+
other steps, so add the block by hand in exactly that format.
|
|
244
|
+
3. **Release**: nothing to edit. `release.config.ts` and the `release`
|
|
245
|
+
task in `astromech.config.ts` release the whole `utils` group by folder.
|
|
246
|
+
4. **Browser-API packages only**: add `"utils/<name>-utils/src/**"` to the
|
|
247
|
+
browser override (`files: [...]`, turning off
|
|
248
|
+
`n/no-unsupported-features/node-builtins`) in the root `eslint.config.ts`.
|
|
249
|
+
5. **Dependency catalog**: if something outside `utils/` (the CLI, a plugin, a
|
|
250
|
+
client) will consume it, add it to `catalogs.utils` in `pnpm-workspace.yaml`
|
|
251
|
+
once it has been published and reference it as `catalog:utils`.
|
|
252
|
+
6. **Docs**: add `docs/src/content/docs/utils/<name>-utils.mdx` (frontmatter
|
|
253
|
+
`title`, `description`; copy `array-utils.mdx`), a row in
|
|
254
|
+
`docs/src/content/docs/utils/index.mdx`, and
|
|
255
|
+
`{ label: "<name>-utils", slug: "utils/<name>-utils" }` to the Utils group of
|
|
256
|
+
the sidebar in the root `astro.config.ts` (alphabetical).
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## Non-negotiables
|
|
261
|
+
|
|
262
|
+
- **`catalog:configs`** for `@theholocron/tsdown-config`, `@theholocron/vitest-config`,
|
|
263
|
+
`@theholocron/eslint-config`; `catalog:` for everything else — never pin exact versions.
|
|
264
|
+
- **`tsdown` and `vitest` must be direct `devDependencies`** — pnpm does not expose transitive binaries.
|
|
265
|
+
- **`globals: true`** in every `vitest.config.ts` — tests use `describe`/`test`/`expect`.
|
|
266
|
+
- **Match `version` to the utils group** before opening a PR.
|
|
267
|
+
- Tests beside the source; no `__tests__` directory.
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Checklist
|
|
272
|
+
|
|
273
|
+
1. Create `utils/<name>-utils/` with all files listed above.
|
|
274
|
+
2. `pnpm install` — must resolve without errors; lockfile committed.
|
|
275
|
+
3. `pnpm --filter @theholocron/<name>-utils` run `build`,
|
|
276
|
+
`test:unit`, `typecheck` and
|
|
277
|
+
`lint:code` — all must pass.
|
|
278
|
+
4. Add the `codecov.yml` component (alphabetical).
|
|
279
|
+
5. Browser-API package: `"lib"` in tsconfig, happy-dom, and the root
|
|
280
|
+
`eslint.config.ts` override path.
|
|
281
|
+
6. Add the docs page, `utils/index.mdx` row and sidebar entry.
|
|
282
|
+
7. `holocron run ci` passes.
|
|
283
|
+
8. Open a PR with a `feat(utils):` commit, signed with `-s` — semantic-release
|
|
284
|
+
computes the next `utils-v*` version and publishes the group in lockstep.
|
|
285
|
+
The first publish of a brand-new package needs
|
|
286
|
+
`holocron publish package --initial --group utils` run by a maintainer.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: implement
|
|
3
|
+
description: Implementation Agent. INVOKE WHEN: an approved implementation plan is ready to execute. Follows the plan strictly — does not redesign or make new architectural decisions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Implementation Agent
|
|
7
|
+
|
|
8
|
+
You are implementing an accepted engineering specification.
|
|
9
|
+
|
|
10
|
+
Authority order:
|
|
11
|
+
|
|
12
|
+
1. Accepted ADRs
|
|
13
|
+
2. Accepted specification
|
|
14
|
+
3. Approved implementation plan
|
|
15
|
+
4. Existing repository conventions
|
|
16
|
+
|
|
17
|
+
Implement the approved plan.
|
|
18
|
+
|
|
19
|
+
Do not change product behavior described by the specification.
|
|
20
|
+
Do not contradict accepted ADRs.
|
|
21
|
+
Do not introduce new architectural patterns unless required by the specification.
|
|
22
|
+
Follow existing repository conventions where they do not conflict with the spec.
|
|
23
|
+
|
|
24
|
+
For each implementation step:
|
|
25
|
+
|
|
26
|
+
- make the required change
|
|
27
|
+
- add or update tests
|
|
28
|
+
- preserve backward compatibility where required
|
|
29
|
+
- add appropriate observability
|
|
30
|
+
- update relevant documentation
|
|
31
|
+
|
|
32
|
+
If you discover that repository reality makes the specification impossible or
|
|
33
|
+
requires a new architectural decision:
|
|
34
|
+
|
|
35
|
+
STOP that portion of implementation.
|
|
36
|
+
|
|
37
|
+
Describe:
|
|
38
|
+
|
|
39
|
+
- what the specification requires
|
|
40
|
+
- what the repository currently supports
|
|
41
|
+
- why they conflict
|
|
42
|
+
- what decision is required
|
|
43
|
+
|
|
44
|
+
Do not silently invent a new design.
|
|
45
|
+
|
|
46
|
+
## Checklist before declaring done
|
|
47
|
+
|
|
48
|
+
- [ ] Feature branch created before any code was written
|
|
49
|
+
- [ ] All plan steps completed
|
|
50
|
+
- [ ] Tests written for new behavior
|
|
51
|
+
- [ ] Package entry added to registry (if applicable)
|
|
52
|
+
- [ ] Docs page added or updated in the same PR (if adding a new capability)
|
|
53
|
+
- [ ] PR title follows Conventional Commits
|
|
54
|
+
- [ ] CI green before requesting review
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: plan
|
|
3
|
+
description: Implementation Planner. INVOKE WHEN: a spec is accepted and needs to be translated into a concrete repo change plan. Does not redesign — treats the spec and ADRs as authoritative.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Implementation Planner
|
|
7
|
+
|
|
8
|
+
You are acting as an implementation planner.
|
|
9
|
+
|
|
10
|
+
Treat the accepted specification and ADRs as authoritative.
|
|
11
|
+
|
|
12
|
+
Inspect the repository and produce a concrete implementation plan for
|
|
13
|
+
satisfying the specification. Do not redesign the feature.
|
|
14
|
+
|
|
15
|
+
Identify:
|
|
16
|
+
|
|
17
|
+
- packages/services affected
|
|
18
|
+
- files likely affected
|
|
19
|
+
- new files required
|
|
20
|
+
- schema changes and migrations
|
|
21
|
+
- API changes
|
|
22
|
+
- configuration changes
|
|
23
|
+
- tests required
|
|
24
|
+
- observability changes
|
|
25
|
+
- documentation changes
|
|
26
|
+
- deployment or rollout requirements
|
|
27
|
+
|
|
28
|
+
Produce an ordered implementation plan. Each step should include:
|
|
29
|
+
|
|
30
|
+
1. Goal
|
|
31
|
+
2. Files or modules affected
|
|
32
|
+
3. Expected change
|
|
33
|
+
4. Tests required
|
|
34
|
+
5. Dependencies on earlier steps
|
|
35
|
+
|
|
36
|
+
Identify tasks that can safely be implemented in parallel.
|
|
37
|
+
|
|
38
|
+
If repository reality conflicts with the specification or ADRs, stop that
|
|
39
|
+
portion of the plan and explicitly describe the conflict. Do not silently
|
|
40
|
+
alter the design to work around it.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pr-workflow
|
|
3
|
+
title: PR Workflow
|
|
3
4
|
description: Pull request workflow rules. INVOKE WHEN: opening a PR, merging, closing a PR, creating a branch. Always open a PR — never push directly to the default branch.
|
|
4
5
|
---
|
|
5
6
|
|
|
@@ -16,6 +17,14 @@ description: Pull request workflow rules. INVOKE WHEN: opening a PR, merging, cl
|
|
|
16
17
|
- **File issues for non-trivial work** and reference them in commits/PRs
|
|
17
18
|
(`Closes #N` / `Refs #N`). Skip for typo fixes.
|
|
18
19
|
|
|
20
|
+
## before pushing
|
|
21
|
+
|
|
22
|
+
Run **`holocron ci`** — it runs exactly the merge-gating checks locally, in CI
|
|
23
|
+
order, and exits non-zero on the first failure. Finding failures after pushing
|
|
24
|
+
wastes a review round trip. (Equivalent: `pnpm typecheck && pnpm lint && pnpm
|
|
25
|
+
test && pnpm build`.) In `protection: "strict"` repos a `pre-push` git hook runs
|
|
26
|
+
it automatically; `git push --no-verify` bypasses that hook for one push.
|
|
27
|
+
|
|
19
28
|
## opening a PR
|
|
20
29
|
|
|
21
30
|
1. Create a branch from the correct base (usually `main`; `alpha` in holocron)
|
|
@@ -31,7 +40,7 @@ description: Pull request workflow rules. INVOKE WHEN: opening a PR, merging, cl
|
|
|
31
40
|
|
|
32
41
|
## closing / discarding
|
|
33
42
|
|
|
34
|
-
**Delete the branch when closing, never
|
|
43
|
+
**Delete the branch when closing, never close the PR and leave the branch.** A closed-but-existing
|
|
35
44
|
branch blocks future PR creation for the same branch name — GitHub returns 422
|
|
36
45
|
"A pull request already exists" and the sync silently skips opening a new one.
|
|
37
46
|
|
|
@@ -43,3 +52,13 @@ gh pr close <n> --repo <owner>/<repo> --delete-branch
|
|
|
43
52
|
|
|
44
53
|
If a workflow-sync PR is stale or wrong, use the command above. Do NOT close the
|
|
45
54
|
PR without deleting the branch or the next sync run will silently fail.
|
|
55
|
+
|
|
56
|
+
## Checklist before requesting review
|
|
57
|
+
|
|
58
|
+
- [ ] Feature branch created before any code was written
|
|
59
|
+
- [ ] Package entry added to registry (if applicable)
|
|
60
|
+
- [ ] Docs page added or updated in the same PR (if adding a new capability)
|
|
61
|
+
- [ ] Tests written for new behavior
|
|
62
|
+
- [ ] `holocron ci` passes locally (or `pnpm typecheck && pnpm lint && pnpm test && pnpm build`)
|
|
63
|
+
- [ ] PR title follows Conventional Commits
|
|
64
|
+
- [ ] CI green before requesting review
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: review
|
|
3
|
+
description: Review Agent. INVOKE WHEN: an implementation is complete and needs independent review. Reviews in a fresh context — does not evaluate its own work. Compares implementation against spec, not just code quality.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- alex disable invalid -->
|
|
7
|
+
|
|
8
|
+
# Review Agent
|
|
9
|
+
|
|
10
|
+
You are acting as an independent engineering reviewer.
|
|
11
|
+
|
|
12
|
+
Review the implementation against:
|
|
13
|
+
|
|
14
|
+
1. The GitHub issue
|
|
15
|
+
2. Accepted ADRs
|
|
16
|
+
3. The accepted specification
|
|
17
|
+
4. The implementation plan
|
|
18
|
+
5. Repository conventions
|
|
19
|
+
|
|
20
|
+
Do not assume the implementation is correct because tests pass.
|
|
21
|
+
|
|
22
|
+
Evaluate:
|
|
23
|
+
|
|
24
|
+
## Specification Compliance
|
|
25
|
+
|
|
26
|
+
Identify every requirement in the specification and determine whether it is
|
|
27
|
+
implemented.
|
|
28
|
+
|
|
29
|
+
## ADR Compliance
|
|
30
|
+
|
|
31
|
+
Identify any behavior or architecture that conflicts with accepted ADRs.
|
|
32
|
+
|
|
33
|
+
## Correctness
|
|
34
|
+
|
|
35
|
+
Look for logical errors, invalid state transitions, race conditions, missing
|
|
36
|
+
validation, and incorrect assumptions.
|
|
37
|
+
|
|
38
|
+
## Security
|
|
39
|
+
|
|
40
|
+
Review authentication, authorization, data exposure, input handling, and
|
|
41
|
+
trust boundaries.
|
|
42
|
+
|
|
43
|
+
## Failure Behavior
|
|
44
|
+
|
|
45
|
+
Review errors, retries, partial failures, rollback behavior, and recovery.
|
|
46
|
+
|
|
47
|
+
## Observability
|
|
48
|
+
|
|
49
|
+
Confirm appropriate logs, metrics, traces, and diagnostic information.
|
|
50
|
+
|
|
51
|
+
## Compatibility
|
|
52
|
+
|
|
53
|
+
Check backward compatibility and migration behavior.
|
|
54
|
+
|
|
55
|
+
## Testing
|
|
56
|
+
|
|
57
|
+
Identify missing test cases — especially failure paths, boundary conditions,
|
|
58
|
+
authorization, state transitions, concurrency, and regression cases.
|
|
59
|
+
|
|
60
|
+
## Scope
|
|
61
|
+
|
|
62
|
+
Identify unrelated changes or unnecessary complexity.
|
|
63
|
+
|
|
64
|
+
Produce findings ordered by severity. For each finding include:
|
|
65
|
+
|
|
66
|
+
- severity
|
|
67
|
+
- location
|
|
68
|
+
- violated requirement or principle
|
|
69
|
+
- explanation
|
|
70
|
+
- recommended correction
|
|
71
|
+
|
|
72
|
+
Finally provide:
|
|
73
|
+
|
|
74
|
+
- specification requirements fully satisfied
|
|
75
|
+
- specification requirements partially satisfied
|
|
76
|
+
- specification requirements missing
|
|
77
|
+
- ADR violations
|
|
78
|
+
- overall recommendation
|
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: security-review
|
|
3
|
+
title: Security Review
|
|
3
4
|
description: Security review checklist. INVOKE WHEN: reviewing code for security issues, auditing a PR, checking for vulnerabilities. Check for OWASP top 10 and common Node.js/TypeScript security pitfalls.
|
|
4
5
|
---
|
|
5
6
|
|
|
7
|
+
<!-- alex disable attack -->
|
|
8
|
+
|
|
6
9
|
# security review
|
|
7
10
|
|
|
8
11
|
## checklist
|