xtrm-tools 0.7.13 → 0.7.15

package/.xtrm/skills/default/releasing/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: releasing
 description: >-
-  Cut a release end-to-end via the changelog-keeper specialist. Use when the
-  operator wants to publish a new tag (vX.Y.Z) — drafts CHANGELOG section
-  from xt reports, bumps package.json, rebuilds dist, commits, tags, pushes,
-  optional GH release. Strict scope: only CHANGELOG.md + package.json + dist/.
-version: 1.0.0
+  Cut a release with the canonical xt release prepare/publish flow. Use when the
+  operator wants to publish a new tag (vX.Y.Z). Prepare drafts CHANGELOG from xt
+  reports and performs deterministic release-file mutations; publish creates the
+  annotated tag, pushes commits/tags, and can create a GitHub release.
+version: 1.2.0
 ---
 
 # releasing
 
-One-step release publication via specialist delegation.
+Canonical release publication via `xt release prepare` and `xt release publish`.
 
 ## When to use
 
@@ -18,73 +18,77 @@ The operator wants to cut a release. They say "release it", "ship vX.Y.Z", "cut
 
 ## How
 
-1. Determine the target version. Default is patch bump from the most recent semver tag. Operator may specify `--minor`, `--major`, or an explicit version.
+1. Determine target version. Default is patch bump from most recent semver tag. Operator may specify `--minor`, `--major`, or explicit version.
 
-2. Determine the tag range. Default is `<latest-tag>..HEAD`. For backfills, operator names `--from` / `--to` explicitly.
+2. Determine tag range. Default is `<latest-tag>..HEAD`. For backfills, operator names `--from` / `--to` explicitly.
 
-3. Create a release bead. Template:
-
-   ```
-   PROBLEM: Cut release vX.Y.Z covering <prev-tag>..HEAD.
-   SUCCESS: CHANGELOG.md updated with new section above prior release; package.json bumped; dist rebuilt; commit `release: vX.Y.Z` pushed with tag.
-   SCOPE: CHANGELOG.md, package.json, dist/. Synthesis input: xt reports under .xtrm/reports/ dated within <prev-tag-date>..HEAD.
-   NON_GOALS: No source/docs/config edits. No retroactive changes to prior release sections.
-   CONSTRAINTS: Keep-a-Changelog v1.0.0 format. One-line bullets. Default bucket Changed. Deprecated only for explicit sunsets.
-   VALIDATION: git diff --stat HEAD~1 HEAD shows only CHANGELOG.md, package.json, dist/.
-   OUTPUT: Final report with VERSION, COMMIT, TAG, PUSHED status.
-   GH_RELEASE: <true|false>   # whether to also `gh release create`
-   ```
-
-4. Dispatch the specialist:
+3. Prepare release files:
 
    ```bash
-   sp run changelog-keeper --bead <bead-id> --background
+   xt release prepare --patch
+   # or: xt release prepare --minor --from <tag> --to HEAD
    ```
 
-   No worktree (release work is on the active branch). No reviewer chain — the verification is the diff check below.
+   `prepare` is the canonical path. It builds the xt report bundle, calls the specialists changelog drafting script (`sp script changelog-keeper`), updates release files, rebuilds dist, and enforces the release scope guard.
+
+   Current blocker: until specialists issue `unitAI-dnmcg` lands, `prepare` can fail with `interactive specialists are not allowed` because the changelog drafting specialist is not yet script-compatible. If that happens, do a manual prepare using the same scope rules and then continue with `xt release publish`.
 
-5. **Verify the diff after the specialist completes.** This is the critical operator gate.
+4. Verify release diff before publishing.
 
    ```bash
    git diff --stat HEAD~1 HEAD
+   git status --short
    ```
 
-   The output MUST show ONLY:
+   Release diff must be limited to release artifacts such as:
    - `CHANGELOG.md`
-   - `package.json`
-   - `dist/index.js`, `dist/lib.js`, `dist/types/**`
+   - package manifests / lockfile for version sync
+   - generated `cli/dist/**` or `dist/**`
 
