@jaggerxtrm/specialists 3.18.1 → 3.18.2

package/config/mandatory-rules/code-quality-defaults.md

@@ -2,4 +2,61 @@
 name: code-quality-defaults
 kind: mandatory-rule
 ---
-SRP, DRY, KISS, YAGNI. No premature abstraction. No speculative features. Don't add comments to explain what well-named code already says. Match existing project conventions; never invent a new style mid-file.
+The lazy senior lens. Best code = code never written.
+
+## The ladder (stop at the first rung that holds)
+
+1. Does this need to exist at all? Speculative need = skip it, say so in one line. (YAGNI)
+2. Already in this codebase? A helper, util, type, or pattern that already lives here — reuse it. Look before you write.
+3. Stdlib does it? Use it. Name the function.
+4. Native platform feature covers it? DB constraint over app code, CSS over JS, `<input type="date">` over a picker lib.
+5. Already-installed dependency solves it? Use it. Never add a new one for what a few lines can do.
+6. One line? Prefer one line.
+7. Only then: the minimum code that works.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate scaffolding "for later".
+- Deletion over addition. Boring over clever.
+- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place is a second bug.
+- SRP, DRY, KISS, YAGNI. No premature abstraction. No speculative features.
+- Match existing project conventions; never invent a new style mid-file.
+- Don't add comments to explain what well-named code already says.
+
+## Never simplify away
+
+- Input validation at trust boundaries.
+- Error handling that prevents data loss.
+- Security, accessibility, explicitly requested behavior.
+- Understanding the problem — the ladder shortens solutions, not reading.
+
+## Deliberate shortcuts
+
+When a lazy choice has a known ceiling, mark it in code:
+
+```
+// SIMPLIFIED: <ceiling>. upgrade when <trigger>.
+```
+
+Example: `// SIMPLIFIED: O(n²) scan. upgrade when list > 1k items.`
+Unmarked shortcuts silently rot; marked ones stay tracked.
+
+## Finding-report format (for review/audit modes)
+
+One line per finding, tag-prefixed:
+
+```
+<file>:L<line>: <tag> <what>. <replacement>.
+```
+
+Tags:
+
+- `delete:` dead code, unused flexibility, speculative feature. Nothing replaces it.
+- `stdlib:` hand-rolled thing the stdlib ships. Name the function.
+- `native:` code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+- `keep:` explicitly defended keep — used when refuting a proposed shrink; state the load-bearing reason.
+
+End quality passes with `net: -<N> lines possible.` or `Lean already. Ship.`

package/config/skills/setup-specialists/SKILL.md

@@ -552,5 +552,5 @@ KAN-91 global setup result:
   not allowlisted at the global layer. The global override layer reuses the
   same per-spec field semantics; see its §"Global User Override Layer
   (KAN-90/91)" section for the dot-path syntax mapping.
-- `using-specialists-v3` — orchestration discipline once specialists are
+- `using-specialists` — orchestration discipline once specialists are
   configured.

package/config/skills/using-script-specialists/SKILL.md

@@ -8,7 +8,7 @@ description: >
   specialist into a service, script, or library, when the caller needs the
   output immediately, or when the work is a single LLM call with structured
   input/output. Do NOT use for tracked agent work — that belongs to
-  `using-specialists-v2`.
+  `using-specialists`.
 version: 1.1.0
 updated: 2026-05-06
 synced_at: a0e54d0c
@@ -17,7 +17,7 @@ synced_at: a0e54d0c
 # Script-Class Specialists
 
 `sp script` and `sp serve` are a separate runtime from the bead-first
-orchestration covered by `using-specialists-v2`. They exist for service and
+orchestration covered by `using-specialists`. They exist for service and
 library integration, not for agent chains.
 
 | Aspect | `sp run` (orchestration) | `sp script` / `sp serve` |
@@ -47,7 +47,7 @@ Trigger when:
 
 Do NOT trigger for: code review, debugging, implementation, multi-turn work,
 keep-alive sessions, anything that should write files. Those belong to
-`using-specialists-v2`.
+`using-specialists`.
 
 ## Specialist Compatibility (compatGuard)
 
@@ -183,7 +183,7 @@ saturated past `queue-timeout-ms`.
 - For container deployments, see `docs/specialists-service-install.md`. Image
   runs as non-root UID 10001; bind-mount `~/.pi` and `.specialists/`.
 
-## When To Switch Back To `using-specialists-v2`
+## When To Switch Back To `using-specialists`
 
 If any of these become true mid-design, drop script-class and use the
 orchestration runtime:
@@ -198,7 +198,7 @@ orchestration runtime:
 ## What Not To Put Here
 
 - Bead workflow, chains, epics, reviewers, worktrees — those live in
-  `using-specialists-v2`.
+  `using-specialists`.
 - Orchestration MCP tooling (`use_specialist`).
 - Long-running multi-turn examples.