xtrm-tools 0.7.12 → 0.7.14

package/.xtrm/skills/default/specialists-creator/SKILL.md

@@ -5,7 +5,7 @@ description: >
   agent through writing a valid `.specialist.json`, choosing supported models,
   validating against the schema, and avoiding common specialist authoring
   mistakes.
-version: 1.1
+version: 1.2
 synced_at: 236ca5e6
 ---
 
@@ -40,6 +40,7 @@ Model tiers:
 Rules:
 - Always pick the **highest version** in a family (`claude-sonnet-4-6` not `4-5`, `gemini-3.1-pro-preview` not `gemini-2.5-pro`)
 - `model` and `fallback_model` must be **different providers**
+- If a specialist needs a longer fallback chain, keep first fallback in `fallback_model` and let runtime supply any extra retry tier.
 - Never write a model string you have not pinged in this session
 
 ---
@@ -162,6 +163,10 @@ specialists models  # confirm assignments look balanced
 
 ---
 
+## Canonical references
+
+Reference any canonical skill or rule by name; runtime finds it.
+
 ## Quick Start: Scaffold + `sp edit`
 
 ```bash
@@ -169,7 +174,7 @@ specialists models  # confirm assignments look balanced
 node config/skills/specialists-creator/scripts/scaffold-specialist.ts config/specialists/my-specialist.specialist.json
 
 # 2. Apply a preset for common model/thinking defaults (optional but preferred)
-sp edit my-specialist --preset standard
+sp edit my-specialist --preset medium
 
 # 3. Set individual fields via dot.path (primary mutation workflow)
 sp edit my-specialist specialist.metadata.name my-specialist
@@ -177,6 +182,8 @@ sp edit my-specialist specialist.metadata.version 1.0.0
 sp edit my-specialist specialist.execution.model anthropic/claude-sonnet-4-6
 sp edit my-specialist specialist.execution.fallback_model google-gemini-cli/gemini-3.1-pro-preview
 sp edit my-specialist specialist.execution.permission_required READ_ONLY
+sp edit my-specialist specialist.execution.extensions.serena false
+sp edit my-specialist specialist.execution.extensions.gitnexus false
 
 # 4. Use --file only for multiline prompt fields
 sp edit my-specialist specialist.prompt.system --file .tmp/system.prompt.txt
@@ -186,7 +193,7 @@ sp edit my-specialist specialist.prompt.task_template --file .tmp/task-template.
 sp view my-specialist
 
 # 6. Validate schema
-bun skills/specialist-author/scripts/validate-specialist.ts config/specialists/my-specialist.specialist.json
+bun config/skills/specialists-creator/scripts/validate-specialist.ts config/specialists/my-specialist.specialist.json
 ```
 
 ---
@@ -199,19 +206,47 @@ bun skills/specialist-author/scripts/validate-specialist.ts config/specialists/m
 |-------|------|----------|-------|
 | `name` | string | yes | kebab-case: `[a-z][a-z0-9-]*` |
 | `version` | string | yes | semver: `1.0.0` |
-| `description` | string | yes | One sentence |
+| `description` | string | yes | Routing summary surfaced by `specialists list`; see Description writing below |
 | `category` | string | yes | Free text (e.g. `workflow`, `analysis`, `codegen`) |
 | `author` | string | no | Optional |
 | `created` | string | no | Optional date |
 | `updated` | string | no | Optional date, quote it: `"2026-03-22"` |
 | `tags` | string[] | no | Optional list |
 
+
+### Description writing for `specialists list`
+
+`specialist.metadata.description` is the routing surface that orchestrators see in `specialists list`. Write it as an operational role definition, not marketing copy. Keep the first clause distinctive because list output may truncate.
+
+A good description answers, in this order:
+
+1. **Choose when** — the task shape that should route here.
+2. **Do not choose when** — adjacent roles that should win instead.
+3. **Distinctive capability** — what this specialist does that others do not.
+4. **Permission/risk note** — READ_ONLY/LOW/MEDIUM/HIGH implication when it affects orchestration.
+
+Pattern:
+
+```text
+<role noun>. Use for <specific task shape>. Not for <near misses>; use <better roles>. <permission/workflow distinction>.
+```
+
+Examples:
+
+```text
+Scoped implementation only. Use when requirements, files/symbols, constraints, and validation are clear. Not diagnosis, planning, review, tests, release, or research. HIGH worktree.
+
+Debug symptoms/errors/regressions first. Use when cause is unknown or tests fail unexpectedly; traces, fixes targeted code, and verifies. HIGH keep-alive.
+```
+
+Avoid vague descriptions like "general purpose assistant" or "helps with code". Those cause orchestrators to overuse familiar specialists instead of routing to debugger, test-runner, researcher, sync-docs, or other sharper roles.
+
 ### `specialist.execution` (required)
 
 | Field | Type | Default | Notes |
 |-------|------|---------|-------|
 | `model` | string | — | required — ping before using |
