@softspark/ai-toolkit 4.30.3 → 4.32.0

package/scripts/generate_opencode_skills.py

@@ -21,7 +21,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from codex_skill_adapter import build_opencode_skill_text
 from emission import skills_dir
-from frontmatter import frontmatter_field
+from frontmatter import frontmatter_block, frontmatter_field, frontmatter_sections
 from secure_fs import SecureDestination, SecureTransaction, nearest_existing_root
 
 
@@ -43,24 +43,6 @@ class PreparedSkill:
         return {Path("SKILL.md"), Path(MANAGED_MANIFEST), *self.files}
 
 
-def _frontmatter_sections(skill_file: Path) -> dict[str, list[str]]:
-    text = skill_file.read_text(encoding="utf-8")
-    if not text.startswith("---\n"):
-        return {}
-    parts = text.split("---", 2)
-    if len(parts) != 3:
-        return {}
-    sections: dict[str, list[str]] = {}
-    current: str | None = None
-    for line in parts[1].strip("\n").splitlines():
-        if line and not line[0].isspace() and ":" in line:
-            current = line.split(":", 1)[0].strip()
-            sections[current] = [line]
-        elif current is not None:
-            sections[current].append(line)
-    return sections
-
-
 def _portable_body(skill_file: Path) -> str:
     rendered = build_opencode_skill_text(skill_file)
     if not rendered.startswith("---\n"):
@@ -72,7 +54,7 @@ def _portable_body(skill_file: Path) -> str:
 def _render_skill(skill_file: Path) -> str:
     name = frontmatter_field(skill_file, "name")
     description = frontmatter_field(skill_file, "description")
