@theholocron/skills 1.3.3 → 1.12.1-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE 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/src/` 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 `configs/` |
46
+ | [`holocron-skill-client`](./src/holocron-skill-client/SKILL.md) | Scaffold a new `@theholocron/*-client` package in `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 `utils/` |
49
+ | [`holocron-skill-skill`](./src/holocron-skill-skill/SKILL.md) | Add a new owned skill to `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 update skills` (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/src/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/src/<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 --filter @theholocron/skills test:unit` — 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, and add the docs page (`docs/src/content/docs/skills/<name>.mdx`), its row in `skills/index.mdx` and its sidebar entry in `astro.config.ts`.
130
+ 4. Open a PR with a `feat(skills):` 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,53 +1,39 @@
1
1
  {
2
2
  "name": "@theholocron/skills",
3
- "version": "1.3.3",
3
+ "version": "1.12.1-alpha.4",
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-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-report.junit.xml test/index.mjs",
51
- "test:coverage": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-report.junit.xml test/index.mjs"
37
+ "test:unit": "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"
52
38
  }
53
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,64 @@
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
+ <!-- alex disable pros -->
16
+
17
+ # [Short title of the decision]
18
+
19
+ - Status: [proposed | accepted | rejected | deprecated | superseded by ADR-XXXX]
20
+ - Date: YYYY-MM-DD
21
+
22
+ ## Context and Problem Statement
23
+
24
+ 2–3 sentences describing the situation that forced this decision.
25
+
26
+ ## Decision Drivers
27
+
28
+ - [driver 1 — a constraint, goal, or value]
29
+ - [driver 2]
30
+
31
+ ## Considered Options
32
+
33
+ - [Option A]
34
+ - [Option B]
35
+ - [Option C — do nothing]
36
+
37
+ ## Decision Outcome
38
+
39
+ Chosen option: **[Option A]**, because [one-sentence justification].
40
+
41
+ ### Positive Consequences
42
+
43
+ - …
44
+
45
+ ### Negative Consequences
46
+
47
+ - …
48
+
49
+ ## Pros and Cons of the Options
50
+
51
+ ### [Option A]
52
+
53
+ - Good, because [argument]
54
+ - Bad, because [argument]
55
+
56
+ ### [Option B]
57
+
58
+ - Good, because [argument]
59
+ - Bad, because [argument]
60
+
61
+ ### [Option C — do nothing]
62
+
63
+ - Good, because [argument]
64
+ - 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 only 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 refuses 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.