v0.16.1

Fixed

• MCP setup records the running Node directory and absolute terminal PATH entries so desktop clients can find NVM-managed node and npx, including when SuperSkill was installed globally with Bun.
• Setup and upgrade repair missing PATH values in existing default JSON, OpenCode array and Codex TOML launchers while preserving vault paths, custom environment values, pinned launchers and unrelated client settings.

Upgrade notes

• Update SuperSkill, run superskill setup or superskill upgrade from a terminal where Node and npx work, then restart the AI client. Bun installation still requires Node and npm; its optional postinstall guidance may remain blocked.
• Explicit custom PATH values remain unchanged. If the Node installation was moved or removed, use setup with --force for the intended client to regenerate its environment.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.16.0...v0.16.1

v0.16.0

Added

• Shared atomic-rule scope: eight language-independent security, logging, testing, audit and financial-integrity controls, referenced by adapters across all eight supported languages. Retrieval follows verified shared references one hop, deduplicates them and respects the same token budget. The catalog contains 2,257 atomic rules.
• Lazy project-domain routing from jailed context.md frontmatter (routing.domains). Banking guidance loads for explicit banking work or an applicable banking project; ordinary ecommerce, accounting and unrelated documentation work do not automatically load banking methodology.
• Task-routed comment-discipline, production-logging and banking packs, plus a compact universal safety/comment policy reserved even at the minimum activation budget.
• Host-owned MCP tool allowlists (SUPERSKILL_MCP_ALLOWED_TOOLS) and skill bundle pins (SUPERSKILL_SKILL_PINS, SUPERSKILL_REQUIRE_SKILL_PINS). Tool policy is enforced before dispatch and at indirect resource/prompt boundaries.
• A restricted retrieval/routing Docker profile and launcher in the repository checkout: digest-pinned base, read-only data mounts, no network egress, non-root execution, dropped capabilities, no-new-privileges and bounded resources. CI and release workflows run real kernel/MCP isolation smoke tests.
• An external metadata-only audit supervisor for the restricted launcher. Exclusive writer locks, validated existing history, file/directory sync, bounded protocol framing and fail-closed forwarding protect evidence without collecting request or response payloads.

Changed

• Skill activation reports delivered, partial, missing, blocked, fallback or error, with per-skill delivery and trust metadata. Missing specialists are disclosed rather than silently downloaded; zero delivered skills for a selected/requested set no longer report success.
• Automatic graph task history uses process-keyed opaque labels by default, including minimization of legacy intents in the active graph on activation. SUPERSKILL_RETAIN_TASK_TEXT=1 explicitly enables screened text retention; authored memories and external backups are not silently deleted.
• Source-backed principles replace unsupported absolutes with applicable, reviewable guidance. Sixteen held principles were independently sourced and restored; all 25 principles have source metadata. Language-specific logging and documentation rules were revised and independently verified, including removal of blanket comment requirements where no project contract requires them.
• Removed decorative/step-by-step production comments and redundant installer narratives while preserving meaningful contracts, safety rationale, tooling directives and licenses.

Security

• Activation and direct skill/support-file inspection share trust checks. Non-catalog bundles undergo bounded whole-directory scans, file inventory/hash comparison and optional host-pin enforcement; modified, missing, additional or unsafe files are refused. Local manifests and bundled catalog entries are not presented as external attestations or script-execution authorization.
• Prompt-injection screening normalizes tested Unicode/spacing variants and detects the reproduced authority-escalation wording. Scanning remains heuristic; the restricted runtime enforces permissions outside the model.
• MCP exception responses and hardened diagnostics use fixed messages and allowlisted event/code fields. Secret findings no longer include source snippets; quoted credentials, credential URLs and Basic authentication detection were strengthened. Evidence input is scanned before truncation.
• The restricted launcher refuses unsafe mount arguments, remote Docker endpoints, unapproved image pulls, unsafe audit locations and corrupted/partial audit history. Audit failure stops forwarding; arbitrary child diagnostics are withheld. Vault mutations and remote installation are deliberately unavailable in this profile.

Upgrade notes

• Consumers should inspect activation status, delivery records and isError rather than treating a successful transport call as complete specialist coverage. Public error wording is intentionally less revealing.
• Restart updated MCP processes to load the new behavior. The version change refreshes the indexed catalog; deliberately pinned installations remain pinned.
• The restricted deployment assets are used from a repository checkout; see docs/restricted-runtime.md. Host/model permissions, storage retention and institutional compliance remain deployment responsibilities. This release does not claim a transactional banking writer or zero unknown vulnerabilities.
• npm publication remains manual. The known upstream sprintf-js advisory in the unused YAML CLI dependency chain remains documented; no incompatible dependency downgrade or advisory suppression was applied.