-   If ANY other file appears (`src/**`, `docs/**` other than CHANGELOG, `config/**`, `tests/**`, `README.md`, etc.), the specialist violated scope. Action:
+5. Publish:
 
    ```bash
-   git push --delete origin vX.Y.Z   # delete remote tag
-   git tag -d vX.Y.Z                 # delete local tag
-   git reset --hard HEAD~1           # discard the release commit
-   git push --force-with-lease       # only if push already happened
+   xt release publish
+   # optional GitHub release:
+   xt release publish --gh-release
    ```
 
-   Then file a bug bead naming the offending paths and revisit the specialist's mandatory rule.
+   `publish` creates the annotated tag for the current package version, pushes commits and tags, and optionally creates the GitHub release.
 
-6. If the diff check passes, the release is shipped. Confirm:
+6. Confirm:
 
    ```bash
-   git tag --list 'v*' | tail -3     # new tag present
-   git log --oneline -1              # message starts with "release: vX.Y.Z"
+   git tag --list 'v*' | tail -3
+   git log --oneline -1
+   git status --short --branch
    ```
 
 ## Why this design
 
-- Specialist does the work itself (Read xt reports, Edit files, Bash for build/commit/tag/push). No CLI plumbing, no template substitution, no JSON output schema, no two-phase prepare/publish gate.
-- Mandatory rule `changelog-keeper-scope` enforces the edit whitelist at the specialist level.
-- Operator gate is the single `git diff --stat HEAD~1 HEAD` check after the specialist finishes. If it shows only whitelisted paths, the release is correct.
-- xt reports are the synthesis input, not git log + bd query. Reports are pre-curated, signal-rich, written in user-facing language.
+- `xt` owns deterministic release mutation: changelog insertion, version bump, build, scope guard, commit/tag/push.
+- The specialist owns only changelog drafting from xt reports through a script-compatible, READ_ONLY surface.
+- xt reports are synthesis input, not raw git log + bd query. Reports are pre-curated, signal-rich, written in user-facing language.
+- `xt release publish` is intentionally separate so operators can inspect prepared release files before pushing the tag.
+
+## Manual fallback while unitAI-dnmcg is open
+
+If `xt release prepare` fails on the changelog script compatibility guard:
+
+1. Draft the CHANGELOG section manually from `.xtrm/reports/` and recent commits.
+2. Bump package versions and lockfile.
+3. Run `npm run build`.
+4. Commit with `release: vX.Y.Z`.
+5. Run `xt release publish`.
+
+Do not broaden the release diff beyond release artifacts.
 
 ## Parallel sessions
 
-Each orchestrator runs this skill in its own session. The specialist commits + tags + pushes atomically. If two sessions try to release the same version, whichever pushes first wins; the other sees a remote tag conflict on push and aborts with a clean error. Operator picks the next version and retries.
+Each orchestrator runs this skill in its own session. Specialist commits + tags + pushes atomically. If two sessions try same version, first push wins; second sees remote tag conflict and aborts cleanly. Operator picks next version and retries.
 
 ## Don't
 
-- Don't manually `sp release prepare`/`publish` — those CLIs are removed in v3.X.Y (TBD).
-- Don't edit CHANGELOG.md outside the specialist run — manual edits leak into the next release's diff and break scope verification.
-- Don't pre-stage files. The specialist stages exactly what it commits.
+- Don't call `sp release prepare` / `sp release publish` as the canonical path. They are deprecated aliases in specialists.
+- Don't bypass `xt release publish` for tag/push unless the command itself is broken.
+- Don't broaden release diffs with source/docs/config changes. File a separate bead for non-release work.
+- Don't pre-stage unrelated files. The release scope guard should see a clean tree except allowed release artifacts.

package/.xtrm/skills/default/releasing/scripts/xt-reports.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+
+import { buildReportBundle, listXtReports } from '../../../../../cli/src/core/xt-reports.ts';
+
+async function main() {
+  const since = process.argv[2];
+  const to = process.argv[3] ?? 'HEAD';
+  const capArg = process.argv[4];
+  const capBytes = capArg ? Number(capArg) : 50_000;
+
+  if (!since) throw new Error('Usage: xt-reports.ts <since> [to] [capBytes]');
+
+  const reports = listXtReports({ since, to, capBytes });
+  const bundle = buildReportBundle(reports, capBytes);
+  console.log(bundle.output);
+}
+
+if (import.meta.main) await main();

package/.xtrm/skills/default/session-close-report/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: session-close-report
 description: |
