@softspark/ai-toolkit 3.0.1 → 3.1.0

package/llms.txt

@@ -58,4 +58,5 @@
 - [Supported Tools Registry](kb/reference/supported-tools-registry.md)
 - [Config Sync](kb/reference/sync.md)
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
+- [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.1",
+  "version": "3.1.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
@@ -9,7 +9,7 @@
       "tags": ["core", "agents"]
     },
     "skills": {
-      "description": "99 skills (32 task + 31 hybrid + 36 knowledge)",
+      "description": "112 skills (32 task + 31 hybrid + 49 knowledge)",
       "path": "app/skills",
       "target": ".claude/skills",
       "type": "symlink",
@@ -90,7 +90,7 @@
       "default": true
     },
     "skills": {
-      "description": "99 skills (task, hybrid, knowledge)",
+      "description": "112 skills (task, hybrid, knowledge)",
       "default": true
     },
     "rules-common": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "3.0.1",
-  "description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
+  "version": "3.1.0",
+  "description": "AI coding toolkit: 112 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",
     "claude-code",
@@ -60,16 +60,27 @@
     "generate:roo": "python3 scripts/generate_roo_modes.py > .roomodes",
     "generate:aider": "python3 scripts/generate_aider_conf.py > .aider.conf.yml",
     "generate:codex-rules": "python3 scripts/generate_codex_rules.py .",
+    "generate:language-rules": "python3 scripts/generate_language_rules_skills.py",
     "generate:opencode-agents": "python3 scripts/generate_opencode_agents.py .",
     "generate:opencode-commands": "python3 scripts/generate_opencode_commands.py .",
-    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
+    "generate:cursor-mdc": "python3 scripts/generate_cursor_mdc.py .",
+    "generate:windsurf-rules": "python3 scripts/generate_windsurf_rules.py .",
+    "generate:roo-rules": "python3 scripts/generate_roo_rules.py .",
+    "generate:augment-rules": "python3 scripts/generate_augment_rules.py .",
+    "generate:all": "npm run generate:language-rules && npm run generate:agents && npm run generate:codex-rules && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:cursor && npm run generate:cursor-mdc && npm run generate:windsurf && npm run generate:windsurf-rules && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:roo-rules && npm run generate:aider && npm run generate:augment-rules && npm run generate:llms"
   },
   "files": [
     "bin/",
     "app/",
+    "!app/**/__pycache__",
+    "!app/**/*.pyc",
     "scripts/",
+    "!scripts/**/__pycache__",
+    "!scripts/**/*.pyc",
     "kb/",
     "benchmarks/",
+    "!benchmarks/**/__pycache__",
+    "!benchmarks/**/*.pyc",
     "action.yml",
     "manifest.json",
     "README.md",

package/scripts/_common.py

@@ -165,6 +165,27 @@ def detect_os() -> dict[str, str]:
             "install_cmd": install_cmd,
         }
 
+    if system == "windows":
+        managers = (
+            ("winget", "winget install"),
+            ("choco", "choco install -y"),
+            ("scoop", "scoop install"),
+        )
+        for manager, install_cmd in managers:
+            if shutil.which(manager):
+                return {
+                    "os": "Windows",
+                    "distro": platform.version(),
+                    "pkg_manager": manager,
+                    "install_cmd": install_cmd,
+                }
+        return {
+            "os": "Windows",
+            "distro": platform.version(),
+            "pkg_manager": "none",
+            "install_cmd": "",
+        }
+
     return {
         "os": system,
         "distro": "",

package/scripts/check_deps.py

@@ -37,6 +37,9 @@ REQUIRED = [
             "pacman": "python3",
             "apk": "python3",
             "zypper": "python3",
+            "winget": "Python.Python.3",
+            "choco": "python",
+            "scoop": "python",
         },
         "reason": "All toolkit scripts run on Python 3 (stdlib only, no pip needed)",
     },
@@ -50,6 +53,9 @@ REQUIRED = [
             "pacman": "git",
             "apk": "git",
             "zypper": "git",
+            "winget": "Git.Git",
+            "choco": "git",
+            "scoop": "git",
         },
         "reason": "Version control — hooks, commits, PR workflows",
     },
@@ -64,6 +70,9 @@ REQUIRED = [
             "pacman": "nodejs",
             "apk": "nodejs",
             "zypper": "nodejs18",
+            "winget": "OpenJS.NodeJS",
+            "choco": "nodejs",
+            "scoop": "nodejs",
         },
         "reason": "CLI entry point (bin/ai-toolkit.js)",
     },