Verification

• The integrated suite passed 4,037 tests across 228 files with unchanged coverage thresholds. The script suite, rule schemas, native-skill authoring, package boundaries, grammar integrity and version parity are release gates.
• Independent reviewers compiled the 24 revised Bad/Good snippets without skips and exercised targeted behavior; principle verification is source/applicability review, not a claim of measured model efficacy. The catalog-wide schema check retains 18 pre-existing compile-exemption warnings.
• Live restricted-runtime tests prove eight kernel checks and real MCP denial, private routing-state, payload-free audit and audit-failure behavior using synthetic fixtures.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.15.1...v0.16.0

v0.15.1

Fixed

• Native CLI skill validation works in clean, unmapped checkouts without creating a vault project mapping. Mapped workspace roots and all relative-path, symlink, metadata, and required-reference checks remain intact. Added real built-CLI regressions for valid input and escaping references.
• Native authoring-gate failures preserve structured stdout diagnostics alongside stderr warnings, so a SQLite experimental warning cannot hide the rejection reason.

Release notes

• Includes the skill delivery, native validation, resource paging, project-safety, and recovery improvements from 0.15.0; see the full changelog. The first tag's clean-checkout CI failure was corrected without rewriting v0.15.0; npm publication remains manual.
• Release checks pass 3,908 tests in 219 files and 44 offline script tests, with unchanged coverage thresholds. The shipped-skill gate also passes with a fresh, unmapped home and no vault mapping created.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.15.0...v0.15.1

v0.14.0

Added

• Obsidian-native visualization: graph viz (shorthand superskill viz, MCP knowledge_viz) writes four Mermaid architecture notes to projects/<slug>/architecture/ (high-level-architecture, low-level-architecture, data-model-erd, dataflow) and generated code notes to projects/<slug>/code/<repo-relative path>.md — frontmatter, symbol list, [[wikilink]] imports/imported-by, and the full source in a fenced code block; --open deep-links Obsidian to the project context.
• Session notes emit [[wikilinks]] to the project context and to code notes for the files touched.
• Knowledge index normalizes [[...]] related values and .ts wikilink targets.
• Project dashboard note: graph viz writes projects/<slug>/index.md with hub links, scoped search/graph hints, the latest decisions/learnings/sessions, and a pointer to the code notes.
• Bases views file: graph viz writes projects/<slug>/views.base with live table views (Decisions, Learnings, Sessions, Tasks, All notes) scoped with file.inFolder(...) — no global Obsidian config is touched, and deleting the marker line keeps manual edits.
• graph viz --scope-graph (shorthand superskill viz --scope-graph) writes path:projects/<slug> into the vault's .obsidian/graph.json so Obsidian's graph view opens scoped to the project.

Changed

• Documentation restructured: the usage manual moved from the README into docs/ guides with a docs index; the README is now a hub.
• Code notes are indexed as metadata + edges only — source text does not enter search. Code notes are regenerated on every run; hand-edited architecture notes are preserved.
• Mermaid diagrams render at natural size (useMaxWidth: false) — large diagrams scroll instead of shrinking.
• graph viz --open lands on the project dashboard when there is no context.md (context → dashboard → architecture note).

Removed

• The HTML visualization stack (knowledge-graph.html, architecture-diagrams.html, knowledge-graph.canvas, and all CDN/HTML output), the qa CLI command, the qa_viz MCP tool, and the Chrome/playwright QA harness.

Fixed

• graph viz --open reports the vault path instead of failing silently when Obsidian cannot be launched.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.13.0...v0.14.0

v0.13.0

Added

