@softspark/ai-toolkit 4.23.1 → 4.24.1

package/CHANGELOG.md

@@ -7,6 +7,59 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.24.1 — a dead link reported itself as installed (2026-08-19)
+
+### Fixed
+
+- **`plugin install` treated a dangling symlink as an installed asset.** The guard
+  was `if path.exists() or path.is_symlink()`, and a link whose target is gone
+  satisfies the second half — so the installer printed `OK agent` / `OK skill`,
+  changed nothing, and left the user with a dead link and a green log. This is the
+  exact state a toolkit upgrade produces: `npm install -g @softspark/ai-toolkit`
+  replaces `app/` wholesale, so every `~/.claude` link into the old package points
+  at nothing, and re-running install could not repair it.
+
+  A dangling link is now dropped before the guard runs and relinked to the
+  resolved source, printing `Dangling agent link removed: <name>`. **Live links and
+  real files are untouched** — those are user content, and the merge-friendly
+  install model keeps them.
+
+  Surfaced while migrating a pack from `app/plugins/` to the v4.24.0 user root:
+  the upgrade broke both links and `plugin install` insisted everything was fine.
+
+### Added
+
+- **Two tests.** One builds the post-upgrade state (links pointing into a path
+  that no longer exists) and asserts install removes and relinks both; the other
+  pins the negative — a real file on the agent name and a live skill link survive
+  a reinstall untouched.
+
+## v4.24.0 — external packs stop dying on upgrade (2026-08-18)
+
+### Added
+
+- **`~/.softspark/ai-toolkit/plugins/` is a second pack root.** Until now
+  `plugin.py` scanned exactly one directory — `app/plugins/`, inside the npm
+  package — so the only way to add a pack from its own repository was to drop it
+  in there, where the next `npm install -g @softspark/ai-toolkit` deleted it along
+  with the rest of `app/`. External packs now live in the user-owned data dir and
+  survive every upgrade. `plugin list`, `install`, `update`, `remove` and `status`
+  all see both roots; `AI_TOOLKIT_HOME` moves the user root with the data dir.
+
+  A **core pack wins a name collision**, so an external directory cannot shadow
+  shipped behaviour. Each pack dict carries `_root` (`core` or `user`) — `_source`
+  was already taken as the hook-ownership marker.
+
+  The entry may be a directory or a **symlink**, which is what gives an external
+  pack a versioned update path: point it at an npm-installed package and
+  `npm install -g <pack>@latest` rewrites the target in place, with nothing to
+  re-link. Documented in `kb/reference/plugin-pack-conventions.md`
+  (*Where Packs Live*), including the per-scope registry caveat when one package
+  in a scope is public and another private.
+
+- **Three tests.** A pack in the user root is listed, installs with both its agent
+  and skill linked back into that root, and loses a name collision to a core pack.
+
 ## v4.23.1 — a pack could ship an agent nobody installed (2026-08-18)
 
 ### Fixed

package/README.md