@@ -80,6 +89,9 @@ OPTIONAL = [
             "pacman": "sqlite",
             "apk": "sqlite",
             "zypper": "sqlite3",
+            "winget": "SQLite.SQLite",
+            "choco": "sqlite",
+            "scoop": "sqlite",
         },
         "reason": "Memory plugin pack (session persistence via SQLite + FTS5)",
     },
@@ -93,6 +105,8 @@ OPTIONAL = [
             "pacman": "bash-bats",
             "apk": "bats",
             "zypper": "bats",
+            "choco": "bats",
+            "scoop": "bats",
         },
         "reason": "Running toolkit test suite (npm test)",
     },

package/scripts/codex_skill_adapter.py

@@ -155,15 +155,31 @@ def sync_codex_skill(skill_dir: Path, skills_dst: Path) -> str:
 
 def cleanup_codex_skills(skills_dst: Path, skills_src: Path) -> None:
     """Remove broken symlinks and stale generated Codex skill wrappers."""
+    skills_src_resolved = skills_src.resolve()
     for item in skills_dst.iterdir():
         src = skills_src / item.name
-        if item.is_symlink() and not item.exists():
-            item.unlink()
-            continue
+        if item.is_symlink():
+            if not item.exists():
+                item.unlink()
+                continue
+            target = item.resolve()
+            if src.is_dir() and target == src.resolve():
+                continue
+            if _is_relative_to(target, skills_src_resolved):
+                item.unlink()
+                continue
         if item.is_dir() and (item / ADAPTED_MARKER).is_file() and not src.is_dir():
             shutil.rmtree(item)
 
 