-| `fallback_model` | string | — | must be a different provider |
+| `fallback_model` | string | — | first fallback only; runtime may append more tiers |
 | `mode` | enum | `auto` | `tool` \| `skill` \| `auto` |
 | `timeout_ms` | number | `120000` | ms |
 | `stall_timeout_ms` | number | — | kill if no event for N ms |
@@ -220,6 +255,8 @@ bun skills/specialist-author/scripts/validate-specialist.ts config/specialists/m
 | `output_type` | enum | `custom` | `codegen` \| `analysis` \| `review` \| `synthesis` \| `orchestration` \| `workflow` \| `research` \| `custom` |
 | `permission_required` | enum | `READ_ONLY` | see tier table below |
 | `thinking_level` | enum | — | `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` |
+| `extensions.serena` | boolean | `true` | set `false` to opt out of Serena extension injection for this specialist |
+| `extensions.gitnexus` | boolean | `true` | set `false` to opt out of GitNexus extension injection for this specialist |
 
 **When to use `execution.interactive`**
 
@@ -230,17 +267,81 @@ bun skills/specialist-author/scripts/validate-specialist.ts config/specialists/m
   - MCP `start_specialist`: `keep_alive` enables, `no_keep_alive` disables.
 - Effective precedence: explicit disable (`--no-keep-alive` / `no_keep_alive`) → explicit enable (`--keep-alive` / `keep_alive`) → `execution.interactive` → one-shot default.
 
-**Permission tiers** — controls which pi tools are available:
+**Permission tiers** — controls the *native* pi tools the specialist gets. The full resolved tool set also includes catalog-defined GitNexus and Serena tools per tier; see [docs/manifest.md](../../../docs/manifest.md) for the complete picture.
+
+| Level | Native tools (cumulative) | Use when |
+|-------|---------------------------|----------|
+| `READ_ONLY` | `read, grep, find, ls` | Read-only analysis, no bash |
+| `LOW` | `+ bash` | Inspect/run commands, no file edits |
+| `MEDIUM` | `+ edit` | Can edit existing files |
+| `HIGH` | `+ write` | Full access — can create new files |
 
-| Level | pi --tools | Use when |
-|-------|-----------|----------|
-| `READ_ONLY` | `read,grep,find,ls` | Read-only analysis, no bash |
-| `LOW` | `+bash` | Inspect/run commands, no file edits |
-| `MEDIUM` | `+edit` | Can edit existing files |
-| `HIGH` | `+write` | Full access — can create new files |
+After choosing a tier, verify the resolved tool list before dispatching:
+
+```bash
+sp config show <name> --resolved
+```
 
 **Common pitfall:** `READ_WRITE` is **not** a valid value — use `LOW` or higher.
 