@@ -6,18 +6,17 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1519%20passing-success)](tests/)
-
-## What's New in v4.23.1
-
-**v4.23.1** — a plugin pack that shipped its own agent never got it installed.
-`plugin install` resolved `includes.agents` against the toolkit's own
-`app/agents/`, printed `WARN agent not found`, and moved on — while the removal
-path already knew how to unlink a pack-owned agent, and skills had resolved from
-the pack directory all along. `validate.py` had the same blind spot for both
-agents and skills, so a self-contained pack was reported broken twice over.
-Agents now resolve from the pack first-class, core assets still win, and
-validation accepts either. Found by a downstream pack's post-release smoke test.
+[![Tests](https://img.shields.io/badge/tests-1524%20passing-success)](tests/)
+
+## What's New in v4.24.1
+
+**v4.24.1** — `plugin install` accepted a dead symlink as proof of installation.
+The guard asked `exists() or is_symlink()`, and a link with no target still
+answers yes to the second half, so the installer logged `OK` and repaired
+nothing — precisely the state a toolkit upgrade leaves, since replacing `app/`
+breaks every link into it. Dangling links are now dropped and relinked; real
+files and live links stay untouched. Pairs with v4.24.0's user-level pack root,
+which is what stops the breakage happening in the first place.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.23.1",
+  "version": "4.24.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/skills/documentation-standards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation-standards
-description: "KB conventions: YAML frontmatter, 8-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base."
+description: "KB conventions: YAML frontmatter, 10-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning/business/templates). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base."
 effort: medium
 user-invocable: false
 allowed-tools: Read
@@ -17,7 +17,7 @@ Every document in `kb/` MUST start with YAML frontmatter:
 ```yaml
 ---
 title: "Document Title"                    # REQUIRED — English, descriptive
-category: reference                        # REQUIRED — one of 5 valid categories
+category: reference                        # REQUIRED — one of the 10 valid categories
 service: ai-toolkit                        # REQUIRED — service identifier
 tags: [tag1, tag2, tag3]                   # REQUIRED — minimum 1, recommended 3+
 last_updated: "YYYY-MM-DD"                 # REQUIRED — ISO format
@@ -53,11 +53,21 @@ and never authoritative on its own.
 | `decisions` | `kb/decisions/` | Architecture decision records and design rationale | `adr-004-kb-migration.md` |
 | `runbooks` | `kb/runbooks/` | Procedures run against a live system, usually under pressure | `deployment.md`, `incident-response.md` |
 | `planning` | `kb/planning/` | Roadmaps, PRDs, work not yet done | `q3-roadmap.md` |
+| `business` | `kb/business/` | Domain model, requirements, use cases, user stories | `domain-model.md`, `user-stories.md` |
+| `templates` | `kb/templates/` | Reusable document templates | `adr-template.md`, `sop-template.md` |
 
 **Rule:** A document filed under one of the directories above MUST declare that
 category. The rule is scoped to those directories deliberately: `kb/history/`
-and similar are lifecycle locations rather than types, and a finished plan filed
-under `history/completed/` is still a `planning` document.
+and `kb/summaries/` are lifecycle and runtime locations rather than types, and a
+finished plan filed under `history/completed/` is still a `planning` document.
+
+**Templates carry placeholders on purpose.** A file under `templates/` exists to
+be copied, so a literal `YYYY-MM-DD` date and `[placeholder]` body text are
+correct there rather than defects. Every other convention still applies.
+
+This taxonomy lives in three places: ai-toolkit's `scripts/validate.py`,
+rag-mcp's `scripts/validate_kb_frontmatter.py`, and this document. They are one
+list, and a change belongs in all three.
 
 ## Naming Conventions
 

package/app/surface.json

@@ -230,12 +230,14 @@
   ],
   "kb_categories": [
     "best-practices",
+    "business",
     "decisions",
     "howto",
     "planning",
     "procedures",
     "reference",
     "runbooks",
+    "templates",
     "troubleshooting"
   ],
   "cli_commands": [

package/kb/reference/plugin-pack-conventions.md

@@ -3,9 +3,9 @@ title: "Plugin Pack Conventions"
 category: reference
 service: ai-toolkit
 tags: [plugins, plugin-packs, conventions, manifests, hooks, policy-packs]
-version: "1.1.0"
+version: "1.2.0"
 created: "2026-03-28"
-last_updated: "2026-07-14"
+last_updated: "2026-08-18"
 description: "Conventions for experimental ai-toolkit plugin packs, policy packs, hook packs, and plugin-creator scaffolding across Claude Code and Codex runtimes."
 ---
 
@@ -13,7 +13,46 @@ description: "Conventions for experimental ai-toolkit plugin packs, policy packs
 
 ## Purpose
 
-`ai-toolkit` includes experimental plugin packs under `app/plugins/` for Claude Code and optional global Codex layering. These internal pack manifests are distinct from the official uploadable Claude app plugin built by `ai-toolkit claude-app export`.
+`ai-toolkit` includes experimental plugin packs under `app/plugins/` for Claude Code and optional global Codex layering, and discovers external packs under `~/.softspark/ai-toolkit/plugins/` (see *Where Packs Live*). These internal pack manifests are distinct from the official uploadable Claude app plugin built by `ai-toolkit claude-app export`.
+
+## Where Packs Live
+
+| Root | Owner | Survives `npm install -g @softspark/ai-toolkit` | Use for |
+|------|-------|------------------------------------------------|---------|
+| `app/plugins/<pack>/` | this repository | no — the upgrade replaces `app/` wholesale | packs shipped with the toolkit (`memory-pack`, `enterprise-pack`) |
+| `~/.softspark/ai-toolkit/plugins/<pack>/` | the user | **yes** | external / private packs maintained in their own repository |
+
+Both roots are scanned by `plugin list`, `install`, `update`, `remove` and
+`status`. A **core pack wins a name collision**, so an external directory cannot
+shadow shipped behaviour. `AI_TOOLKIT_HOME` moves the user root along with the
+rest of the toolkit data dir, which is what the test suite uses.
+
+Before v4.24.0 there was only the first root, so the only way to add an external
+pack was to drop it inside the npm package — where the next toolkit upgrade
+deleted it. That is what the user root exists to end.
+
+### Installing an external pack
+
+The entry may be a directory **or a symlink**, which is what gives an external
+pack a versioned update path:
+
+```bash
+# Distributed as a package (private registry example)
+npm install -g @softspark/<pack> --registry=https://npm.pkg.github.com
+mkdir -p ~/.softspark/ai-toolkit/plugins
+ln -s "$(npm root -g)/@softspark/<pack>" ~/.softspark/ai-toolkit/plugins/<pack>
+ai-toolkit plugin install --editor claude <pack>
+
+# Update later: the symlink target is rewritten in place, nothing to re-link
+npm install -g @softspark/<pack>@latest --registry=https://npm.pkg.github.com
+```
+
+A plain `git clone` into the same directory works too; update it with `git pull`.
+
+> **Scope note:** `npm` resolves a registry per **scope**, not per package. If one
+> package in a scope lives on public npm and another on a private registry, the
+> private one needs `--registry=` on every command — a scope-wide
+> `npm config set @scope:registry` would misroute the public one.
 
 ## Pack Types
 

package/llms-full.txt

@@ -109,7 +109,7 @@
 - **design-engineering**: UI craftsmanship: animation rules, easing, micro-interactions, state polish. Triggers: animation, transition, ease-out, motion, micro-interaction, hover, loading state, UI polish.
 - **docker-devops**: Docker/K8s: Dockerfile, multi-stage, compose, manifests, Helm. Triggers: Docker, Dockerfile, container, Kubernetes, k8s, compose, Helm, pod.
 - **docs**: Generates/updates README, API docs, architecture notes. Triggers: docs, README, API docs, architecture note, documentation.
-- **documentation-standards**: KB conventions: YAML frontmatter, 8-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.
+- **documentation-standards**: KB conventions: YAML frontmatter, 10-category taxonomy (reference/howto/procedures/troubleshooting/best-practices/decisions/runbooks/planning/business/templates). Triggers: kb/, SOP, runbook, howto, frontmatter, knowledge base.
 - **ecommerce-patterns**: E-commerce: cart, checkout, payments (Stripe/Adyen), order state, inventory, promos, tax. Triggers: cart, checkout, SKU, payment, Stripe, Shopify, Medusa, Magento, coupon, refund.
 - **evaluate**: Evaluates RAG retrieval and LLM-as-judge metrics (faithfulness, relevancy, context precision). Triggers: measure RAG quality, knowledge gap, RAG eval, golden dataset.
 - **evolve**: Analyzes agent/skill failures, drafts prompt/permission fixes. Triggers: improve agent, refine skill, system prompt, optimize agent.
@@ -14349,9 +14349,9 @@ title: "Plugin Pack Conventions"
 category: reference
 service: ai-toolkit
 tags: [plugins, plugin-packs, conventions, manifests, hooks, policy-packs]
-version: "1.1.0"
+version: "1.2.0"
 created: "2026-03-28"
-last_updated: "2026-07-14"
+last_updated: "2026-08-18"
 description: "Conventions for experimental ai-toolkit plugin packs, policy packs, hook packs, and plugin-creator scaffolding across Claude Code and Codex runtimes."
 ---
 
@@ -14359,7 +14359,46 @@ description: "Conventions for experimental ai-toolkit plugin packs, policy packs
 
 ## Purpose
 
-`ai-toolkit` includes experimental plugin packs under `app/plugins/` for Claude Code and optional global Codex layering. These internal pack manifests are distinct from the official uploadable Claude app plugin built by `ai-toolkit claude-app export`.
+`ai-toolkit` includes experimental plugin packs under `app/plugins/` for Claude Code and optional global Codex layering, and discovers external packs under `~/.softspark/ai-toolkit/plugins/` (see *Where Packs Live*). These internal pack manifests are distinct from the official uploadable Claude app plugin built by `ai-toolkit claude-app export`.
+
+## Where Packs Live
+
+| Root | Owner | Survives `npm install -g @softspark/ai-toolkit` | Use for |
+|------|-------|------------------------------------------------|---------|
+| `app/plugins/<pack>/` | this repository | no — the upgrade replaces `app/` wholesale | packs shipped with the toolkit (`memory-pack`, `enterprise-pack`) |
+| `~/.softspark/ai-toolkit/plugins/<pack>/` | the user | **yes** | external / private packs maintained in their own repository |
+
+Both roots are scanned by `plugin list`, `install`, `update`, `remove` and
+`status`. A **core pack wins a name collision**, so an external directory cannot
+shadow shipped behaviour. `AI_TOOLKIT_HOME` moves the user root along with the
+rest of the toolkit data dir, which is what the test suite uses.
+
+Before v4.24.0 there was only the first root, so the only way to add an external
+pack was to drop it inside the npm package — where the next toolkit upgrade
+deleted it. That is what the user root exists to end.
+
+### Installing an external pack
+
+The entry may be a directory **or a symlink**, which is what gives an external
+pack a versioned update path:
+
+```bash
+# Distributed as a package (private registry example)
+npm install -g @softspark/<pack> --registry=https://npm.pkg.github.com
+mkdir -p ~/.softspark/ai-toolkit/plugins
+ln -s "$(npm root -g)/@softspark/<pack>" ~/.softspark/ai-toolkit/plugins/<pack>
+ai-toolkit plugin install --editor claude <pack>
+
+# Update later: the symlink target is rewritten in place, nothing to re-link
+npm install -g @softspark/<pack>@latest --registry=https://npm.pkg.github.com
+```
+
+A plain `git clone` into the same directory works too; update it with `git pull`.
+
+> **Scope note:** `npm` resolves a registry per **scope**, not per package. If one
+> package in a scope lives on public npm and another on a private registry, the
+> private one needs `--registry=` on every command — a scope-wide
+> `npm config set @scope:registry` would misroute the public one.
 
 ## Pack Types
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.23.1",
+  "version": "4.24.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.23.1",
+  "version": "4.24.1",
   "description": "AI coding toolkit: 109 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/plugin.py

@@ -60,6 +60,12 @@ from plugin_schema import resolve_hook_event
 
 
 PLUGINS_DIR = app_dir / "plugins"
+# External packs live outside the npm package so a toolkit upgrade cannot delete
+# them: `npm install -g @softspark/ai-toolkit` replaces app/ wholesale, taking any
+# third-party pack dropped in there with it. TOOLKIT_DATA_DIR is user-owned and
+# survives. The entry may be a directory or a symlink (e.g. to an npm-installed
+# pack), which is how an external pack gets a versioned update path.
+USER_PLUGINS_DIR = TOOLKIT_DATA_DIR / "plugins"
 CLAUDE_DIR = Path.home() / ".claude"
 CODEX_ROOT = Path.home()
 CODEX_HOME = Path(os.environ.get("CODEX_HOME", CODEX_ROOT / ".codex")).expanduser()
@@ -178,22 +184,40 @@ def _set_installed(state: dict, editor: str, names: list[str]) -> None:
 # Plugin discovery
 # ---------------------------------------------------------------------------
 
+def plugin_roots() -> list[Path]:
+    """Directories scanned for packs, in precedence order.
+
+    Core packs ship inside the npm package; user packs live under
+    TOOLKIT_DATA_DIR and outlive every toolkit upgrade. A core pack wins a name
+    collision so a stray external directory cannot shadow shipped behaviour.
+    """
+    return [PLUGINS_DIR, USER_PLUGINS_DIR]
+
+
 def list_available() -> list[dict]:
-    """List all available plugin packs."""
+    """List all available plugin packs, core first, then user-installed."""
     packs: list[dict] = []
-    if not PLUGINS_DIR.is_dir():
-        return packs
-    for d in sorted(PLUGINS_DIR.iterdir()):
-        manifest = d / "plugin.json"
-        if not manifest.is_file():
+    seen: set[str] = set()
+    for root in plugin_roots():
+        if not root.is_dir():
             continue
-        try:
-            with open(manifest, encoding="utf-8") as f:
-                data = json.load(f)
+        for d in sorted(root.iterdir()):
+            manifest = d / "plugin.json"
+            if not manifest.is_file():
+                continue
+            try:
+                with open(manifest, encoding="utf-8") as f:
+                    data = json.load(f)
+            except (json.JSONDecodeError, OSError):
+                continue
+            name = data.get("name")
+            if not name or name in seen:
+                continue
+            seen.add(name)
             data["_dir"] = str(d)
+            # "_source" is taken: hook entries use it as an ownership marker.
+            data["_root"] = "core" if root == PLUGINS_DIR else "user"
             packs.append(data)
-        except (json.JSONDecodeError, OSError):
-            continue
     return packs
 
 
@@ -579,10 +603,30 @@ def _ensure_claude_settings() -> Path:
     return settings_path
 
 
+def _clear_dangling_link(path: Path, label: str) -> bool:
+    """Drop a symlink whose target no longer exists, so install can relink it.
+
+    A toolkit upgrade replaces app/ wholesale, which leaves every ~/.claude link
+    into the old package pointing at nothing. The install guard treated such a
+    link as installed (`exists() or is_symlink()`), reported OK and repaired
+    nothing — the user was left with a dead link and a green log. Only dangling
+    links are removed: a live link or a real file is user content and stays.
+    """
+    if path.is_symlink() and not path.exists():
+        try:
+            path.unlink()
+        except OSError:
+            return False
+        print(f"    Dangling {label} link removed: {path.name}")
+        return True
+    return False
+
+
 def _install_claude_skills(pack: dict, pack_dir: Path, installed_items: list[str]) -> None:
     for skill in pack.get("includes", {}).get("skills", []):
         skill_dir = CLAUDE_DIR / "skills" / skill
         source_dir = _resolve_skill_source(pack_dir, skill)
+        _clear_dangling_link(skill_dir, "skill")
         if skill_dir.exists() or skill_dir.is_symlink():
             print(f"    OK skill: {skill}")
         elif source_dir:
@@ -598,6 +642,7 @@ def _install_claude_agents(pack: dict, pack_dir: Path, installed_items: list[str
     for agent in pack.get("includes", {}).get("agents", []):
         agent_file = CLAUDE_DIR / "agents" / f"{agent}.md"
         source_file = _resolve_agent_source(pack_dir, agent)
+        _clear_dangling_link(agent_file, "agent")
         if agent_file.exists() or agent_file.is_symlink():
             print(f"    OK agent: {agent}")
         elif source_file is not None:

package/scripts/validate.py

@@ -97,15 +97,26 @@ HOOK_REQUIRED_FIELDS = {
 }
 
 # The taxonomy. `app/skills/documentation-standards/SKILL.md` documents the same
-# eight and is what authors read; this set is what rejects a typo. They are one
-# list in two places, so a change belongs in both.
+# list and is what authors read; this set is what rejects a typo. rag-mcp holds
+# a third copy in `scripts/validate_kb_frontmatter.py`, which runs against
+# knowledge bases this validator never sees. They are one list in three places,
+# so a change belongs in all of them.
 #
 # `decisions` and `runbooks` were missing until v4.21.0 while the kb-migration
 # SOP had been telling people to create those directories for months, so a
 # correctly-filed ADR failed validation.
+#
+# `business` and `templates` were missing for the same reason: rag-mcp's
+# `add-new-repository-to-rag-mcp.md` mandates `kb/business/` and
+# `kb/templates/`. A directory an SOP mandates must be a category the validator
+# accepts, or the two documents contradict each other.
+#
+# `history/` and `summaries/` are deliberately absent. They are lifecycle and
+# runtime locations, not types: a finished plan under `history/completed/` is
+# still a `planning` document and declares that.
 VALID_KB_CATEGORIES = frozenset({
     "reference", "howto", "procedures", "troubleshooting", "best-practices",
-    "decisions", "runbooks", "planning",
+    "decisions", "runbooks", "planning", "business", "templates",
 })
 
 # Skill body budget, in bytes after the frontmatter block.