• Autonomous legacy repair at MCP server start: managed launchers (JSON + TOML), owned legacy obsidian-mcp/obsidian-kb aliases, and instruction blocks — including unmarked legacy OpenCode/Cursor files — are reconciled and upgraded to the current format without a manual setup run. superskill upgrade performs the same reconciliation on demand, with --dry-run and --json.
• setup --check reports configuration drift read-only, and setup/upgrade dry runs now report what would actually change.
• Session coordination hardening: exclusive TTL'd workspace leases (allow_shared for co-tenants), heartbeat file-lease refresh with conflict reporting, expired sessions with pid/host liveness, listInterrupted (surfaced by resume), and worktree cleanup gated on completion age and live pids.
• Incremental knowledge index: a per-file files table with user_version migration means only changed notes are re-parsed; removeVaultFileFromIndex keeps prune/move/delete in sync; extract/capture write through the index and validate item types.
• Search recall: KnowledgeIndex.search does AND-first retrieval with an OR fallback and recency-decayed ranking; graph_traverse resolve accepts files and pre-filters natural-language vault queries.
• MCP output bounding: compact JSON by default (SUPERSKILL_PRETTY=1 for pretty), a global SUPERSKILL_MAX_RESPONSE_BYTES cap (default 64 KB) with explicit truncation markers, read.max_bytes, full-mode project_context.max_tokens, and limit on list actions (default 50, cap 500, negatives clamped).
• Security: fail-closed skill installs for unknown/warn audits with an explicit allow_unaudited/--allow-unaudited override, audit provenance in skill list/skill status, extended secret patterns (OpenAI, Anthropic, Google, AWS secret keys, Slack webhooks, generic tokens), whole-skill-directory prompt-injection scans, a local vault write audit trail, 0700/0600 telemetry permissions, trust-on-first-use Maven jar hashing, and pinned CDN assets with SRI (no external font requests).
• Doctor health checks: version parity (package vs plugin/marketplace), managed-launcher staleness, config backup residue, stale graph/session/cleanup locks, session registry and knowledge-index schema health, and a real worktree-cache probe.
• CI version-parity gate (npm run check:versions).
• Rules: stem-variant termsMatch matching (e.g. cache ↔ caching) across router, principles, and traverse; phase inference scores the earliest matched keyword instead of the first matching group; loader warns on id/filename mismatches and content resolution falls back to the parsed index.

Changed

• MCP tool responses are compact JSON and bounded; error payloads stay uncapped.
• write validates its mode and snapshots existing content before any replacement, not just explicit overwrite.
• Session registry operations never hold the registry lock across worktree cleanup; stale locks (registry, cleanup, graph) are recovered when their owning pid is dead, and a live pid is never stolen.
• Prune validates retention values (negative/NaN rejected), honors learning/brainstorm/ADR retention, computes oldestFile, and keeps the knowledge index consistent on archive/delete.
• Setup writes are atomic (temp file + revalidation + rename) and ownership-gated: foreign MCP entries are preserved and reported; instruction rewrites are scoped to managed markers so user content survives.
• Telemetry, knowledge_rebuild, and qa_viz annotations/rate limits corrected; list tools paginate via limit.
• graph cross-project help text now states it is project-jailed by design.

Fixed

• Router files hints no longer flood selection with language-wide glob matches; keyword evidence outranks glob-only candidates and ties break by keyword/symbol hit counts.
• session complete persists the session note using the resolved project when project is omitted (MCP clients no longer lose the memory loop).
• Knowledge index writes no longer trigger a full project rebuild on the next search; .stamp state migrates to the per-file table.
• Traverse cache is sectioned (code/rules/vault) and written atomically with unique temp files; symbol spans detect stale files instead of returning wrong line ranges.
• Corrupt graph.json is quarantined (graph.json.corrupt-<ts>) instead of permanently bricking mutations; stale graph locks are recovered by pid liveness.
• resume reports interrupted sessions; onboard counts installed skills; link rejects unsafe wikilink targets; snapshot dead branch removed; watchdog --count rejects NaN.
• Doctor's worktree-cache check is a real probe instead of a hard-coded ok.

Removed

• The preuninstall lifecycle script (npm ≥ 7 never runs uninstall scripts). Use superskill teardown to remove MCP entries, instructions, slash commands, and the shared skill.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.12.0...v0.13.0

v0.12.0

Changed

• Published package no longer ships source maps or .d.ts files (files exclusions) — smaller tarball; local builds keep both.
• Tree-sitter grammar wasms are vendored into dist/lib/codegraph/grammars/ at build time from the tree-sitter-wasms devDependency (sha256-verified against MANIFEST.json); tree-sitter-wasms moved from dependencies to devDependencies, removing ~49 MB from default installs with no language coverage change.
• playwright-core moved from dependencies to devDependencies: Chrome QA/viz is now opt-in (npm install playwright-core). QA commands fail with install guidance when it is missing, and doctor reports QA browser availability.
• doctor validates the rules catalog with bounded-concurrency reads (compile checks stay sequential to avoid toolchain races) and gains --fast to skip catalog validation and toolchain probes.
• doctor caches catalog validation keyed by a fingerprint of the rules tree (~/.superskill/cache/rules-validation.json); warm runs skip re-parsing ~2,200 files and report the cached age. The explicit validate CLI still runs fresh.
• project_context now derives bounded open threads (top 3 of blocked / partially_completed, deduped, from the five most recent sessions) and the MCP context prompt renders them — parked work recorded at session close is visible at session start, with no separate backlog file to maintain.

Removed