+### Per-specialist `permissions[<TIER>]` override (rarely needed)
+
+Most specialists use the catalog default deny baseline. **Do not declare an override unless this specialist's policy genuinely diverges from its tier.** When you do override, remember the specialist block replaces catalog defaults for that tier.
+
+If divergence is real, add a top-level `permissions` block (sibling to `execution`):
+
+```jsonc
+{
+  "specialist": {
+    "execution": { "permission_required": "READ_ONLY" },
+    "permissions": {
+      "READ_ONLY": {
+        "denied_natives_when_extension": ["grep", "find", "ls"],
+        "denied_natives_mode": "hard"
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Effect |
+|-------|------|---------|--------|
+| `denied_natives_when_extension` | `string[]` | `[]` | Native tools to deny only when a replacement extension is healthy. Catalog defaults apply first; specialist override replaces them for that tier. |
+| `denied_natives_mode` | `"soft"` \| `"hard"` | `"soft"` | `soft` keeps the tool with a preference hint; `hard` removes it (with auto-restore if the extension degrades) |
+
+The override block can only *deny* natives — it cannot add new tools beyond the catalog tier. To add tools, change the tier or update the catalog file.
+
+**Decision rule when authoring:**
+1. Pick the lowest tier that satisfies the specialist's actual capability needs.
+2. Run `sp config show <name> --resolved` and inspect the `--tools` line.
+3. If the tools are right, you're done — no override needed.
+4. If a native tool is genuinely worse than an extension equivalent for this specialist's task, declare a soft-deny first to observe behavior, then promote to hard-deny once you trust it.
+
+See [docs/manifest.md](../../../docs/manifest.md) for full deny-mode semantics, extension health gating, and the canonical explorer example.
+
+**Per-specialist extension opt-out**
+
+Use `execution.extensions` only when this specialist must suppress default extension injection.
+Both flags default to `true`, so omit this block unless opt-out is required.
+
+```json
+{
+  "specialist": {
+    "execution": {
+      "extensions": {
+        "serena": false,
+        "gitnexus": false
+      }
+    }
+  }
+}
+```
+
+Typical use cases:
+- `serena: false` for specialists that must avoid Serena tool/LSP injection
+- `gitnexus: false` for specialists that should not receive GitNexus graph tooling
+- set both `false` for constrained runs that need clean extension surface
+
 ### `specialist.prompt` (required)
 
 | Field | Type | Required | Notes |
@@ -356,8 +457,6 @@ planner — epic result:
 
 `run` accepts either a **file path** (`./scripts/foo.sh`, `~/scripts/foo.sh`) or a **shell command** (`bd ready`, `git status`). Pre-run validation checks that file paths exist and shell commands are on `PATH`. Shebang typos (e.g. `pytho` instead of `python`) are caught and reported as errors before the session starts.
 
-`path` is accepted as a deprecated alias for `run`.
-
 ### `specialist.capabilities` (optional)
 
 Informational declarations used by pre-run validation and future tooling (e.g. `specialists doctor`).
@@ -383,27 +482,6 @@ Informational declarations used by pre-run validation and future tooling (e.g. `
 
 Writes the final session output to this file path after the session completes. Relative to the working directory.
 
-### `specialist.communication` (optional)
-
-```json
-{
-  "communication": {
-    "next_specialists": "planner"
-  }
-}
-```
-
-Or as an array:
-```json
-{
-  "communication": {
-    "next_specialists": ["planner", "test-runner"]
-  }
-}
-```
-
-`next_specialists` declares which specialist(s) should receive this specialist's output as `$previous_result`. Chaining is executed by the caller (e.g. `run_parallel` pipeline) — this field is declarative metadata.
-
 ### `specialist.validation` (optional)
 
 Drives the staleness detection shown in `specialists status` and `specialists list`.
@@ -480,7 +558,7 @@ Files listed under `skills.paths` are read and appended to the system prompt at
 {
   "skills": {
     "paths": [
-      "skills/specialist-author/SKILL.md",
+      ".xtrm/skills/active/specialists-creator/SKILL.md",
       ".claude/agents.md"
     ]
   }
@@ -576,9 +654,6 @@ Scripts run **locally** (not inside the agent session):
       "required_tools": ["bash", "read"],
       "external_commands": ["git"]
     },
-    "communication": {
-      "next_specialists": ["sync-docs"]
-    },
     "output_file": ".specialists/review.md",
     "beads_integration": "auto"
   }
@@ -681,7 +756,7 @@ pi --model <provider>/<fallback-model-id> --print "ping"   # must return "pong"
 node config/skills/specialists-creator/scripts/scaffold-specialist.ts config/specialists/my-specialist.specialist.json
 
 # 3. Mutate with sp edit (dot.path + presets)
-sp edit my-specialist --preset standard
+sp edit my-specialist --preset medium
 sp edit my-specialist specialist.execution.model <provider>/<primary-model-id>
 sp edit my-specialist specialist.execution.fallback_model <provider>/<fallback-model-id>
 
@@ -693,7 +768,7 @@ sp edit my-specialist specialist.prompt.task_template --file .tmp/task-template.
 sp view my-specialist
 
 # 6. Validate schema with the bundled helper
