@softspark/ai-toolkit 4.10.1 → 4.11.0

package/scripts/install_steps/ai_tools.py

@@ -661,17 +661,16 @@ def _apply_extends_config(cwd: Path, merged: dict) -> None:
 
 
 def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
-    """Inject ``app/rules/common/*.md`` content into project's ``.claude/CLAUDE.md``.
+    """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. This
-    keeps ``CLAUDE.md`` small while ensuring language-specific guidance still
-    reaches Claude when relevant.
+    contextually via the Agent Skills progressive-disclosure mechanism.
 
-    Common rules are language-agnostic (security, git workflow, testing,
-    coding-style, performance) and stay inlined so they remain in scope for
-    every prompt.
+    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.
     """
     if not language_modules:
         return
@@ -681,6 +680,8 @@ 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)
+
     # Detect requested per-language modules so we can name the linked skills
     # in the marker block. The modules themselves are not inlined.
     langs: list[str] = []
@@ -690,38 +691,30 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
             if name != "common":
                 langs.append(name)
 
-    # Inline full content of every common rule file, stripping YAML
-    # frontmatter so the resulting block reads as plain Markdown.
-    inlined: list[str] = []
-    for f in sorted(common_dir.glob("*.md")):
-        body = f.read_text(encoding="utf-8")
-        if body.startswith("---"):
-            end = body.find("\n---", 3)
-            if end != -1:
-                body = body[end + 4:].lstrip("\n")
-        inlined.append(body.rstrip())
-
     lines: list[str] = ["# Language Rules", ""]
     lines.append(
-        "Common (language-agnostic) rules apply to every change in this "
-        "project. Language-specific rules live in `<lang>-rules` knowledge "
-        "skills (e.g. `python-rules`, `typescript-rules`) and load "
-        "automatically when their triggers match -- you do not need to "
-        "Read them manually."
+        "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."
+    )
+    if rule_files:
+        lines.append("")
+        lines.append("Common rule files: " + ", ".join(f"`{p}`" for p in rule_files) + ".")
+    lines.append("")
+    lines.append(
+        "Language-specific rules live in `<lang>-rules` knowledge skills "
+        "(e.g. `python-rules`, `typescript-rules`) and load automatically "
+        "when their triggers match -- you do not need to Read them manually."
     )
     if langs:
         skill_names = ", ".join(f"`{l}-rules`" for l in langs)
         lines.append("")
         lines.append(f"Detected languages: {skill_names}.")
-    lines.append("")
-    lines.append("---")
-    lines.append("")
-    lines.extend(inlined)
 
     # Write to temp file, then inject as a single named section so reruns are
     # idempotent (existing block is replaced, not duplicated).
     import tempfile
-    combined = "\n\n".join(lines).rstrip() + "\n"
+    combined = "\n".join(lines).rstrip() + "\n"
     with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False,
                                      encoding="utf-8") as tmp:
         tmp.write(combined)
@@ -738,6 +731,51 @@ 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
+
+
+def _sync_claude_common_rules(cwd: Path, common_dir: Path) -> list[str]:
+    """Write common ai-toolkit rules as Claude Code path-scoped rules.
+
+    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}
+    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()
+        rel = Path(".claude") / "rules" / f"ai-toolkit-{src.stem}.md"
+        target = cwd / rel
+        target.write_text(
+            "\n".join([
+                "---",
+                "paths:",
+                '  - "**/*"',
+                "---",
+                "",
+                body,
+                "",
+            ]),
+            encoding="utf-8",
+        )
+        written.append(rel.as_posix())
+
+    return written
+
+
 def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
                             profile: str = "standard",
                             codex_skills: bool = False) -> None:
@@ -750,6 +788,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         print("  Would create: CLAUDE.md (if missing)")
         print("  Would create: .claude/settings.local.json (if missing)")
         print("  Would inject: .claude/constitution.md")
+        print("  Would generate: .claude/rules/ai-toolkit-*.md")
 
     add_copilot_dir = profile in {"standard", "strict", "full"}
     add_gemini_hooks = profile in {"standard", "strict", "full"}

package/scripts/install_steps/markers.py

@@ -1,9 +1,21 @@
-"""Marker file injection and rule injection."""
+"""Marker file injection and rule installation."""
 from __future__ import annotations
 
+import re
 from pathlib import Path
 
-from _common import app_dir, inject_rule, inject_section, should_install
+from _common import (
+    app_dir,
+    inject_section,
+    remove_rule_section,
+    should_install,
+    _collapse_blank_runs,
+    _strip_section,
+    _trim_trailing_blanks,
+)
+
+
+GLOBAL_RULES_SECTION = "global-rules"
 
 
 def install_marker_files(claude_dir: Path, only: str, skip: str,
@@ -34,7 +46,7 @@ def install_marker_files(claude_dir: Path, only: str, skip: str,
 def inject_rules(claude_dir: Path, target_dir: Path, rules_dir: Path,
                  only: str, skip: str, dry_run: bool,
                  refresh_urls: bool = False) -> None:
-    """Inject rules into CLAUDE.md.
+    """Install Claude Code user-level rules.
 
     When refresh_urls is True, re-fetches URL-sourced rules before injection.
     Only the global install path should set this to True (once per update).
@@ -53,26 +65,131 @@ def inject_rules(claude_dir: Path, target_dir: Path, rules_dir: Path,
         claude_md.touch()
         print("  Created: ~/.claude/CLAUDE.md")
 
-    if not should_install("rules", only, skip):
-        print("  Skipped: rules injection")
+    install_toolkit_rules = should_install("rules", only, skip)
+    if not install_toolkit_rules:
+        print("  Skipped: toolkit rule files")
 
-    rules_injected: list[str] = []
+    expected: set[str] = set()
+    rules_synced: list[str] = []
 
     if rules_dir.is_dir():
         for rule_file in sorted(rules_dir.glob("*.md")):
             rule_name = rule_file.stem
-            inject_rule(rule_file, target_dir)
-            rules_injected.append(rule_name)
+            output_name = f"ai-toolkit-registered-{_safe_rule_name(rule_name)}"
+            _write_claude_rule_file(claude_dir, rule_file, output_name)
+            _remove_legacy_rule_marker(target_dir, rule_name)
+            expected.add(output_name)
+            rules_synced.append(rule_name)
 
-    if should_install("rules", only, skip):
+    if install_toolkit_rules:
         rules_src = app_dir / "rules"
         if rules_src.is_dir():
             for source_file in sorted(rules_src.glob("*.md")):
                 rule_name = source_file.stem
-                inject_rule(source_file, target_dir)
-                rules_injected.append(rule_name)
+                output_name = f"ai-toolkit-{_safe_rule_name(rule_name)}"
+                _write_claude_rule_file(claude_dir, source_file, output_name)
+                _remove_legacy_rule_marker(target_dir, rule_name)
+                expected.add(output_name)
+                rules_synced.append(rule_name)
+
+    if not install_toolkit_rules and not rules_synced:
+        return
 
-    print(f"  Rules injected: {' '.join(rules_injected)}")
+    removed = _cleanup_managed_claude_rules(
+        claude_dir,
+        expected,
+        cleanup_toolkit_rules=install_toolkit_rules,
+    )
+    _inject_global_rules_index(claude_md, sorted(expected), rules_synced)
+
+    print(f"  Rules synced: {' '.join(rules_synced)}")
+    if removed:
+        print(f"  Cleaned: {removed} stale .claude/rules/ai-toolkit-*.md file(s)")
+
+
+def _safe_rule_name(name: str) -> str:
+    """Return a Claude-safe filename/marker stem."""
+    return re.sub(r"[^a-zA-Z0-9_-]", "", name)
+
+
+def _write_claude_rule_file(
+    claude_dir: Path,
+    source_file: Path,
+    output_name: str,
+) -> None:
+    """Write a managed user-level rule under ``~/.claude/rules``."""
+    rules_root = claude_dir / "rules"
+    rules_root.mkdir(parents=True, exist_ok=True)
+    dst = rules_root / f"{output_name}.md"
+    content = source_file.read_text(encoding="utf-8").rstrip() + "\n"
+    dst.write_text(content, encoding="utf-8")
+
+
+def _remove_legacy_rule_marker(target_dir: Path, rule_name: str) -> None:
+    """Remove old CLAUDE.md marker sections for rules now stored as files."""
+    remove_rule_section(_safe_rule_name(rule_name), target_dir)
+
+
+def _cleanup_managed_claude_rules(
+    claude_dir: Path,
+    expected: set[str],
+    *,
+    cleanup_toolkit_rules: bool,
+) -> int:
+    """Remove stale ai-toolkit-managed user-level rule files only."""
+    rules_root = claude_dir / "rules"
+    if not rules_root.is_dir():
+        return 0
+
+    removed = 0
+    for path in sorted(rules_root.glob("ai-toolkit-*.md")):
+        if path.stem in expected:
+            continue
+        if not cleanup_toolkit_rules and not path.stem.startswith("ai-toolkit-registered-"):
+            continue
+        path.unlink()
+        removed += 1
+    return removed
+
+
+def _inject_global_rules_index(
+    claude_md: Path,
+    managed_rule_names: list[str],
+    display_names: list[str],
+) -> None:
+    """Keep CLAUDE.md as a compact pointer to user-level rule files."""
+    existing = claude_md.read_text(encoding="utf-8") if claude_md.is_file() else ""
+    existing = _trim_trailing_blanks(_strip_section(existing, GLOBAL_RULES_SECTION))
+
+    lines = [
+        "# Global ai-toolkit Rules",
+        "",
+        "ai-toolkit rules live in `~/.claude/rules/ai-toolkit-*.md` as Claude Code user-level rules.",
+        "They are intentionally not inlined into this `CLAUDE.md`; use `/memory` to inspect loaded rule files.",
+    ]
+    if display_names:
+        names = ", ".join(f"`{name}`" for name in display_names)
+        lines.extend(["", f"Rules: {names}"])
+    if managed_rule_names:
+        files = ", ".join(f"`~/.claude/rules/{name}.md`" for name in managed_rule_names)
+        lines.extend(["", f"Files: {files}"])
+
+    parts: list[str] = []
+    if existing.strip():
+        parts.append(existing)
+        parts.append("")
+    parts.extend([
+        f"<!-- TOOLKIT:{GLOBAL_RULES_SECTION} START -->",
+        "<!-- Auto-injected by ai-toolkit. Re-run to update. -->",
+        "",
+        "\n".join(lines),
+        "",
+        f"<!-- TOOLKIT:{GLOBAL_RULES_SECTION} END -->",
+    ])
+
+    output = _collapse_blank_runs("\n".join(parts) + "\n").lstrip("\n")
+    claude_md.parent.mkdir(parents=True, exist_ok=True)
+    claude_md.write_text(output, encoding="utf-8")
 
 
 def _refresh_url_rules(rules_dir: Path) -> None:
@@ -186,9 +303,10 @@ def _inject_rules_dry_run(rules_dir: Path) -> None:
     rule_names = " ".join(
         f.stem for f in sorted(rules_src.glob("*.md"))
     ) if rules_src.is_dir() else ""
-    print(f"  Would inject rules: {rule_names}")
+    print(f"  Would generate: ~/.claude/rules/ai-toolkit-*.md ({rule_names})")
     if rules_dir.is_dir():
         registered = list(rules_dir.glob("*.md"))
         if registered:
             reg_names = " ".join(f.stem for f in sorted(registered))
-            print(f"  Would inject registered rules: {reg_names}")
+            print(f"  Would generate: ~/.claude/rules/ai-toolkit-registered-*.md ({reg_names})")
+    print("  Would update: ~/.claude/CLAUDE.md global rules index")

package/scripts/remove_rule.py

@@ -2,8 +2,9 @@
 """remove-rule -- Unregister a rule (opposite of add-rule).
 
 Removes the rule file from ~/.softspark/ai-toolkit/rules/ (so it is no longer
-re-applied on future 'ai-toolkit install' runs) AND strips its injected
-block from the target CLAUDE.md.
+re-applied on future 'ai-toolkit install' runs), removes the generated Claude
+Code user-level rule file, and strips the legacy injected block from
+CLAUDE.md.
 
 Usage:
   remove_rule.py <rule-name> [target-dir]
@@ -16,13 +17,14 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+import re
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import remove_rule_section
 
 
 def main() -> None:
-    """Unregister a rule and strip its injected block."""
+    """Unregister a rule and remove generated Claude rule artifacts."""
     if len(sys.argv) < 2:
         print("Usage: remove_rule.py <rule-name> [target-dir]", file=sys.stderr)
         sys.exit(1)
@@ -48,7 +50,16 @@ def main() -> None:
     if unregister_source(rules_dir, rule_name):
         print(f"Removed URL source for '{rule_name}'")
 
-    # 2. Strip injected block from .claude/CLAUDE.md
+    safe_rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_name)
+
+    # 2. Remove generated Claude Code user-level rule file
+    generated_rule = target_dir / ".claude" / "rules" / f"ai-toolkit-registered-{safe_rule_name}.md"
+    if generated_rule.is_file():
+        generated_rule.unlink()
+        print(f"Removed generated Claude rule: {generated_rule}")
+        removed += 1
+
+    # 3. Strip legacy injected block from .claude/CLAUDE.md
     found = remove_rule_section(rule_name, target_dir)
     if found:
         print(f"Removed rule '{rule_name}' from {target_dir / '.claude' / 'CLAUDE.md'}")