-  Generate a structured technical handoff report at session close.
-  You run `xt report generate` to get the data skeleton, then fill every
-  <!-- FILL --> section from your own session context. The result is the
-  definitive handoff contract for the next agent.
+  Generate or update the structured technical handoff report at session close.
+  Prefer one same-day SSOT report: update the latest report for today when it
+  exists, otherwise run `xt report generate`, then fill every `<!-- FILL -->`
+  section from orchestrator context.
 ---
 
 # session-close-report
@@ -15,9 +15,43 @@ Invoke this skill at the end of a productive session — after issues are closed
 code is committed, but before final push. It produces the handoff report that
 the next agent reads to start cold without losing context.
 
+## Report identity rule
+
+Prefer a single same-day SSOT handoff report.
+
+Before generating anything, check existing reports:
+
+```bash
+xt report list
+ls -t .xtrm/reports/*.md 2>/dev/null | head
+```
+
+Decision:
+- If a report for today already exists, update the latest same-day report.
+- If multiple orchestrators ran today, merge your context into that same report;
+  do not create a competing handoff unless the operator explicitly asks for a
+  separate report.
+- If no suitable same-day report exists, run `xt report generate` and fill the
+  new skeleton.
+
+When updating an existing report, preserve prior orchestrator content. Append,
+merge, or revise sections so the file remains one coherent handoff package — do
+not overwrite earlier waves, issue context, problems, or decisions unless they
+are factually superseded.
+
 ## Workflow
 