-    sections = _frontmatter_sections(skill_file)
+    sections = frontmatter_sections(frontmatter_block(skill_file))
     lines = [
         "---",
         f"name: {name}",

package/scripts/generate_toolkit_rules_skills.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
+"""Generate knowledge skills from the top-level rule files in ``app/rules/``.
+
+Each ``app/rules/<stem>.md`` becomes ``app/skills/<stem>/SKILL.md``. The
+per-language directories are not touched here; ``generate_language_rules_skills``
+owns those.
+
+Why this exists
+---------------
+The rules were reachable only as Claude Code user-level files under
+``~/.claude/rules/``, with the global ``CLAUDE.md`` carrying a pointer to them
+rather than their content. That pointer is a Claude Code idiom. DeepSeek Harness
+reads ``AGENTS.md``, ``AGENTS.local.md``, ``CLAUDE.md`` and ``CLAUDE.local.md``
+and has no rules-directory support at all, so under DSH every one of those rules
+was inert: named in an injected file, never loaded, never applied.
+
+Shipping them as skills fixes that without changing the Claude Code surface. A
+skill is discovered by every editor that reads the shared skill catalogue, and
+the catalogue injects each skill's *description* into the session. So the
+description here is written as the rule itself in one imperative line — it is in
+context whether or not the model chooses to load the body.
+
+Idempotent: rerunning overwrites the generated ``SKILL.md`` and leaves anything
+else in the skill directory alone.
+
+Usage:
+    python3 scripts/generate_toolkit_rules_skills.py            # write all
+    python3 scripts/generate_toolkit_rules_skills.py --check    # dry-run
+    python3 scripts/generate_toolkit_rules_skills.py --rules git-conventions
+"""
+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"
+
+# The description is the rule. It is injected into every session through the
+# skill catalogue, so it has to state the obligation on its own — a reader who
+# never opens the body should still know what is required. Keep it imperative,
+# keep it one line, and put the reasoning in the file under app/rules/.
+DESCRIPTIONS: dict[str, str] = {
+    "edit-discipline": (
+        "Change files with the edit and write tools, never by rewriting them "
+        "through bash (sed, awk, tee, heredoc, redirection), and show `git diff` "
+        "before reporting a file-changing task as done. "
+        "Triggers: edit, write, modify, refactor, patch, fix, diff, review changes."
+    ),
+    "git-conventions": (
+        "Conventional Commits only (feat, fix, docs, refactor, test, chore); no "
+        "AI co-authorship trailer and no AI signature in a commit message. "
+        "Triggers: commit, git, message, changelog, release, pull request."
+    ),
+    "output-mode": (
+        "Answer concisely: lead with the result, no preamble, tables over prose, "
+        "no trailing restatement of a diff the reader can already see. "
+        "Triggers: response style, verbosity, summary, explanation, report."
+    ),
+    "quality-gates": (
+        "Plan before work over an hour, and hold the gates: ruff clean, mypy "
+        "--strict clean, pytest coverage above 70 percent, no secrets in code. "
+        "Triggers: quality, lint, mypy, pytest, coverage, gate, definition of done."
+    ),
+    "claude-toolkit-rules": (
+        "SoftSpark working agreement: never guess a home directory path, give at "
+        "least three alternatives, and apply a devil's advocate critique to "
+        "decisions. Triggers: toolkit, conventions, workflow, alternatives, review."
+    ),
+}
+
+
+def _strip_frontmatter(text: str) -> str:
+    """Remove YAML frontmatter (--- ... ---) if present."""
+    if not text.startswith("---\n"):
+        return text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return text
+    return text[end + len("\n---\n"):]
+
+
+def _title(stem: str) -> str:
+    return stem.replace("-", " ").title()
+
+
+def _build_skill_md(stem: str, rule_file: Path) -> str:
+    description = DESCRIPTIONS[stem]
+    body = _strip_frontmatter(rule_file.read_text(encoding="utf-8")).strip()
+    frontmatter = dedent(
+        f"""\
+        ---
+        name: {stem}
+        description: "{description}"
+        effort: low
+        user-invocable: false
+        allowed-tools: Read
+        ---
+
+        # {_title(stem)}
+
+        This rule comes from `app/rules/{stem}.md` in ai-toolkit. It applies to
+        every task in this workspace, not only when it is loaded.
+
+        """
+    )
+    return frontmatter + body + "\n"
+
+
+def discover_rules() -> list[str]:
+    """List top-level rule files that have a description to ship them under.
+
+    A rule with no entry in DESCRIPTIONS is skipped loudly rather than shipped
+    with a generated summary: the description is the part that reaches every
+    session, so it is written by a person.
+    """
+    if not RULES_DIR.is_dir():
+        return []
+    found: list[str] = []
+    for path in sorted(RULES_DIR.glob("*.md")):
+        if path.stem in DESCRIPTIONS:
+            found.append(path.stem)
+        else:
+            print(
+                f"  SKIP: {path.name} has no entry in DESCRIPTIONS; add one to ship it",
+                file=sys.stderr,
+            )
+    return found
+
+
+def generate(rules: list[str] | None = None, check: bool = False) -> int:
+    """Generate skills. Returns the number written, or that would be written."""
+    selected = rules if rules else discover_rules()
+    written = 0
+    for stem in selected:
+        rule_file = RULES_DIR / f"{stem}.md"
+        if not rule_file.is_file():
+            print(f"  SKIP: {stem} (app/rules/{stem}.md missing)", file=sys.stderr)
+            continue
+        if stem not in DESCRIPTIONS:
+            print(f"  SKIP: {stem} (no description)", file=sys.stderr)
+            continue
+
+        skill_dir = SKILLS_DIR / stem
+        skill_md = skill_dir / "SKILL.md"
+        content = _build_skill_md(stem, rule_file)
+
+        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:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="report drift, write nothing")
+    parser.add_argument("--rules", help="comma-separated rule stems")
+    args = parser.parse_args()
+
+    rules = [r.strip() for r in args.rules.split(",")] if args.rules else None
+    written = generate(rules, check=args.check)
+    if args.check:
+        if written:
+            print(f"{written} generated skill(s) differ from app/rules/", file=sys.stderr)
+            return 1
+        print("toolkit rule skills are up to date")
+        return 0
+    print(f"{written} toolkit rule skill(s) written")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/generate_windsurf_rules.py

@@ -50,7 +50,6 @@ from dir_rules_shared import (
     build_language_rules,
     build_registered_rules,
     cleanup_stale,
-    rule_testing,
     write_rules,
 )
 

package/scripts/generator_base.py

@@ -32,7 +32,6 @@ from __future__ import annotations
 
 import os
 import sys
-from pathlib import Path
 
 from paths import RULES_DIR
 

package/scripts/inject_hook_cli.py

@@ -221,8 +221,17 @@ def _entry_source(entry: dict) -> str | None:
     return None
 
 
+# Handler fields that change *how* a command hook is scheduled, not *what* it
+# runs. A legacy untagged entry that differs only in these is the same hook,
+# otherwise adding `async` or `timeout` to app/hooks.json would leave every
+# existing install running the old copy and the new copy side by side.
+_SCHEDULING_FIELDS = frozenset({
+    "async", "asyncRewake", "timeout", "statusMessage", "shell", "once", "if",
+})
+
+
 def _entry_signature(entry: dict) -> tuple:
-    """Return behavior-defining hook fields without source tags."""
+    """Return behavior-defining hook fields without source or scheduling tags."""
     handlers = []
     for hook in entry.get("hooks", []):
         if not isinstance(hook, dict):