• The deprecated todo command layer: todo list|add|complete CLI aliases, todos.md retention in prune (--todos retention flag), and the todo frontmatter type. task remains the single vault task surface.
• Committed campaign artifacts: results.txt, validator.json, and workstreams/{plan,state}.json; rules-campaign working state is now gitignored and workstreams/STATUS.md moved to docs/authoring/rules-campaign-status.md.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.11.2...v0.12.0

v0.11.2

Fixed

• Repo identity for local-path remotes (file://, absolute/relative paths): the identity now follows the chain to the source repo's own remote (or its git dir), so local clones share one cache namespace instead of each getting a unique snowflake namespace. Legacy per-path namespaces are renamed into the shared identity on the next worktree bootstrap (session or worktree-create) or worktree activate, preserving cached content.
• Per-worktree cache dirs (cargo-build/<worktreeKey>) whose worktree path no longer exists are flagged as orphans and promoted from consent to auto tier in worktree gc/hygiene, so age-based reclamation actually reaches them. Worktrees register liveness markers under <repoHash>/.worktrees/ via bootstrap and worktree activate.
• SCCACHE_CACHE_SIZE no longer hardcodes 20G (2x the sccache default); it now defaults to 10G and can be overridden with SUPERSKILL_SCCACHE_CACHE_SIZE.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.11.1...v0.11.2

v0.11.1

Fixed

• OpenCode host adapter: worktree activate now writes an OpenCode V2 plugin definition (export default { id, setup } registering the shell create.before hook) instead of the V1 shell.env function form, which OpenCode 2.x rejects with "Plugin must export a default definition with an id and an effect or setup function". The removed Bun $ helper is replaced with node:child_process; the CLI call, JSON merge, and silent-on-failure behavior are unchanged, and a V1 server() fallback keeps OpenCode 1.18.29+ working.
• Re-run superskill worktree activate in a repo to regenerate the plugin; the previous file is backed up as <plugin>.bak.superskill. Adapter tests now import the generated module and run the shell hook end-to-end so format drift fails CI.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.11.0...v0.11.1

SuperSkill 0.11.0

Added

• Session-start orchestration with workspace-aware routing, explicit work phases, first-use graph initialization, and release-aware catalog refresh that preserves learned state.
• Completed-session worktree cleanup after verified integration into local main, with active/dirty/locked checkout protection and archival of local graph metadata.
• Local integration guidance for related dependent agent changes before authorized batch pushes.
• Managed MCP launchers follow npm's latest tag on new server starts; managed skill and recognized Markdown instructions refresh at startup. Pinned/custom launchers remain unchanged.
• Generic project architecture and knowledge views with directory/file/symbol traversal and bounded source excerpts.

Fixed

• Cooperative atomic vault updates, concurrent ticket dependency allocation, graph/session ownership locks, and fail-closed session registry validation.
• File- and phase-aware skill routing, bounded compact diagnostics, and isolated session learning.
• Nested Codex trace activity and structured failure detection; documented harness setup contracts and safe legacy migrations.
• Project and installer path confinement, secret rejection/redaction, knowledge-index initialization and cache freshness.

Requirements

• Node.js 22.16+ on the 22.x line, or 24+, with SQLite FTS5. Older runtimes fail with an actionable upgrade message.
• Existing installations should run setup once and restart their MCP server to migrate managed launchers. Future latest-tag updates take effect on subsequent starts, not during active sessions.

Verification

• 2,219 tests passed on macOS with Node.js 22.16.0; coverage thresholds, build and type checks passed.
• 42 version-specific checks and the exact 0.11.0 packaged MCP smoke passed.
• Isolated npm-registry smoke confirmed next-launch updates using the same cache.

Upgrade

npm install -g superskill@0.11.0
superskill setup

Restart MCP servers and begin a new harness session. Managed launchers then follow the npm latest tag on future starts; deliberate version pins and custom launchers are preserved.

v0.10.0

Added

• Deep contracts adopted from community skills, alongside the pstack-derived catalog/principles/*: optimizer/adhd (action-first replies, banned preamble/recap/closer patterns, ≤5 grouped lists, evidence labels, auto-clarity escapes, intensity levels) and pipeline/lazy-build (reuse → stdlib → platform → minimal ladder, root-cause rule, hard safety floors, ponytail: tradeoff markers), referenced from the always-on pipeline/norms.

Fixed

• Router: triggered pipeline skills (plan, tdd, verify, lazy-build) now load in every phase; previously the pack was never allowed during task matching, so their triggers could not fire.

---

Install: npm install -g superskill or via Claude Code /plugin install superskill

Full Changelog: v0.9.0...v0.10.0