@softspark/ai-toolkit 1.3.6 → 1.3.8

package/CHANGELOG.md

@@ -7,6 +7,21 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.3.8 — Language Rules as References (2026-04-07)
+
+### Changed
+- **Language rules injection**: Instead of inlining full rule content (~705 lines), `install --local` now injects lightweight reference pointers (~12 lines) with absolute paths to rule files. Claude reads them on demand via Read tool, keeping CLAUDE.md compact.
+- **plugin.json**: Version synced from stale 1.2.1 to 1.3.8.
+
+---
+
+## v1.3.7 — Update Notifications (2026-04-07)
+
+### Added
+- **Update notifications**: `session-start.sh` hook checks npm for newer versions (cached 24h, non-blocking). `ai-toolkit status` shows installed vs latest version with upgrade command.
+
+---
+
 ## v1.3.6 — Patch (2026-04-07)
 
 ### Fixed

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

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit: 90 skills, 44 agents, persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "1.2.1",
+  "version": "1.3.8",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/session-start.sh

@@ -8,7 +8,14 @@
 echo "MANDATORY: Before answering ANY technical question, apply ALL rules from your CLAUDE.md files (global + project). Follow the exact order of operations defined there. Do NOT skip mandatory steps even if you think you already know the answer."
 echo "REMINDER: When writing features or fixing bugs, ensure tests cover the changes. When modifying API, config, or setup, update relevant documentation. Propose these steps to the user — do not silently skip them."
 
-# 2. Load session context (if available)
+# 2. Check for updates (cached, max once per 24h, non-blocking)
+TOOLKIT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+VERSION_MSG=$(python3 "$TOOLKIT_DIR/scripts/version_check.py" 2>/dev/null)
+if [ -n "$VERSION_MSG" ]; then
+    echo "$VERSION_MSG"
+fi
+
+# 3. Load session context (if available)
 SESSION_FILE=".claude/session-context.md"
 if [ -f "$SESSION_FILE" ]; then
     echo "=== Session Context ==="

package/kb/reference/benchmark-config.md

@@ -32,17 +32,17 @@ AI Toolkit Config Benchmark
 ========================
 
 ## Your Configuration (~/.claude/)
-  Agents:  47
+  Agents:  44
   Skills:  80
   Hooks:   12
 
 ## Toolkit Totals
-  Agents:  47
+  Agents:  44
   Skills:  80
   Hooks:   12
 
 ## Coverage
-  Agents:  100%  (47 / 47)
+  Agents:  100%  (44 / 44)
   Skills:  100%  (80 / 80)
   Hooks:   100%  (12 / 12)
 

package/kb/reference/competitive-features-implementation.md

@@ -384,7 +384,7 @@ All entries are tagged with "_source": "<source-name>" for idempotent updates.
       "required": true
     },
     "agents": {
-      "description": "47 specialized agents",
+      "description": "44 specialized agents",
       "files": ["app/agents/*.md"],
       "required": false,
       "default": true

package/kb/reference/extension-api.md

@@ -3,7 +3,7 @@ title: "Extension API Reference"
 category: reference
 service: ai-toolkit
 tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration]
-version: "1.3.0"
+version: "1.3.8"
 created: "2026-04-07"
 last_updated: "2026-04-07"
 description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and mcp template management."

package/kb/reference/manifest-install.md

@@ -24,7 +24,7 @@ Modules are defined in `manifest.json` at the repository root. There are 17 modu
 | Module | Description | In Profile |
 |--------|-------------|-----------|
 | `core` | Core hooks and essential skills | minimal, standard, strict, full |
-| `agents` | 47 specialized agents | standard, strict, full |
+| `agents` | 44 specialized agents | standard, strict, full |
 | `skills` | 90 skills (task, hybrid, knowledge) | standard, strict, full |
 | `rules-common` | Common coding rules (5 files) | standard, strict, full |
 | `rules-typescript` | TypeScript-specific rules (5 files) | auto-detect |

package/kb/reference/skills-catalog.md

@@ -3,7 +3,7 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.3.3"
+version: "1.3.8"
 created: "2026-03-23"
 last_updated: "2026-04-07"
 description: "Complete catalog of 90 skills: 28 task, 30 hybrid, 32 knowledge. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."

