@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,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 just close the PR.** A closed-but-existing
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