@softspark/ai-toolkit 3.0.2 → 3.1.0

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:

package/scripts/generate_language_rules_skills.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Generate language-rules knowledge skills from app/rules/<lang>/*.md.
+
+Each language directory under ``app/rules/`` (except ``common/``) is compiled
+into a single ``app/skills/<lang>-rules/SKILL.md`` knowledge skill. The skill
+is ``user-invocable: false`` so Claude loads it contextually when the
+description triggers match (file extensions, framework names).
+
+This is the proper progressive-disclosure replacement for the v1.3.8 pointer
+block in ``.claude/CLAUDE.md``: instead of nudging Claude to Read absolute
+nvm-pinned paths on demand, the rules ride on the Agent Skills mechanism.
+
+Common rules (``app/rules/common/``) stay inlined in ``CLAUDE.md`` because
+they are language-agnostic and should be visible regardless of context.
+
+Idempotent: rerunning overwrites generated SKILL.md but leaves any other
+files in the skill directory alone.
+
+Usage:
+    python3 scripts/generate_language_rules_skills.py            # write all
+    python3 scripts/generate_language_rules_skills.py --check    # dry-run
+    python3 scripts/generate_language_rules_skills.py --langs python,rust
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from textwrap import dedent
+
+ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = ROOT / "app" / "rules"
+SKILLS_DIR = ROOT / "app" / "skills"
+
+# Per-language description triggers. Concrete file extensions and framework
+# names give Claude a high-signal match against user prompts and file paths,
+# so the skill activates reliably when the user is actually working in that
+# language.
+TRIGGERS: dict[str, dict[str, str]] = {
+    "python": {
+        "label": "Python",
+        "triggers": ".py, .pyi, pyproject.toml, requirements.txt, Pipfile, FastAPI, Django, Flask, pytest, SQLAlchemy, ruff, mypy",
+    },
+    "typescript": {
+        "label": "TypeScript/JavaScript",
+        "triggers": ".ts, .tsx, .js, .jsx, package.json, tsconfig.json, React, Next.js, Vue, Vite, Vitest, Jest, ESLint",
+    },
+    "golang": {
+        "label": "Go",
+        "triggers": ".go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt",
+    },
+    "rust": {
+        "label": "Rust",
+        "triggers": ".rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test",
+    },
+    "java": {
+        "label": "Java",
+        "triggers": ".java, pom.xml, build.gradle, Spring, Spring Boot, JPA, Hibernate, JUnit, Maven, Gradle",
+    },
+    "kotlin": {
+        "label": "Kotlin",
+        "triggers": ".kt, .kts, build.gradle.kts, Ktor, Jetpack Compose, coroutines, kotlinx",
+    },
+    "swift": {
+        "label": "Swift",
+        "triggers": ".swift, Package.swift, .xcodeproj, SwiftUI, Combine, async/await, XCTest",
+    },
+    "dart": {
+        "label": "Dart/Flutter",
+        "triggers": ".dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget",
+    },
+    "csharp": {
+        "label": "C#/.NET",
+        "triggers": ".cs, .csproj, .sln, ASP.NET, ASP.NET Core, EF Core, LINQ, NUnit, xUnit, dotnet",
+    },
+    "php": {
+        "label": "PHP",
+        "triggers": ".php, composer.json, Laravel, Symfony, PHPUnit, PSR-12, Composer",
+    },
+    "cpp": {
+        "label": "C++",
+        "triggers": ".cpp, .cc, .cxx, .hpp, .h, CMakeLists.txt, Makefile, GoogleTest, clang-tidy",
+    },
+    "ruby": {
+        "label": "Ruby",
+        "triggers": ".rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop",
+    },
+    "medplum": {
+        "label": "Medplum (FHIR healthcare)",
+        "triggers": "medplum.config.mts, medplum.config.ts, FHIR, Medplum, Bot, Subscription, Questionnaire",
+    },
+}
+
+
+def _strip_frontmatter(text: str) -> str:
+    """Remove YAML frontmatter (--- ... ---) if present."""
+    if not text.startswith("---"):
+        return text.lstrip("\n")
+    end = text.find("\n---", 3)
+    if end == -1:
+        return text.lstrip("\n")
+    return text[end + 4:].lstrip("\n")
+
+
+def _category_title(stem: str) -> str:
+    """Convert filename stem (e.g. ``coding-style``) to a section title."""
+    return " ".join(part.capitalize() for part in stem.split("-"))
+
+
+def _build_skill_body(lang_dir: Path) -> str:
+    """Concatenate all rule category files into a skill body."""
+    parts: list[str] = []
+    for f in sorted(lang_dir.glob("*.md")):
+        body = _strip_frontmatter(f.read_text(encoding="utf-8")).rstrip()
+        # If the source file already starts with a top-level "# Title", keep
+        # it. Otherwise, prepend a "## Category" header so the skill body
+        # has structure.
+        if body.lstrip().startswith("#"):
+            parts.append(body)
+        else:
+            parts.append(f"## {_category_title(f.stem)}\n\n{body}")
+    return "\n\n".join(parts) + "\n"
+
+
+def _build_description(lang: str) -> str:
+    meta = TRIGGERS.get(lang)
+    if not meta:
+        return (
+            f"{lang.capitalize()} coding rules: coding-style, frameworks, "
+            f"patterns, security, testing. Load when writing or reviewing "
+            f"{lang.capitalize()} code."
+        )
+    label = meta["label"]
+    triggers = meta["triggers"]
+    return (
+        f"{label} coding rules from ai-toolkit: coding-style, frameworks, "
+        f"patterns, security, testing. "
+        f"Triggers: {triggers}. "
+        f"Load when writing, reviewing, or editing {label} code."
+    )
+
+
+def _build_skill_md(lang: str, lang_dir: Path) -> str:
+    description = _build_description(lang)
+    body = _build_skill_body(lang_dir)
+    label = TRIGGERS.get(lang, {}).get("label", lang.capitalize())
+    frontmatter = dedent(
+        f"""\
+        ---
+        name: {lang}-rules
+        description: "{description}"
+        effort: medium
+        user-invocable: false
+        allowed-tools: Read
+        ---
+
+        # {label} Rules
+
+        These rules come from `app/rules/{lang}/` in ai-toolkit. They cover
+        the project's standards for coding style, frameworks, patterns,
+        security, and testing in {label}. Apply them when writing or
+        reviewing {label} code.
+
+        """
+    )
+    return frontmatter + body
+
+
+def discover_languages() -> list[str]:
+    """List language directories under app/rules/ excluding ``common``."""
+    if not RULES_DIR.is_dir():
+        return []
+    out: list[str] = []
+    for d in sorted(RULES_DIR.iterdir()):
+        if not d.is_dir() or d.name == "common":
+            continue
+        if any(d.glob("*.md")):
+            out.append(d.name)
+    return out
+
+
+def generate(langs: list[str] | None = None, check: bool = False) -> int:
+    """Generate skills. Returns count of skills written (or that would be)."""
+    languages = langs if langs else discover_languages()
+    written = 0
+    for lang in languages:
+        lang_dir = RULES_DIR / lang
+        if not lang_dir.is_dir():
+            print(f"  SKIP: {lang} (directory missing)", file=sys.stderr)
+            continue
+        skill_dir = SKILLS_DIR / f"{lang}-rules"
+        skill_md = skill_dir / "SKILL.md"
+        content = _build_skill_md(lang, lang_dir)
+
+        if check:
+            existing = skill_md.read_text(encoding="utf-8") if skill_md.is_file() else ""
+            status = "OK" if existing == content else "DIFF"
+            print(f"  [{status}] {skill_md.relative_to(ROOT)}")
+            if existing != content:
+                written += 1
+            continue
+
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        skill_md.write_text(content, encoding="utf-8")
+        print(f"  Wrote: {skill_md.relative_to(ROOT)}")
+        written += 1
+    return written
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    ap.add_argument(
+        "--langs",
+        default="",
+        help="Comma-separated language list (default: all)",
+    )
+    ap.add_argument(
+        "--check",
+        action="store_true",
+        help="Dry-run: report which skills would change without writing",
+    )
+    args = ap.parse_args()
+    langs = [s.strip() for s in args.langs.split(",") if s.strip()] or None
+    n = generate(langs=langs, check=args.check)
+    if args.check and n > 0:
+        print(f"\n{n} skill(s) out of date. Re-run without --check.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/generate_roo_rules.py

@@ -23,12 +23,20 @@ from dir_rules_shared import (
 
 def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
-             rules_dir: Path | None = None) -> None:
-    """Write .roo/rules/*.md files to target_dir."""
+             rules_dir: Path | None = None,
+             output_root: Path | None = None) -> None:
+    """Write Roo Code rule files.
+
+    By default writes project-local ``target_dir/.roo/rules/*.md``. When
+    ``output_root`` is provided, writes directly into that directory for
+    documented global rules such as ``~/.roo/rules``.
+    """
     rules = dict(STANDARD_RULES)
     rules.update(build_language_rules(language_modules))
     rules.update(build_registered_rules(rules_dir))
-    write_rules(target_dir, rules, ".roo/rules")
+    root = output_root.parent if output_root is not None else target_dir
+    subdir = output_root.name if output_root is not None else ".roo/rules"
+    write_rules(root, rules, subdir)
 
 
 def main() -> None:

package/scripts/install.py

@@ -12,9 +12,14 @@ Claude Code (~/.claude/):
   - Rules injected into ~/.claude/CLAUDE.md
 
 Other tools (global config locations):
-  - Cursor:   ~/.cursor/rules
   - Windsurf: ~/.codeium/windsurf/memories/global_rules.md
   - Gemini:   ~/.gemini/GEMINI.md
+  - Cline:    ~/Documents/Cline/Rules/
+  - Roo Code: ~/.roo/rules/
+  - Aider:    ~/.aider.conf.yml (created only if absent)
+  - Augment:  ~/.augment/rules/ai-toolkit.md
+  - Codex:    ~/AGENTS.md, ~/.agents/, ~/.codex/hooks.json
+  - opencode: ~/.config/opencode/
 
 Registered rules (~/.softspark/ai-toolkit/rules/*.md) are also injected into
 all of the above. Add rules with: ai-toolkit add-rule <rule.md>