@technomoron/agent-brain 0.1.1 → 0.1.3
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/CHANGES.md +21 -0
- package/README.md +19 -15
- package/dist/brain/built-in-skills.js +2 -0
- package/dist/brain/cli.js +8 -0
- package/dist/brain/config.js +7 -0
- package/dist/brain/connectors.js +2 -0
- package/dist/brain/consolidation.js +4 -0
- package/dist/brain/git.js +9 -2
- package/dist/brain/github-reviews.js +13 -0
- package/dist/brain/projects.js +4 -6
- package/dist/brain/remote-policy.js +12 -3
- package/dist/brain/remote-server.js +54 -12
- package/dist/brain/repositories.js +3 -0
- package/dist/brain/repository-discovery.js +4 -1
- package/dist/brain/server.js +14 -2
- package/dist/brain/skills.js +11 -0
- package/dist/brain/store.js +36 -1
- package/dist/brain/todos.js +10 -1
- package/dist/brain/windows-pipe.js +2 -1
- package/dist/version.js +1 -4
- package/examples/remote.jsonc +1 -1
- package/ops/brain-pipe-security.ps1 +40 -0
- package/ops/config-deploy-root.cjs +6 -0
- package/ops/config-deploy.cjs +11 -4
- package/ops/config-policy.cjs +16 -0
- package/ops/config-sync.cjs +34 -1
- package/package.json +1 -1
- package/skills/brain-consolidate/README.md +5 -0
- package/skills/brain-import/README.md +5 -0
- package/skills/brain-memory/README.md +5 -0
- package/skills/brain-memory/SKILL.md +7 -3
- package/skills/code-review/README.md +7 -0
- package/skills/code-review/SKILL.md +26 -0
- package/skills/git-workflow/README.md +5 -0
- package/skills/git-workflow/SKILL.md +14 -0
- package/skills/node-cleanup/README.md +5 -0
- package/skills/node-cleanup/SKILL.md +239 -0
- package/skills/node-cleanup/agents/openai.yaml +4 -0
- package/skills/package-integrity-check/README.md +5 -0
- package/skills/package-integrity-check/SKILL.md +27 -0
- package/skills/todo-manager/README.md +5 -0
- package/skills/todo-manager/SKILL.md +9 -3
- package/skills/unslop/README.md +5 -0
- package/skills/unslop/SKILL.md +177 -0
- package/skills/unslop/agents/openai.yaml +4 -0
- package/skills/brain-review/SKILL.md +0 -38
- package/skills/code-review-organizer/SKILL.md +0 -150
- package/skills/review-items/SKILL.md +0 -43
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: node-cleanup
|
|
3
|
+
description: Audit and clean global Node tooling, npm/pnpm packages and command shims on Linux, Unix-like, and Windows hosts. Use when Codex or Claude needs to enforce that admin/root-owned global npm installs are limited to approved CLI packages, Node/npm/pnpm global assets live under /usr/local on Unix-like hosts, random npm/pnpm-installed shims, bins, links, and node_modules under /usr/bin, /usr/lib, /usr/share, or other non-/usr/local locations are removed, pnpm has no user-global installs, pnpm global state uses one admin/root-owned repository, updater units or scheduled tasks follow the same policy, and project directories keep using their own package managers and local dependencies.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Node Cleanup
|
|
7
|
+
|
|
8
|
+
Use this skill to audit and remediate global Node package-manager state without disturbing project-local dependencies.
|
|
9
|
+
|
|
10
|
+
## Policy
|
|
11
|
+
|
|
12
|
+
Only these tools may be installed globally, and they must be installed by `npm`, not `pnpm`:
|
|
13
|
+
|
|
14
|
+
- `npm`
|
|
15
|
+
- `pnpm`
|
|
16
|
+
- `@openai/codex` for the `codex` command
|
|
17
|
+
- `@anthropic-ai/claude-code` for the `claude` command
|
|
18
|
+
- `@google/gemini-cli` for the `gemini` command
|
|
19
|
+
- `@xai-official/grok` for the `grok` command
|
|
20
|
+
- `@technomoron/agent-run` for the `agent-run` command
|
|
21
|
+
- `corepack`, if this host uses Corepack shims
|
|
22
|
+
- `fallow`
|
|
23
|
+
- `ripgrep` for the `rg`/`ripgrep` commands
|
|
24
|
+
- `pm2`
|
|
25
|
+
- `tsx`
|
|
26
|
+
- `typescript` for the `tsc` command
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
Global installs are host tooling only. Do not remove or rewrite project-local `node_modules`, lockfiles, `package.json`, package-manager fields, or workspace configuration unless the user explicitly asks for project cleanup. Projects should continue to use their preferred package manager and their own local dependencies.
|
|
30
|
+
|
|
31
|
+
On Linux and Unix-like hosts, `/usr/local` is the only approved root for globally managed Node tooling. Approved command shims should resolve from `/usr/local/bin`, npm global packages from `/usr/local/lib/node_modules`, and pnpm global state from `/usr/local/share/pnpm`. Treat npm, pnpm, corepack, random npm/pnpm-installed shims, bins, links, and global `node_modules` under `/usr/bin`, `/usr/lib`, `/usr/lib/node_modules`, `/usr/share/nodejs`, `/usr/share/npm`, `/usr/share/pnpm`, `/opt`, or user-local global directories as stale or noncompliant unless the user explicitly asks to keep a distro-managed Node runtime. The cleanup target is that global package-manager assets and AI/tooling CLIs are consolidated under `/usr/local/*`.
|
|
32
|
+
|
|
33
|
+
## Root-Only Globals
|
|
34
|
+
|
|
35
|
+
Require global package-manager commands to run as root:
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
test "$(id -u)" -eq 0
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
For `npm`, the global prefix should be a root-owned system prefix such as `/usr/local`, with commands installed into `/usr/local/bin`:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
npm prefix -g
|
|
45
|
+
npm root -g
|
|
46
|
+
npm config get prefix
|
|
47
|
+
for name in node npm npx corepack pnpm; do command -v "$name" 2>/dev/null || true; done
|
|
48
|
+
test "$(npm prefix -g)/bin" = /usr/local/bin
|
|
49
|
+
test "$(npm root -g)" = /usr/local/lib/node_modules
|
|
50
|
+
stat -Lc '%U:%G %a %n' "$(npm prefix -g)" "$(npm root -g)" "$(npm prefix -g)/bin"
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
For `pnpm`, `-g` is allowed only as root, and there must be a single root-owned global package repository. The pnpm global bin directory must also be `/usr/local/bin`, matching npm. Prefer explicit system locations such as:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
pnpm config set --global global-dir /usr/local/share/pnpm/global
|
|
57
|
+
pnpm config set --global global-bin-dir /usr/local/bin
|
|
58
|
+
install -d -o root -g root -m 0755 /usr/local/share/pnpm/global /usr/local/bin
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
If non-root users resolve different pnpm global paths, put the same defaults in `/etc/npmrc`:
|
|
62
|
+
|
|
63
|
+
```ini
|
|
64
|
+
global-dir=/usr/local/share/pnpm/global
|
|
65
|
+
global-bin-dir=/usr/local/bin
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Also set `PNPM_HOME=/usr/local` system-wide, for example in `/etc/environment`, so pnpm's fallback global bin path resolves to `/usr/local/bin` instead of a user-local pnpm directory:
|
|
69
|
+
|
|
70
|
+
```ini
|
|
71
|
+
PNPM_HOME=/usr/local
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
No user-global pnpm locations should be active. Check at least:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
pnpm config get global-dir
|
|
78
|
+
pnpm config get global-bin-dir
|
|
79
|
+
pnpm root -g
|
|
80
|
+
pnpm bin -g
|
|
81
|
+
find /root "$HOME" -maxdepth 4 \( -path '*/.local/share/pnpm' -o -path '*/.pnpm-global' -o -path '*/pnpm/global' \) -type d 2>/dev/null
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Ignore package-manager caches when deciding global compliance. Caches like `~/.npm`, `~/.cache/pnpm`, and pnpm metadata stores are not global package installs. Never print raw auth tokens from `.npmrc`, pnpm config, environment variables, or logs.
|
|
85
|
+
|
|
86
|
+
The pnpm package repository may live directly at `/usr/local/share/pnpm/global`, or `/usr/local/share/pnpm` may be a symlink to another storage location for disk space. When a global directory is a symlink, check the symlink target with `stat -L`; symlink mode bits commonly display as `777` and do not grant write access to the target.
|
|
87
|
+
|
|
88
|
+
## Audit
|
|
89
|
+
|
|
90
|
+
Inventory npm globals:
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
npm list -g --depth=0 --json
|
|
94
|
+
ls -la "$(npm root -g)"
|
|
95
|
+
ls -la "$(npm prefix -g)/bin" | grep -E 'npm|pnpm|codex|claude|gemini|grok|agent-run|corepack|fallow|rg|ripgrep|pm2|tsx|tsc'
|
|
96
|
+
for name in node npm npx pnpm pnpx corepack codex claude gemini grok agent-run fallow rg ripgrep pm2 pm2-dev pm2-runtime tsx tsc; do command -v "$name" 2>/dev/null || true; done
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Normalize the allowlist to package names before comparing:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
npm
|
|
103
|
+
pnpm
|
|
104
|
+
@openai/codex
|
|
105
|
+
@anthropic-ai/claude-code
|
|
106
|
+
@google/gemini-cli
|
|
107
|
+
@xai-official/grok
|
|
108
|
+
@technomoron/agent-run
|
|
109
|
+
corepack
|
|
110
|
+
fallow
|
|
111
|
+
ripgrep
|
|
112
|
+
pm2
|
|
113
|
+
tsx
|
|
114
|
+
typescript
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Inventory pnpm globals:
|
|
118
|
+
|
|
119
|
+
```sh
|
|
120
|
+
pnpm list -g --depth 0 --json
|
|
121
|
+
test "$(pnpm bin -g)" = /usr/local/bin
|
|
122
|
+
find /usr/local/share/pnpm -maxdepth 4 -type f -o -type l 2>/dev/null
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Inventory non-`/usr/local` Node assets that should be deleted or explained. This includes known host-tool commands and arbitrary npm/pnpm-created shims or symlinks in `/usr/bin` and related bin directories:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
find /usr/bin /usr/sbin /bin /sbin -maxdepth 1 \( -type f -o -type l \) \
|
|
129
|
+
\( -name node -o -name npm -o -name npx -o -name pnpm -o -name pnpx -o -name corepack -o -name codex -o -name claude -o -name gemini -o -name grok -o -name agent-run -o -name fallow -o -name rg -o -name ripgrep -o -name pm2 -o -name 'pm2-*' -o -name tsx -o -name tsc \) -print 2>/dev/null
|
|
130
|
+
find /usr/bin /usr/sbin /bin /sbin -maxdepth 1 -type l -exec sh -c 'for p do t=$(readlink "$p" 2>/dev/null || true); case "$t" in *node_modules*|*npm*|*pnpm*|*corepack*) printf "%s -> %s\n" "$p" "$t";; esac; done' sh {} + 2>/dev/null
|
|
131
|
+
find /usr/bin /usr/sbin /bin /sbin -maxdepth 1 -type f -exec sh -c 'for p do head -n 1 "$p" 2>/dev/null | grep -Eq "node|npm|pnpm|node_modules" && printf "%s\n" "$p"; done' sh {} + 2>/dev/null
|
|
132
|
+
find /usr/lib /usr/share /opt -maxdepth 4 \( -type d -o -type l \) \
|
|
133
|
+
\( -path '*/node_modules' -o -path '*/node_modules/*' -o -path '*/npm' -o -path '*/pnpm' -o -path '*/corepack' -o -path '*/@openai/codex' -o -path '*/@anthropic-ai/claude-code' -o -path '*/@google/gemini-cli' -o -path '*/@xai-official/grok' -o -path '*/@technomoron/agent-run' \) -print 2>/dev/null
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The compliant result is:
|
|
137
|
+
|
|
138
|
+
- `npm list -g --depth=0` contains only the allowlisted packages.
|
|
139
|
+
- `pnpm list -g --depth 0` is empty or reports no globally installed packages.
|
|
140
|
+
- npm and pnpm both resolve global bins to `/usr/local/bin`.
|
|
141
|
+
- globally managed Node/npm/pnpm/corepack assets, random npm/pnpm-installed shims, bins, links, and global `node_modules` live under `/usr/local/*`, not `/usr/bin`, `/usr/lib`, `/usr/share`, `/opt`, or user-local global paths.
|
|
142
|
+
- pnpm global directories are root-owned and not group/world-writable.
|
|
143
|
+
- npm global prefix/root are root-owned and not group/world-writable.
|
|
144
|
+
- user-global pnpm/npm directories are absent or unused.
|
|
145
|
+
- project-local dependencies are left untouched.
|
|
146
|
+
|
|
147
|
+
## Remediation
|
|
148
|
+
|
|
149
|
+
Remove disallowed npm globals by package name:
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
npm uninstall -g <disallowed-package>
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Remove all pnpm global packages. Use exact package names from `pnpm list -g --depth 0`:
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
pnpm remove -g <package>
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Remove stale non-`/usr/local` Node assets after confirming they are command shims, symlinks into npm/pnpm state, package-manager global directories, or obsolete package-manager assets. This includes random executables left by `npm install -g` or `pnpm add -g`, not only the approved tool names. Use package-manager uninstall commands first when an OS package manager owns the files; otherwise delete the stale paths directly. Do not touch project-local dependencies.
|
|
162
|
+
|
|
163
|
+
```sh
|
|
164
|
+
rm -f /usr/bin/npm /usr/bin/npx /usr/bin/pnpm /usr/bin/pnpx /usr/bin/corepack
|
|
165
|
+
rm -f /usr/bin/codex /usr/bin/claude /usr/bin/gemini /usr/bin/grok /usr/bin/agent-run /usr/bin/fallow /usr/bin/rg /usr/bin/ripgrep /usr/bin/pm2 /usr/bin/pm2-dev /usr/bin/pm2-runtime /usr/bin/tsx /usr/bin/tsc
|
|
166
|
+
find /usr/bin /usr/sbin /bin /sbin -maxdepth 1 -type l -exec sh -c 'for p do t=$(readlink "$p" 2>/dev/null || true); case "$t" in *node_modules*|*npm*|*pnpm*|*corepack*) rm -f "$p";; esac; done' sh {} + 2>/dev/null
|
|
167
|
+
rm -rf /usr/lib/node_modules /usr/lib/npm /usr/lib/pnpm /usr/lib/corepack
|
|
168
|
+
rm -rf /usr/share/nodejs/npm /usr/share/nodejs/pnpm /usr/share/nodejs/corepack /usr/share/npm /usr/share/pnpm
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
If a stale `/usr/bin/node` shadows the intended `/usr/local/bin/node`, remove it only after installing or confirming a working `/usr/local/bin/node` and confirming the user wants Node itself managed from `/usr/local`:
|
|
172
|
+
|
|
173
|
+
```sh
|
|
174
|
+
test -x /usr/local/bin/node
|
|
175
|
+
rm -f /usr/bin/node
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Remove stale pnpm global command shims only after confirming the target package has been removed. If pnpm previously used a separate bin home, remove stale files there. If stale shims are in `/usr/local/bin`, remove only links that point into pnpm global state; do not blindly delete npm-managed commands from `/usr/local/bin`.
|
|
179
|
+
|
|
180
|
+
```sh
|
|
181
|
+
rm -f /usr/local/share/pnpm/bin/<command>
|
|
182
|
+
readlink /usr/local/bin/<command> | grep -q '/usr/local/share/pnpm/' && rm -f /usr/local/bin/<command>
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Install or update approved host tooling with npm:
|
|
186
|
+
|
|
187
|
+
```sh
|
|
188
|
+
npm install -g --force npm@latest pnpm@latest corepack@latest @openai/codex@latest @anthropic-ai/claude-code@latest @google/gemini-cli@latest @xai-official/grok@latest @technomoron/agent-run@latest fallow@latest ripgrep@latest pm2@latest tsx@latest typescript@latest
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
Re-check command ownership and resolution after cleanup:
|
|
192
|
+
|
|
193
|
+
```sh
|
|
194
|
+
command -v npm pnpm corepack codex claude gemini grok agent-run fallow rg pm2 tsx tsc
|
|
195
|
+
npm list -g --depth=0 --json
|
|
196
|
+
pnpm list -g --depth 0 --json
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
## Systemd Updaters
|
|
200
|
+
|
|
201
|
+
Systemd updater units that maintain these tools must enforce the same policy:
|
|
202
|
+
|
|
203
|
+
- run as root with `HOME=/root`
|
|
204
|
+
- set pnpm global package repository to the single root-owned pnpm home
|
|
205
|
+
- set pnpm global bin directory to `/usr/local/bin`
|
|
206
|
+
- remove pnpm global installs and stale pnpm shims for the host tools
|
|
207
|
+
- install or update the approved tool packages with `npm install -g`
|
|
208
|
+
- not install packages outside the npm global allowlist
|
|
209
|
+
- not run `pnpm add -g` or `pnpm install -g` for these tools
|
|
210
|
+
|
|
211
|
+
Audit likely units with:
|
|
212
|
+
|
|
213
|
+
```sh
|
|
214
|
+
systemctl list-timers --all --no-pager | grep -Ei 'update|npm|pnpm|node|codex|claude|gemini|grok|agent-run|corepack|fallow|pm2|tsx|tsc'
|
|
215
|
+
systemctl list-unit-files --no-pager | grep -Ei 'update|npm|pnpm|node|codex|claude|gemini|grok|agent-run|corepack|fallow|pm2|tsx|tsc'
|
|
216
|
+
systemctl cat <unit>.service
|
|
217
|
+
systemctl cat <unit>.timer
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
If an updater installs non-allowlisted npm globals, remove them from `ExecStart` and uninstall them globally. If an updater installs or references Node package-manager assets, random npm/pnpm shims, bins, links, or `node_modules` under `/usr/bin`, `/usr/lib`, `/usr/share`, `/opt`, or user-local paths, change it to use `/usr/local/bin`, `/usr/local/lib/node_modules`, and `/usr/local/share/pnpm`, then delete the stale non-`/usr/local` assets. If an updater leaves pnpm global directories writable by non-root users, fix ownership and permissions before restarting the timer:
|
|
221
|
+
|
|
222
|
+
```sh
|
|
223
|
+
chown -R root:root /usr/local/share/pnpm /usr/local/lib/node_modules
|
|
224
|
+
chmod 0755 /usr/local/share/pnpm /usr/local/share/pnpm/global /usr/local/bin /usr/local/lib/node_modules
|
|
225
|
+
stat -Lc '%U:%G %a %n' /usr/local/share/pnpm /usr/local/share/pnpm/global /usr/local/bin /usr/local/lib/node_modules
|
|
226
|
+
systemctl daemon-reload
|
|
227
|
+
systemctl restart <unit>.timer
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
## Install automatic updates
|
|
231
|
+
|
|
232
|
+
Updater installation and implementation belong to agent-run. When the user requests automatic updates on Linux with systemd, use the bundled command:
|
|
233
|
+
|
|
234
|
+
```sh
|
|
235
|
+
agent-run auto-update --dry-run
|
|
236
|
+
agent-run auto-update
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
It installs the hourly timer and packaged helpers, requesting sudo when needed. Configure host-specific choices in `/etc/default/ai-tools-update`. Do not generate competing service units, inline package installers, or scheduled tasks from this skill. The command currently supports Linux/systemd only; report that limitation on other platforms.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: package-integrity-check
|
|
3
|
+
description: Use before package releases and publish-ready changes to verify package metadata, release notes, lockfiles, workflows, git state, and agent-file hygiene.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Package Integrity Check
|
|
7
|
+
|
|
8
|
+
Use this skill for release and package policy checks that are not covered by normal project test commands.
|
|
9
|
+
For package release or publish-ready work, verify the relevant package directory before finalizing:
|
|
10
|
+
|
|
11
|
+
- The directory contains `package.json` and is inside a git repository.
|
|
12
|
+
- The repository path follows `<org>/<repo>`, and `package.json.name` is `@<org>/<package-dir-name>`.
|
|
13
|
+
- `package.json.version`, `package.json.license`, and `package.json.copyright` are present and non-empty.
|
|
14
|
+
- A package-local `LICENSE` file exists and contains the exact copyright string from `package.json.copyright`.
|
|
15
|
+
- A package-local changelog exists, named either `CHANGES.md` (preferred) or `CHANGES` (legacy). Exactly one of the two, never both.
|
|
16
|
+
- The first `Version ...` line in that changelog matches `Version <package.json.version> (<YYYY-MM-DD>)`.
|
|
17
|
+
- The year in the top changelog version line appears in `package.json.copyright`.
|
|
18
|
+
- The git `origin` remote matches `<org>/<repo>`.
|
|
19
|
+
- The current branch has an upstream configured and is in sync with it after fetching.
|
|
20
|
+
- The repository does not contain agent files or directories such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `codex.md`, `.claude`, `.codex`, `.gemini`, or `.grok`.
|
|
21
|
+
- The repository root has a lockfile: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`, or `bun.lock`.
|
|
22
|
+
- Every GitHub Actions `uses:` reference is pinned to a full commit SHA. The pinned `actions/setup-node` release is v6-compatible and workflows use `node-version: 24`.
|
|
23
|
+
- GitHub workflows do not reference `node20` or `node22`.
|
|
24
|
+
- The git working tree is clean for files under the checked package directory.
|
|
25
|
+
- If files beyond the changelog changed in the checked package directory, that package changelog is also changed.
|
|
26
|
+
|
|
27
|
+
Run the checks configured for the active project after this checklist. Report failures and checks that could not be run.
|
|
@@ -1,8 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: todo-manager
|
|
3
|
-
description:
|
|
3
|
+
description: Track feature requests and planned work in GitHub Issues without a separate local todo list.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Use
|
|
6
|
+
Use GitHub Issues in the affected repository as the task backlog. Use the available GitHub connector or `gh`; do not create a separate local todo list or duplicate brain task records.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
1. Confirm the repository and requested task. Retrieve open issues of the relevant type by default; search existing open and closed issues before creating a request to avoid duplicates.
|
|
9
|
+
2. Create or update issues only when requested or authorized by the current workflow. Use issue numbers as permanent IDs, descriptive titles, and clear requirements or acceptance criteria. Read the current issue before updates and preserve unrelated content and discussion.
|
|
10
|
+
3. Set feature requests to issue type `Feature` with the `enhancement` label. Use `Task` for other planned work. Create missing types or labels only when authorized with the required permissions; report unavailable capabilities rather than silently substituting a local list.
|
|
11
|
+
4. Code review findings use type `Code Review`, never `Feature`; use the code-review skill for that workflow. Filter feature-request lists by type `Feature` so review findings remain separate even when they have an `enhancement` label.
|
|
12
|
+
5. Leave unfinished or deferred requests open. After an authorized implementation passes relevant checks, record verification and close the issue as completed. Close as not planned only on the user's decision. Preserve closed issues for history rather than deleting them.
|
|
13
|
+
|
|
14
|
+
A request to do work does not by itself authorize creating a saved task or GitHub issue. Reuse authorization already given. Do not migrate or delete existing local tasks without authorization. If GitHub is unavailable, report the limitation and unsaved requests in the reply.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: unslop
|
|
3
|
+
description: Clean up AI-generated or AI-looking code without changing behavior. Use when asked to unslop code, make generated code idiomatic, remove needless abstraction, boilerplate, speculative flexibility, invented defaults, redundant types, verbose names or over-explanation, or to do a human review and cleanup pass. Examples are TypeScript; apply the equivalent in other languages.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Code Cleanup / Human Review
|
|
7
|
+
|
|
8
|
+
Remove code that exists because a generator was being defensive, explicit, reusable or
|
|
9
|
+
future-proof rather than because the product needs it. This is not a redesign and not a
|
|
10
|
+
generic "clean code" pass.
|
|
11
|
+
|
|
12
|
+
Default target is the code just generated, or the current diff. If neither is clear, ask
|
|
13
|
+
before touching anything wider.
|
|
14
|
+
|
|
15
|
+
Never add code for a hypothetical caller, state, failure mode, configuration, compatibility
|
|
16
|
+
need or future requirement unless explicitly asked for. Future requirements can add future
|
|
17
|
+
code.
|
|
18
|
+
|
|
19
|
+
## Behavior is a hard constraint
|
|
20
|
+
|
|
21
|
+
Do not change public or exported APIs, CLI behavior, return values, request/response and
|
|
22
|
+
serialized shapes, persistence, network calls, side effects, thrown errors, logging relied
|
|
23
|
+
on operationally, configuration semantics, or user-visible output.
|
|
24
|
+
|
|
25
|
+
If a cleanup would require a behavior change, leave that part alone and report it as a
|
|
26
|
+
follow-up. Never use "cleanup" to justify fixing unrelated bugs.
|
|
27
|
+
|
|
28
|
+
## Order of work
|
|
29
|
+
|
|
30
|
+
1. Read the surrounding code, real callers, tests and schemas first.
|
|
31
|
+
2. Clean production code in small steps. Prefer deleting over replacing.
|
|
32
|
+
3. Run the existing tests unchanged. A failure means the cleanup may have changed behavior:
|
|
33
|
+
fix the code, not the test.
|
|
34
|
+
4. Run the formatter, linter, type checker, and `fallow` if it is already installed. Never
|
|
35
|
+
install tools or dependencies as part of cleanup.
|
|
36
|
+
5. Report.
|
|
37
|
+
|
|
38
|
+
## What to remove, highest value first
|
|
39
|
+
|
|
40
|
+
1. **Dead code and unused abstractions.** Confirm callers directly before deleting an
|
|
41
|
+
export. Where `fallow` is available its output is additional evidence, not proof: static
|
|
42
|
+
analysis can miss dynamic use.
|
|
43
|
+
|
|
44
|
+
2. **Speculative flexibility.** Remove options, hooks, callbacks, factories, interfaces,
|
|
45
|
+
strategies, generics, enum members, compatibility shims and plugin points with one or no
|
|
46
|
+
current use. Do not preserve something because it may be useful later.
|
|
47
|
+
|
|
48
|
+
3. **Invented defaults never asked for.** Question `?? []`, `?? {}`, `?? ''`, `|| 0`,
|
|
49
|
+
placeholder objects and unknown enum values mapped to a default. Missing and empty are
|
|
50
|
+
different states. If absence is invalid, fail rather than inventing a value. Never use
|
|
51
|
+
`||` where `false`, `0` or `''` are legitimate values.
|
|
52
|
+
|
|
53
|
+
4. **Artificial optionality.** Remove `?` properties, `T | null` / `T | undefined`, and
|
|
54
|
+
optional parameters when every real caller supplies the value; remove null checks after
|
|
55
|
+
validation and optional chaining on values already proven to exist. For an exported API,
|
|
56
|
+
narrowing a signature is a behavior/API change: leave it and report it.
|
|
57
|
+
|
|
58
|
+
5. **Needless indirection.** Remove one-caller wrappers, pass-through methods, adapters
|
|
59
|
+
between identical shapes, services wrapping a single library call, classes with no state,
|
|
60
|
+
and abstractions whose only justification is hypothetical reuse.
|
|
61
|
+
|
|
62
|
+
6. **Defensive error handling.** Question broad `try/catch`, catch-and-rethrow that adds
|
|
63
|
+
nothing, swallowed errors and duplicate logging. Narrow it, but keep handling that protects
|
|
64
|
+
real workflows and never change observable error behavior.
|
|
65
|
+
|
|
66
|
+
7. **Redundant types.** Reuse the canonical project type or derive from it with
|
|
67
|
+
`Pick`/`Omit` rather than copying its fields. Remove duplicate type shapes and generics with
|
|
68
|
+
one concrete instantiation.
|
|
69
|
+
|
|
70
|
+
Do not create a named type or interface for a one-shot local shape. Inline it unless the
|
|
71
|
+
name carries real domain meaning, defines a public contract, or the type is reused.
|
|
72
|
+
|
|
73
|
+
Prefer, in order:
|
|
74
|
+
|
|
75
|
+
1. existing canonical type
|
|
76
|
+
2. `Pick`, `Omit`, or another simple derivation
|
|
77
|
+
3. inline one-off shape
|
|
78
|
+
4. new named type only when genuinely justified
|
|
79
|
+
|
|
80
|
+
Keep intentionally independent contracts separate: an external DTO may correctly remain
|
|
81
|
+
separate from an internal model even when their fields happen to match today.
|
|
82
|
+
|
|
83
|
+
8. **Comments that restate the code.** Keep comments explaining domain rules, invariants,
|
|
84
|
+
compatibility constraints, incident-derived defensive behavior, or why odd-looking code
|
|
85
|
+
has to stay.
|
|
86
|
+
|
|
87
|
+
9. **Cosmetic verbosity, only while already editing that code.** Remove ceremonial
|
|
88
|
+
annotations such as `const n: number = items.length`, `x ? true : false`, redundant
|
|
89
|
+
conditionals and needlessly nested ternaries. Removing an annotation can change inference,
|
|
90
|
+
so run the type checker.
|
|
91
|
+
|
|
92
|
+
Comments and git history are evidence that unusual code may be deliberate, not absolute
|
|
93
|
+
authority: verify before removing it, but do not preserve obvious slop solely because an old
|
|
94
|
+
comment or commit mentions it. A failing test is not evidence of the same kind — see below.
|
|
95
|
+
|
|
96
|
+
## Follow the project
|
|
97
|
+
|
|
98
|
+
Use existing helpers, naming, file layout, error handling, validation and test patterns.
|
|
99
|
+
Project convention beats generic best practice unless the convention is itself the slop
|
|
100
|
+
being removed.
|
|
101
|
+
|
|
102
|
+
Do not add dependencies, frameworks, layers, base classes, factories, interfaces,
|
|
103
|
+
configuration systems, extension points or abstractions during cleanup unless the current
|
|
104
|
+
code genuinely requires them.
|
|
105
|
+
|
|
106
|
+
Cleanup should shrink the conceptual surface, not grow it.
|
|
107
|
+
|
|
108
|
+
## Names: short, not cryptic
|
|
109
|
+
|
|
110
|
+
Prefer the shortest name that is still immediately clear in its scope. Remove words whose
|
|
111
|
+
meaning is already supplied by the class, module, function, type, parameter type, or local
|
|
112
|
+
context.
|
|
113
|
+
|
|
114
|
+
* `currentAuthenticatedUserInformation` → `user`
|
|
115
|
+
* `validateUserAuthenticationCredentials` → `validateCredentials`
|
|
116
|
+
* `UserAuthenticationCredentialsValidationService` → `CredentialValidator`
|
|
117
|
+
* inside `UserService`: `getUserByUserId(id)` → `get(id)`
|
|
118
|
+
|
|
119
|
+
Drop suffixes that add no distinction (`Data`, `Info`, `Object`, `Value`, `Details`,
|
|
120
|
+
`Manager`, `Handler`, `Processor`, `Service`), but keep them where they carry real domain or
|
|
121
|
+
architectural meaning.
|
|
122
|
+
|
|
123
|
+
Do not swing the other way into `usr`, `cfg`, `mgr`, `x` unless that abbreviation is already
|
|
124
|
+
established locally or the scope is tiny.
|
|
125
|
+
|
|
126
|
+
The goal is the fewest unnecessary words, not the fewest characters.
|
|
127
|
+
|
|
128
|
+
Rename only where the better name is obvious from surrounding code. No repo-wide renaming
|
|
129
|
+
sweeps.
|
|
130
|
+
|
|
131
|
+
## Tests
|
|
132
|
+
|
|
133
|
+
Treat the existing suite as the behavioral contract.
|
|
134
|
+
|
|
135
|
+
While cleaning production code, do not touch tests, fixtures, snapshots, mocks or expected
|
|
136
|
+
values — not to make them pass, and not because a simplified implementation makes one look
|
|
137
|
+
obsolete.
|
|
138
|
+
|
|
139
|
+
Production code and the tests asserting its behavior must not move together during cleanup.
|
|
140
|
+
|
|
141
|
+
If a test fails after cleanup:
|
|
142
|
+
|
|
143
|
+
1. assume the production cleanup may be wrong
|
|
144
|
+
2. fix or revert the production change
|
|
145
|
+
3. run the unchanged test again
|
|
146
|
+
|
|
147
|
+
If an existing test appears wrong, obsolete, or inconsistent with the specification, leave
|
|
148
|
+
it unchanged and report the conflict. Changing behavior and updating its tests is a separate
|
|
149
|
+
task.
|
|
150
|
+
|
|
151
|
+
Once the cleaned production code passes the unchanged tests, behavior preservation is
|
|
152
|
+
established and the tests themselves can be updated and cleaned. Do that as a separate step,
|
|
153
|
+
never alongside the production changes.
|
|
154
|
+
|
|
155
|
+
For a risky cleanup, a characterization test may first be added for behavior that already
|
|
156
|
+
exists:
|
|
157
|
+
|
|
158
|
+
1. add the characterization test
|
|
159
|
+
2. confirm it passes before cleanup
|
|
160
|
+
3. clean the production code
|
|
161
|
+
4. confirm the same test still passes
|
|
162
|
+
|
|
163
|
+
Never write tests for hypothetical behavior.
|
|
164
|
+
|
|
165
|
+
## Report
|
|
166
|
+
|
|
167
|
+
Briefly report:
|
|
168
|
+
|
|
169
|
+
* main cleanup changes
|
|
170
|
+
* abstractions, defaults, optionality, types or verbose names removed
|
|
171
|
+
* checks run and results
|
|
172
|
+
* whether `fallow` ran or was unavailable
|
|
173
|
+
* behavior assumptions and remaining risk
|
|
174
|
+
* anything noticed but deliberately left alone
|
|
175
|
+
* cleaned code with no existing test coverage
|
|
176
|
+
|
|
177
|
+
Do not explain every trivial edit.
|
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: brain-review
|
|
3
|
-
description: Review changes against project constraints and previous findings,
|
|
4
|
-
and save confirmed review knowledge.
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Review backend selection
|
|
8
|
-
|
|
9
|
-
Before conducting a review or modifying findings, call `brain_status`. Its
|
|
10
|
-
`reviewBackend` selects the destination. For `github`, findings are issues in the
|
|
11
|
-
active repository shown by `repository`; use `review_list`, `review_get`,
|
|
12
|
-
`review_create`, `review_update`, `resolve_review`, and `review_history`.
|
|
13
|
-
This backend selection takes precedence over internal-storage instructions below.
|
|
14
|
-
Do not use `remember`, `get_knowledge`, or `amend_knowledge` for GitHub findings,
|
|
15
|
-
and do not create an internal duplicate or silently fall back when GitHub fails.
|
|
16
|
-
Each repository keeps its own issues; split findings that affect different repos.
|
|
17
|
-
Use a stable, repository-specific retry `key` for `review_create`. Remote writes
|
|
18
|
-
require user authorization, enabled GitHub writes, and `confirmed: true` for
|
|
19
|
-
creation or updates. Read the current issue revision before updating or closing.
|
|
20
|
-
Preserve discussion outside the managed finding block. Closing requires verified
|
|
21
|
-
fixes or the user's explicit decision to drop a finding; deferral leaves it open.
|
|
22
|
-
GitHub retains closed history, so do not call `review_archive` for this backend.
|
|
23
|
-
For `internal`, retain the existing knowledge storage and closure workflow below.
|
|
24
|
-
Read-only listing can call `review_list` or `review_history` directly without
|
|
25
|
-
loading this workflow. Never enable writes or migrate old findings implicitly.
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
Call review_context with the task and changed paths. Check correctness, security, architecture, and meaningful test coverage against relevant constraints. Report concrete, actionable findings with severity and file references. If authorized to save the review, call remember with type=review. Keep suspected hazards marked inferred. Never convert a finding into an authoritative constraint without user confirmation.
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
Use review_list for current findings and review_history for old fixes or dropped findings.
|
|
33
|
-
After completing an authorized fix and relevant checks, call resolve_review as fixed
|
|
34
|
-
with a short change and verification summary. Use wontfix only for an explicit user
|
|
35
|
-
decision; deferred issues stay open. Closing saves compact history and deletes the full
|
|
36
|
-
finding file. For requested cleanup, review_archive compacts already closed files in the
|
|
37
|
-
specified scope. Do not create separate full archives or done lists. Git commits and
|
|
38
|
-
remote issue updates require their own authorization.
|