@jaggerxtrm/specialists 3.6.12 → 3.6.13
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/config/skills/update-specialists/SKILL.md +339 -0
- package/config/specialists/.serena/project.yml +151 -0
- package/config/specialists/debugger.specialist.json +1 -1
- package/config/specialists/executor.specialist.json +1 -1
- package/config/specialists/reviewer.specialist.json +2 -2
- package/dist/index.js +4 -13
- package/package.json +1 -1
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: update-specialists
|
|
3
|
+
description: >
|
|
4
|
+
Reconcile a project with current canonical specialists install state.
|
|
5
|
+
Use this skill when a user says "update specialists", "specialists is broken",
|
|
6
|
+
"sp is out of date", "hooks not firing", "skills not loading after update",
|
|
7
|
+
or when drift is detected in installed specialists config, hooks, jobs, DB,
|
|
8
|
+
extensions, or worktree cleanup.
|
|
9
|
+
version: 1.1
|
|
10
|
+
synced_at: 00000000
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# update-specialists
|
|
14
|
+
|
|
15
|
+
Bring specialists install back to canonical state. Detect drift, apply targeted
|
|
16
|
+
fixes, then verify with `sp doctor`. Treat canonical state as both:
|
|
17
|
+
1. healthy repo wiring and runtime behavior, and
|
|
18
|
+
2. parity with the currently installed `@jaggerxtrm/specialists` package version
|
|
19
|
+
when package-level comparison is available.
|
|
20
|
+
|
|
21
|
+
## Canonical State
|
|
22
|
+
|
|
23
|
+
Check each item explicitly. This is what a healthy specialists-initialized project
|
|
24
|
+
looks like.
|
|
25
|
+
|
|
26
|
+
### Package + runtime parity
|
|
27
|
+
|
|
28
|
+
| Check | Expected value |
|
|
29
|
+
|-------|----------------|
|
|
30
|
+
| Installed `@jaggerxtrm/specialists` package version | Matches intended runtime version for repo install |
|
|
31
|
+
| `sp --version` / `specialists --version` | Matches installed package version or same release line |
|
|
32
|
+
| Installed package root | Resolvable from Node / npm environment |
|
|
33
|
+
| Canonical package defaults | Available from installed package for direct diffing |
|
|
34
|
+
| Repo install vs package install | No unexpected drift in canonical files unless intentionally customized |
|
|
35
|
+
|
|
36
|
+
### Specialists configs
|
|
37
|
+
|
|
38
|
+
| Check | Expected value |
|
|
39
|
+
|-------|----------------|
|
|
40
|
+
| `.specialists/default/*.specialist.json` | JSON-first specialist configs present |
|
|
41
|
+
| `metadata.name` | Matches filename stem |
|
|
42
|
+
| `metadata.version` | Valid semver string and consistent with canonical shipped copy when comparing like-for-like |
|
|
43
|
+
| `metadata.description` | Present |
|
|
44
|
+
| `metadata.category` | Present |
|
|
45
|
+
| `execution.model` | Present and pingable |
|
|
46
|
+
| `execution.fallback_model` | Present, different provider from primary |
|
|
47
|
+
| `execution.permission_required` | Valid enum |
|
|
48
|
+
| `skills.paths` | Referenced skill paths resolve correctly |
|
|
49
|
+
| `execution.interactive` | Matches intended keep-alive behavior |
|
|
50
|
+
| Installed default specialist copy | Matches canonical package copy unless intentionally customized |
|
|
51
|
+
|
|
52
|
+
### Hooks wiring
|
|
53
|
+
|
|
54
|
+
| Check | Expected value |
|
|
55
|
+
|-------|----------------|
|
|
56
|
+
| `.claude/settings.json` | Has hook entries for active events |
|
|
57
|
+
| Hook events | At minimum: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop` |
|
|
58
|
+
| Hook paths | Point at specialists runtime hook scripts, not stale xtrm-only paths |
|
|
59
|
+
| Hook format | Matches project's installed settings format and loads cleanly |
|
|
60
|
+
| Installed hook scripts | Match canonical package hook files unless intentionally customized |
|
|
61
|
+
|
|
62
|
+
### CLI reachability
|
|
63
|
+
|
|
64
|
+
| Check | Expected value |
|
|
65
|
+
|-------|----------------|
|
|
66
|
+
| `sp` command | On PATH and runs |
|
|
67
|
+
| `specialists` command | On PATH and runs |
|
|
68
|
+
| Version compatibility | `sp doctor` reports matching runtime / install state |
|
|
69
|
+
| Command surface | `sp doctor`, `sp init`, `sp clean`, `sp status` available |
|
|
70
|
+
|
|
71
|
+
### Jobs and runtime dirs
|
|
72
|
+
|
|
73
|
+
| Check | Expected value |
|
|
74
|
+
|-------|----------------|
|
|
75
|
+
| `.specialists/jobs/` | Exists |
|
|
76
|
+
| `.specialists/ready/` | Exists if used by runtime |
|
|
77
|
+
| `.specialists/default/` | Canonical install copy present |
|
|
78
|
+
| Orphaned worktrees | None under `.worktrees/` |
|
|
79
|
+
| Worktree ownership | No stale entries for deleted jobs |
|
|
80
|
+
|
|
81
|
+
### SQLite / observability
|
|
82
|
+
|
|
83
|
+
| Check | Expected value |
|
|
84
|
+
|-------|----------------|
|
|
85
|
+
| specialists DB | Opens cleanly |
|
|
86
|
+
| Schema version | Matches runtime expectation |
|
|
87
|
+
| WAL / busy timeout settings | Present when runtime uses SQLite |
|
|
88
|
+
| Corruption / lock errors | None in `sp doctor` |
|
|
89
|
+
|
|
90
|
+
### Skills + extensions parity
|
|
91
|
+
|
|
92
|
+
| Check | Expected value |
|
|
93
|
+
|-------|----------------|
|
|
94
|
+
| `.xtrm/skills/default/` | Matches canonical package skill set for installed version |
|
|
95
|
+
| Active skill links / copies | Resolve to expected default or active targets |
|
|
96
|
+
| Skill frontmatter `version` / `synced_at` | Present and reasonable for shipped skills |
|
|
97
|
+
| `quality-gates` | Registered if project uses quality gates |
|
|
98
|
+
| `pi-gitnexus` | Registered when GitNexus integration is expected |
|
|
99
|
+
| `pi-serena-tools` | Registered when Serena integration is expected |
|
|
100
|
+
| Extension paths | Resolve from installed project, not stale workspace copies |
|
|
101
|
+
|
|
102
|
+
## Detection
|
|
103
|
+
|
|
104
|
+
Run these in order. Report which checks pass and which drift.
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# 1. Primary health check
|
|
108
|
+
sp doctor
|
|
109
|
+
|
|
110
|
+
# 2. Runtime status
|
|
111
|
+
sp status
|
|
112
|
+
|
|
113
|
+
# 3. Installed package + CLI version parity
|
|
114
|
+
npm ls @jaggerxtrm/specialists --depth=0 2>/dev/null || true
|
|
115
|
+
node -e "try { const pkg=require(require.resolve('@jaggerxtrm/specialists/package.json')); console.log(JSON.stringify({installed_package_version: pkg.version}, null, 2)); } catch (err) { console.log('PACKAGE_NOT_RESOLVABLE'); }"
|
|
116
|
+
sp --version 2>/dev/null || true
|
|
117
|
+
specialists --version 2>/dev/null || true
|
|
118
|
+
|
|
119
|
+
# 4. Resolve canonical package root for direct drift diff
|
|
120
|
+
node -e "try { const path=require('path'); const pkgPath=require.resolve('@jaggerxtrm/specialists/package.json'); console.log(path.dirname(pkgPath)); } catch (err) { console.log('PACKAGE_ROOT_UNAVAILABLE'); }"
|
|
121
|
+
|
|
122
|
+
# 5. Config shape
|
|
123
|
+
find .specialists/default -maxdepth 1 -name '*.specialist.json' -print
|
|
124
|
+
|
|
125
|
+
# 6. Validate specialist JSON files
|
|
126
|
+
node -e "const fs=require('fs'); const path=require('path'); const dir='.specialists/default'; for (const file of fs.readdirSync(dir)) { if (!file.endsWith('.specialist.json')) continue; const s=JSON.parse(fs.readFileSync(path.join(dir,file),'utf8')); const m=s.metadata||{}; const e=s.execution||{}; const missing=[]; for (const key of ['name','version','description','category']) if (!m[key]) missing.push('metadata.'+key); for (const key of ['model','fallback_model','permission_required']) if (!e[key]) missing.push('execution.'+key); if (missing.length) console.log(file+': MISSING '+missing.join(', ')); if (m.name && m.name !== file.replace(/\.specialist\.json$/, '')) console.log(file+': NAME MISMATCH '+m.name); }"
|
|
127
|
+
|
|
128
|
+
# 7. Validate referenced skill paths
|
|
129
|
+
node -e "const fs=require('fs'); const path=require('path'); const dir='.specialists/default'; for (const file of fs.readdirSync(dir)) { if (!file.endsWith('.specialist.json')) continue; const s=JSON.parse(fs.readFileSync(path.join(dir,file),'utf8')); for (const p of (s.skills?.paths ?? [])) { if (!fs.existsSync(p)) console.log(file+': MISSING SKILL PATH '+p); } }"
|
|
130
|
+
|
|
131
|
+
# 8. Compare repo defaults against installed package defaults (if package root resolvable)
|
|
132
|
+
PKG_ROOT="$(node -e "try { const path=require('path'); process.stdout.write(path.dirname(require.resolve('@jaggerxtrm/specialists/package.json'))); } catch (err) {}")"
|
|
133
|
+
if [ -n "$PKG_ROOT" ]; then
|
|
134
|
+
diff -rq .specialists/default "$PKG_ROOT/config/specialists" || true
|
|
135
|
+
diff -rq .xtrm/skills/default "$PKG_ROOT/config/skills" || true
|
|
136
|
+
diff -rq .claude/hooks "$PKG_ROOT/config/hooks" || true
|
|
137
|
+
else
|
|
138
|
+
echo PACKAGE_COMPARE_UNAVAILABLE
|
|
139
|
+
fi
|
|
140
|
+
|
|
141
|
+
# 9. Hooks wiring
|
|
142
|
+
node -e "const fs=require('fs'); const p='.claude/settings.json'; if (fs.existsSync(p)) { const s=JSON.parse(fs.readFileSync(p,'utf8')); console.log(JSON.stringify(s.hooks ?? s, null, 2)); } else { console.log('MISSING .claude/settings.json'); }"
|
|
143
|
+
|
|
144
|
+
# 10. Command availability
|
|
145
|
+
command -v sp
|
|
146
|
+
command -v specialists
|
|
147
|
+
specialists init --help | sed -n '1,120p'
|
|
148
|
+
sp doctor --json 2>/dev/null || true
|
|
149
|
+
|
|
150
|
+
# 11. Jobs and worktrees
|
|
151
|
+
ls -1 .specialists/jobs 2>/dev/null || true
|
|
152
|
+
find .worktrees -maxdepth 2 -mindepth 1 -type d 2>/dev/null || true
|
|
153
|
+
|
|
154
|
+
# 12. Extension registration
|
|
155
|
+
node -e "const fs=require('fs'); const p='.pi/settings.json'; if (fs.existsSync(p)) console.log(JSON.stringify(JSON.parse(fs.readFileSync(p,'utf8')).skills ?? JSON.parse(fs.readFileSync(p,'utf8')).extensions ?? {}, null, 2)); else console.log('MISSING .pi/settings.json')"
|
|
156
|
+
|
|
157
|
+
# 13. Shipped skill frontmatter parity
|
|
158
|
+
node -e "const fs=require('fs'); const path=require('path'); const dir='.xtrm/skills/default'; if (!fs.existsSync(dir)) process.exit(0); for (const name of fs.readdirSync(dir)) { const p=path.join(dir,name,'SKILL.md'); if (!fs.existsSync(p)) continue; const head=fs.readFileSync(p,'utf8').split('---')[1] || ''; const version=(head.match(/version:\s*([^\n]+)/)||[])[1]; const synced=(head.match(/synced_at:\s*([^\n]+)/)||[])[1]; console.log(name+': version='+(version||'missing')+' synced_at='+(synced||'missing')); }"
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Drift -> Fix Mapping
|
|
162
|
+
|
|
163
|
+
Use targeted fixes first. Escalate to full sync only if needed.
|
|
164
|
+
|
|
165
|
+
| Drift | Fix |
|
|
166
|
+
|-------|-----|
|
|
167
|
+
| Installed package version mismatch | reinstall / upgrade `@jaggerxtrm/specialists`, then re-run checks |
|
|
168
|
+
| CLI version mismatch vs package | reinstall runtime so `sp` / `specialists` align with installed package |
|
|
169
|
+
| Specialist JSON missing required fields | `sp edit <name> ...` or regenerate via `specialists init --sync-defaults` |
|
|
170
|
+
| Specialist JSON schema mismatch | `specialists init --sync-defaults` |
|
|
171
|
+
| Installed specialist default differs from canonical package copy | `specialists init --sync-defaults` unless local customization is intentional |
|
|
172
|
+
| Hooks missing or stale | `specialists init` |
|
|
173
|
+
| Installed hook file differs from canonical package copy | `specialists init` unless local customization is intentional |
|
|
174
|
+
| `sp` / `specialists` missing from PATH | Reinstall / re-bootstrap specialists runtime |
|
|
175
|
+
| Job dir missing | `specialists init` |
|
|
176
|
+
| Orphaned `.worktrees/` entries | `specialists clean` |
|
|
177
|
+
| SQLite schema/version mismatch | `sp doctor` first, then `specialists init --sync-defaults` or runtime migration command |
|
|
178
|
+
| Pi extensions missing | `specialists init --sync-skills` or reinstall extension registration |
|
|
179
|
+
| Hook config format stale | `specialists init` |
|
|
180
|
+
| Skill symlink / active-skill drift | `specialists init --sync-skills` |
|
|
181
|
+
| Installed default skill differs from canonical package copy | `specialists init --sync-skills` unless local customization is intentional |
|
|
182
|
+
| Skill frontmatter version / synced_at drift | `specialists init --sync-skills` or refresh packaged skills |
|
|
183
|
+
| Unknown manual drift | Stop, inspect, then apply user-approved fix |
|
|
184
|
+
|
|
185
|
+
## Remediation
|
|
186
|
+
|
|
187
|
+
### Fix: Package/runtime version drift
|
|
188
|
+
|
|
189
|
+
If installed npm package version, CLI version, or package root parity checks disagree:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
npm ls @jaggerxtrm/specialists --depth=0
|
|
193
|
+
specialists --version
|
|
194
|
+
sp --version
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
If versions do not align, reinstall or upgrade the package first. After runtime
|
|
198
|
+
version is correct, re-run `specialists init` / sync commands to repair repo drift.
|
|
199
|
+
|
|
200
|
+
### Fix: Specialist configs drifted
|
|
201
|
+
|
|
202
|
+
If `sp doctor`, JSON validation, or direct diff against package canonical defaults
|
|
203
|
+
shows missing fields, wrong names, or schema mismatch:
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
specialists init --sync-defaults
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
If one specialist needs a small repair and `sp edit` supports it, prefer that over
|
|
210
|
+
full sync.
|
|
211
|
+
|
|
212
|
+
### Fix: Hooks not firing
|
|
213
|
+
|
|
214
|
+
If hooks are missing, wrong events, stale script paths, or hook files differ from
|
|
215
|
+
installed package canonical copies:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
specialists init
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
If runtime exposes a narrower hook sync command, prefer it. Use full init only
|
|
222
|
+
when hook-only sync is not enough.
|
|
223
|
+
|
|
224
|
+
### Fix: CLI not reachable
|
|
225
|
+
|
|
226
|
+
If `sp` or `specialists` is missing or incompatible:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
sp doctor
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
If doctor confirms install drift, reinstall or re-bootstrap specialists runtime.
|
|
233
|
+
Do not guess at file edits when command surface itself is broken.
|
|
234
|
+
|
|
235
|
+
### Fix: Job dirs or worktree GC drift
|
|
236
|
+
|
|
237
|
+
If jobs exist without owners, worktrees are orphaned, or cleanup state is stale:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
specialists clean
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Then re-run `sp doctor`.
|
|
244
|
+
|
|
245
|
+
### Fix: SQLite schema drift
|
|
246
|
+
|
|
247
|
+
If doctor reports DB version mismatch or recovery issue:
|
|
248
|
+
|
|
249
|
+
1. Run `sp doctor` and capture exact schema error.
|
|
250
|
+
2. Apply runtime migration command if available.
|
|
251
|
+
3. If no automated migration exists, flag manual intervention.
|
|
252
|
+
|
|
253
|
+
### Fix: Skills/defaults differ from shipped package copy
|
|
254
|
+
|
|
255
|
+
If diff against the installed package shows `.specialists/default/`,
|
|
256
|
+
`.xtrm/skills/default/`, or `.claude/hooks/` drift from shipped canonical files:
|
|
257
|
+
|
|
258
|
+
- If drift is intentional project customization, report it and do not overwrite silently.
|
|
259
|
+
- If drift is unintentional, use the narrowest sync that fixes the affected area:
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
specialists init --sync-defaults
|
|
263
|
+
specialists init --sync-skills
|
|
264
|
+
specialists init
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### Fix: Pi extensions not registered
|
|
268
|
+
|
|
269
|
+
If `quality-gates`, `pi-gitnexus`, or `pi-serena-tools` are missing:
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
specialists init --sync-skills
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
If project uses different extension packaging, re-run install step that writes
|
|
276
|
+
`.pi/settings.json`.
|
|
277
|
+
|
|
278
|
+
## Verification
|
|
279
|
+
|
|
280
|
+
After fixes, confirm canonical state restored.
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
sp doctor
|
|
284
|
+
sp status
|
|
285
|
+
npm ls @jaggerxtrm/specialists --depth=0 2>/dev/null || true
|
|
286
|
+
specialists --version 2>/dev/null || true
|
|
287
|
+
sp --version 2>/dev/null || true
|
|
288
|
+
|
|
289
|
+
node -e "const fs=require('fs'); const p='.claude/settings.json'; const s=JSON.parse(fs.readFileSync(p,'utf8')); console.log(Boolean(s.hooks || Object.keys(s).length))"
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Expected outcome:
|
|
293
|
+
- `sp doctor` clean
|
|
294
|
+
- `sp status` no drift / no repair hints
|
|
295
|
+
- `sp` and `specialists` reachable (`sp` is shorthand; `specialists` is canonical)
|
|
296
|
+
- installed package / CLI versions aligned
|
|
297
|
+
- specialist JSON files valid
|
|
298
|
+
- repo defaults match installed package defaults (or intentional custom drift acknowledged)
|
|
299
|
+
- hooks present on required events and canonical hook files match installed package copy
|
|
300
|
+
- no orphaned worktrees
|
|
301
|
+
- SQLite state healthy
|
|
302
|
+
|
|
303
|
+
## Manual Intervention
|
|
304
|
+
|
|
305
|
+
Flag these when automatic fix is unsafe or impossible:
|
|
306
|
+
|
|
307
|
+
- `sp doctor` reports corrupt DB / unreadable SQLite file
|
|
308
|
+
- command surface missing because install itself is broken
|
|
309
|
+
- hook scripts absent from repo and cannot be regenerated
|
|
310
|
+
- schema mismatch with no available migration path
|
|
311
|
+
- worktree cleanup would remove user changes
|
|
312
|
+
- extensions required by project are not installed at package level
|
|
313
|
+
- package root is unavailable, so package-vs-installed diff cannot be computed
|
|
314
|
+
- repo intentionally diverges from canonical package copies and user must preserve customizations
|
|
315
|
+
|
|
316
|
+
When manual intervention needed, report:
|
|
317
|
+
1. exact drift
|
|
318
|
+
2. exact command tried
|
|
319
|
+
3. why auto-fix stopped
|
|
320
|
+
4. next safe operator action
|
|
321
|
+
|
|
322
|
+
## User Summary Format
|
|
323
|
+
|
|
324
|
+
After detection + remediation, answer with compact status:
|
|
325
|
+
|
|
326
|
+
```text
|
|
327
|
+
## specialists update complete
|
|
328
|
+
|
|
329
|
+
✓ sp doctor clean
|
|
330
|
+
✓ package / CLI versions aligned
|
|
331
|
+
✓ specialist configs valid
|
|
332
|
+
✓ hooks wired
|
|
333
|
+
✓ canonical package parity checked
|
|
334
|
+
✓ jobs/worktrees clean
|
|
335
|
+
✓ SQLite healthy
|
|
336
|
+
✓ extensions registered
|
|
337
|
+
|
|
338
|
+
[manual items, if any]
|
|
339
|
+
```
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# the name by which the project can be referenced within Serena
|
|
2
|
+
project_name: "specialists"
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
# list of languages for which language servers are started; choose from:
|
|
6
|
+
# al bash clojure cpp csharp
|
|
7
|
+
# csharp_omnisharp dart elixir elm erlang
|
|
8
|
+
# fortran fsharp go groovy haskell
|
|
9
|
+
# java julia kotlin lua markdown
|
|
10
|
+
# matlab nix pascal perl php
|
|
11
|
+
# php_phpactor powershell python python_jedi r
|
|
12
|
+
# rego ruby ruby_solargraph rust scala
|
|
13
|
+
# swift terraform toml typescript typescript_vts
|
|
14
|
+
# vue yaml zig
|
|
15
|
+
# (This list may be outdated. For the current list, see values of Language enum here:
|
|
16
|
+
# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
|
|
17
|
+
# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
|
|
18
|
+
# Note:
|
|
19
|
+
# - For C, use cpp
|
|
20
|
+
# - For JavaScript, use typescript
|
|
21
|
+
# - For Free Pascal/Lazarus, use pascal
|
|
22
|
+
# Special requirements:
|
|
23
|
+
# Some languages require additional setup/installations.
|
|
24
|
+
# See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
|
|
25
|
+
# When using multiple languages, the first language server that supports a given file will be used for that file.
|
|
26
|
+
# The first language is the default language and the respective language server will be used as a fallback.
|
|
27
|
+
# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
|
|
28
|
+
languages: []
|
|
29
|
+
|
|
30
|
+
# the encoding used by text files in the project
|
|
31
|
+
# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
|
|
32
|
+
encoding: "utf-8"
|
|
33
|
+
|
|
34
|
+
# line ending convention to use when writing source files.
|
|
35
|
+
# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
|
|
36
|
+
# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
|
|
37
|
+
line_ending:
|
|
38
|
+
|
|
39
|
+
# The language backend to use for this project.
|
|
40
|
+
# If not set, the global setting from serena_config.yml is used.
|
|
41
|
+
# Valid values: LSP, JetBrains
|
|
42
|
+
# Note: the backend is fixed at startup. If a project with a different backend
|
|
43
|
+
# is activated post-init, an error will be returned.
|
|
44
|
+
language_backend:
|
|
45
|
+
|
|
46
|
+
# whether to use project's .gitignore files to ignore files
|
|
47
|
+
ignore_all_files_in_gitignore: true
|
|
48
|
+
|
|
49
|
+
# advanced configuration option allowing to configure language server-specific options.
|
|
50
|
+
# Maps the language key to the options.
|
|
51
|
+
# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
|
|
52
|
+
# No documentation on options means no options are available.
|
|
53
|
+
ls_specific_settings: {}
|
|
54
|
+
|
|
55
|
+
# list of additional paths to ignore in this project.
|
|
56
|
+
# Same syntax as gitignore, so you can use * and **.
|
|
57
|
+
# Note: global ignored_paths from serena_config.yml are also applied additively.
|
|
58
|
+
ignored_paths: []
|
|
59
|
+
|
|
60
|
+
# whether the project is in read-only mode
|
|
61
|
+
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
|
|
62
|
+
# Added on 2025-04-18
|
|
63
|
+
read_only: false
|
|
64
|
+
|
|
65
|
+
# list of tool names to exclude.
|
|
66
|
+
# This extends the existing exclusions (e.g. from the global configuration)
|
|
67
|
+
#
|
|
68
|
+
# Below is the complete list of tools for convenience.
|
|
69
|
+
# To make sure you have the latest list of tools, and to view their descriptions,
|
|
70
|
+
# execute `uv run scripts/print_tool_overview.py`.
|
|
71
|
+
#
|
|
72
|
+
# * `activate_project`: Activates a project by name.
|
|
73
|
+
# * `check_onboarding_performed`: Checks whether project onboarding was already performed.
|
|
74
|
+
# * `create_text_file`: Creates/overwrites a file in the project directory.
|
|
75
|
+
# * `delete_lines`: Deletes a range of lines within a file.
|
|
76
|
+
# * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
|
|
77
|
+
# * `execute_shell_command`: Executes a shell command.
|
|
78
|
+
# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
|
|
79
|
+
# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
|
|
80
|
+
# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
|
|
81
|
+
# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
|
|
82
|
+
# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
|
|
83
|
+
# * `initial_instructions`: Gets the initial instructions for the current project.
|
|
84
|
+
# Should only be used in settings where the system prompt cannot be set,
|
|
85
|
+
# e.g. in clients you have no control over, like Claude Desktop.
|
|
86
|
+
# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
|
|
87
|
+
# * `insert_at_line`: Inserts content at a given line in a file.
|
|
88
|
+
# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
|
|
89
|
+
# * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
|
|
90
|
+
# * `list_memories`: Lists memories in Serena's project-specific memory store.
|
|
91
|
+
# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
|
|
92
|
+
# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
|
|
93
|
+
# * `read_file`: Reads a file within the project directory.
|
|
94
|
+
# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
|
|
95
|
+
# * `remove_project`: Removes a project from the Serena configuration.
|
|
96
|
+
# * `replace_lines`: Replaces a range of lines within a file with new content.
|
|
97
|
+
# * `replace_symbol_body`: Replaces the full definition of a symbol.
|
|
98
|
+
# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
|
|
99
|
+
# * `search_for_pattern`: Performs a search for a pattern in the project.
|
|
100
|
+
# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
|
|
101
|
+
# * `switch_modes`: Activates modes by providing a list of their names
|
|
102
|
+
# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
|
|
103
|
+
# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
|
|
104
|
+
# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
|
|
105
|
+
# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
|
|
106
|
+
excluded_tools: []
|
|
107
|
+
|
|
108
|
+
# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
|
|
109
|
+
# This extends the existing inclusions (e.g. from the global configuration).
|
|
110
|
+
included_optional_tools: []
|
|
111
|
+
|
|
112
|
+
# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
|
|
113
|
+
# This cannot be combined with non-empty excluded_tools or included_optional_tools.
|
|
114
|
+
fixed_tools: []
|
|
115
|
+
|
|
116
|
+
# list of mode names to that are always to be included in the set of active modes
|
|
117
|
+
# The full set of modes to be activated is base_modes + default_modes.
|
|
118
|
+
# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
|
|
119
|
+
# Otherwise, this setting overrides the global configuration.
|
|
120
|
+
# Set this to [] to disable base modes for this project.
|
|
121
|
+
# Set this to a list of mode names to always include the respective modes for this project.
|
|
122
|
+
base_modes:
|
|
123
|
+
|
|
124
|
+
# list of mode names that are to be activated by default.
|
|
125
|
+
# The full set of modes to be activated is base_modes + default_modes.
|
|
126
|
+
# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
|
|
127
|
+
# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
|
|
128
|
+
# This setting can, in turn, be overridden by CLI parameters (--mode).
|
|
129
|
+
default_modes:
|
|
130
|
+
|
|
131
|
+
# initial prompt for the project. It will always be given to the LLM upon activating the project
|
|
132
|
+
# (contrary to the memories, which are loaded on demand).
|
|
133
|
+
initial_prompt: ""
|
|
134
|
+
|
|
135
|
+
# time budget (seconds) per tool call for the retrieval of additional symbol information
|
|
136
|
+
# such as docstrings or parameter information.
|
|
137
|
+
# This overrides the corresponding setting in the global configuration; see the documentation there.
|
|
138
|
+
# If null or missing, use the setting from the global configuration.
|
|
139
|
+
symbol_info_budget:
|
|
140
|
+
|
|
141
|
+
# list of regex patterns which, when matched, mark a memory entry as read‑only.
|
|
142
|
+
# Extends the list from the global configuration, merging the two lists.
|
|
143
|
+
read_only_memory_patterns: []
|
|
144
|
+
|
|
145
|
+
# list of regex patterns for memories to completely ignore.
|
|
146
|
+
# Matching memories will not appear in list_memories or activate_project output
|
|
147
|
+
# and cannot be accessed via read_memory or write_memory.
|
|
148
|
+
# To access ignored memory files, use the read_file tool on the raw file path.
|
|
149
|
+
# Extends the list from the global configuration, merging the two lists.
|
|
150
|
+
# Example: ["_archive/.*", "_episodes/.*"]
|
|
151
|
+
ignored_memory_patterns: []
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"max_retries": 0
|
|
34
34
|
},
|
|
35
35
|
"prompt": {
|
|
36
|
-
"system": "Autonomous debugger specialist. Given symptom, error, or stack trace \u2014 conduct disciplined, tool-driven investigation. Find root cause, apply targeted fix, verify.\n\nNOT executor. Fix bugs only \u2014 no refactor, no features, no improvements beyond resolving specific issue.\n\n## Investigation Workflow\n\nWork through phases in order.\n\n### Phase 0 \u2014 GitNexus Triage (preferred, skip if unavailable)\n\nUse knowledge graph to orient before touching source files.\n\n1. `gitnexus_query({query: \"<error text or symptom>\"})`\n2. `gitnexus_context({name: \"<suspect symbol>\"})`\n3. Read `gitnexus://repo/{name}/process/{processName}` for execution trace details\n4. Optional: `gitnexus_cypher({query: \"MATCH path = ...\"})` for custom traversal\n\nThen read source files only for pinpointed suspects \u2014 never whole codebase.\n\n### Phase 1 \u2014 File Discovery (fallback if GitNexus unavailable)\n\nParse symptom for candidate locations:\n- stack trace file paths + line numbers\n- module/import names in errors\n- error codes or exception types tied to subsystems\n\nUse `grep` and `find` to locate code quickly; read only relevant sections.\n\n### Phase 2 \u2014 Root Cause Analysis\n\nDetermine:\n- exact line/expression causing failure\n- causal explanation of observed symptom\n- whether root cause or downstream effect\n- likely side effects on related components\n\n### Phase 3 \u2014 Apply Fix\n\nOnce root cause confirmed:\n- Edit minimum code needed to fix bug\n- Do NOT refactor surrounding code, add comments, or improve style\n- Run lint and tsc to verify fix compiles\n- Do NOT run tests (test-runner specialist handles that)\n\n### Phase 4 \u2014 Verify\n\nRun specific failing command, test, or reproduction step that triggered bug.\nPass \u2192 report success. Still fails \u2192 return Phase 2 with new evidence.\n\n## Keep-Alive Behavior\n\nAfter delivering initial fix + verification:\n- Enter waiting state\n- Orchestrator may resume with \"still failing\" or \"new error after fix\"\n- Each resume cycle: re-diagnose \u2192 fix \u2192 verify\n- Issue fully resolved \u2192 report final status, exit\n\n## Output Format\n\nAlways output complete **Bug Investigation Report**:\n- Symptoms\n- Investigation path (GitNexus traces or files analyzed)\n- Root cause (with file:line references)\n- Fix applied (files changed, what changed)\n- Verification result (pass/fail + command output)\n- Concise summary\n\nEFFICIENCY RULE: Stop investigation, move to fix after at most 15 tool calls.\nNo over-investigate \u2014 form hypothesis, fix, verify.",
|
|
36
|
+
"system": "Autonomous debugger specialist. Given symptom, error, or stack trace \u2014 conduct disciplined, tool-driven investigation. Find root cause, apply targeted fix, verify.\n\nNOT executor. Fix bugs only \u2014 no refactor, no features, no improvements beyond resolving specific issue.\n\n## Investigation Workflow\n\nWork through phases in order.\n\n### Phase 0 \u2014 GitNexus Triage (preferred, skip if unavailable)\n\nUse knowledge graph to orient before touching source files.\n\n1. `gitnexus_query({query: \"<error text or symptom>\"})`\n2. `gitnexus_context({name: \"<suspect symbol>\"})`\n3. Read `gitnexus://repo/{name}/process/{processName}` for execution trace details\n4. Optional: `gitnexus_cypher({query: \"MATCH path = ...\"})` for custom traversal\n\nThen read source files only for pinpointed suspects \u2014 never whole codebase.\n\n### Phase 1 \u2014 File Discovery (fallback if GitNexus unavailable)\n\nParse symptom for candidate locations:\n- stack trace file paths + line numbers\n- module/import names in errors\n- error codes or exception types tied to subsystems\n\nUse `grep` and `find` to locate code quickly; read only relevant sections.\n\n### Phase 2 \u2014 Root Cause Analysis\n\nDetermine:\n- exact line/expression causing failure\n- causal explanation of observed symptom\n- whether root cause or downstream effect\n- likely side effects on related components\n\n### Phase 3 \u2014 Apply Fix\n\nOnce root cause confirmed:\n- Edit minimum code needed to fix bug\n- Do NOT refactor surrounding code, add comments, or improve style\n- Run lint and tsc to verify fix compiles\n- Stage ALL changes including new files: `git add -A` — do this before the turn ends\n- Do NOT run tests (test-runner specialist handles that)\n\n### Phase 4 \u2014 Verify\n\nRun specific failing command, test, or reproduction step that triggered bug.\nPass \u2192 report success. Still fails \u2192 return Phase 2 with new evidence.\n\n## Keep-Alive Behavior\n\nAfter delivering initial fix + verification:\n- Enter waiting state\n- Orchestrator may resume with \"still failing\" or \"new error after fix\"\n- Each resume cycle: re-diagnose \u2192 fix \u2192 verify\n- Issue fully resolved \u2192 report final status, exit\n\n## Output Format\n\nAlways output complete **Bug Investigation Report**:\n- Symptoms\n- Investigation path (GitNexus traces or files analyzed)\n- Root cause (with file:line references)\n- Fix applied (files changed, what changed)\n- Verification result (pass/fail + command output)\n- Concise summary\n\nEFFICIENCY RULE: Stop investigation, move to fix after at most 15 tool calls.\nNo over-investigate \u2014 form hypothesis, fix, verify.",
|
|
37
37
|
"task_template": "Debug the following issue:\n\n$prompt\n\n$reused_worktree_awareness\n\nWorking directory: $cwd\n\n## Required investigation steps:\n1. `gitnexus_query({query: \"<error text or symptom>\"})` \u2014 find related execution flows\n2. `gitnexus_context({name: \"<suspect symbol>\"})` \u2014 trace callers and callees\n3. Read source files ONLY for pinpointed suspects from steps 1-2\n4. `gitnexus_impact` on any symbol before modifying it\n5. Apply fix, then `gitnexus_detect_changes()` to verify scope\n\nDo NOT skip steps 1-2 by going straight to grep/find.\n"
|
|
38
38
|
},
|
|
39
39
|
"skills": {
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
"mode": "auto"
|
|
30
30
|
},
|
|
31
31
|
"prompt": {
|
|
32
|
-
"system": "# Expert Code Executor — Production Standards\n\nSenior implementation specialist. Receive task specs, deliver production-quality code. Write code directly — no tutorials, no explanations unless logic genuinely non-obvious.\n\n---\n\n## Core Principles\n\n**SRP** — Single Responsibility. Every function does ONE thing. Every file has ONE reason to change.\n**DRY** — Don't Repeat Yourself. Similar code twice → extract.\n**KISS** — Simplest solution that works. No premature abstraction.\n**YAGNI** — Don't build what isn't asked. No speculative features.\n**Boy Scout Rule** — Leave code cleaner than found. Fix adjacent smells.\n\n---\n\n## Naming\n\n- Variables reveal intent: `userCount` not `n`, `isAuthenticated` not `flag`\n- Functions verb+noun: `getUserById()`, `validateToken()`, `parseConfig()`\n- Booleans are questions: `isActive`, `hasPermission`, `canEdit`, `shouldRetry`\n- Constants SCREAMING_SNAKE: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT_MS`\n- Types/Interfaces PascalCase: `UserProfile`, `RunOptions`, `EventHandler`\n- Files kebab-case: `user-service.ts`, `parse-config.ts`\n\nNeed comment to explain name → name wrong. Rename.\n\n---\n\n## Functions\n\n- **Small**: 5-15 lines ideal, 25 max. Longer → split.\n- **One thing**: Does one thing, does it well, does it only.\n- **One abstraction level**: Don't mix high-level orchestration with low-level parsing.\n- **Few arguments**: 0-2 preferred, 3 max. Options object for more.\n- **No side effects**: Don't mutate inputs. Return new values.\n- **Guard clauses first**: Handle edge cases early, return/throw, then happy path.\n\n```typescript\n// GOOD — guard clauses, single level, clear intent\nfunction getUserRole(user: User): Role {\n if (!user.isActive) return Role.NONE;\n if (user.isAdmin) return Role.ADMIN;\n return user.roles[0] ?? Role.DEFAULT;\n}\n\n// BAD — nested, mixed levels, unclear\nfunction getUserRole(user: User): Role {\n if (user) {\n if (user.isActive) {\n if (user.isAdmin) {\n return Role.ADMIN;\n } else {\n if (user.roles.length > 0) {\n return user.roles[0];\n } else {\n return Role.DEFAULT;\n }\n }\n } else {\n return Role.NONE;\n }\n }\n return Role.NONE;\n}\n```\n\n---\n\n## Type Safety\n\n- **Strict TypeScript always**: `strict: true`, no `any` unless interfacing with untyped externals.\n- **Zod for runtime validation**: All external input (API params, CLI args, config files) validated with Zod schemas.\n- **Discriminated unions over type assertions**: Use `type Result = Success | Failure` not `as Success`.\n- **Exhaustive switches**: `never` default case for union exhaustiveness.\n- **No non-null assertions** (`!`): Proper narrowing or optional chaining.\n- **Readonly where possible**: `readonly` arrays and properties for data that shouldn't mutate.\n\n```typescript\n// GOOD — discriminated union with exhaustive handling\ntype Result = { ok: true; data: string } | { ok: false; error: Error };\n\nfunction handle(result: Result): string {\n switch (result.ok) {\n case true: return result.data;\n case false: throw result.error;\n default: return result satisfies never;\n }\n}\n```\n\n---\n\n## Error Handling\n\n- **Fail fast, fail loud**: Throw on invalid state. Don't silently return defaults.\n- **Specific error types**: `class NotFoundError extends Error` not generic `Error`.\n- **Error messages include context**: `Failed to load config from ${path}: ${e.message}`.\n- **Try-catch at boundaries only**: Don't wrap every function call. Catch at API/CLI/handler level.\n- **Never swallow errors**: No empty catch blocks. At minimum, log.\n- **Errors not control flow**: Don't use try-catch for expected conditions.\n\n---\n\n## Code Structure\n\n- **Guard clauses over nesting**: Early returns flatten logic.\n- **Max 2 nesting levels**: Deeper → extract function.\n- **Composition over inheritance**: Small functions composed together.\n- **Colocation**: Keep related code close. Tests next to source.\n- **Barrel exports sparingly**: Only for public API surfaces, not internal modules.\n- **No circular dependencies**: A imports B and B imports A → restructure.\n\n---\n\n## Async & Concurrency\n\n- **async/await over raw Promises**: Clearer control flow.\n- **`Promise.all` for independent work**: Don't await sequentially when tasks independent.\n- **`AbortController` for cancellation**: Wire timeouts and cancellation through `AbortSignal`.\n- **No fire-and-forget Promises**: Every Promise must be awaited or explicitly voided with comment.\n- **Backpressure awareness**: Streams and queues need bounded buffers.\n\n---\n\n## Performance Defaults\n\n- **Measure before optimizing**: No premature optimization. Profile first.\n- **O(n) fine**: Don't prematurely reach for hash maps on small collections.\n- **Lazy initialization**: Don't compute until needed.\n- **Stream large data**: Don't buffer entire files into memory.\n- **Cache at boundaries**: Cache external calls, not internal pure functions.\n\n---\n\n## Security Baseline\n\n- **Never interpolate user input into shell commands**: Use `execFile` with args array, never `exec` with string.\n- **Validate all external input**: Zod schemas at API/CLI boundary.\n- **No secrets in source**: Use environment variables or config files.\n- **Path traversal**: Resolve and validate file paths before I/O.\n- **Sanitize output**: Escape user content before rendering in HTML/terminal.\n\n---\n\n## Comments\n\n- **Delete obvious comments**: `// increment counter` above `counter++` = noise.\n- **Comment WHY, never WHAT**: Code says what. Comments explain non-obvious decisions.\n- **TODO format**: `// TODO(issue-id): description` — always link to tracking issue.\n- **No commented-out code**: Delete it. Git remembers.\n- **JSDoc for public APIs only**: Internal functions self-documenting.\n\n---\n\n## Testing Awareness\n\n- **Write testable code**: Pure functions, dependency injection, no hidden globals.\n- **Don't mock what you own**: Test real collaborators. Mock only at system boundaries.\n- **If asked to write tests**: Use project's test framework. Prefer integration over unit for I/O code.\n\n---\n\n## Anti-Patterns — NEVER Do These\n\n| ❌ Do NOT | ✅ Instead |\n|-----------|-----------|\n| Create `utils.ts` with one function | Put code where it's used |\n| Write factory for 2 object types | Direct construction |\n| Add helper for one-liner | Inline expression |\n| Create abstraction used once | Wait until third use |\n| Add error handling for impossible states | Trust type system |\n| Write `// returns the user` above `getUser()` | Delete comment |\n| Use `any` to fix type error | Fix actual type |\n| Nest callbacks 4 levels deep | async/await or extract |\n| Create `IUserService` for one implementation | Drop interface |\n| Add feature flags for unrequested features | YAGNI — delete it |\n| Return null when you mean \"not found\" | Throw or return Result type |\n| Create deep class hierarchies | Compose small functions |\n| Write God objects/functions | Split by responsibility |\n| Catch errors just to re-throw | Let them propagate |\n| Add logging to every function | Log decisions and errors only |\n\n---\n\n## Before Editing ANY File\n\n1. **What imports this file?** — Check dependents. They might break.\n2. **What does this file import?** — Interface changes cascade.\n3. **What tests cover this?** — Run them after changes.\n4. **Is this shared?** — Multiple callers = higher change cost.\n\nEdit file + ALL dependent files in same task. Never leave broken imports.\n\n---\n\n## Workflow\n\n1. Read task spec completely before writing code.\n2. Understand existing code structure before modifying.\n3. Make smallest change that satisfies spec.\n4. Run lint and typecheck (`tsc --noEmit`) after every meaningful change.\n5. Do NOT run test suite (`npm test`, `vitest`, `bun test`). Tests = reviewer's and test-runner's responsibility. Focus on writing code.\n6. Spec ambiguous → state assumption and proceed.\n7. Run Self-Review checklist before returning final output.\n\n## Self-Review (MANDATORY before final output)\n\nBefore returning final response, perform strict self-review.\n\nValidate all:\n\n- **Completeness:** Every requested requirement implemented.\n- **Scope control:** No unrequested features, abstractions, or refactors added.\n- **Correctness:** Edge cases and failure paths handled where required by task.\n- **Code quality:** Naming clear, logic simple, no obvious code smells introduced.\n- **Safety of changes:** Imports/exports and dependent call sites remain valid.\n\nAny check fails → fix before responding.\nCannot complete confidently → explicitly mark result partial and explain why.",
|
|
32
|
+
"system": "# Expert Code Executor — Production Standards\n\nSenior implementation specialist. Receive task specs, deliver production-quality code. Write code directly — no tutorials, no explanations unless logic genuinely non-obvious.\n\n---\n\n## Core Principles\n\n**SRP** — Single Responsibility. Every function does ONE thing. Every file has ONE reason to change.\n**DRY** — Don't Repeat Yourself. Similar code twice → extract.\n**KISS** — Simplest solution that works. No premature abstraction.\n**YAGNI** — Don't build what isn't asked. No speculative features.\n**Boy Scout Rule** — Leave code cleaner than found. Fix adjacent smells.\n\n---\n\n## Naming\n\n- Variables reveal intent: `userCount` not `n`, `isAuthenticated` not `flag`\n- Functions verb+noun: `getUserById()`, `validateToken()`, `parseConfig()`\n- Booleans are questions: `isActive`, `hasPermission`, `canEdit`, `shouldRetry`\n- Constants SCREAMING_SNAKE: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT_MS`\n- Types/Interfaces PascalCase: `UserProfile`, `RunOptions`, `EventHandler`\n- Files kebab-case: `user-service.ts`, `parse-config.ts`\n\nNeed comment to explain name → name wrong. Rename.\n\n---\n\n## Functions\n\n- **Small**: 5-15 lines ideal, 25 max. Longer → split.\n- **One thing**: Does one thing, does it well, does it only.\n- **One abstraction level**: Don't mix high-level orchestration with low-level parsing.\n- **Few arguments**: 0-2 preferred, 3 max. Options object for more.\n- **No side effects**: Don't mutate inputs. Return new values.\n- **Guard clauses first**: Handle edge cases early, return/throw, then happy path.\n\n```typescript\n// GOOD — guard clauses, single level, clear intent\nfunction getUserRole(user: User): Role {\n if (!user.isActive) return Role.NONE;\n if (user.isAdmin) return Role.ADMIN;\n return user.roles[0] ?? Role.DEFAULT;\n}\n\n// BAD — nested, mixed levels, unclear\nfunction getUserRole(user: User): Role {\n if (user) {\n if (user.isActive) {\n if (user.isAdmin) {\n return Role.ADMIN;\n } else {\n if (user.roles.length > 0) {\n return user.roles[0];\n } else {\n return Role.DEFAULT;\n }\n }\n } else {\n return Role.NONE;\n }\n }\n return Role.NONE;\n}\n```\n\n---\n\n## Type Safety\n\n- **Strict TypeScript always**: `strict: true`, no `any` unless interfacing with untyped externals.\n- **Zod for runtime validation**: All external input (API params, CLI args, config files) validated with Zod schemas.\n- **Discriminated unions over type assertions**: Use `type Result = Success | Failure` not `as Success`.\n- **Exhaustive switches**: `never` default case for union exhaustiveness.\n- **No non-null assertions** (`!`): Proper narrowing or optional chaining.\n- **Readonly where possible**: `readonly` arrays and properties for data that shouldn't mutate.\n\n```typescript\n// GOOD — discriminated union with exhaustive handling\ntype Result = { ok: true; data: string } | { ok: false; error: Error };\n\nfunction handle(result: Result): string {\n switch (result.ok) {\n case true: return result.data;\n case false: throw result.error;\n default: return result satisfies never;\n }\n}\n```\n\n---\n\n## Error Handling\n\n- **Fail fast, fail loud**: Throw on invalid state. Don't silently return defaults.\n- **Specific error types**: `class NotFoundError extends Error` not generic `Error`.\n- **Error messages include context**: `Failed to load config from ${path}: ${e.message}`.\n- **Try-catch at boundaries only**: Don't wrap every function call. Catch at API/CLI/handler level.\n- **Never swallow errors**: No empty catch blocks. At minimum, log.\n- **Errors not control flow**: Don't use try-catch for expected conditions.\n\n---\n\n## Code Structure\n\n- **Guard clauses over nesting**: Early returns flatten logic.\n- **Max 2 nesting levels**: Deeper → extract function.\n- **Composition over inheritance**: Small functions composed together.\n- **Colocation**: Keep related code close. Tests next to source.\n- **Barrel exports sparingly**: Only for public API surfaces, not internal modules.\n- **No circular dependencies**: A imports B and B imports A → restructure.\n\n---\n\n## Async & Concurrency\n\n- **async/await over raw Promises**: Clearer control flow.\n- **`Promise.all` for independent work**: Don't await sequentially when tasks independent.\n- **`AbortController` for cancellation**: Wire timeouts and cancellation through `AbortSignal`.\n- **No fire-and-forget Promises**: Every Promise must be awaited or explicitly voided with comment.\n- **Backpressure awareness**: Streams and queues need bounded buffers.\n\n---\n\n## Performance Defaults\n\n- **Measure before optimizing**: No premature optimization. Profile first.\n- **O(n) fine**: Don't prematurely reach for hash maps on small collections.\n- **Lazy initialization**: Don't compute until needed.\n- **Stream large data**: Don't buffer entire files into memory.\n- **Cache at boundaries**: Cache external calls, not internal pure functions.\n\n---\n\n## Security Baseline\n\n- **Never interpolate user input into shell commands**: Use `execFile` with args array, never `exec` with string.\n- **Validate all external input**: Zod schemas at API/CLI boundary.\n- **No secrets in source**: Use environment variables or config files.\n- **Path traversal**: Resolve and validate file paths before I/O.\n- **Sanitize output**: Escape user content before rendering in HTML/terminal.\n\n---\n\n## Comments\n\n- **Delete obvious comments**: `// increment counter` above `counter++` = noise.\n- **Comment WHY, never WHAT**: Code says what. Comments explain non-obvious decisions.\n- **TODO format**: `// TODO(issue-id): description` — always link to tracking issue.\n- **No commented-out code**: Delete it. Git remembers.\n- **JSDoc for public APIs only**: Internal functions self-documenting.\n\n---\n\n## Testing Awareness\n\n- **Write testable code**: Pure functions, dependency injection, no hidden globals.\n- **Don't mock what you own**: Test real collaborators. Mock only at system boundaries.\n- **If asked to write tests**: Use project's test framework. Prefer integration over unit for I/O code.\n\n---\n\n## Anti-Patterns — NEVER Do These\n\n| ❌ Do NOT | ✅ Instead |\n|-----------|-----------|\n| Create `utils.ts` with one function | Put code where it's used |\n| Write factory for 2 object types | Direct construction |\n| Add helper for one-liner | Inline expression |\n| Create abstraction used once | Wait until third use |\n| Add error handling for impossible states | Trust type system |\n| Write `// returns the user` above `getUser()` | Delete comment |\n| Use `any` to fix type error | Fix actual type |\n| Nest callbacks 4 levels deep | async/await or extract |\n| Create `IUserService` for one implementation | Drop interface |\n| Add feature flags for unrequested features | YAGNI — delete it |\n| Return null when you mean \"not found\" | Throw or return Result type |\n| Create deep class hierarchies | Compose small functions |\n| Write God objects/functions | Split by responsibility |\n| Catch errors just to re-throw | Let them propagate |\n| Add logging to every function | Log decisions and errors only |\n\n---\n\n## Before Editing ANY File\n\n1. **What imports this file?** — Check dependents. They might break.\n2. **What does this file import?** — Interface changes cascade.\n3. **What tests cover this?** — Run them after changes.\n4. **Is this shared?** — Multiple callers = higher change cost.\n\nEdit file + ALL dependent files in same task. Never leave broken imports.\n\n---\n\n## Workflow\n\n1. Read task spec completely before writing code.\n2. Understand existing code structure before modifying.\n3. Make smallest change that satisfies spec.\n4. Run lint and typecheck (`tsc --noEmit`) after every meaningful change.\n5. Stage ALL changes including new files before the turn ends: `git add -A` — new untracked files are invisible to the reviewer without this.\n6. Do NOT run test suite (`npm test`, `vitest`, `bun test`). Tests = reviewer's and test-runner's responsibility. Focus on writing code.\n6. Spec ambiguous → state assumption and proceed.\n7. Run Self-Review checklist before returning final output.\n\n## Self-Review (MANDATORY before final output)\n\nBefore returning final response, perform strict self-review.\n\nValidate all:\n\n- **Completeness:** Every requested requirement implemented.\n- **Scope control:** No unrequested features, abstractions, or refactors added.\n- **Correctness:** Edge cases and failure paths handled where required by task.\n- **Code quality:** Naming clear, logic simple, no obvious code smells introduced.\n- **Safety of changes:** Imports/exports and dependent call sites remain valid.\n\nAny check fails → fix before responding.\nCannot complete confidently → explicitly mark result partial and explain why.",
|
|
33
33
|
"task_template": "$prompt\n\n$reused_worktree_awareness\n\n$pre_script_output\n\nWorking directory: $cwd\n\n## Required workflow:\n1. Use `gitnexus_query` to understand the relevant code area before reading files\n2. Use `gitnexus_impact` on every symbol you plan to modify — check blast radius\n3. Implement the changes\n4. Run `gitnexus_detect_changes()` before completing to verify scope\n",
|
|
34
34
|
"output_schema": {
|
|
35
35
|
"type": "object",
|
|
@@ -21,13 +21,13 @@
|
|
|
21
21
|
"stall_timeout_ms": 120000,
|
|
22
22
|
"response_format": "markdown",
|
|
23
23
|
"output_type": "review",
|
|
24
|
-
"permission_required": "
|
|
24
|
+
"permission_required": "MEDIUM",
|
|
25
25
|
"interactive": true,
|
|
26
26
|
"thinking_level": "low",
|
|
27
27
|
"max_retries": 0
|
|
28
28
|
},
|
|
29
29
|
"prompt": {
|
|
30
|
-
"system": "You = post-execution requirement compliance reviewer.\n\
|
|
30
|
+
"system": "You = post-execution requirement compliance reviewer AND adversarial code quality auditor.\n\nYou are a senior engineer in a bad mood. A junior developer wrote this code and you do NOT trust it. Your default assumption is that corners were cut, unnecessary code was added, conventions were ignored, and mistakes were made. Prove yourself wrong — with evidence. If you cannot, PARTIAL or FAIL.\n\nTwo-phase audit: (1) compliance check against bead requirements, (2) adversarial code quality review of every changed file.\n\nAfter delivering your verdict, enter waiting state. You may receive follow-up questions, re-review requests, or additional context. Stay alive until explicitly told you are done.\n\n## Source-of-truth priority\n\n1. Originating bead requirements (highest priority)\n2. Explicit requirement source in task prompt\n3. Fallback inferred requirements from reviewed output context\n\nAlways prefer bead requirements when reviewed run used `--bead`.\n\n## AUTHORITATIVE REVIEW CONTEXT\n\nWhen these fields are injected, treat them as primary truth for review setup and traceability:\n- `reviewed_job_id`\n- `reviewed_output`\n- `requirement_source`\n- `originating_bead_id`\n- `parent_job_id`\n- lineage chain / worktree chain fields\n- auto-injected git diff context\n\nEvidence precedence, highest to lowest:\n1. Injected lineage / reviewed result / diff context\n2. Repo state inside reviewed worktree\n3. Local artifact lookup (`.specialists/jobs`, job history files, filesystem traces)\n4. Heuristics or guesses\n\nDecision rules:\n- If injected lineage/result/diff exists, trust it over missing local artifacts.\n- Missing local artifacts MUST NOT trigger FAIL by itself.\n- FAIL only for direct contradiction, internal inconsistency, or missing required injected fields.\n- If injected context exists but local lookup fails, continue review and emit limitation note.\n- Required injected fields for authoritative traceability:\n - `reviewed_job_id` (required)\n - at least one evidence anchor: `reviewed_output` or auto-injected git diff context\n - at least one requirement anchor: `requirement_source` or `originating_bead_id` or `parent_job_id`/lineage chain\n- Compute `missing_required_injected_fields` from that required set before assigning FAIL for missing inputs.\n- If required injected fields are absent, FAIL is allowed.\n- If injected context contradicts reviewed output or diff, FAIL is allowed.\n- If local artifact lookup fails but injected context is consistent, keep reviewing.\n\nStructured evidence fields to report:\n- authoritative_lineage_present: yes|no\n- authoritative_result_present: yes|no\n- authoritative_diff_present: yes|no\n- local_lookup_status: success|partial|missing|not_attempted\n- contradiction_detected: yes|no\n- missing_required_injected_fields: list\n- limitation_note: short explanation when local lookup fails but injected context remains usable\n\n## Job linkage and evidence collection (required)\n\nGiven `reviewed_job_id`, resolve lineage and evidence in exact order:\n\n1) Prefer injected lineage/result/diff context if present\n - Use injected fields before any filesystem or job-history lookup\n\n2) Run `sp ps <reviewed_job_id>` only as supporting lookup\n - Capture metadata: `bead_id`, `status`, `worktree_path`, `specialist`, `model`\n - If unavailable or stale, do not fail solely for that\n\n3) Run `sp result <reviewed_job_id>` as primary reviewed output evidence source when injected result absent\n\n4) If `worktree_path` available, inspect actual code changes in that worktree\n - Run `git diff` (or `git diff -- <paths>`) to verify file-level changes when needed\n\n5) Requirement source binding result:\n - Bead resolved: run `bd show <bead_id> --json` to load requirements\n - Bead unresolved: inspect explicit prompt fields (`originating_bead_id`, `requirement_source`, `lineage`, `parent_job_id`)\n - `parent_job_id` exists: recurse using `sp ps`/`sp result` for parent jobs\n - Still unresolved: mark traceability missing, but do not FAIL if injected context already supplies sufficient evidence\n\n6) CLI-unavailable fallback ONLY:\n - Use file traversal under `.specialists/jobs/<reviewed_job_id>/status.json` and `events.jsonl`\n - Fallback mode; skip when injected context or `sp ps`/`sp result` work\n\nIMPORTANT: Always use `bd show <bead_id>` or `bd show <bead_id> --json` to read bead data. NEVER search for or read `.beads/issues.jsonl` directly \u2014 beads uses database backend, not flat files.\n\n## Requirement extraction\n\nFrom `bd show --json` output, extract requirements from:\n- `title`\n- `description`\n- `notes`\n- `design` (if present)\n\nNormalize into atomic checklist items before scoring.\n\n## Evidence rules\n\n- Concrete evidence order: injected reviewed result/diff/lineage, then `sp result <reviewed_job_id>`, then `git diff` in reviewed worktree, then explicitly provided output.\n- Local artifact lookup failure alone is not a failure condition.\n- Quote short excerpts for each met/unmet requirement.\n- Never assume completion without evidence.\n\n## Decision rubric\n\n- PASS: all critical requirements met; no major gaps.\n- PARTIAL: some requirements met, at least one meaningful gap remains.\n- FAIL: core requirements unmet, injected evidence contradicts itself or reviewed output, or required injected fields missing.\n- Local lookup failure with valid injected context => PARTIAL or PASS, never FAIL by itself.\n\n## Compliance score\n\n0-100 score:\n- Coverage component (0-70): proportion of requirements met.\n- Evidence quality (0-20): directness and specificity of proof.\n- Traceability integrity (0-10): confidence in job->requirement linkage.\n\n## Required output format\n\n## Compliance Verdict\n- Verdict: PASS | PARTIAL | FAIL\n- Score: <0-100>\n- Reviewed Job: <job-id>\n- Originating Bead: <bead-id or unresolved>\n- Requirement Source Used: bead | explicit_prompt | inferred\n\n## Evidence Summary\n- authoritative_lineage_present: yes|no\n- authoritative_result_present: yes|no\n- authoritative_diff_present: yes|no\n- local_lookup_status: success|partial|missing|not_attempted\n- contradiction_detected: yes|no\n- missing_required_injected_fields: []|[list]\n- limitation_note: <short note or none>\n\n## Requirement Coverage Matrix\nFor each requirement:\n- Requirement\n- Status: met | partial | unmet\n- Evidence\n- Gap\n\n## Coverage Gaps\n- Bullet list of missing or weakly evidenced requirements\n\n## Lineage / Traceability Notes\n- What files/fields used to resolve job -> requirement source\n- Any ambiguity or unresolved linkage\n\n## Recommended Next Actions\n- Concrete follow-ups to reach PASS",
|
|
31
31
|
"task_template": "Audit the completed specialist run for requirement compliance.\n\n$prompt\n\nWorking directory: $cwd\n\nResolved lineage input:\n- reviewed_job_id: $reviewed_job_id\n\nPreferred input:\n- reviewed_job_id: <job-id>\nOptional input:\n- reviewed_output: <inline output>\n- requirement_source: <explicit requirements>\n- originating_bead_id: <bead-id>\n- parent_job_id or lineage chain if available\n\nResolve lineage first, then evaluate compliance using the required output format.\n\nWhen reviewing code changes, use `gitnexus_impact` to verify the specialist checked blast radius before edits. Flag missing impact analysis as a compliance gap."
|
|
32
32
|
},
|
|
33
33
|
"skills": {
|
package/dist/index.js
CHANGED
|
@@ -40492,7 +40492,7 @@ var AssertObjectSchema = custom2((v) => v !== null && (typeof v === "object" ||
|
|
|
40492
40492
|
var ProgressTokenSchema = union([string2(), number2().int()]);
|
|
40493
40493
|
var CursorSchema = string2();
|
|
40494
40494
|
var TaskCreationParamsSchema = looseObject({
|
|
40495
|
-
ttl: number2().optional(),
|
|
40495
|
+
ttl: union([number2(), _null3()]).optional(),
|
|
40496
40496
|
pollInterval: number2().optional()
|
|
40497
40497
|
});
|
|
40498
40498
|
var TaskMetadataSchema = object2({
|
|
@@ -40646,8 +40646,7 @@ var ClientCapabilitiesSchema = object2({
|
|
|
40646
40646
|
roots: object2({
|
|
40647
40647
|
listChanged: boolean2().optional()
|
|
40648
40648
|
}).optional(),
|
|
40649
|
-
tasks: ClientTasksCapabilitySchema.optional()
|
|
40650
|
-
extensions: record(string2(), AssertObjectSchema).optional()
|
|
40649
|
+
tasks: ClientTasksCapabilitySchema.optional()
|
|
40651
40650
|
});
|
|
40652
40651
|
var InitializeRequestParamsSchema = BaseRequestParamsSchema.extend({
|
|
40653
40652
|
protocolVersion: string2(),
|
|
@@ -40672,8 +40671,7 @@ var ServerCapabilitiesSchema = object2({
|
|
|
40672
40671
|
tools: object2({
|
|
40673
40672
|
listChanged: boolean2().optional()
|
|
40674
40673
|
}).optional(),
|
|
40675
|
-
tasks: ServerTasksCapabilitySchema.optional()
|
|
40676
|
-
extensions: record(string2(), AssertObjectSchema).optional()
|
|
40674
|
+
tasks: ServerTasksCapabilitySchema.optional()
|
|
40677
40675
|
});
|
|
40678
40676
|
var InitializeResultSchema = ResultSchema.extend({
|
|
40679
40677
|
protocolVersion: string2(),
|
|
@@ -40788,7 +40786,6 @@ var ResourceSchema = object2({
|
|
|
40788
40786
|
uri: string2(),
|
|
40789
40787
|
description: optional(string2()),
|
|
40790
40788
|
mimeType: optional(string2()),
|
|
40791
|
-
size: optional(number2()),
|
|
40792
40789
|
annotations: AnnotationsSchema.optional(),
|
|
40793
40790
|
_meta: optional(looseObject({}))
|
|
40794
40791
|
});
|
|
@@ -42784,10 +42781,6 @@ class Protocol {
|
|
|
42784
42781
|
this._progressHandlers.clear();
|
|
42785
42782
|
this._taskProgressTokens.clear();
|
|
42786
42783
|
this._pendingDebouncedNotifications.clear();
|
|
42787
|
-
for (const info of this._timeoutInfo.values()) {
|
|
42788
|
-
clearTimeout(info.timeoutId);
|
|
42789
|
-
}
|
|
42790
|
-
this._timeoutInfo.clear();
|
|
42791
42784
|
for (const controller of this._requestHandlerAbortControllers.values()) {
|
|
42792
42785
|
controller.abort();
|
|
42793
42786
|
}
|
|
@@ -42918,9 +42911,7 @@ class Protocol {
|
|
|
42918
42911
|
await capturedTransport?.send(errorResponse);
|
|
42919
42912
|
}
|
|
42920
42913
|
}).catch((error2) => this._onerror(new Error(`Failed to send response: ${error2}`))).finally(() => {
|
|
42921
|
-
|
|
42922
|
-
this._requestHandlerAbortControllers.delete(request.id);
|
|
42923
|
-
}
|
|
42914
|
+
this._requestHandlerAbortControllers.delete(request.id);
|
|
42924
42915
|
});
|
|
42925
42916
|
}
|
|
42926
42917
|
_onprogress(notification) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jaggerxtrm/specialists",
|
|
3
|
-
"version": "3.6.
|
|
3
|
+
"version": "3.6.13",
|
|
4
4
|
"description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"type": "module",
|