@softspark/ai-toolkit 2.11.0 → 3.0.0

package/scripts/generate_windsurf_rules.py

@@ -1,9 +1,21 @@
 #!/usr/bin/env python3
-"""Generate .windsurf/rules/*.md files for Windsurf IDE.
+"""Generate ``.windsurf/rules/*.md`` (and workflows) for Windsurf IDE.
 
-Windsurf reads directory-based rules from .windsurf/rules/*.md (since mid-2025).
-The legacy .windsurfrules single-file format is still generated separately
-by generate_windsurf.py for backwards compatibility.
+Windsurf reads directory-based rules from ``.windsurf/rules/*.md`` (since
+mid-2025). Each rule file supports YAML frontmatter with these fields
+(from docs.windsurf.com/windsurf/cascade/memories):
+
+* ``trigger`` — activation mode: ``always_on`` | ``glob`` | ``model_decision``
+  | ``manual``. When omitted, Windsurf defaults to manual-only.
+* ``globs`` — comma-separated glob patterns (only when ``trigger: glob``).
+* ``description`` — shown to the model when ``trigger: model_decision``.
+
+Windsurf also reads workflow markdown files from ``.windsurf/workflows/*.md``
+which users invoke via ``/<name>`` slash commands (Cascade). This generator
+emits the same workflow catalogue used by Antigravity and Cline.
+
+The legacy ``.windsurfrules`` single-file format is still produced by
+``generate_windsurf.py`` for backwards compatibility.
 
 Usage:
   python3 scripts/generate_windsurf_rules.py [target-dir]
@@ -15,21 +27,161 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from dir_rules_shared import (
+    CUSTOM_SCOPE,
+    LANG_GLOBS,
+    LANG_PREFIX,
+    LANG_SCOPE,
+    PREFIX,
     STANDARD_RULES,
+    STANDARD_SCOPE,
+    STANDARD_WORKFLOWS,
     build_language_rules,
     build_registered_rules,
+    cleanup_stale,
+    rule_testing,
     write_rules,
 )
 
 
+# ---------------------------------------------------------------------------
+# Frontmatter helpers — Windsurf rule activation modes
+# ---------------------------------------------------------------------------
+
+def _frontmatter(content: str, *,
+                 trigger: str,
+                 description: str = "",
+                 globs: list[str] | None = None) -> str:
+    """Prepend a Windsurf YAML frontmatter block to rule content.
+
+    ``trigger`` must be one of: ``always_on``, ``glob``, ``model_decision``,
+    ``manual``. ``description`` is shown to the model for ``model_decision``
+    mode; ignored otherwise. ``globs`` is only meaningful for ``glob`` mode.
+    """
+    lines = ["---", f"trigger: {trigger}"]
+    if description:
+        lines.append(f"description: {description}")
+    if trigger == "glob" and globs:
+        lines.append("globs: " + ",".join(globs))
+    lines.append("---")
+    lines.append("")
+    lines.append(content.rstrip("\n"))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _always_on(content_fn):
+    """Wrap a content callable so Windsurf treats it as always-on."""
+    return lambda: _frontmatter(content_fn(), trigger="always_on")
+
+
+def _glob_rule(content_fn, globs: list[str]):
+    """Wrap a content callable for Windsurf's glob activation mode."""
+    return lambda: _frontmatter(content_fn(), trigger="glob", globs=globs)
+
+
+def _model_decision(content_fn, description: str):
+    """Wrap a content callable for Windsurf's model-decision activation."""
+    return lambda: _frontmatter(
+        content_fn(), trigger="model_decision", description=description,
+    )
+
+
+def _build_rules(language_modules: list[str] | None,
+                 rules_dir: Path | None) -> dict[str, callable]:
+    """Build the full rule registry with per-rule activation frontmatter."""
+    rules: dict[str, callable] = {}
+
+    # Standard rules: agents/skills index + quality/security are always-on.
+    # Code style + testing + workflow are model-decision so Cascade only
+    # expands them when relevant.
+    always_on_names = {
+        f"{PREFIX}agents-and-skills.md",
+        f"{PREFIX}security.md",
+        f"{PREFIX}quality-standards.md",
+    }
+    model_decision_descs = {
+        f"{PREFIX}code-style.md":
+            "Code style conventions for all languages",
+        f"{PREFIX}workflow.md":
+            "Development workflow, commits, and quality gates",
+    }
+    testing_globs = ["**/*.test.*", "**/*.spec.*", "**/test_*", "**/tests/**"]
+
+    for filename, content_fn in STANDARD_RULES.items():
+        if filename in always_on_names:
+            rules[filename] = _always_on(content_fn)
+        elif filename == f"{PREFIX}testing.md":
+            rules[filename] = _glob_rule(content_fn, testing_globs)
+        elif filename in model_decision_descs:
+            rules[filename] = _model_decision(
+                content_fn, model_decision_descs[filename],
+            )
+        else:
+            rules[filename] = _always_on(content_fn)
+
+    # Language rules: scope to their own file globs so they activate only
+    # when touching matching files.
+    for filename, content_fn in build_language_rules(language_modules).items():
+        lang = filename.removeprefix(LANG_PREFIX).removesuffix(".md")
+        if lang == "common":
+            rules[filename] = _always_on(content_fn)
+            continue
+        globs = LANG_GLOBS.get(lang)
+        if globs:
+            rules[filename] = _glob_rule(content_fn, globs)
+        else:
+            rules[filename] = _always_on(content_fn)
+
+    # Custom user-registered rules — always-on by default (user intent).
+    rules.update({
+        name: _always_on(fn)
+        for name, fn in build_registered_rules(rules_dir).items()
+    })
+
+    return rules
+
+
+# ---------------------------------------------------------------------------
+# Workflows — .windsurf/workflows/<name>.md invocable via /<name>
+# ---------------------------------------------------------------------------
+
+def _write_workflows(target_dir: Path, *, cleanup: bool = True) -> None:
+    """Write ``.windsurf/workflows/*.md`` files for Cascade slash commands."""
+    workflows_dir = target_dir / ".windsurf" / "workflows"
+    workflows_dir.mkdir(parents=True, exist_ok=True)
+
+    if cleanup:
+        cleanup_stale(workflows_dir, set(STANDARD_WORKFLOWS.keys()))
+
+    for filename, content_fn in STANDARD_WORKFLOWS.items():
+        (workflows_dir / filename).write_text(content_fn(), encoding="utf-8")
+        print(f"  Generated: .windsurf/workflows/{filename}")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
 def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
-             rules_dir: Path | None = None) -> None:
-    """Write .windsurf/rules/*.md files to target_dir."""
-    rules = dict(STANDARD_RULES)
-    rules.update(build_language_rules(language_modules))
-    rules.update(build_registered_rules(rules_dir))
-    write_rules(target_dir, rules, ".windsurf/rules")
+             rules_dir: Path | None = None,
+             cleanup: bool = True,
+             emit_workflows: bool = True,
+             managed_scopes: tuple[str, ...] = (
+                 STANDARD_SCOPE, LANG_SCOPE, CUSTOM_SCOPE,
+             )) -> None:
+    """Write ``.windsurf/rules/*.md`` and ``.windsurf/workflows/*.md``."""
+    rules = _build_rules(language_modules, rules_dir)
+    write_rules(
+        target_dir,
+        rules,
+        ".windsurf/rules",
+        cleanup=cleanup,
+        managed_scopes=managed_scopes,
+    )
+
+    if emit_workflows:
+        _write_workflows(target_dir, cleanup=cleanup)
 
 
 def main() -> None:

package/scripts/install.py

@@ -216,6 +216,7 @@ def parse_args(argv: list[str]) -> dict:
         "config": "",
         "refresh_base": False,
         "skip_register": False,
+        "codex_skills": False,
     }
     i = 0
     while i < len(argv):
@@ -274,6 +275,8 @@ def parse_args(argv: list[str]) -> dict:
             cfg["refresh_base"] = True
         elif arg == "--skip-register":
             cfg["skip_register"] = True
+        elif arg == "--codex-skills":
+            cfg["codex_skills"] = True
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}")
             sys.exit(1)
@@ -361,8 +364,12 @@ def resolve_profile(profile: str, only: str) -> str:
         pass
     elif profile == "strict":
         pass
+    elif profile == "full":
+        # `full` is a `standard`-shaped install for Claude Code components;
+        # the extra native surfaces are wired into editor-local generators.
+        pass
     else:
-        print(f"Unknown profile: {profile} (valid: minimal, standard, strict)")
+        print(f"Unknown profile: {profile} (valid: minimal, standard, strict, full)")
         sys.exit(1)
     return only
 
@@ -714,7 +721,9 @@ def main() -> None:
         local_editors_arg: str = cfg["editors"]
         install_local_project(rules_dir, dry_run, reset, lang_modules or None,
                               editors=local_editors_arg,
-                              merged_config=merged_config)
+                              merged_config=merged_config,
+                              profile=profile or "standard",
+                              codex_skills=cfg.get("codex_skills", False))
         installed_eds: list[str] = []  # local install doesn't track global editors
         install_strict_git_hooks(profile, local, dry_run)
     else:

package/scripts/install_steps/ai_tools.py

@@ -314,7 +314,9 @@ def _resolve_editors(editors_arg: str, cwd: Path) -> list[str]:
 def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
                           language_modules: list[str] | None = None,
                           editors: str = "",
-                          merged_config: dict | None = None) -> None:
+                          merged_config: dict | None = None,
+                          profile: str = "standard",
+                          codex_skills: bool = False) -> None:
     """Install project-local configs.
 
     Claude Code configs (CLAUDE.md, settings, constitution) are always installed.
@@ -323,6 +325,17 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
     - ``--editors cursor,aider``: install only these
     - (empty): auto-detect from existing project files, install only those
 
+    ``profile`` controls which native surfaces are emitted for each editor:
+    - ``minimal``  / ``standard`` / ``strict``: rules (+ Copilot directory mode
+      and Gemini hooks from ``standard`` onwards — both non-breaking).
+    - ``full``: adds every native surface an editor can host (subagents,
+      custom commands, hooks, skill-catalogue pointers).
+
+    ``codex_skills`` (opt-in, off by default) additionally writes a full skill
+    mirror under ``.codex/skills/``. Required even for ``--profile full`` —
+    the mirror is intentionally gated behind an extra flag to keep the default
+    footprint small.
+
     If ``merged_config`` is provided (from .softspark-toolkit.json extends resolution),
     additional rules and constitution amendments from the base config are injected.
     """
@@ -340,10 +353,13 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
         print(f"   Editors: {', '.join(resolved_editors)}")
     else:
         print("   Editors: none (use --editors <list> or --editors all to enable)")
+    if profile:
+        print(f"   Profile: {profile}")
     print()
 
     if dry_run:
-        _install_local_dry_run(reset, resolved_editors)
+        _install_local_dry_run(reset, resolved_editors, profile=profile,
+                               codex_skills=codex_skills)
         if language_modules:
             print(f"  Would inject language rules: {', '.join(language_modules)}")
         if merged_config:
@@ -382,7 +398,9 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
 
     # Install editor configs only for resolved editors
     _create_local_ai_tool_configs(cwd, rules_dir, resolved_editors,
-                                  language_modules=language_modules)
+                                  language_modules=language_modules,
+                                  profile=profile,
+                                  codex_skills=codex_skills)
 
 
 def _apply_extends_config(cwd: Path, merged: dict) -> None:
@@ -533,7 +551,9 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
         tmp_path.unlink(missing_ok=True)
 
 
-def _install_local_dry_run(reset: bool, editors: list[str] | None = None) -> None:
+def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
+                            profile: str = "standard",
+                            codex_skills: bool = False) -> None:
     eds = set(editors or [])
     if reset:
         print("  Would remove: CLAUDE.md, .claude/settings.local.json")
@@ -544,6 +564,10 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None) -> Non
         print("  Would create: .claude/settings.local.json (if missing)")
         print("  Would inject: .claude/constitution.md")
 
+    add_copilot_dir = profile in {"standard", "strict", "full"}
+    add_gemini_hooks = profile in {"standard", "strict", "full"}
+    add_native_surfaces = profile == "full"
+
     # Editor-specific dry-run messages
     _EDITOR_DRY_RUN = {
         "copilot":      "  Would inject: .github/copilot-instructions.md",
@@ -554,12 +578,31 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None) -> Non
         "aider":        "  Would generate: .aider.conf.yml + CONVENTIONS.md",
         "augment":      "  Would generate: .augment/rules/ai-toolkit-*.md",
         "antigravity":  "  Would generate: .agent/rules/ + .agent/workflows/",
+        "gemini":       "  Would generate: GEMINI.md",
         "opencode":     "  Would generate: AGENTS.md + .opencode/{agents,commands,plugins}/ + opencode.json",
     }
     for ed, msg in _EDITOR_DRY_RUN.items():
         if ed in eds:
             print(msg)
 
+    # Profile-driven extras (matrix in kb/reference/global-install-model.md)
+    if "copilot" in eds and add_copilot_dir:
+        print("  Would generate: .github/instructions/ + .github/prompts/ (profile >= standard)")
+    if "gemini" in eds and add_gemini_hooks:
+        print("  Would generate: .gemini/settings.json hooks (profile >= standard)")
+    if add_native_surfaces:
+        if "cursor" in eds:
+            print("  Would generate: .cursor/hooks.json + .cursor/agents/ (profile=full)")
+        if "windsurf" in eds:
+            print("  Would generate: .windsurf/hooks.json (profile=full)")
+        if "augment" in eds:
+            print("  Would generate: .augment/agents/ + .augment/commands/ + "
+                  "$HOME/.augment/settings.json + .augment/skills/ (profile=full)")
+        if "gemini" in eds:
+            print("  Would generate: .gemini/commands/ + .gemini/skills/ (profile=full)")
+    if "codex" in eds and codex_skills:
+        print("  Would generate: .codex/skills/ full mirror (--codex-skills)")
+
     if not eds:
         print("  No editors selected (use --editors <list> or --editors all)")
 
@@ -695,10 +738,46 @@ def _install_codex_skills(cwd: Path) -> None:
     )
 
 
+def _try_generator(module_name: str, *args, **kwargs) -> bool:
+    """Import and invoke ``<module>.generate(...)``.
+
+    Post v3.0.0 all referenced generators ship with the toolkit. An ImportError
+    here therefore indicates a real packaging bug, not a roll-out gap. We print
+    a loud error and re-raise so CI and interactive installs fail fast instead
+    of silently skipping a native surface.
+    """
+    try:
+        module = __import__(module_name)
+    except ImportError as exc:
+        print(f"  INTERNAL ERROR: shipped generator '{module_name}' failed to "
+              f"import ({exc.msg}). Please file a bug at "
+              f"https://github.com/softspark/ai-toolkit/issues")
+        raise
+
+    gen = getattr(module, "generate", None)
+    if gen is None:
+        raise RuntimeError(
+            f"INTERNAL ERROR: shipped generator '{module_name}' has no "
+            f"generate() function. This is a packaging bug."
+        )
+
+    gen(*args, **kwargs)
+    return True
+
+
 def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
                                    editors: list[str],
-                                   language_modules: list[str] | None = None) -> None:
+                                   language_modules: list[str] | None = None,
+                                   profile: str = "standard",
+                                   codex_skills: bool = False) -> None:
     eds = set(editors)
+    # `full` implies the `standard` additions (Copilot dir + Gemini hooks)
+    # plus every native-surface generator we ship. Normalize unknown
+    # profiles to `standard` so callers never produce a silent no-op.
+    _profile = profile if profile in {"minimal", "standard", "strict", "full"} else "standard"
+    add_copilot_dir = _profile in {"standard", "strict", "full"}
+    add_gemini_hooks = _profile in {"standard", "strict", "full"}
+    add_native_surfaces = _profile == "full"
 
     if "copilot" in eds:
         inject_with_rules(
@@ -706,6 +785,12 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             cwd / ".github" / "copilot-instructions.md",
             rules_dir,
         )
+        # `standard` and above: emit path-specific instructions + prompt files
+        # (directory mode). `minimal` stays backwards-compatible with v2.
+        if add_copilot_dir:
+            from generate_copilot import generate as gen_copilot_dir
+            gen_copilot_dir(cwd, language_modules=language_modules,
+                            rules_dir=rules_dir)
 
     if "cursor" in eds:
         inject_with_rules(
@@ -716,6 +801,9 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         from generate_cursor_mdc import generate as gen_cursor_mdc
         gen_cursor_mdc(cwd, language_modules=language_modules,
                        rules_dir=rules_dir)
+        if add_native_surfaces:
+            _try_generator("generate_cursor_hooks", cwd)
+            _try_generator("generate_cursor_agents", cwd)
 
     if "windsurf" in eds:
         inject_with_rules(
@@ -726,6 +814,8 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         from generate_windsurf_rules import generate as gen_windsurf_rules
         gen_windsurf_rules(cwd, language_modules=language_modules,
                            rules_dir=rules_dir)
+        if add_native_surfaces:
+            _try_generator("generate_windsurf_hooks", cwd)
 
     if "cline" in eds:
         # Migrate: remove legacy .clinerules single file (replaced by directory)
@@ -759,6 +849,13 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         from generate_augment_rules import generate as gen_augment_rules
         gen_augment_rules(cwd, language_modules=language_modules,
                           rules_dir=rules_dir)
+        if add_native_surfaces:
+            _try_generator("generate_augment_agents", cwd)
+            _try_generator("generate_augment_commands", cwd)
+            # Augment hooks live under $HOME/.augment/settings.json. The
+            # generator takes HOME (not cwd) per bucket-1 contract.
+            _try_generator("generate_augment_hooks", Path.home())
+            _try_generator("generate_augment_skills", cwd)
 
     if "antigravity" in eds:
         from generate_antigravity import generate as gen_antigravity
@@ -786,6 +883,24 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         print("  Created: .codex/hooks.json")
         # .agents/skills/ — filtered symlinks (Codex-compatible skills only)
         _install_codex_skills(cwd)
+        # .codex/skills/ — full mirror, gated behind explicit --codex-skills flag
+        # (does NOT activate automatically on --profile full — must opt in).
+        if codex_skills:
+            _try_generator("generate_codex_skills", cwd,
+                           enable_codex_skills=True)
+
+    if "gemini" in eds:
+        # GEMINI.md — marker injection from the shared generator output
+        inject_with_rules(
+            "generate-gemini.sh",
+            cwd / "GEMINI.md",
+            rules_dir,
+        )
+        if add_gemini_hooks:
+            _try_generator("generate_gemini_hooks", cwd)
+        if add_native_surfaces:
+            _try_generator("generate_gemini_commands", cwd)
+            _try_generator("generate_gemini_skills", cwd)
 
     if "opencode" in eds:
         # AGENTS.md — shared with Codex via marker injection (opencode reads same file)

package/scripts/validate.py

@@ -39,9 +39,26 @@ VALID_TOOLS = frozenset({
 })
 
 VALID_HOOK_EVENTS = frozenset({
-    "SessionStart", "Notification", "PreToolUse", "PostToolUse", "Stop",
-    "PreCompact", "SubagentStop", "UserPromptSubmit", "TaskCompleted",
-    "TeammateIdle", "SubagentStart", "SessionEnd", "PermissionRequest", "Setup",
+    # Core lifecycle
+    "SessionStart", "SessionEnd", "UserPromptSubmit", "Notification",
+    # Tool lifecycle
+    "PreToolUse", "PostToolUse",
+    # Turn lifecycle
+    "Stop", "StopFailure",
+    # Subagent lifecycle
+    "SubagentStart", "SubagentStop",
+    # Compaction
+    "PreCompact", "PostCompact",
+    # Permissions & elicitation
+    "PermissionRequest", "PermissionDenied",
+    "Elicitation", "ElicitationResult",
+    # Agent Teams
+    "TaskCreated", "TaskCompleted", "TeammateIdle",
+    # Worktrees & environment
+    "WorktreeCreate", "WorktreeRemove",
+    "CwdChanged", "FileChanged", "ConfigChange",
+    # Setup / bootstrap
+    "Setup", "InstructionsLoaded",
 })
 
 VALID_KB_CATEGORIES = frozenset({