package/llms-full.txt

@@ -1199,17 +1199,17 @@ AI Toolkit Config Benchmark
 ========================
 
 ## Your Configuration (~/.claude/)
-  Agents:  47
+  Agents:  44
   Skills:  80
   Hooks:   12
 
 ## Toolkit Totals
-  Agents:  47
+  Agents:  44
   Skills:  80
   Hooks:   12
 
 ## Coverage
-  Agents:  100%  (47 / 47)
+  Agents:  100%  (44 / 44)
   Skills:  100%  (80 / 80)
   Hooks:   100%  (12 / 12)
 
@@ -1907,7 +1907,7 @@ All entries are tagged with "_source": "<source-name>" for idempotent updates.
       "required": true
     },
     "agents": {
-      "description": "47 specialized agents",
+      "description": "44 specialized agents",
       "files": ["app/agents/*.md"],
       "required": false,
       "default": true
@@ -2276,7 +2276,7 @@ title: "Extension API Reference"
 category: reference
 service: ai-toolkit
 tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration]
-version: "1.3.0"
+version: "1.3.8"
 created: "2026-04-07"
 last_updated: "2026-04-07"
 description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and mcp template management."
@@ -3454,7 +3454,7 @@ Modules are defined in `manifest.json` at the repository root. There are 17 modu
 | Module | Description | In Profile |
 |--------|-------------|-----------|
 | `core` | Core hooks and essential skills | minimal, standard, strict, full |
-| `agents` | 47 specialized agents | standard, strict, full |
+| `agents` | 44 specialized agents | standard, strict, full |
 | `skills` | 90 skills (task, hybrid, knowledge) | standard, strict, full |
 | `rules-common` | Common coding rules (5 files) | standard, strict, full |
 | `rules-typescript` | TypeScript-specific rules (5 files) | auto-detect |
@@ -4067,7 +4067,7 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.3.0"
+version: "1.3.8"
 created: "2026-03-23"
 last_updated: "2026-04-07"
 description: "Complete catalog of 90 skills: 28 task, 30 hybrid, 32 knowledge. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
@@ -4177,7 +4177,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | `application-deploy` | 3 | Deploy → smoke test → release notes |
 | `proactive-troubleshooting` | 4 | Investigate → check perf → preventive fix → docs |
 
-## Knowledge Skills - Development (10)
+## Knowledge Skills - Development (16)
 
 | Skill | Directory | Domain |
 |-------|-----------|--------|
@@ -4188,6 +4188,12 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **ecommerce-patterns** | `skills/ecommerce-patterns/` | E-commerce: catalog, cart, checkout, payments |
 | **clean-code** | `skills/clean-code/` | Multi-language code quality: Python, TS, PHP, Go, Dart |
 | **typescript-patterns** | `skills/typescript-patterns/` | TypeScript/JavaScript patterns for frontend and backend |
+| **rust-patterns** | `skills/rust-patterns/` | Ownership, borrowing, error handling, Cargo, tokio, serde |
+| **java-patterns** | `skills/java-patterns/` | Records, sealed classes, Stream API, Spring Boot, JUnit 5 |
+| **csharp-patterns** | `skills/csharp-patterns/` | Nullable refs, async/await, ASP.NET Core, EF Core |
+| **kotlin-patterns** | `skills/kotlin-patterns/` | Coroutines, DSLs, sealed classes, Ktor, MockK |
+| **swift-patterns** | `skills/swift-patterns/` | Protocol-oriented, SwiftUI, async/await, SPM |
+| **ruby-patterns** | `skills/ruby-patterns/` | Blocks, Rails conventions, RSpec, ActiveRecord |
 | **design-engineering** | `skills/design-engineering/` | UI polish, animation craft, easing, transforms, accessibility |
 | **documentation-standards** | `skills/documentation-standards/` | KB document conventions, frontmatter validation, category taxonomy |
 | **brand-voice** | `skills/brand-voice/` | Anti-trope list, voice principles, LLM rhetoric prevention |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Professional-grade AI coding toolkit: 90 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",