@@ -230,7 +239,11 @@ def _entry_signature(entry: dict) -> tuple:
             continue
         handlers.append(
             tuple(
-                sorted((key, value) for key, value in hook.items() if key != "_source")
+                sorted(
+                    (key, value)
+                    for key, value in hook.items()
+                    if key != "_source" and key not in _SCHEDULING_FIELDS
+                )
             )
         )
     return (entry.get("matcher", ""), tuple(handlers))

package/scripts/inject_mcp_cli.py

@@ -55,7 +55,6 @@ from __future__ import annotations
 
 import copy
 import json
-import os
 import re
 import sys
 import urllib.parse
@@ -163,7 +162,7 @@ def _check_collisions(
 
     if not force:
         print(
-            f"Error: server name collision(s) in .mcp.json (re-run with --force):",
+            "Error: server name collision(s) in .mcp.json (re-run with --force):",
             file=sys.stderr,
         )
         for name, other_source in collisions:

package/scripts/install.py

@@ -41,6 +41,9 @@ Options:
   --persona <p>           backend-lead|frontend-lead|devops-eng|junior-dev
   --modules <list>        Install specific modules (comma-separated)
   --auto-detect           Detect project languages and install matching rules
+  --language-skills <s>   detected (default): turn off <lang>-rules/<lang>-patterns
+                          skills for languages no registered project uses;
+                          all: keep every language skill on (persisted)
   --status                Show installed modules and exit
 """
 from __future__ import annotations
@@ -50,7 +53,7 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _common import toolkit_dir, app_dir, inject_rule
+from _common import toolkit_dir, app_dir, inject_rule, should_install
 from emission import agent_count as count_agents, skill_count as count_skills
 
 # Step modules
@@ -223,6 +226,7 @@ def parse_args(argv: list[str]) -> dict:
         "refresh_base": False,
         "skip_register": False,
         "codex_skills": False,
+        "language_skills": "",
     }
     i = 0
     while i < len(argv):
@@ -283,6 +287,11 @@ def parse_args(argv: list[str]) -> dict:
             cfg["skip_register"] = True
         elif arg == "--codex-skills":
             cfg["codex_skills"] = True
+        elif arg.startswith("--language-skills="):
+            cfg["language_skills"] = arg.split("=", 1)[1]
+        elif arg == "--language-skills":
+            i += 1
+            cfg["language_skills"] = argv[i] if i < len(argv) else ""
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}")
             sys.exit(1)
@@ -335,6 +344,15 @@ def validate_args(cfg: dict) -> None:
             if c and c not in VALID_COMPONENTS:
                 errors.append(f"Unknown component in --skip: '{c}' (valid: {', '.join(sorted(VALID_COMPONENTS))})")
 
+    # Validate --language-skills
+    if cfg["language_skills"]:
+        from install_steps.skill_scope import VALID_SCOPES
+        if cfg["language_skills"] not in VALID_SCOPES:
+            errors.append(
+                f"Unknown --language-skills value: '{cfg['language_skills']}' "
+                f"(valid: {', '.join(VALID_SCOPES)})"
+            )
+
     # Validate --editors
     if cfg["editors"] and cfg["editors"] != "all":
         for e in cfg["editors"].split(","):
@@ -848,6 +866,19 @@ def main() -> None:
             if is_new:
                 print(f"  Registered project in {TOOLKIT_DATA_DIR / 'projects.json'}")
 
+    # Language knowledge skills are symlinked for every language, but their
+    # descriptions load into every session. Scope them to the languages the
+    # registered projects actually use (after registration, so a new project's
+    # language re-enables its skills in the same run). Read-only in dry-run.
+    if should_install("skills", only, skip):
+        from install_steps.skill_scope import reconcile_language_skill_overrides, resolve_scope
+        reconcile_language_skill_overrides(
+            toolkit_dir,
+            target_dir / ".claude" / "settings.json",
+            scope=resolve_scope(cfg["language_skills"]),
+            dry_run=dry_run,
+        )
+
     # A global install is authoritative for Claude Code, so an uploaded Claude
     # app plugin must not feed it in parallel. Uploading the ZIP re-enables the
     # plugin every time, so this is re-asserted on every install/update rather

package/scripts/install_git_hooks.py

@@ -11,7 +11,6 @@ Usage: python3 install_git_hooks.py [target-dir]
 """
 from __future__ import annotations
 
-import os
 import sys
 from pathlib import Path
 

package/scripts/install_steps/ai_tools.py

@@ -12,6 +12,7 @@ import subprocess
 from pathlib import Path
 
 from _common import app_dir, inject_section, toolkit_dir
+from frontmatter import FrontmatterError, parse_frontmatter, split_frontmatter
 from codex_skill_adapter import (
     cleanup_codex_skills,
     managed_skill_surface_transaction,
@@ -965,7 +966,7 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
         _apply_extends_config(cwd, merged_config)
 
     # Inject language-specific rules into project CLAUDE.md
-    _inject_language_rules(cwd, language_modules)
+    _inject_language_rules(cwd, language_modules, profile=profile)
 
     # Install editor configs only for resolved editors
     _create_local_ai_tool_configs(cwd, rules_dir, resolved_editors,
@@ -1061,17 +1062,21 @@ def _apply_extends_config(cwd: Path, merged: dict) -> None:
         print("  Saved: .softspark-toolkit-extends.json (resolution metadata)")
 
 
-def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
+def _inject_language_rules(cwd: Path, language_modules: list[str] | None,
+                           profile: str = "standard") -> None:
     """Install Claude language-rule entrypoints for a project.
 
     Per-language rules (``app/rules/<lang>/``) are NOT injected here -- they
     ship as ``<lang>-rules`` knowledge skills under ``app/skills/`` and load
     contextually via the Agent Skills progressive-disclosure mechanism.
 
-    Common rules are written as Claude Code path-scoped rules under
-    ``.claude/rules/``. Current Claude Code guidance targets under 200 lines
-    per ``CLAUDE.md`` file; path-scoped rules keep startup context smaller
-    while still loading the rule bodies when project files are opened.
+    Common rules are written as Claude Code rules under ``.claude/rules/``.
+    Each source rule's ``paths`` frontmatter decides whether it is always-on
+    (``**/*``: coding-style, git-workflow, security) or path-scoped (testing,
+    performance load only for matching files). Current Claude Code guidance
+    targets under 200 lines per ``CLAUDE.md`` file; keeping rule bodies out
+    of it and scoping the ones that are file-type specific keeps startup
+    context smaller.
     """
     if not language_modules:
         return
@@ -1081,7 +1086,7 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
     if not common_dir.is_dir():
         return
 
-    rule_files = _sync_claude_common_rules(cwd, common_dir)
+    rule_files = _sync_claude_common_rules(cwd, common_dir, profile)
 
     # Detect requested per-language modules so we can name the linked skills
     # in the marker block. The modules themselves are not inlined.
@@ -1095,12 +1100,18 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
     lines: list[str] = ["# Language Rules", ""]
     lines.append(
         "Common ai-toolkit rules live in `.claude/rules/ai-toolkit-*.md` "
-        "with Claude Code `paths` frontmatter so they load when project files "
-        "are opened instead of expanding this CLAUDE.md at session startup."
+        "with Claude Code `paths` frontmatter instead of expanding this "
+        "CLAUDE.md. Always-on rules load in every session; path-scoped rules "
+        "load only when a matching file is touched."
     )
-    if rule_files:
+    always_on = [p for p, on in rule_files if on]
+    scoped = [p for p, on in rule_files if not on]
+    if always_on:
         lines.append("")
-        lines.append("Common rule files: " + ", ".join(f"`{p}`" for p in rule_files) + ".")
+        lines.append("Always-on: " + ", ".join(f"`{p}`" for p in always_on) + ".")
+    if scoped:
+        lines.append("")
+        lines.append("Path-scoped: " + ", ".join(f"`{p}`" for p in scoped) + ".")
     lines.append("")
     lines.append(
         "Language-specific rules live in `<lang>-rules` knowledge skills "
@@ -1132,39 +1143,68 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
         tmp_path.unlink(missing_ok=True)
 
 
-def _strip_rule_frontmatter(text: str) -> str:
-    if text.startswith("---"):
-        end = text.find("\n---", 3)
-        if end != -1:
-            return text[end + 4:].lstrip("\n")
-    return text
+ALWAYS_ON_RULE_PATHS = ["**/*"]
+
 
+def _rule_source(src: Path) -> tuple[str, list[str], list[str]]:
+    """Return ``(body, paths, profiles)`` for one ``app/rules/common`` file.
 
-def _sync_claude_common_rules(cwd: Path, common_dir: Path) -> list[str]:
+    ``paths`` defaults to always-on (``**/*``); an empty ``profiles`` means
+    the rule ships in every profile. Shipped rules pass ``validate.py`` before
+    release, so a parse failure here is a broken install, not a soft case.
+    """
+    text = src.read_text(encoding="utf-8")
+    try:
+        _, body = split_frontmatter(text)
+        meta = parse_frontmatter(text)
+    except FrontmatterError as error:
+        raise RuntimeError(f"invalid frontmatter in {src}: {error}") from error
+    paths = meta.get("paths")
+    profiles = meta.get("profiles")
+    return (
+        body,
+        [str(p) for p in paths] if isinstance(paths, list) and paths else list(ALWAYS_ON_RULE_PATHS),
+        [str(p) for p in profiles] if isinstance(profiles, list) else [],
+    )
+
+
+def _sync_claude_common_rules(cwd: Path, common_dir: Path,
+                              profile: str = "standard") -> list[tuple[str, bool]]:
     """Write common ai-toolkit rules as Claude Code path-scoped rules.
 
+    Each source rule's ``paths`` frontmatter decides its scope; rules
+    without one are always-on. A ``profiles`` frontmatter restricts the rule
+    to those install profiles (``git-team`` ships with ``strict`` only); a
+    managed file whose rule no longer applies is removed, so switching profile
+    on a rerun converges. Returns ``(relative path, always_on)`` pairs.
+
     Only ``ai-toolkit-*.md`` files are managed. User-authored files in
     ``.claude/rules/`` are preserved.
     """
     rules_dir = cwd / ".claude" / "rules"
     rules_dir.mkdir(parents=True, exist_ok=True)
 
-    source_files = sorted(common_dir.glob("*.md"))
-    expected = {f"ai-toolkit-{src.stem}.md" for src in source_files}
+    source_files: list[tuple[Path, str, list[str]]] = []
+    for src in sorted(common_dir.glob("*.md")):
+        body, paths, gate = _rule_source(src)
+        if gate and profile not in gate:
+            continue
+        source_files.append((src, body, paths))
+    expected = {f"ai-toolkit-{src.stem}.md" for src, _, _ in source_files}
     for stale in sorted(rules_dir.glob("ai-toolkit-*.md")):
         if stale.name not in expected:
             stale.unlink()
 
-    written: list[str] = []
-    for src in source_files:
-        body = _strip_rule_frontmatter(src.read_text(encoding="utf-8")).rstrip()
+    written: list[tuple[str, bool]] = []
+    for src, body, paths in source_files:
+        body = body.lstrip("\n").rstrip()
         rel = Path(".claude") / "rules" / f"ai-toolkit-{src.stem}.md"
         target = cwd / rel
         target.write_text(
             "\n".join([
                 "---",
                 "paths:",
-                '  - "**/*"',
+                *[f'  - "{p}"' for p in paths],
                 "---",
                 "",
                 body,
@@ -1172,7 +1212,7 @@ def _sync_claude_common_rules(cwd: Path, common_dir: Path) -> list[str]:
             ]),
             encoding="utf-8",
         )
-        written.append(rel.as_posix())
+        written.append((rel.as_posix(), paths == ALWAYS_ON_RULE_PATHS))
 
     return written
 

package/scripts/install_steps/markers.py

@@ -214,10 +214,10 @@ def _refresh_url_rules(rules_dir: Path) -> None:
         except Exception as exc:
             if rule_file.is_file():
                 print(f"  Warning: could not refresh '{rule_name}' from {url}: {exc}")
-                print(f"           Using cached version.")
+                print("           Using cached version.")
             else:
                 print(f"  Warning: could not fetch '{rule_name}' from {url}: {exc}")
-                print(f"           No cached version — rule will be skipped.")
+                print("           No cached version — rule will be skipped.")
 
 
 def refresh_url_hooks(target_dir: str | None = None) -> None:
@@ -250,10 +250,10 @@ def refresh_url_hooks(target_dir: str | None = None) -> None:
         except Exception as exc:
             if cached_file.is_file():
                 print(f"  Warning: could not refresh '{hook_name}' from {url}: {exc}")
-                print(f"           Using cached version.")
+                print("           Using cached version.")
             else:
                 print(f"  Warning: could not fetch '{hook_name}' from {url}: {exc}")
-                print(f"           No cached version — hook will be skipped.")
+                print("           No cached version — hook will be skipped.")
                 continue
 
         # Re-inject from cached file
@@ -291,10 +291,10 @@ def refresh_url_mcp(target_dir: str | None = None) -> None:
         except Exception as exc:
             if cached_file.is_file():
                 print(f"  Warning: could not refresh '{template_name}' from {url}: {exc}")
-                print(f"           Using cached version.")
+                print("           Using cached version.")
             else:
                 print(f"  Warning: could not fetch '{template_name}' from {url}: {exc}")
-                print(f"           No cached version — template will be skipped.")
+                print("           No cached version — template will be skipped.")
                 continue
 
         if cached_file.is_file():