+def _is_relative_to(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
 def _parse_frontmatter(frontmatter_text: str) -> list[tuple[str, str]]:
     entries: list[tuple[str, str]] = []
     for line in frontmatter_text.splitlines():

package/scripts/ecosystem_tools.json

@@ -81,8 +81,7 @@
         "~/.cursor/mcp.json",
         ".cursor/skills/*/SKILL.md",
         ".cursor/agents/*.md",
-        ".cursor/hooks.json",
-        "~/.cursor/hooks.json"
+        ".cursor/hooks.json"
       ],
       "our_generators": [
         "scripts/generate_cursor_rules.py",
@@ -264,8 +263,8 @@
         ".roo/rules-{slug}/*.md",
         ".roo/mcp.json",
         "~/.roo/rules/",
-        "~/.roo/settings/custom_modes.yaml",
-        "~/.roo/settings/mcp_settings.json"
+        "~/.roo/custom_modes.yaml",
+        "mcp_settings.json"
       ],
       "our_generators": [
         "scripts/generate_roo_modes.py",
@@ -413,14 +412,15 @@
       "config_paths": [
         "AGENTS.md",
         ".agents/rules/*.md",
+        ".agents/skills/*/SKILL.md",
         ".codex/hooks.json",
-        ".codex/skills/*/SKILL.md",
         "~/.codex/config.toml"
       ],
       "our_generators": [
         "scripts/generate_codex.py",
         "scripts/generate_codex_rules.py",
-        "scripts/generate_codex_hooks.py"
+        "scripts/generate_codex_hooks.py",
+        "scripts/generate_codex_skills.py"
       ],
       "capability_markers": [
         "AGENTS.md",
@@ -437,7 +437,7 @@
         "hook handler: command",
         "hook handler: prompt",
         "hook handler: agent",
-        ".codex/skills"
+        ".agents/skills"
       ],
       "version_probe": {
         "kind": "command",

package/scripts/generate_cline_rules.py

@@ -79,13 +79,20 @@ def generate(target_dir: Path, *,
              rules_dir: Path | None = None,
              cleanup: bool = True,
              emit_workflows: bool = True,
-             managed_scopes: tuple[str, ...] = (STANDARD_SCOPE,)) -> None:
-    """Write ``.clinerules/*.md`` (and workflow) files to target_dir."""
+             managed_scopes: tuple[str, ...] = (STANDARD_SCOPE,),
+             output_root: Path | None = None) -> None:
+    """Write Cline rule files.
+
+    By default writes project-local ``target_dir/.clinerules/*.md``. When
+    ``output_root`` is provided, writes directly into that directory; this is
+    used for Cline's documented global rules directory.
+    """
     # Migrate: if .clinerules exists as a single file, remove it so the
     # directory can be created (Cline 3.7+ uses directory format).
-    clinerules = target_dir / ".clinerules"
-    if clinerules.is_file():
-        clinerules.unlink()
+    if output_root is None:
+        clinerules = target_dir / ".clinerules"
+        if clinerules.is_file():
+            clinerules.unlink()
 
     rules: dict[str, callable] = dict(STANDARD_RULES)
     # Replace the testing rule with a conditional variant so it only
@@ -107,15 +114,17 @@ def generate(target_dir: Path, *,
 
     rules.update(build_registered_rules(rules_dir))
 
+    root = output_root.parent if output_root is not None else target_dir
+    subdir = output_root.name if output_root is not None else ".clinerules"
     write_rules(
-        target_dir,
+        root,
         rules,
-        ".clinerules",
+        subdir,
         cleanup=cleanup,
         managed_scopes=managed_scopes,
     )
 
-    if emit_workflows:
+    if emit_workflows and output_root is None:
         _write_workflows(target_dir, cleanup=cleanup)
 
 

package/scripts/generate_codex_skills.py

@@ -1,26 +1,23 @@
 #!/usr/bin/env python3
-"""Mirror the full ai-toolkit skill catalogue into ``.codex/skills/``.
+"""Mirror the ai-toolkit skill catalogue into Codex ``.agents/skills/``.
 
-OpenAI Codex CLI supports the Agent Skills standard at
-``.codex/skills/<skill-name>/SKILL.md`` with optional supporting files
-(scripts, references, assets) in the skill directory. Unlike the Augment
-and Gemini pointer pattern, Codex benefits from having the full skill
-content on disk, so this generator performs a **full mirror** of every
-skill in ``app/skills/`` into ``<target-dir>/.codex/skills/<name>/``.
+OpenAI Codex CLI discovers Agent Skills from ``.agents/skills/`` in the
+repository tree, plus user/admin/system skill locations. Unlike the Augment
+and Gemini pointer pattern, Codex benefits from having the full skill catalog
+on disk, so this generator syncs every skill in ``app/skills/`` into
+``<target-dir>/.agents/skills/<name>/``.
 
 The mirror is **opt-in**: ``enable_codex_skills=False`` is the default.
 Bucket 4 wires a ``--codex-skills`` CLI flag that toggles this on.
 
 Implementation:
-  * Prefer symlinks from ``.codex/skills/<name>`` to the canonical
-    ``app/skills/<name>`` directory (atomic and cheap).
-  * Fall back to a recursive copy when symlinks are unavailable (Windows
-    without developer mode, hostile filesystems, etc.).
+  * Native Codex-compatible skills are symlinked to canonical ``app/skills``.
+  * Skills that use Claude-only delegation tools are rendered as Codex
+    wrappers through ``codex_skill_adapter.sync_codex_skill``.
   * Skip ``_lib`` and any dotfile directories under ``app/skills/``.
-  * Remove stale entries under ``.codex/skills/`` that no longer
-    correspond to a source skill (cleanup on rerun).
-  * Never touch user-authored entries in ``.codex/skills/`` that do not
-    match a source skill name and are not our managed targets.
+  * Remove stale generated wrappers and broken managed symlinks.
+  * Preserve user-authored entries in ``.agents/skills/`` that are not managed
+    by ai-toolkit.
 
 Idempotent on rerun.
 
@@ -32,12 +29,11 @@ keeping the opt-in default enforced even when invoked directly.
 """
 from __future__ import annotations
 
-import os
-import shutil
 import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+from codex_skill_adapter import cleanup_codex_skills, sync_codex_skill
 from emission import skills_dir
 
 
@@ -69,69 +65,11 @@ def _iter_source_skills() -> list[Path]:
 # Mirror operations
 # ---------------------------------------------------------------------------
 
-def _remove_existing(target: Path) -> None:
-    """Remove an existing file, symlink, or directory at ``target``.
-
-    Uses ``lstat`` so symlinks are unlinked without following them.
-    """
-    if not target.exists() and not target.is_symlink():
-        return
-    if target.is_symlink() or target.is_file():
-        target.unlink()
-        return
-    shutil.rmtree(target)
-
-
-def _symlink_or_copy(source: Path, target: Path) -> str:
-    """Create ``target`` as a symlink to ``source``; fall back to a copy.
-
-    Returns ``"symlink"`` or ``"copy"`` indicating which strategy was used.
-    """
-    _remove_existing(target)
-    target.parent.mkdir(parents=True, exist_ok=True)
-    try:
-        os.symlink(source, target, target_is_directory=True)
-        return "symlink"
-    except (OSError, NotImplementedError):
-        shutil.copytree(source, target, symlinks=False)
-        return "copy"
-
-
-def _cleanup_stale(codex_skills_dir: Path, live_names: set[str]) -> list[str]:
-    """Remove managed entries under ``.codex/skills/`` that no longer map
-    to a source skill. Returns the names removed.
-
-    A managed entry is one whose directory name matches a historical
-    source skill name pattern: it contains a ``SKILL.md`` either directly
-    (copy) or via a symlink back into ``app/skills/``. User-authored
-    entries that do not look managed are left alone.
-    """
+def _count_entries(codex_skills_dir: Path) -> int:
+    """Count top-level skill entries after sync."""
     if not codex_skills_dir.is_dir():
-        return []
-    removed: list[str] = []
-    for entry in sorted(codex_skills_dir.iterdir()):
-        if not entry.is_dir() and not entry.is_symlink():
-            continue
-        if entry.name in live_names:
-            continue
-        if entry.is_symlink():
-            # Only remove symlinks that point inside our app/skills/ tree.
-            try:
-                resolved = entry.resolve()
-            except OSError:
-                continue
-            try:
-                resolved.relative_to(skills_dir.resolve())
-            except ValueError:
-                continue
-            entry.unlink()
-            removed.append(entry.name)
-            continue
-        # Copy mode: treat as managed only if a SKILL.md is present.
-        if (entry / "SKILL.md").is_file():
-            shutil.rmtree(entry)
-            removed.append(entry.name)
-    return removed
+        return 0
+    return sum(1 for entry in codex_skills_dir.iterdir() if entry.is_dir() or entry.is_symlink())
 
 
 # ---------------------------------------------------------------------------
@@ -139,10 +77,10 @@ def _cleanup_stale(codex_skills_dir: Path, live_names: set[str]) -> list[str]:
 # ---------------------------------------------------------------------------
 
 def generate(target_dir: Path, enable_codex_skills: bool = False) -> None:
-    """Mirror ``app/skills/`` into ``<target_dir>/.codex/skills/``.
+    """Mirror ``app/skills/`` into ``<target_dir>/.agents/skills/``.
 
     Args:
-      target_dir: Project root where ``.codex/skills/`` is written.
+      target_dir: Project root where ``.agents/skills/`` is written.
       enable_codex_skills: Opt-in flag. Defaults to ``False`` (no-op).
 
     Contract for Bucket 4 wiring::
@@ -156,31 +94,30 @@ def generate(target_dir: Path, enable_codex_skills: bool = False) -> None:
     if not enable_codex_skills:
         return
 
-    codex_skills_dir = target_dir / ".codex" / "skills"
+    codex_skills_dir = target_dir / ".agents" / "skills"
     codex_skills_dir.mkdir(parents=True, exist_ok=True)
 
     sources = _iter_source_skills()
-    live_names: set[str] = {s.name for s in sources}
 
-    symlink_count = 0
-    copy_count = 0
+    linked = 0
+    adapted = 0
+    skipped = 0
     for skill in sources:
-        target = codex_skills_dir / skill.name
-        mode = _symlink_or_copy(skill, target)
-        if mode == "symlink":
-            symlink_count += 1
+        mode = sync_codex_skill(skill, codex_skills_dir)
+        if mode == "linked":
+            linked += 1
+        elif mode == "adapted":
+            adapted += 1
         else:
-            copy_count += 1
+            skipped += 1
 
-    removed = _cleanup_stale(codex_skills_dir, live_names)
+    cleanup_codex_skills(codex_skills_dir, skills_dir)
 
-    total = symlink_count + copy_count
     print(
-        f"  Codex skill mirror: {total} skills "
-        f"({symlink_count} symlink, {copy_count} copy)"
+        f"  Codex skill mirror: {_count_entries(codex_skills_dir)} skills "
+        f"to .agents/skills/ ({linked} linked, {adapted} adapted, "
+        f"{skipped} skipped)"
     )
-    if removed:
-        print(f"  Codex skill mirror: removed {len(removed)} stale entries")
 
 
 def main() -> None: