@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) Newton Koumantzelis
3
+ Copyright (c) 2026 Newton Koumantzelis
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
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.2",
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://github.com/theholocron/skills/tree/main/packages/skills#readme",
14
- "bugs": "https://github.com/theholocron/skills/issues",
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/skills.git",
18
- "directory": "packages/skills"
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
- "README.md"
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
- "test": "node --test test/index.mjs"
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
  }
@@ -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
- entry: ["index.ts"],
119
- format: "esm",
120
- fixedExtension: false,
121
- dts: true,
122
- clean: true,
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
- it("exports a non-empty config object", () => {
181
- expect(typeof config).toBe("object");
182
- expect(Object.keys(config).length).toBeGreaterThan(0);
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
- "@theholocron/<slug>-client": ^<version>
76
+ "@theholocron/<slug>-client": ^<version>
65
77
  ```
66
78
 
67
79
  ```json
@@ -73,6 +85,7 @@ catalog:
73
85
  ## Auth pattern (4-step precedence)
74
86
 
75
87
  Every plugin's `auth.ts` follows this order:
88
+
76
89
  1. `--token` CLI flag (`RuntimeContext.cliToken`)
77
90
  2. `HOLOCRON_<VENDOR>_TOKEN` env var
78
91
  3. `<VENDOR_NATIVE_ENV_VAR>` env var
@@ -1,5 +1,6 @@
1
1
  ---
2
2
  name: holocron-skill-skill
3
+ title: "Holocron: New Skill"
3
4
  description: Add a new owned skill to theholocron/skills. INVOKE WHEN: user asks to create or add a new skill to the skills repo. Invoked as /holocron-skill-skill.
4
5
  ---
5
6
 
@@ -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
- deps: { neverBundle: [/^@theholocron\//] },
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
- return value;
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
- test("does X", () => {
177
- expect(myUtil("input")).toBe("expected");
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 * as <name> from "@theholocron/<name>-utils";
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
@@ -1,5 +1,6 @@
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
 
@@ -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.