@theholocron/skills 1.3.2 → 1.12.1-alpha.1
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 -25
- package/skills-lock.json +30 -0
- package/src/adr/SKILL.md +53 -0
- package/src/adr/assets/template.md +62 -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/{holocron-skill-client → src/holocron-skill-client}/SKILL.md +6 -0
- package/{holocron-skill-config → src/holocron-skill-config}/SKILL.md +11 -10
- package/{holocron-skill-plugin → src/holocron-skill-plugin}/SKILL.md +14 -1
- package/{holocron-skill-skill → src/holocron-skill-skill}/SKILL.md +1 -0
- package/{holocron-skill-util → src/holocron-skill-util}/SKILL.md +8 -6
- package/src/implement/SKILL.md +54 -0
- package/src/plan/SKILL.md +40 -0
- package/{pr-workflow → src/pr-workflow}/SKILL.md +19 -0
- package/src/review/SKILL.md +76 -0
- package/{security-review → src/security-review}/SKILL.md +1 -0
- package/src/spec/SKILL.md +52 -0
- package/src/verify/SKILL.md +22 -0
- package/commit-standards/SKILL.md +0 -65
package/LICENSE
CHANGED
package/README.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# `@theholocron/skills`
|
|
2
|
+
|
|
3
|
+
<!-- holocron:description -->
|
|
4
|
+
|
|
5
|
+
Shared agent skill registry.
|
|
6
|
+
|
|
7
|
+
<!-- /holocron:description -->
|
|
8
|
+
|
|
9
|
+
<!-- holocron:installation -->
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pnpm install @theholocron/skills
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import {} from "@theholocron/skills";
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
<!-- /holocron:installation -->
|
|
24
|
+
|
|
25
|
+
Each skill is a directory under `skills/` containing a `SKILL.md` file that Claude Code (and compatible
|
|
26
|
+
agents) can load as a slash command.
|
|
27
|
+
|
|
28
|
+
## Owned skills
|
|
29
|
+
|
|
30
|
+
Skills authored and maintained in this repo. Published inside the npm package.
|
|
31
|
+
|
|
32
|
+
### Workflow & safety
|
|
33
|
+
|
|
34
|
+
| Skill | Description |
|
|
35
|
+
| ----------------------------------------------------- | -------------------------------------------------------------- |
|
|
36
|
+
| [`git-safety`](./src/git-safety/SKILL.md) | Never force-push or run destructive git ops without permission |
|
|
37
|
+
| [`pr-workflow`](./src/pr-workflow/SKILL.md) | Always open a PR; one-change-per-PR; delete branch on close |
|
|
38
|
+
| [`commit-standards`](./src/commit-standards/SKILL.md) | Conventional Commits format + DCO signing |
|
|
39
|
+
| [`security-review`](./src/security-review/SKILL.md) | OWASP-oriented checklist for code review |
|
|
40
|
+
|
|
41
|
+
### Project-specific (theholocron)
|
|
42
|
+
|
|
43
|
+
| Skill | Description |
|
|
44
|
+
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
45
|
+
| [`holocron-skill-config`](./src/holocron-skill-config/SKILL.md) | Scaffold a new `@theholocron/*-config` package in `theholocron/configs` |
|
|
46
|
+
| [`holocron-skill-client`](./src/holocron-skill-client/SKILL.md) | Scaffold a new `@theholocron/*-client` package in `theholocron/clients` |
|
|
47
|
+
| [`holocron-skill-plugin`](./src/holocron-skill-plugin/SKILL.md) | Scaffold or migrate a new `holocron-plugin-*` package |
|
|
48
|
+
| [`holocron-skill-util`](./src/holocron-skill-util/SKILL.md) | Scaffold a new `@theholocron/*-utils` package in `theholocron/utils` |
|
|
49
|
+
| [`holocron-skill-skill`](./src/holocron-skill-skill/SKILL.md) | Add a new owned skill to `theholocron/skills` |
|
|
50
|
+
|
|
51
|
+
## External skills
|
|
52
|
+
|
|
53
|
+
Tracked in [`skills-lock.json`](./skills-lock.json) with source provenance and content hash.
|
|
54
|
+
Not committed to this repo — fetched from upstream by `holocron skills update` (planned).
|
|
55
|
+
|
|
56
|
+
| Skill | Source | Description |
|
|
57
|
+
| ----------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
58
|
+
| `find-skills` | [vercel-labs/skills](https://github.com/vercel-labs/skills) | Discover and install agent skills from the skills.sh ecosystem |
|
|
59
|
+
| `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills) | Distinctive, intentional UI design guidance |
|
|
60
|
+
| `vercel-cli` | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) | Vercel CLI: deploy, env vars, logs, domains, project linking |
|
|
61
|
+
| `turbopack` | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) | Turbopack bundler: HMR, CSS, tree shaking, webpack migration |
|
|
62
|
+
| `turborepo` | [vercel/turbo](https://github.com/vercel/turbo) | Turborepo task pipeline configuration and cache optimization |
|
|
63
|
+
| `vercel-react-best-practices` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | React/Next.js performance optimization guidelines from Vercel Engineering |
|
|
64
|
+
| `vercel-composition-patterns` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | React composition patterns that scale — avoids boolean prop proliferation |
|
|
65
|
+
| `web-design-guidelines` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | Review UI code for Web Interface Guidelines compliance (accessibility, UX, performance) |
|
|
66
|
+
| `deploy-to-vercel` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | Deploy applications and websites to Vercel with framework auto-detection |
|
|
67
|
+
| `building-components` | [vercel/components.build](https://github.com/vercel/components.build) | Building accessible, composable UI components — design tokens, APIs, publishing |
|
|
68
|
+
|
|
69
|
+
## Installation via `holocron setup`
|
|
70
|
+
|
|
71
|
+
Skills are installed by `holocron setup` based on the `skills` field in
|
|
72
|
+
`holocron.config.ts`. They are written to `.agents/skills/<name>/` with a
|
|
73
|
+
symlink at the agent-specific path, and **gitignored** — treated as dependencies,
|
|
74
|
+
not source.
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
// holocron.config.ts
|
|
78
|
+
import { defineConfig } from "@theholocron/cli";
|
|
79
|
+
|
|
80
|
+
export default defineConfig({
|
|
81
|
+
agent: "claude",
|
|
82
|
+
skills: ["git-safety", "pr-workflow", "commit-standards", "security-review"],
|
|
83
|
+
// ...
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Then run:
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
pnpm add -D @theholocron/skills
|
|
91
|
+
GITHUB_TOKEN=$(gh auth token) pnpm exec holocron setup
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Manual installation
|
|
95
|
+
|
|
96
|
+
Copy a skill directory into your project's `.agents/skills/` and symlink it:
|
|
97
|
+
|
|
98
|
+
```sh
|
|
99
|
+
cp -r node_modules/@theholocron/skills/skills/git-safety .agents/skills/
|
|
100
|
+
ln -s ../../.agents/skills/git-safety .claude/skills/git-safety
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Add both to `.gitignore`:
|
|
104
|
+
|
|
105
|
+
```gitignore
|
|
106
|
+
# managed by holocron setup — skills
|
|
107
|
+
/.agents/skills/
|
|
108
|
+
/.claude/skills/git-safety
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Contributing
|
|
112
|
+
|
|
113
|
+
### Adding an owned skill
|
|
114
|
+
|
|
115
|
+
1. Create `skills/<name>/SKILL.md` with the frontmatter format:
|
|
116
|
+
|
|
117
|
+
```markdown
|
|
118
|
+
---
|
|
119
|
+
name: <name>
|
|
120
|
+
description: One-line description. INVOKE WHEN: <trigger conditions>.
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
# skill title
|
|
124
|
+
|
|
125
|
+
…
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
2. Run `pnpm test` — the smoke test checks that every skill dir has a `SKILL.md`.
|
|
129
|
+
3. Update this README with a row in the owned skills table.
|
|
130
|
+
4. Open a PR with a `feat:` commit — semantic-release handles versioning.
|
|
131
|
+
|
|
132
|
+
### Registering an external skill
|
|
133
|
+
|
|
134
|
+
Run `pnpm exec skills add <repo> --skill <name>` from this repo root. This records the
|
|
135
|
+
skill in `skills-lock.json` with its source and content hash but does **not** copy
|
|
136
|
+
it into `skills/` — external skill content is fetched at install time.
|
package/package.json
CHANGED
|
@@ -1,52 +1,39 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/skills",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.12.1-alpha.1",
|
|
4
4
|
"description": "Shared agent skill registry.",
|
|
5
5
|
"keywords": [
|
|
6
|
-
"agent",
|
|
7
|
-
"claude",
|
|
8
|
-
"codex",
|
|
9
|
-
"developer-tools",
|
|
6
|
+
"agent-skills",
|
|
7
|
+
"claude-code",
|
|
10
8
|
"skills",
|
|
11
9
|
"theholocron"
|
|
12
10
|
],
|
|
13
|
-
"homepage": "https://
|
|
14
|
-
"bugs": "https://github.com/theholocron/
|
|
11
|
+
"homepage": "https://docs.theholocron.dev/holocron/skills/",
|
|
12
|
+
"bugs": "https://github.com/theholocron/holocron/issues",
|
|
15
13
|
"repository": {
|
|
16
14
|
"type": "git",
|
|
17
|
-
"url": "git+https://github.com/theholocron/
|
|
18
|
-
"directory": "
|
|
15
|
+
"url": "git+https://github.com/theholocron/holocron.git",
|
|
16
|
+
"directory": "skills"
|
|
19
17
|
},
|
|
20
18
|
"license": "MIT",
|
|
21
19
|
"author": "Newton Koumantzelis",
|
|
20
|
+
"sideEffects": false,
|
|
22
21
|
"type": "module",
|
|
23
22
|
"exports": {
|
|
24
23
|
"./package.json": "./package.json",
|
|
25
|
-
"./skills/*": "
|
|
24
|
+
"./skills/*": "./src/*"
|
|
26
25
|
},
|
|
27
26
|
"files": [
|
|
28
|
-
"commit-standards/",
|
|
29
|
-
"git-safety/",
|
|
30
|
-
"holocron-skill-client/",
|
|
31
|
-
"holocron-skill-config/",
|
|
32
|
-
"holocron-skill-plugin/",
|
|
33
|
-
"holocron-skill-skill/",
|
|
34
|
-
"holocron-skill-util/",
|
|
35
|
-
"pr-workflow/",
|
|
36
|
-
"security-review/",
|
|
37
27
|
"skills-lock.json",
|
|
38
|
-
"
|
|
28
|
+
"src/"
|
|
39
29
|
],
|
|
40
30
|
"engines": {
|
|
41
|
-
"node": ">=22"
|
|
42
|
-
"pnpm": ">=10"
|
|
31
|
+
"node": ">=22"
|
|
43
32
|
},
|
|
44
33
|
"publishConfig": {
|
|
45
34
|
"access": "public"
|
|
46
35
|
},
|
|
47
|
-
"releases": "https://github.com/theholocron/skills/releases",
|
|
48
|
-
"wiki": "https://github.com/theholocron/skills/wiki",
|
|
49
36
|
"scripts": {
|
|
50
|
-
"
|
|
37
|
+
"verification.unitTests": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-report.junit.xml --test-reporter=lcov --test-reporter-destination=lcov.info test/index.mjs"
|
|
51
38
|
}
|
|
52
39
|
}
|
package/skills-lock.json
CHANGED
|
@@ -1,6 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"version": 1,
|
|
3
3
|
"skills": {
|
|
4
|
+
"building-components": {
|
|
5
|
+
"source": "vercel/components.build",
|
|
6
|
+
"sourceType": "github",
|
|
7
|
+
"skillPath": "skills/building-components/SKILL.md",
|
|
8
|
+
"computedHash": "20889af7cb9b3abca1e38824f7fffaa873eb0cc4d45187967b97bd85462cf934"
|
|
9
|
+
},
|
|
10
|
+
"deploy-to-vercel": {
|
|
11
|
+
"source": "vercel-labs/agent-skills",
|
|
12
|
+
"sourceType": "github",
|
|
13
|
+
"skillPath": "skills/deploy-to-vercel/SKILL.md",
|
|
14
|
+
"computedHash": "d2b5bcc7c09fdb649129ffc7dd7b647ec1b155736974b974292675afd588cb39"
|
|
15
|
+
},
|
|
4
16
|
"find-skills": {
|
|
5
17
|
"source": "vercel-labs/skills",
|
|
6
18
|
"sourceType": "github",
|
|
@@ -30,6 +42,24 @@
|
|
|
30
42
|
"sourceType": "github",
|
|
31
43
|
"skillPath": "skills/vercel-cli/SKILL.md",
|
|
32
44
|
"computedHash": "730854ddcfabf771468e6ab83d0a3635b006d5e1ecbcc59b5682e1b14dd1f5de"
|
|
45
|
+
},
|
|
46
|
+
"vercel-composition-patterns": {
|
|
47
|
+
"source": "vercel-labs/agent-skills",
|
|
48
|
+
"sourceType": "github",
|
|
49
|
+
"skillPath": "skills/composition-patterns/SKILL.md",
|
|
50
|
+
"computedHash": "f98931159fa9c7fed043bcd18a891a46dcf89ababa38df13a4c5b7b30dc0ce07"
|
|
51
|
+
},
|
|
52
|
+
"vercel-react-best-practices": {
|
|
53
|
+
"source": "vercel-labs/agent-skills",
|
|
54
|
+
"sourceType": "github",
|
|
55
|
+
"skillPath": "skills/react-best-practices/SKILL.md",
|
|
56
|
+
"computedHash": "3219a1944e404ffc14d1d9d6aef6dd2e3855b81387ee0a044ccbfe14d34c2357"
|
|
57
|
+
},
|
|
58
|
+
"web-design-guidelines": {
|
|
59
|
+
"source": "vercel-labs/agent-skills",
|
|
60
|
+
"sourceType": "github",
|
|
61
|
+
"skillPath": "skills/web-design-guidelines/SKILL.md",
|
|
62
|
+
"computedHash": "a6a44d5498f7e8f68289902f3dedfc6f38ae0cee1e96527c80724cf27f727c2a"
|
|
33
63
|
}
|
|
34
64
|
}
|
|
35
65
|
}
|
package/src/adr/SKILL.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: adr
|
|
3
|
+
description: ADR Author. INVOKE WHEN: an engineering discussion has reached an accepted decision that needs to be recorded as an Architecture Decision Record. Summarizes the decision — does not reproduce the full debate.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ADR Author
|
|
7
|
+
|
|
8
|
+
Create an Architecture Decision Record from the accepted engineering decision.
|
|
9
|
+
|
|
10
|
+
Use the accepted GitHub Discussion as the primary source of decision history.
|
|
11
|
+
|
|
12
|
+
Capture the final architectural conclusion, not the full discussion.
|
|
13
|
+
|
|
14
|
+
Include:
|
|
15
|
+
|
|
16
|
+
- Title
|
|
17
|
+
- Status
|
|
18
|
+
- Date
|
|
19
|
+
- Context
|
|
20
|
+
- Decision
|
|
21
|
+
- Rationale
|
|
22
|
+
- Alternatives considered
|
|
23
|
+
- Consequences
|
|
24
|
+
- Related issue, Discussion, and specifications
|
|
25
|
+
|
|
26
|
+
Succinctly distinguish between the final decision, supporting rationale, and
|
|
27
|
+
alternatives that were rejected.
|
|
28
|
+
|
|
29
|
+
Do not introduce new architectural decisions.
|
|
30
|
+
|
|
31
|
+
If the Discussion does not contain enough information to state a decision
|
|
32
|
+
confidently, identify the missing information instead of inventing it.
|
|
33
|
+
|
|
34
|
+
## Format
|
|
35
|
+
|
|
36
|
+
Use MADR format. Start from this skill's template, `assets/template.md`
|
|
37
|
+
(next to this file). Number the record with the next unused number: list
|
|
38
|
+
`docs/wiki/decisions/` first, and never reuse or overwrite an existing file.
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
mkdir -p docs/wiki/decisions
|
|
42
|
+
dest=docs/wiki/decisions/000N-short-title.md
|
|
43
|
+
test ! -e "$dest" && cp <path-to-this-skill>/assets/template.md "$dest" \
|
|
44
|
+
|| echo "$dest already exists — pick the next unused number"
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The template starts as `status: proposed`. This skill records decisions that
|
|
48
|
+
were already accepted, so set `status: accepted` in the frontmatter and in the
|
|
49
|
+
`Status` line, and set `date` to the acceptance date from the Discussion. Use a
|
|
50
|
+
different status only when the Discussion says the decision was rejected,
|
|
51
|
+
deprecated or superseded.
|
|
52
|
+
|
|
53
|
+
`madr` has no CLI — creation is manual. Save to `docs/wiki/decisions/NNNN-<slug>.md`.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-XXXX
|
|
3
|
+
title: ""
|
|
4
|
+
status: proposed
|
|
5
|
+
date: YYYY-MM-DD
|
|
6
|
+
owners: []
|
|
7
|
+
specs: []
|
|
8
|
+
discussion:
|
|
9
|
+
github:
|
|
10
|
+
supersedes: []
|
|
11
|
+
superseded-by: []
|
|
12
|
+
tags: []
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# [Short title of the decision]
|
|
16
|
+
|
|
17
|
+
- Status: [proposed | accepted | rejected | deprecated | superseded by ADR-XXXX]
|
|
18
|
+
- Date: YYYY-MM-DD
|
|
19
|
+
|
|
20
|
+
## Context and Problem Statement
|
|
21
|
+
|
|
22
|
+
2–3 sentences describing the situation that forced this decision.
|
|
23
|
+
|
|
24
|
+
## Decision Drivers
|
|
25
|
+
|
|
26
|
+
- [driver 1 — a constraint, goal, or value]
|
|
27
|
+
- [driver 2]
|
|
28
|
+
|
|
29
|
+
## Considered Options
|
|
30
|
+
|
|
31
|
+
- [Option A]
|
|
32
|
+
- [Option B]
|
|
33
|
+
- [Option C — do nothing]
|
|
34
|
+
|
|
35
|
+
## Decision Outcome
|
|
36
|
+
|
|
37
|
+
Chosen option: **[Option A]**, because [one-sentence justification].
|
|
38
|
+
|
|
39
|
+
### Positive Consequences
|
|
40
|
+
|
|
41
|
+
- …
|
|
42
|
+
|
|
43
|
+
### Negative Consequences
|
|
44
|
+
|
|
45
|
+
- …
|
|
46
|
+
|
|
47
|
+
## Pros and Cons of the Options
|
|
48
|
+
|
|
49
|
+
### [Option A]
|
|
50
|
+
|
|
51
|
+
- Good, because [argument]
|
|
52
|
+
- Bad, because [argument]
|
|
53
|
+
|
|
54
|
+
### [Option B]
|
|
55
|
+
|
|
56
|
+
- Good, because [argument]
|
|
57
|
+
- Bad, because [argument]
|
|
58
|
+
|
|
59
|
+
### [Option C — do nothing]
|
|
60
|
+
|
|
61
|
+
- Good, because [argument]
|
|
62
|
+
- Bad, because [argument]
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: commit-standards
|
|
3
|
+
title: Commit Standards
|
|
4
|
+
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).
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# commit standards
|
|
8
|
+
|
|
9
|
+
## Conventional Commits
|
|
10
|
+
|
|
11
|
+
All commit subjects must follow the Conventional Commits format:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
<type>[optional scope]: <description>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
### Types
|
|
18
|
+
|
|
19
|
+
| Type | Use for |
|
|
20
|
+
| ---------- | --------------------------------------------------- |
|
|
21
|
+
| `feat` | New feature (triggers minor version bump) |
|
|
22
|
+
| `fix` | Bug fix (triggers patch bump) |
|
|
23
|
+
| `chore` | Maintenance that doesn't affect published artifacts |
|
|
24
|
+
| `docs` | Documentation-only changes |
|
|
25
|
+
| `ci` | CI/workflow changes (won't appear in changelog) |
|
|
26
|
+
| `test` | Test additions or changes |
|
|
27
|
+
| `refactor` | Code restructuring with no behavior change |
|
|
28
|
+
| `perf` | Performance improvement |
|
|
29
|
+
|
|
30
|
+
### Breaking changes
|
|
31
|
+
|
|
32
|
+
Append `!` after the type/scope, or add `BREAKING CHANGE:` in the footer:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
feat!: remove deprecated auth endpoint
|
|
36
|
+
|
|
37
|
+
BREAKING CHANGE: the /v1/auth endpoint has been removed; use /v2/auth
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Devmoji — always add the emoji
|
|
41
|
+
|
|
42
|
+
All commits use [devmoji](https://github.com/folke/devmoji). The emoji goes **inside the subject, after `type(scope): `** and before the description. The `prepare-commit-msg` hook adds it automatically on `git commit`, but always include it explicitly in `-m` strings:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
feat: 💥 add OAuth2 login flow
|
|
46
|
+
fix: 🐛 handle null session on logout
|
|
47
|
+
fail: 💩 emergency patch for broken prod deploy
|
|
48
|
+
docs: 📚 update deploy prerequisites
|
|
49
|
+
chore: 🔧 update dependencies
|
|
50
|
+
ci: 👷 cache pnpm store
|
|
51
|
+
test: 🚨 add coverage for edge case
|
|
52
|
+
refactor: ♻️ extract helper function
|
|
53
|
+
perf: ⚡ reduce bundle size
|
|
54
|
+
build: 📦 migrate to tsdown
|
|
55
|
+
chore(release): 🚀 1.2.0
|
|
56
|
+
lint: fix all eslint warnings
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
| Type | Emoji | Notes |
|
|
60
|
+
| ---------------- | -------- | ---------------------------------------------- |
|
|
61
|
+
| `feat` | 💥 | New feature (custom: boom instead of sparkles) |
|
|
62
|
+
| `fix` | 🐛 | Bug fix |
|
|
63
|
+
| `fail` | 💩 | Catastrophic failure or emergency hot fix |
|
|
64
|
+
| `docs` | 📚 | Documentation |
|
|
65
|
+
| `chore` | 🔧 | Maintenance |
|
|
66
|
+
| `chore(release)` | 🚀 | Release |
|
|
67
|
+
| `chore(deps)` | 🔗 | Dependencies |
|
|
68
|
+
| `ci` | 👷 | CI changes |
|
|
69
|
+
| `refactor` | ♻️ | Refactor |
|
|
70
|
+
| `test` | 🚨 | Tests |
|
|
71
|
+
| `perf` | ⚡ | Performance |
|
|
72
|
+
| `build` | 📦 | Build changes |
|
|
73
|
+
| `style` | 🎨 | Style/formatting |
|
|
74
|
+
| `security` | 🔒 | Security |
|
|
75
|
+
| `revert` | ⏪ | Revert |
|
|
76
|
+
| `lint` | _(none)_ | Extra accepted type; no emoji mapped |
|
|
77
|
+
|
|
78
|
+
## DCO — always `git commit -s`
|
|
79
|
+
|
|
80
|
+
The `Signed-off-by:` trailer is required on every commit in theholocron repos.
|
|
81
|
+
The `-s` flag generates it automatically from your git config:
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
git commit -s -m "feat: add new thing"
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Result:
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
feat: add new thing
|
|
91
|
+
|
|
92
|
+
Signed-off-by: Your Name <you@example.com>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Never skip `-s`. Branch protection and CI enforce DCO.
|
|
96
|
+
|
|
97
|
+
## Validate before committing, don't just guess
|
|
98
|
+
|
|
99
|
+
Per [commitlint's own AI-agent guidance](https://commitlint.js.org/guides/ai-agents.html):
|
|
100
|
+
treat the resolved commitlint config as a contract, not a memory exercise — verify a
|
|
101
|
+
draft message actually passes before running `git commit`, the same way you'd run a
|
|
102
|
+
type checker before trusting your own types are right.
|
|
103
|
+
|
|
104
|
+
```sh
|
|
105
|
+
# Resolved rules for this repo, if unsure what applies
|
|
106
|
+
npx commitlint --print-config json
|
|
107
|
+
|
|
108
|
+
# Validate a draft message before committing
|
|
109
|
+
printf '%s' "feat: 💥 add OAuth2 login flow" | npx commitlint
|
|
110
|
+
# exit 0 = passes
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
If a repo has `@theholocron/commitlint-config` installed, point at its built output
|
|
114
|
+
directly rather than relying on auto-discovery (same pattern this org's own
|
|
115
|
+
`commit-msg` hook and CI already use):
|
|
116
|
+
|
|
117
|
+
```sh
|
|
118
|
+
printf '%s' "<message>" | npx commitlint --config node_modules/@theholocron/commitlint-config/dist/index.js
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
If the `commit-msg` hook rejects a commit, the rejected rule name is in the error —
|
|
122
|
+
fix the message and retry. **Don't reach for `git commit --no-verify` to get past an
|
|
123
|
+
actual commit-message failure** — fix the message. (This is scoped to the message
|
|
124
|
+
itself: bypassing a hook for a separately-confirmed, pre-existing, unrelated failure
|
|
125
|
+
elsewhere in the repo is a different, occasionally legitimate call — see `git-safety`.)
|
|
126
|
+
|
|
127
|
+
## No agent attribution
|
|
128
|
+
|
|
129
|
+
Do not add `Co-Authored-By: Claude` or any agent attribution in commits, PRs,
|
|
130
|
+
issues, or docs. The author is always the user.
|
|
131
|
+
|
|
132
|
+
## Commit scope
|
|
133
|
+
|
|
134
|
+
Keep commits focused. One logical change per commit makes history bisectable and
|
|
135
|
+
makes semantic-release versioning accurate.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: design
|
|
3
|
+
description: Design Agent. INVOKE WHEN: an issue or discovery output needs an architectural solution explored. Compares alternatives and identifies decisions requiring ADRs. Does not write implementation code.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Design Agent
|
|
7
|
+
|
|
8
|
+
You are acting as a software architect.
|
|
9
|
+
|
|
10
|
+
Using the issue, discovery findings, existing architecture, specifications,
|
|
11
|
+
and ADRs, propose a design for this change.
|
|
12
|
+
|
|
13
|
+
Do not write implementation code.
|
|
14
|
+
|
|
15
|
+
Identify the important engineering decisions required.
|
|
16
|
+
|
|
17
|
+
For each meaningful decision:
|
|
18
|
+
|
|
19
|
+
1. Explain the decision that must be made.
|
|
20
|
+
2. Describe viable alternatives.
|
|
21
|
+
3. Explain advantages and disadvantages.
|
|
22
|
+
4. Identify operational and maintenance consequences.
|
|
23
|
+
5. Recommend an approach and explain why.
|
|
24
|
+
|
|
25
|
+
Treat existing accepted ADRs as architectural constraints.
|
|
26
|
+
Do not contradict an accepted ADR without explicitly identifying the conflict.
|
|
27
|
+
|
|
28
|
+
At the end, produce:
|
|
29
|
+
|
|
30
|
+
- Recommended design
|
|
31
|
+
- Open questions
|
|
32
|
+
- Decisions requiring ADRs
|
|
33
|
+
- Decisions that are implementation details and do not require ADRs
|
|
34
|
+
- Suggested specification scope
|
|
35
|
+
|
|
36
|
+
Do not create ADRs merely because a choice exists. An ADR is warranted only
|
|
37
|
+
when the decision is significant enough that a future engineer may reasonably
|
|
38
|
+
ask why one approach was selected over another.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: destructive-command-guard
|
|
3
|
+
title: Destructive Command Guard
|
|
4
|
+
description: Destructive command safety rules. INVOKE WHEN: about to run any Bash command that deletes, resets, drops, prunes, or truncates. Pairs with the dcg PreToolUse hook (https://github.com/Dicklesworthstone/destructive_command_guard).
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# destructive-command-guard
|
|
8
|
+
|
|
9
|
+
These rules mirror what the `dcg` PreToolUse hook enforces at runtime. Follow them proactively so the hook is a safety net, not the first line of defense.
|
|
10
|
+
|
|
11
|
+
## Git — never run without explicit permission
|
|
12
|
+
|
|
13
|
+
| Blocked | Safer alternative |
|
|
14
|
+
| ------------------------------------- | ------------------------------- |
|
|
15
|
+
| `git reset --hard` | `git stash` first, then reset |
|
|
16
|
+
| `git clean -f` / `git clean -fd` | `git clean -n` (dry run) first |
|
|
17
|
+
| `git checkout -- .` / `git restore .` | Restore individual files only |
|
|
18
|
+
| `git push --force` / `git push -f` | `git push --force-with-lease` |
|
|
19
|
+
| `git branch -D` | `git branch -d` (safe delete) |
|
|
20
|
+
| `git rebase -i` with `drop` | Confirm each drop with the user |
|
|
21
|
+
|
|
22
|
+
## Filesystem — never run without explicit permission
|
|
23
|
+
|
|
24
|
+
| Blocked | Safer alternative |
|
|
25
|
+
| ------------------------------ | -------------------------------------- |
|
|
26
|
+
| `rm -rf <dir>` | `trash <dir>` or move to `/tmp/` |
|
|
27
|
+
| `find ... -delete` | `find ... -print` first to verify |
|
|
28
|
+
| `chmod -R 777` | Scope to specific files only |
|
|
29
|
+
| `> file` (truncating redirect) | Confirm file contents before overwrite |
|
|
30
|
+
| `dd if=... of=/dev/...` | Confirm target device explicitly |
|
|
31
|
+
|
|
32
|
+
## Database — never run without explicit permission
|
|
33
|
+
|
|
34
|
+
| Blocked | Safer alternative |
|
|
35
|
+
| ------------------------------ | ----------------------------------------- |
|
|
36
|
+
| `DROP TABLE` / `DROP DATABASE` | Rename table first; drop after confirming |
|
|
37
|
+
| `TRUNCATE` | `DELETE WHERE ...` with a `WHERE` clause |
|
|
38
|
+
| `DELETE` without `WHERE` | Always require a `WHERE` clause |
|
|
39
|
+
|
|
40
|
+
## Containers / infrastructure
|
|
41
|
+
|
|
42
|
+
| Blocked | Safer alternative |
|
|
43
|
+
| ----------------------------- | --------------------------------------- |
|
|
44
|
+
| `docker system prune` | `docker container prune` (scope it) |
|
|
45
|
+
| `kubectl delete namespace` | Confirm namespace + context explicitly |
|
|
46
|
+
| `terraform destroy` | Require `--target` to scope the destroy |
|
|
47
|
+
| `aws ec2 terminate-instances` | Require explicit instance IDs, confirm |
|
|
48
|
+
|
|
49
|
+
## Rule of thumb
|
|
50
|
+
|
|
51
|
+
If a command is irreversible and affects more than one file or row, **stop and ask** before running it. The user's confirmation costs seconds; accidental deletion costs hours.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: discover
|
|
3
|
+
description: Discovery Agent. INVOKE WHEN: starting any non-trivial engineering task. Investigates the problem and existing system before proposing any implementation. Does not write code.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Discovery Agent
|
|
7
|
+
|
|
8
|
+
You are performing engineering discovery.
|
|
9
|
+
|
|
10
|
+
Your goal is to understand the problem and the existing system before
|
|
11
|
+
proposing implementation changes.
|
|
12
|
+
|
|
13
|
+
Read the relevant issue, repository code, documentation, specifications,
|
|
14
|
+
and ADRs.
|
|
15
|
+
|
|
16
|
+
Investigate:
|
|
17
|
+
|
|
18
|
+
- current behavior
|
|
19
|
+
- relevant architecture
|
|
20
|
+
- dependencies
|
|
21
|
+
- constraints
|
|
22
|
+
- existing patterns
|
|
23
|
+
- affected packages/services
|
|
24
|
+
- compatibility concerns
|
|
25
|
+
- security concerns
|
|
26
|
+
- operational concerns
|
|
27
|
+
|
|
28
|
+
Do not implement anything.
|
|
29
|
+
Do not assume the proposed solution is correct.
|
|
30
|
+
|
|
31
|
+
Produce:
|
|
32
|
+
|
|
33
|
+
1. Problem summary
|
|
34
|
+
2. Current system behavior
|
|
35
|
+
3. Relevant architecture
|
|
36
|
+
4. Constraints
|
|
37
|
+
5. Systems/packages likely affected
|
|
38
|
+
6. Unknowns or open questions
|
|
39
|
+
7. Risks
|
|
40
|
+
8. Decisions that may require architectural discussion
|
|
41
|
+
9. Recommended next step
|
|
42
|
+
|
|
43
|
+
If you discover a meaningful architectural choice, explicitly identify it
|
|
44
|
+
rather than silently making the decision.
|
|
@@ -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 clearly 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
|
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: holocron-skill-client
|
|
3
|
+
title: "Holocron: New Client"
|
|
3
4
|
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
|
---
|
|
5
6
|
|
|
@@ -141,6 +142,7 @@ export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
|
|
|
141
142
|
|
|
142
143
|
## 5. Checklist before opening a PR
|
|
143
144
|
|
|
145
|
+
- [ ] Feature branch created before any code was written
|
|
144
146
|
- [ ] `pnpm install` — workspace symlink created
|
|
145
147
|
- [ ] `pnpm --filter @theholocron/<slug>-client typecheck` passes
|
|
146
148
|
- [ ] `pnpm --filter @theholocron/<slug>-client lint` passes
|
|
@@ -149,3 +151,7 @@ export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
|
|
|
149
151
|
- [ ] `packages/<slug>-client` added to `prepareCmd` in `.releaserc.json`
|
|
150
152
|
- [ ] `version` in `package.json` set to current lockstep version
|
|
151
153
|
- [ ] `codecov.yml` entry added
|
|
154
|
+
- [ ] Client entry added to the docs-theme registry
|
|
155
|
+
- [ ] Docs page added under `docs/` in the same PR
|
|
156
|
+
- [ ] PR title follows Conventional Commits
|
|
157
|
+
- [ ] CI green before requesting review
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: holocron-skill-config
|
|
3
|
+
title: "Holocron: New Config"
|
|
3
4
|
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
|
---
|
|
5
6
|
|
|
@@ -115,11 +116,11 @@ Key fields:
|
|
|
115
116
|
```ts
|
|
116
117
|
import { defineConfig } from "tsdown";
|
|
117
118
|
export default defineConfig({
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
119
|
+
entry: ["index.ts"],
|
|
120
|
+
format: "esm",
|
|
121
|
+
fixedExtension: false,
|
|
122
|
+
dts: true,
|
|
123
|
+
clean: true,
|
|
123
124
|
});
|
|
124
125
|
```
|
|
125
126
|
|
|
@@ -154,7 +155,7 @@ export default defineConfig(node());
|
|
|
154
155
|
import type { Config } from "<tool>";
|
|
155
156
|
|
|
156
157
|
const config = {
|
|
157
|
-
|
|
158
|
+
// ...
|
|
158
159
|
} satisfies Config;
|
|
159
160
|
|
|
160
161
|
export default config;
|
|
@@ -177,10 +178,10 @@ import { describe, it, expect } from "vitest";
|
|
|
177
178
|
import config from "./index.js";
|
|
178
179
|
|
|
179
180
|
describe("<tool>-config", () => {
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
181
|
+
it("exports a non-empty config object", () => {
|
|
182
|
+
expect(typeof config).toBe("object");
|
|
183
|
+
expect(Object.keys(config).length).toBeGreaterThan(0);
|
|
184
|
+
});
|
|
184
185
|
});
|
|
185
186
|
```
|
|
186
187
|
|
|
@@ -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,6 +42,17 @@ 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`.
|
|
@@ -61,7 +73,7 @@ export {
|
|
|
61
73
|
```yaml
|
|
62
74
|
# pnpm-workspace.yaml
|
|
63
75
|
catalog:
|
|
64
|
-
|
|
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
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: holocron-skill-util
|
|
3
|
+
title: "Holocron: New Util"
|
|
3
4
|
description: Scaffold a new @theholocron/<slug>-utils package in theholocron/utils. INVOKE WHEN: user asks to add a new utility package to the utils monorepo. Invoked as /holocron-skill-util.
|
|
4
5
|
---
|
|
5
6
|
|
|
@@ -12,6 +13,7 @@ Scaffold a new `@theholocron/<name>-utils` package in `theholocron/utils`.
|
|
|
12
13
|
Replace `<name>` with the utility domain in kebab-case (e.g. `color`, `math`, `format`).
|
|
13
14
|
|
|
14
15
|
Reference implementations:
|
|
16
|
+
|
|
15
17
|
- Node-only package: `packages/string-utils` (canonical, no browser APIs)
|
|
16
18
|
- Browser-API package: `packages/location-utils` (adds DOM lib + eslint override)
|
|
17
19
|
|
|
@@ -97,7 +99,7 @@ import { library } from "@theholocron/tsdown-config/presets/library";
|
|
|
97
99
|
import type { UserConfig } from "tsdown";
|
|
98
100
|
|
|
99
101
|
const config: UserConfig = library({
|
|
100
|
-
|
|
102
|
+
deps: { neverBundle: [/^@theholocron\//] },
|
|
101
103
|
});
|
|
102
104
|
|
|
103
105
|
export default config;
|
|
@@ -152,7 +154,7 @@ export default defineConfig(library({ globals: true }) as never);
|
|
|
152
154
|
```ts
|
|
153
155
|
// Named exports — no default export
|
|
154
156
|
export function myUtil(value: string): string {
|
|
155
|
-
|
|
157
|
+
return value;
|
|
156
158
|
}
|
|
157
159
|
```
|
|
158
160
|
|
|
@@ -173,9 +175,9 @@ import { describe, expect, test } from "vitest";
|
|
|
173
175
|
import { myUtil } from "./index.ts";
|
|
174
176
|
|
|
175
177
|
describe("<Name>", () => {
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
178
|
+
test("does X", () => {
|
|
179
|
+
expect(myUtil("input")).toBe("expected");
|
|
180
|
+
});
|
|
179
181
|
});
|
|
180
182
|
```
|
|
181
183
|
|
|
@@ -195,7 +197,7 @@ pnpm add @theholocron/<name>-utils
|
|
|
195
197
|
## Usage
|
|
196
198
|
|
|
197
199
|
\`\`\`typescript
|
|
198
|
-
import
|
|
200
|
+
import \* as <name> from "@theholocron/<name>-utils";
|
|
199
201
|
|
|
200
202
|
<minimal working example>
|
|
201
203
|
\`\`\`
|
|
@@ -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)
|
|
@@ -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,76 @@
|
|
|
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
|
+
# Review Agent
|
|
7
|
+
|
|
8
|
+
You are acting as an independent engineering reviewer.
|
|
9
|
+
|
|
10
|
+
Review the implementation against:
|
|
11
|
+
|
|
12
|
+
1. The GitHub issue
|
|
13
|
+
2. Accepted ADRs
|
|
14
|
+
3. The accepted specification
|
|
15
|
+
4. The implementation plan
|
|
16
|
+
5. Repository conventions
|
|
17
|
+
|
|
18
|
+
Do not assume the implementation is correct because tests pass.
|
|
19
|
+
|
|
20
|
+
Evaluate:
|
|
21
|
+
|
|
22
|
+
## Specification Compliance
|
|
23
|
+
|
|
24
|
+
Identify every requirement in the specification and determine whether it is
|
|
25
|
+
implemented.
|
|
26
|
+
|
|
27
|
+
## ADR Compliance
|
|
28
|
+
|
|
29
|
+
Identify any behavior or architecture that conflicts with accepted ADRs.
|
|
30
|
+
|
|
31
|
+
## Correctness
|
|
32
|
+
|
|
33
|
+
Look for logical errors, invalid state transitions, race conditions, missing
|
|
34
|
+
validation, and incorrect assumptions.
|
|
35
|
+
|
|
36
|
+
## Security
|
|
37
|
+
|
|
38
|
+
Review authentication, authorization, data exposure, input handling, and
|
|
39
|
+
trust boundaries.
|
|
40
|
+
|
|
41
|
+
## Failure Behavior
|
|
42
|
+
|
|
43
|
+
Review errors, retries, partial failures, rollback behavior, and recovery.
|
|
44
|
+
|
|
45
|
+
## Observability
|
|
46
|
+
|
|
47
|
+
Confirm appropriate logs, metrics, traces, and diagnostic information.
|
|
48
|
+
|
|
49
|
+
## Compatibility
|
|
50
|
+
|
|
51
|
+
Check backward compatibility and migration behavior.
|
|
52
|
+
|
|
53
|
+
## Testing
|
|
54
|
+
|
|
55
|
+
Identify missing test cases — especially failure paths, boundary conditions,
|
|
56
|
+
authorization, state transitions, concurrency, and regression cases.
|
|
57
|
+
|
|
58
|
+
## Scope
|
|
59
|
+
|
|
60
|
+
Identify unrelated changes or unnecessary complexity.
|
|
61
|
+
|
|
62
|
+
Produce findings ordered by severity. For each finding include:
|
|
63
|
+
|
|
64
|
+
- severity
|
|
65
|
+
- location
|
|
66
|
+
- violated requirement or principle
|
|
67
|
+
- explanation
|
|
68
|
+
- recommended correction
|
|
69
|
+
|
|
70
|
+
Finally provide:
|
|
71
|
+
|
|
72
|
+
- specification requirements fully satisfied
|
|
73
|
+
- specification requirements partially satisfied
|
|
74
|
+
- specification requirements missing
|
|
75
|
+
- ADR violations
|
|
76
|
+
- overall recommendation
|
|
@@ -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,65 +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
|
-
## DCO — always `git commit -s`
|
|
40
|
-
|
|
41
|
-
The `Signed-off-by:` trailer is required on every commit in theholocron repos.
|
|
42
|
-
The `-s` flag generates it automatically from your git config:
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
git commit -s -m "feat: add new thing"
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
Result:
|
|
49
|
-
```
|
|
50
|
-
feat: add new thing
|
|
51
|
-
|
|
52
|
-
Signed-off-by: Your Name <you@example.com>
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
Never skip `-s`. Branch protection and CI enforce DCO.
|
|
56
|
-
|
|
57
|
-
## No agent attribution
|
|
58
|
-
|
|
59
|
-
Do not add `Co-Authored-By: Claude` or any agent attribution in commits, PRs,
|
|
60
|
-
issues, or docs. The author is always the user.
|
|
61
|
-
|
|
62
|
-
## Commit scope
|
|
63
|
-
|
|
64
|
-
Keep commits focused. One logical change per commit makes history bisectable and
|
|
65
|
-
makes semantic-release versioning accurate.
|