package/scripts/install_steps/ai_tools.py

@@ -166,11 +166,11 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
 
 
 def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
-    """Inject language-specific rules into project's CLAUDE.md.
+    """Inject language-specific rule summary into project's .claude/CLAUDE.md.
 
-    Concatenates all .md files from matching app/rules/<lang>/ directories
-    into a single marker-injected section in the project's .claude/CLAUDE.md.
-    Also always includes common rules.
+    Instead of injecting full rule content (hundreds of lines), injects a
+    compact summary with the key rules per category. Full rules are available
+    as knowledge skills that Claude auto-loads contextually.
     """
     if not language_modules:
         return
@@ -179,35 +179,40 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
     if not rules_src.is_dir():
         return
 
-    # Always include common + detected languages
-    lang_dirs: list[str] = ["common"]
+    # Detect language names
+    langs: list[str] = []
     for mod in language_modules:
-        # module name format: "rules-typescript" → dir "typescript"
         if mod.startswith("rules-"):
-            lang_dirs.append(mod[6:])
+            langs.append(mod[6:])
 
-    # Collect all rule content
-    parts: list[str] = []
-    for lang_dir in lang_dirs:
-        lang_path = rules_src / lang_dir
-        if not lang_path.is_dir():
-            continue
-        for rule_file in sorted(lang_path.glob("*.md")):
-            content = rule_file.read_text(encoding="utf-8").strip()
-            # Strip YAML frontmatter
-            if content.startswith("---"):
-                end = content.find("---", 3)
-                if end != -1:
-                    content = content[end + 3:].strip()
-            if content:
-                parts.append(content)
-
-    if not parts:
+    if not langs:
         return
 
-    # Write concatenated rules to a temp file, then inject as a section
+    # Build a lightweight reference pointer — NOT the full rules content.
+    # Full rules are available as knowledge skills (auto-loaded by Claude)
+    # and as files Claude can Read on demand.
+    toolkit_pkg = app_dir.parent
+    lines: list[str] = ["# Language Rules", ""]
+    lines.append(f"This project uses: **{', '.join(langs)}**")
+    lines.append("")
+    lines.append("When writing or reviewing code, use the Glob and Read tools to read the rules:")
+    # Resolve actual installed path for the rules
+    rules_resolved = str(rules_src.resolve())
+    all_dirs: list[str] = ["common"]
+    for l in langs:
+        if l not in all_dirs:
+            all_dirs.append(l)
+    for lang in all_dirs:
+        lang_path = rules_src / lang
+        if lang_path.is_dir():
+            categories = ", ".join(f.stem for f in sorted(lang_path.glob("*.md")))
+            lines.append(f"- `{lang_path.resolve()}/` ({categories})")
+    lines.append("")
+    lines.append("Read the relevant rule files before making code changes. Do NOT guess — read first.")
+
+    # Write summary to temp file, then inject as section
     import tempfile
-    combined = "\n\n".join(parts)
+    combined = "\n".join(lines)
     with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False,
                                      encoding="utf-8") as tmp:
         tmp.write(combined)
@@ -215,8 +220,8 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
 
     try:
         inject_section(tmp_path, cwd / ".claude" / "CLAUDE.md", "language-rules")
-        detected = ", ".join(d for d in lang_dirs if d != "common")
-        print(f"  Injected: language rules (common + {detected})")
+        lang_names = [l for l in langs if l != "common"]
+        print(f"  Injected: language rules summary (common + {', '.join(lang_names)})")
     finally:
         tmp_path.unlink(missing_ok=True)
 

package/scripts/install_steps/install_state.py

@@ -115,3 +115,18 @@ def print_status() -> None:
         # Strip "rules-" prefix for readability
         langs = [m.replace("rules-", "") for m in detected]
         print(f"  Detected:   {', '.join(langs)}")
+
+    # Check for updates
+    try:
+        import sys as _sys
+        _sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+        from version_check import check
+        result = check()
+        if result["update_available"]:
+            print()
+            print(f"  Update available: {result['installed']} -> {result['latest']}")
+            print(f"  Run: npm install -g @softspark/ai-toolkit@latest && ai-toolkit update")
+        else:
+            print(f"  Latest:     {result['latest']} (up to date)")
+    except Exception:
+        pass  # version check is optional

package/scripts/version_check.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Check if a newer version of ai-toolkit is available on npm.
+
+Caches the result for 24 hours to avoid hitting npm on every session.
+
+Usage:
+  version_check.py              # Print update notice if available (for hooks)
+  version_check.py --status     # Print detailed version info (for ai-toolkit status)
+  version_check.py --force      # Force re-check (ignore cache)
+
+Exit codes:
+  0  Up to date (or check skipped/failed)
+  1  Update available
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+CACHE_FILE = Path.home() / ".ai-toolkit" / "version-check.json"
+CACHE_TTL = 86400  # 24 hours
+PACKAGE_NAME = "@softspark/ai-toolkit"
+
+
+def _get_installed_version() -> str:
+    """Read version from the toolkit's own package.json."""
+    pkg = Path(__file__).resolve().parent.parent / "package.json"
+    if pkg.is_file():
+        with open(pkg, encoding="utf-8") as f:
+            return json.load(f).get("version", "unknown")
+    return "unknown"
+
+
+def _get_cached() -> dict | None:
+    """Read cached version check result."""
+    if not CACHE_FILE.is_file():
+        return None
+    try:
+        with open(CACHE_FILE, encoding="utf-8") as f:
+            data = json.load(f)
+        checked_at = data.get("checked_at", 0)
+        if time.time() - checked_at > CACHE_TTL:
+            return None  # expired
+        return data
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _save_cache(installed: str, latest: str) -> None:
+    """Save version check result to cache."""
+    CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "installed": installed,
+        "latest": latest,
+        "checked_at": time.time(),
+    }
+    tmp = str(CACHE_FILE) + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(data, f)
+    os.replace(tmp, str(CACHE_FILE))
+
+
+def _fetch_latest_version() -> str | None:
+    """Fetch latest version from npm registry (2s timeout)."""
+    try:
+        result = subprocess.run(
+            ["npm", "view", PACKAGE_NAME, "version"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+    return None
+
+
+def _parse_semver(version: str) -> tuple[int, ...]:
+    """Parse version string to comparable tuple."""
+    try:
+        return tuple(int(x) for x in version.split("."))
+    except (ValueError, AttributeError):
+        return (0, 0, 0)
+
+
+def _is_newer(latest: str, installed: str) -> bool:
+    """Check if latest is newer than installed."""
+    return _parse_semver(latest) > _parse_semver(installed)
+
+
+def check(force: bool = False) -> dict:
+    """Check for updates. Returns {installed, latest, update_available}."""
+    installed = _get_installed_version()
+
+    if not force:
+        cached = _get_cached()
+        if cached:
+            return {
+                "installed": installed,
+                "latest": cached.get("latest", installed),
+                "update_available": _is_newer(cached.get("latest", ""), installed),
+                "cached": True,
+            }
+
+    latest = _fetch_latest_version()
+    if latest:
+        _save_cache(installed, latest)
+        return {
+            "installed": installed,
+            "latest": latest,
+            "update_available": _is_newer(latest, installed),
+            "cached": False,
+        }
+
+    return {
+        "installed": installed,
+        "latest": "unknown",
+        "update_available": False,
+        "cached": False,
+    }
+
+
+def main() -> None:
+    force = "--force" in sys.argv
+    status_mode = "--status" in sys.argv
+
+    result = check(force=force)
+
+    if status_mode:
+        print(f"  Installed:  {result['installed']}")
+        print(f"  Latest:     {result['latest']}")
+        if result["update_available"]:
+            print(f"  Update:     {result['installed']} -> {result['latest']}")
+            print(f"  Run:        npm install -g {PACKAGE_NAME}@latest && ai-toolkit update")
+        else:
+            print("  Update:     up to date")
+        sys.exit(1 if result["update_available"] else 0)
+
+    # Hook mode: only print if update available
+    if result["update_available"]:
+        print(
+            f"ai-toolkit update available: {result['installed']} -> {result['latest']} "
+            f"(npm install -g {PACKAGE_NAME}@latest)"
+        )
+        sys.exit(1)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()