-### 1. Generate the skeleton
+### 1. Select report: update existing or generate new
+
+For same-day update:
+
+```bash
+REPORT=$(ls -t .xtrm/reports/$(date +%F)-*.md 2>/dev/null | head -1)
+```
+
+If `$REPORT` is non-empty, read and update it.
+
+If no same-day report exists:
 
 ```bash
 xt report generate
@@ -26,28 +60,42 @@ xt report generate
 This collects data from git log, bd, .specialists/jobs/ and writes a skeleton
 to `.xtrm/reports/<date>-<hash>.md` with YAML frontmatter and pre-filled tables.
 
-### 2. Read the skeleton
+### 2. Read the target report
+
+Read the chosen report completely enough to understand existing content.
 
-Read the generated file. It has `<!-- FILL -->` markers in every section that
-needs your input.
+Skeleton reports have `<!-- FILL -->` markers in every section that needs your
+input. Existing same-day reports may already be partially filled; update those
+sections with the new session context and remove any now-stale placeholders.
 
-### 3. Fill every section from your context
+### 3. Fill or update every section from your context
 
 You are the orchestrator. You have the full session context. The CLI only
 collected raw data — you provide the meaning.
 
+When updating an existing same-day report:
+- Add new waves, issues, commits, problems, and decisions without duplicating
+  existing rows.
+- Update summary/frontmatter counts to cover the whole same-day handoff, not
+  just your sub-session.
+- Reconcile stale “open issues” entries if you closed them later in the day.
+- Keep one chronological/coherent narrative instead of separate mini-reports.
+
 **For each section, here is exactly what to write:**
 
 #### Summary
 One dense paragraph. What was accomplished, key decisions made, discoveries,
 outcomes. Technical prose — no filler, no "in this session we...". Lead with
-the most important result.
+the most important result. For same-day updates, summarize the whole day’s SSOT
+state, including earlier orchestrators and your additions.
 
 #### Issues Closed
 The skeleton has a flat table. Restructure it:
 - Group by category: bugs discovered, backlog items, cleanup/closures, features
 - If specialists were used, add Specialist and Wave columns
 - Expand terse close reasons into useful context
+- When updating an existing report, add newly closed issues and revise stale open
+  entries that are now closed
 
 #### Issues Filed
 Add every issue you created this session. The **Why** column is mandatory —
@@ -61,18 +109,22 @@ If specialists were dispatched:
 - Add a Problems sub-table for any failed/stalled dispatches
 - Update `specialist_dispatches` and `models_used` in frontmatter
 
-If no specialists were used, delete this section.
+If no specialists were used and the report has no prior specialist dispatches,
+delete this section. If prior dispatches exist, keep and extend them.
 
 #### Problems Encountered
 Every problem hit during the session. Root Cause and Resolution columns are
 mandatory. Include: bugs discovered, wrong approaches tried, blockers hit,
-tooling failures. If no problems, delete this section entirely.
+tooling failures. If no problems exist anywhere in the same-day report, delete
+this section entirely.
 
 #### Code Changes
 The skeleton lists files. Add narrative:
 - Explain key modifications (not every file — focus on the important ones)
 - Group logically if many changes (e.g., "CLI commands", "Hook changes")
 - Note architectural decisions embedded in the changes
+- For same-day updates, include changes from all orchestrators that contributed
+  to the final pushed stack
 
 #### Documentation Updates
 List doc changes, skill updates, memory saves, CHANGELOG entries.
@@ -84,6 +136,8 @@ This is the most valuable handoff section. For each open issue:
   blockers discovered, suggested approach, files to look at, gotchas.
 - Group into "Ready for next session" and "Backlog" subsections
 - Put the most actionable items first
+- If an issue listed earlier in the day was closed later, remove it from open
+  issues and move it to Issues Closed with closure context
 
 #### Memories Saved
 List all `bd remember` calls made this session. If the skeleton missed any,
@@ -96,36 +150,50 @@ Ordered list of 1-4 items with rationale for each. Based on:
 - Urgency of discovered issues
 - Blocked items about to unblock
 
+For same-day updates, make this the next priority from the final state of the
+whole day, not from an earlier partial state.
+
 ### 4. Update frontmatter
 
-Ensure all frontmatter counts are accurate after filling:
-- `issues_filed` — actual count
-- `specialist_dispatches` — actual count
-- `models_used` — list of models that did work this session
+Ensure all frontmatter counts are accurate after filling/updating:
+- `issues_filed` — actual count represented in the report
+- `specialist_dispatches` — actual count represented in the report
+- `models_used` — list of models that did work represented in the report
+- `issues_closed` — actual closed issue count represented in the report
+- `commits` — commit count represented in the report, if known
 
 ### 5. Commit the report
 
+Reports are versioned handoff artifacts and should be tracked.
+
 ```bash
 git add .xtrm/reports/
 git commit -m "session report: <date>"
 ```
 
+If you updated an existing same-day report after an earlier report commit, commit
+that update with the same message style or fold it into the current final commit
+before push.
+
 ## Quality bar
 
 The reference is `~/projects/specialists/.xtrm/reports/2026-03-30-orchestration-session.md`.
 Every report must match that level of detail. Specifically:
 
 - No empty `<!-- FILL -->` markers left in the final output
+- No duplicate same-day reports unless explicitly requested by the operator
 - Every closed issue has context, not just an ID
 - Every open issue has actionable handoff suggestions
 - Problems section captures root causes, not just symptoms
 - Summary is a dense technical paragraph, not a list of bullet points
+- Same-day updates preserve earlier orchestrator context while making the final
+  file read as one SSOT handoff package
 
 ## CLI commands
 
 | Command | Purpose |
 |---------|---------|
-| `xt report generate` | Collect data, write skeleton |
+| `xt report generate` | Collect data, write skeleton when no suitable report exists |
 | `xt report show [target]` | Display latest or specified report |
 | `xt report list` | List all reports with frontmatter summary |
 | `xt report diff <a> <b>` | Compare two reports |

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
 ---
 
@@ -13,6 +13,22 @@ synced_at: 236ca5e6
 
 > Source of truth: `src/specialist/schema.ts` | Runtime: `src/specialist/runner.ts`
 
+
+## Canonical References
+
+When a custom specialist needs a standard rule or skill, reference the canonical asset by name instead of copying its file into the repo. Runtime/package fallback resolves canonical mandatory rules and skills when no project-local override exists.
+
+Example:
+
+```json
+{
+  "mandatory_rules": { "template_sets": ["serena-cheatsheet"] },
+  "skills": { "paths": ["releasing"] }
+}
+```
+
+Only create project-local copies when intentionally changing canonical behavior. After setting references, run `sp config show <name> --resolved` to verify the resolved runtime surface.
+
 ---
 
 ## ACTION REQUIRED BEFORE ANYTHING ELSE
@@ -40,6 +56,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 +179,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 +190,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 +198,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 +209,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 +222,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 +271,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 +283,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 +473,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 +498,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 +574,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 +670,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 +772,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 +784,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 +793,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.