-bun skills/specialist-author/scripts/validate-specialist.ts config/specialists/my-specialist.specialist.json
+bun config/skills/specialists-creator/scripts/validate-specialist.ts config/specialists/my-specialist.specialist.json
 
 # 7. List to confirm discovery
 specialists list
@@ -702,4 +777,4 @@ specialists list
 specialists run my-specialist --prompt "ping" --no-beads
 ```
 
-If you need the underlying implementation, read `skills/specialist-author/scripts/validate-specialist.ts`. It is a thin Bun/TypeScript wrapper over `parseSpecialist()` from `src/specialist/schema.ts`, which keeps the helper cross-platform for Windows, macOS, and Linux.
+If you need the underlying implementation, read `config/skills/specialists-creator/scripts/validate-specialist.ts`. It is a thin Bun/TypeScript wrapper over `parseSpecialist()` from `src/specialist/schema.ts`, which keeps the helper cross-platform for Windows, macOS, and Linux.

package/.xtrm/skills/default/specialists-creator/scripts/audit-spec-uniformity.mjs

@@ -0,0 +1,86 @@
+// Audit every .specialist.json under config/specialists/ and .specialists/default/
+// for: (1) schema parse failures, (2) unknown keys that survive .passthrough() silently.
+//
+// Usage (from repo root): bun config/skills/specialists-creator/scripts/audit-spec-uniformity.mjs
+//
+// Keep KNOWN sets in sync with src/specialist/schema.ts. If a sub-schema gains
+// or drops a field, update this file in the same commit.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = fileURLToPath(import.meta.url);
+const repoRoot = resolve(here, '../../../../..');
+const { validateSpecialist } = await import(resolve(repoRoot, 'src/specialist/schema.ts'));
+
+// Walk known schema keys to detect "unknown" passthrough survivors
+const KNOWN = {
+  root: new Set(['specialist']),
+  specialist: new Set(['metadata','execution','prompt','skills','capabilities','communication','validation','beads_integration','beads_write_notes','stall_detection','heartbeat','mandatory_rules','output_file']),
+  metadata: new Set(['name','version','description','category','author','created','updated','tags']),
+  execution: new Set(['mode','model','fallback_model','timeout_ms','stall_timeout_ms','max_retries','interactive','response_format','output_type','permission_required','requires_worktree','thinking_level','auto_commit','extensions','preferred_profile','approval_mode']),
+  'execution.extensions': new Set(['serena','gitnexus']),
+  prompt: new Set(['system','task_template','normalize_template','output_schema','examples','skill_inherit']),
+  skills: new Set(['paths','scripts']),
+  'skills.scripts.item': new Set(['run','path','phase','inject_output']),
+  capabilities: new Set(['required_tools','external_commands','diagnostic_scripts']),
+  communication: new Set(['next_specialists','publishes']),
+  validation: new Set(['files_to_watch','stale_threshold_days']),
+  stall_detection: new Set(['running_idle_warn_ms','running_idle_kill_ms','waiting_stale_ms','tool_duration_warn_ms']),
+};
+
+function unknownKeys(obj, knownSet, path) {
+  const out = [];
+  for (const k of Object.keys(obj || {})) if (!knownSet.has(k)) out.push(`${path}.${k}`);
+  return out;
+}
+
+function audit(file) {
+  const raw = JSON.parse(readFileSync(file,'utf8'));
+  const findings = [];
+  // raw key check (before parse strips/preserves)
+  findings.push(...unknownKeys(raw, KNOWN.root, ''));
+  const s = raw.specialist ?? {};
+  findings.push(...unknownKeys(s, KNOWN.specialist, 'specialist'));
+  if (s.metadata) findings.push(...unknownKeys(s.metadata, KNOWN.metadata, 'specialist.metadata'));
+  if (s.execution) findings.push(...unknownKeys(s.execution, KNOWN.execution, 'specialist.execution'));
+  if (s.execution?.extensions) findings.push(...unknownKeys(s.execution.extensions, KNOWN['execution.extensions'], 'specialist.execution.extensions'));
+  if (s.prompt) findings.push(...unknownKeys(s.prompt, KNOWN.prompt, 'specialist.prompt'));
+  if (s.skills) findings.push(...unknownKeys(s.skills, KNOWN.skills, 'specialist.skills'));
+  if (Array.isArray(s.skills?.scripts)) for (const [i, sc] of s.skills.scripts.entries()) findings.push(...unknownKeys(sc, KNOWN['skills.scripts.item'], `specialist.skills.scripts[${i}]`));
+  if (s.capabilities) findings.push(...unknownKeys(s.capabilities, KNOWN.capabilities, 'specialist.capabilities'));
+  if (s.communication) findings.push(...unknownKeys(s.communication, KNOWN.communication, 'specialist.communication'));
+  if (s.validation) findings.push(...unknownKeys(s.validation, KNOWN.validation, 'specialist.validation'));
+  if (s.stall_detection) findings.push(...unknownKeys(s.stall_detection, KNOWN.stall_detection, 'specialist.stall_detection'));
+  return findings;
+}
+
+const files = [
+  ...readdirSync(resolve(repoRoot,'config/specialists')).filter(f=>f.endsWith('.specialist.json')).map(f=>join(repoRoot,'config/specialists',f)),
+  ...readdirSync(resolve(repoRoot,'.specialists/default')).filter(f=>f.endsWith('.specialist.json')).map(f=>join(repoRoot,'.specialists/default',f)),
+];
+
+let totalUnknown = 0;
+let parseErrors = 0;
+for (const file of files) {
+  try {
+    const v = await validateSpecialist(readFileSync(file,'utf8'));
+    if (!v.valid) {
+      parseErrors++;
+      console.log(`\n✗ PARSE FAIL ${file}`);
+      for (const e of v.errors) console.log(`    ${e.path}: ${e.message}`);
+      continue;
+    }
+    const unk = audit(file);
+    if (unk.length) {
+      totalUnknown += unk.length;
+      console.log(`\n⚠ ${file}`);
+      for (const k of unk) console.log(`    unknown key: ${k}`);
+    }
+  } catch (e) {
+    parseErrors++;
+    console.log(`\n✗ ERROR ${file}: ${e.message}`);
+  }
+}
+console.log(`\n=== ${files.length} specs · ${parseErrors} parse errors · ${totalUnknown} unknown keys ===`);

package/.xtrm/skills/default/specialists-creator/scripts/scaffold-specialist.ts

@@ -0,0 +1,223 @@
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as z from "zod";
+import { SpecialistSchema } from "../../../../src/specialist/schema.ts";
+
+const DEAD_FIELDS = new Set<string>([]);
+
+interface AddedField {
+  path: string;
+  value: unknown;
+}
+
+interface ScaffoldResult {
+  value: unknown;
+  added: AddedField[];
+  changed: boolean;
+}
+
+function printUsage(): void {
+  console.error("Usage: node scripts/scaffold-specialist.ts <path-to-specialist.json>");
+  console.error("   or: node scripts/scaffold-specialist.ts --all");
+}
+
+function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny {
+  let current = schema;
+  while (
+    current instanceof z.ZodOptional ||
+    current instanceof z.ZodNullable ||
+    current instanceof z.ZodDefault ||
+    current instanceof z.ZodEffects
+  ) {
+    if (current instanceof z.ZodEffects) {
+      current = current.innerType();
+      continue;
+    }
+
+    if (current instanceof z.ZodDefault) {
+      current = current._def.innerType;
+      continue;
+    }
+
+    current = current.unwrap();
+  }
+  return current;
+}
+
+function isOptionalWithoutDefault(schema: z.ZodTypeAny): boolean {
+  if (schema instanceof z.ZodOptional) {
+    return true;
+  }
+  if (schema instanceof z.ZodNullable) {
+    return isOptionalWithoutDefault(schema.unwrap());
+  }
+  if (schema instanceof z.ZodEffects) {
+    return isOptionalWithoutDefault(schema.innerType());
+  }
+  if (schema instanceof z.ZodDefault) {
+    return false;
+  }
+  return false;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(value);
+}
+
+function scaffoldSchema(schema: z.ZodTypeAny, currentValue: unknown, path: string[]): ScaffoldResult {
+  if (schema instanceof z.ZodEffects) {
+    return scaffoldSchema(schema.innerType(), currentValue, path);
+  }
+
+  if (schema instanceof z.ZodDefault) {
+    const inner = schema._def.innerType;
+    if (currentValue === undefined) {
+      const defaultValue = schema._def.defaultValue();
+      const nested = scaffoldSchema(inner, defaultValue, path);
+      return {
+        value: nested.value,
+        added: [{ path: path.join("."), value: nested.value }, ...nested.added],
+        changed: true,
+      };
+    }
+    return scaffoldSchema(inner, currentValue, path);
+  }
+
+  if (schema instanceof z.ZodOptional) {
+    if (currentValue === undefined) {
+      return { value: currentValue, added: [], changed: false };
+    }
+    return scaffoldSchema(schema.unwrap(), currentValue, path);
+  }
+
+  if (schema instanceof z.ZodNullable) {
+    if (currentValue === null || currentValue === undefined) {
+      return { value: currentValue, added: [], changed: false };
+    }
+    return scaffoldSchema(schema.unwrap(), currentValue, path);
+  }
+
+  if (schema instanceof z.ZodArray) {
+    if (currentValue === undefined) {
+      return {
+        value: [],
+        added: [{ path: path.join("."), value: [] }],
+        changed: true,
+      };
+    }
+    return { value: currentValue, added: [], changed: false };
+  }
+
+  if (schema instanceof z.ZodEnum) {
+    return { value: currentValue, added: [], changed: false };
+  }
+
+  if (schema instanceof z.ZodObject) {
+    const source = isRecord(currentValue) ? currentValue : undefined;
+    const draft: Record<string, unknown> = source ? { ...source } : {};
+    const added: AddedField[] = [];
+    let changed = false;
+
+    const shape = schema.shape;
+    for (const [key, childSchema] of Object.entries(shape)) {
+      if (DEAD_FIELDS.has(key)) {
+        continue;
+      }
+
+      const childPath = [...path, key];
+      const childValue = source?.[key];
+      const childResult = scaffoldSchema(childSchema as z.ZodTypeAny, childValue, childPath);
+
+      if (!childResult.changed) {
+        continue;
+      }
+
+      draft[key] = childResult.value;
+      added.push(...childResult.added);
+      changed = true;
+    }
+
+    if (!source) {
+      if (!changed || isOptionalWithoutDefault(schema)) {
+        return { value: currentValue, added, changed: false };
+      }
+      return { value: draft, added, changed: true };
+    }
+
+    return { value: changed ? draft : currentValue, added, changed };
+  }
+
+  const unwrapped = unwrapSchema(schema);
+  if (
+    unwrapped instanceof z.ZodString ||
+    unwrapped instanceof z.ZodNumber ||
+    unwrapped instanceof z.ZodBoolean
+  ) {
+    return { value: currentValue, added: [], changed: false };
+  }
+
+  return { value: currentValue, added: [], changed: false };
+}
+
+function loadTargets(arg: string): string[] {
+  if (arg !== "--all") {
+    return [arg];
+  }
+
+  const specialistsDir = join(process.cwd(), "config", "specialists");
+  return readdirSync(specialistsDir)
+    .filter(file => file.endsWith(".specialist.json"))
+    .sort()
+    .map(file => join(specialistsDir, file));
+}
+
+function processFile(filePath: string): AddedField[] {
+  const raw = readFileSync(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+
+  if (!isRecord(parsed)) {
+    throw new Error(`Expected JSON object in ${filePath}`);
+  }
+
+  const result = scaffoldSchema(SpecialistSchema, parsed, []);
+  if (!result.changed) {
+    return [];
+  }
+
+  writeFileSync(filePath, `${JSON.stringify(result.value, null, 2)}\n`, "utf8");
+  return result.added;
+}
+
+function run(): void {
+  const targetArg = process.argv[2];
+  if (!targetArg) {
+    printUsage();
+    process.exit(64);
+  }
+
+  const targets = loadTargets(targetArg);
+  if (targets.length === 0) {
+    console.log("No specialist files found.");
+    return;
+  }
+
+  for (const filePath of targets) {
+    const addedFields = processFile(filePath);
+    if (addedFields.length === 0) {
+      continue;
+    }
+
+    for (const field of addedFields) {
+      console.log(`${filePath}: ${field.path} = ${formatValue(field.value)}`);
+    }
+  }
+}
+
+run();

package/.xtrm/skills/default/specialists-creator/scripts/validate-specialist.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { parseSpecialist } from "../../../src/specialist/schema.ts";
+import { parseSpecialist } from "../../../../src/specialist/schema.ts";
 
 function printUsage(): void {
   console.error("Usage: bun skills/specialist-author/scripts/validate-specialist.ts <path-to.specialist.yaml>");