npm - @softspark/ai-toolkit - Versions diffs - 2.12.0 → 3.0.0 - Mend

@softspark/ai-toolkit 2.12.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/CHANGELOG.md +38 -0
package/README.md +18 -8
package/app/.claude-plugin/plugin.json +1 -1
package/app/skills/hook-creator/SKILL.md +84 -8
package/app/skills/skill-creator/SKILL.md +8 -4
package/benchmarks/ecosystem-doctor-snapshot.json +395 -0
package/kb/history/completed/deep-coverage-v3-20260423.md +160 -0
package/kb/history/completed/ecosystem-deep-sweep-20260423.md +273 -0
package/kb/procedures/ecosystem-sync-sop.md +255 -0
package/kb/procedures/maintenance-sop.md +13 -2
package/kb/procedures/release-preparation-sop.md +83 -10
package/kb/reference/global-install-model.md +15 -2
package/kb/reference/supported-tools-registry.md +229 -0
package/llms-full.txt +1052 -14
package/llms.txt +4 -0
package/manifest.json +1 -1
package/package.json +4 -1
package/scripts/ecosystem_doctor.py +348 -0
package/scripts/ecosystem_tools.json +500 -0
package/scripts/generate_aider_conf.py +26 -1
package/scripts/generate_antigravity.py +77 -8
package/scripts/generate_augment_agents.py +161 -0
package/scripts/generate_augment_commands.py +160 -0
package/scripts/generate_augment_hooks.py +162 -0
package/scripts/generate_augment_skills.py +98 -0
package/scripts/generate_cline_rules.py +96 -9
package/scripts/generate_codex_hooks.py +13 -2
package/scripts/generate_codex_skills.py +195 -0
package/scripts/generate_copilot.py +296 -18
package/scripts/generate_cursor_agents.py +144 -0
package/scripts/generate_cursor_hooks.py +155 -0
package/scripts/generate_cursor_mdc.py +20 -8
package/scripts/generate_gemini_commands.py +158 -0
package/scripts/generate_gemini_hooks.py +159 -0
package/scripts/generate_gemini_skills.py +98 -0
package/scripts/generate_roo_modes.py +42 -1
package/scripts/generate_windsurf_hooks.py +143 -0
package/scripts/generate_windsurf_rules.py +162 -10
package/scripts/install.py +11 -2
package/scripts/install_steps/ai_tools.py +120 -5
package/scripts/validate.py +20 -3

package/scripts/generate_augment_agents.py ADDED Viewed

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Generate ``.augment/agents/ai-toolkit-*.md`` files for Augment Code.
+Each ai-toolkit agent in ``app/agents/`` is mirrored as an Augment native
+subagent. Augment's subagent frontmatter (per docs.augmentcode.com) supports:
+    ---
+    name: <slug>
+    description: "<single-line description>"
+    model: inherit            # or explicit model id
+    color: <color-name>       # optional UI hint
+    tools: [Read, Write, ...]
+    disabled_tools: []
+    ---
+    <body from agent file>
+Design choices:
+* ``model: inherit`` is used unconditionally. ai-toolkit stores short aliases
+  (``opus``/``sonnet``/``haiku``) that do not map to Augment's full model ids
+  without assuming a provider, so we defer to the user's default model.
+* ``tools`` are passed through verbatim from the source file, normalized into
+  YAML flow-list form (``[Read, Write, ...]``) so Augment parses them as a
+  native list.
+* ``disabled_tools: []`` is emitted as an explicit empty list to match the
+  shape Augment's UI expects when reading back the file.
+* Files are prefixed ``ai-toolkit-`` so uninstall can identify ours without
+  touching user-authored agents.
+* Regeneration removes stale ``ai-toolkit-*.md`` files whose source agent
+  no longer exists.
+Usage:
+  python3 scripts/generate_augment_agents.py [target-dir]
+Writes files to ``target-dir/.augment/agents/``.
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import agents_dir
+from frontmatter import frontmatter_field
+AGENT_PREFIX = "ai-toolkit-"
+def _agent_body(agent_file: Path) -> str:
+    """Return the markdown body of an agent file (content after frontmatter)."""
+    text = agent_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text.strip() + "\n"
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return text.strip() + "\n"
+    return parts[2].lstrip("\n")
+def _parse_tools(tools_raw: str) -> list[str]:
+    """Parse the comma-separated ``tools:`` frontmatter value into a list."""
+    if not tools_raw:
+        return []
+    return [t.strip() for t in tools_raw.split(",") if t.strip()]
+def _render_augment_agent(agent_file: Path) -> str:
+    """Render a single Augment subagent .md file from an ai-toolkit agent."""
+    name = frontmatter_field(agent_file, "name")
+    description = frontmatter_field(agent_file, "description")
+    color = frontmatter_field(agent_file, "color")
+    tools_raw = frontmatter_field(agent_file, "tools")
+    tools = _parse_tools(tools_raw)
+    # Escape description for YAML quoted string
+    safe_desc = description.replace('"', "'")
+    lines: list[str] = ["---"]
+    lines.append(f"name: {name}")
+    lines.append(f'description: "{safe_desc}"')
+    # Augment recommends ``model: inherit`` for plugins that want to follow
+    # the user's active model selection. ai-toolkit agents are authored with
+    # short aliases that do not map to Augment's provider-qualified ids, so
+    # we deliberately emit ``inherit`` instead of translating.
+    lines.append("model: inherit")
+    if color:
+        lines.append(f"color: {color}")
+    if tools:
+        tools_flow = ", ".join(tools)
+        lines.append(f"tools: [{tools_flow}]")
+    else:
+        lines.append("tools: []")
+    # Explicit empty disabled_tools for shape parity with Augment UI exports
+    lines.append("disabled_tools: []")
+    lines.append("---")
+    lines.append("")
+    body = _agent_body(agent_file).rstrip()
+    if body:
+        lines.append(body)
+    lines.append("")
+    return "\n".join(lines)
+def _cleanup_stale(agents_out: Path) -> int:
+    """Remove stale ai-toolkit-* agent files whose source no longer exists.
+    Only touches files with the ``ai-toolkit-`` prefix so user-authored
+    Augment agents are preserved.
+    """
+    if not agents_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(agents_out.glob(f"{AGENT_PREFIX}*.md")):
+        source_name = f.stem[len(AGENT_PREFIX):]
+        source = agents_dir / f"{source_name}.md"
+        if not source.is_file():
+            f.unlink()
+            removed += 1
+    return removed
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write Augment agent files and return (written, removed_stale).
+    By default writes to ``target_dir/.augment/agents/`` (project-local).
+    Pass ``config_root=~/.augment`` for the global layout, which writes
+    directly under ``agents/`` without the ``.augment/`` prefix.
+    """
+    base = config_root if config_root is not None else target_dir / ".augment"
+    agents_out = base / "agents"
+    agents_out.mkdir(parents=True, exist_ok=True)
+    written = 0
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        out_path = agents_out / f"{AGENT_PREFIX}{name}.md"
+        out_path.write_text(_render_augment_agent(agent_file), encoding="utf-8")
+        written += 1
+    removed = _cleanup_stale(agents_out)
+    return written, removed
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .augment/agents/ ({written} agents"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+if __name__ == "__main__":
+    main()

package/scripts/generate_augment_commands.py ADDED Viewed

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Generate ``.augment/commands/ai-toolkit-*.md`` files for Augment Code.
+User-invocable skills become Augment custom slash commands. Knowledge skills
+(``user-invocable: false``) are excluded — they load automatically via
+AGENTS.md/rules context instead of ``/`` invocation.
+Per docs.augmentcode.com, Augment custom commands are plain markdown files
+with an optional YAML frontmatter header. The body of the file IS the prompt
+(no ``template:`` field, no TOML). Supported frontmatter fields:
+    ---
+    description: "<short one-liner shown in the palette>"
+    agent: <optional agent slug to route into>
+    argument-hint: "<optional hint shown after the command name>"
+    ---
+    <prompt body — supports $ARGUMENTS placeholder>
+Files are prefixed ``ai-toolkit-`` so install/uninstall can identify ours
+without touching user files.
+Usage:
+  python3 scripts/generate_augment_commands.py [target-dir]
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import skills_dir
+from frontmatter import frontmatter_field
+COMMAND_PREFIX = "ai-toolkit-"
+def _skill_body(skill_file: Path) -> str:
+    """Return the markdown body of a skill (content after frontmatter)."""
+    text = skill_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text
+    parts = text.split("---", 2)
+    return parts[2].lstrip("\n") if len(parts) >= 3 else text
+def _map_agent_name(value: str) -> str:
+    """Map ai-toolkit agent names to our prefixed Augment subagent slugs."""
+    value = value.strip()
+    if not value:
+        return value
+    if value.startswith(COMMAND_PREFIX):
+        return value
+    return f"{COMMAND_PREFIX}{value}"
+def _render_augment_command(skill_file: Path) -> str:
+    """Render a single Augment command .md file from a user-invocable skill."""
+    description = frontmatter_field(skill_file, "description")
+    agent_field = frontmatter_field(skill_file, "agent")
+    argument_hint = frontmatter_field(skill_file, "argument-hint")
+    body = _skill_body(skill_file).rstrip()
+    lines: list[str] = ["---"]
+    if description:
+        safe_desc = description.replace('"', "'")
+        lines.append(f'description: "{safe_desc}"')
+    if agent_field:
+        lines.append(f"agent: {_map_agent_name(agent_field)}")
+    if argument_hint:
+        safe_hint = argument_hint.replace('"', "'")
+        lines.append(f'argument-hint: "{safe_hint}"')
+    lines.append("---")
+    lines.append("")
+    if body:
+        lines.append(body)
+    lines.append("")
+    return "\n".join(lines)
+def _is_user_invocable(skill_file: Path) -> bool:
+    """Return True if the skill should be exposed as a ``/`` command.
+    Matches the opencode generator's logic:
+    * explicit ``user-invocable: true`` -> yes
+    * implicit: ``disable-model-invocation: true`` -> yes (task skill)
+    * default -> no (keeps knowledge skills out of the command palette)
+    """
+    invocable = frontmatter_field(skill_file, "user-invocable")
+    if invocable:
+        return invocable.lower() not in ("false", "0", "no")
+    disable_model = frontmatter_field(skill_file, "disable-model-invocation")
+    if disable_model and disable_model.lower() in ("true", "1", "yes"):
+        return True
+    return False
+def _cleanup_stale(commands_out: Path) -> int:
+    """Remove stale ai-toolkit-* command files whose source no longer exists.
+    Also removes commands whose source skill is no longer user-invocable so
+    flipping a skill's ``user-invocable`` flag back to ``false`` cleanly
+    retracts the command.
+    """
+    if not commands_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(commands_out.glob(f"{COMMAND_PREFIX}*.md")):
+        source_name = f.stem[len(COMMAND_PREFIX):]
+        source = skills_dir / source_name / "SKILL.md"
+        if not source.is_file() or not _is_user_invocable(source):
+            f.unlink()
+            removed += 1
+    return removed
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write Augment command files and return (written, removed_stale).
+    By default writes to ``target_dir/.augment/commands/`` (project-local).
+    Pass ``config_root=~/.augment`` for the global layout.
+    """
+    base = config_root if config_root is not None else target_dir / ".augment"
+    commands_out = base / "commands"
+    commands_out.mkdir(parents=True, exist_ok=True)
+    written = 0
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_"):
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        if not _is_user_invocable(skill_file):
+            continue
+        name = frontmatter_field(skill_file, "name")
+        if not name:
+            continue
+        out_path = commands_out / f"{COMMAND_PREFIX}{name}.md"
+        out_path.write_text(_render_augment_command(skill_file), encoding="utf-8")
+        written += 1
+    removed = _cleanup_stale(commands_out)
+    return written, removed
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .augment/commands/ ({written} commands"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+if __name__ == "__main__":
+    main()

package/scripts/generate_augment_hooks.py ADDED Viewed

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Generate Augment settings.json hooks block.
+Augment stores hooks in `~/.augment/settings.json` (user scope) — there is no
+per-workspace hooks file. `/etc/augment/settings.json` exists for system-wide
+policy and we never write there. The generator accepts an optional target
+directory; when omitted it defaults to the user's `$HOME` and writes
+`~/.augment/settings.json`.
+Augment hook events (per docs.augmentcode.com/cli/hooks.md):
+    PreToolUse, PostToolUse, SessionStart, SessionEnd, Stop
+Schema mirrors Claude Code — each event holds an array of groups, each group
+holds `{matcher?, hooks: [{type, command, timeout?}]}`. We tag the outer group
+with `_source: ai-toolkit` so we can strip and rewrite idempotently without
+clobbering user hook groups.
+Common Augment tool names relevant to our hooks:
+    launch-process (shell), view (read), str-replace-editor (edit),
+    save-file (write), remove-files (delete), web-fetch, web-search,
+    codebase-retrieval, github-api, linear.
+Usage:
+    python3 scripts/generate_augment_hooks.py [target-dir]
+`target-dir` is the HOME-equivalent directory (default: `$HOME`). The
+settings file is written to `<target-dir>/.augment/settings.json`.
+"""
+from __future__ import annotations
+import json
+import os
+import sys
+from pathlib import Path
+HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+SOURCE_TAG = "ai-toolkit"
+# Event -> list of (matcher, script). Matcher is a regex over tool_name.
+AUGMENT_HOOKS: dict[str, list[tuple[str, str]]] = {
+    "SessionStart": [
+        ("", "session-start.sh"),
+        ("", "mcp-health.sh"),
+        ("", "session-context.sh"),
+    ],
+    "PreToolUse": [
+        ("launch-process", "guard-destructive.sh"),
+        ("launch-process", "commit-quality.sh"),
+        ("view|str-replace-editor|save-file|remove-files", "guard-path.sh"),
+        ("str-replace-editor|save-file", "guard-config.sh"),
+    ],
+    "PostToolUse": [
+        ("str-replace-editor|save-file", "post-tool-use.sh"),
+        ("launch-process|str-replace-editor|save-file", "governance-capture.sh"),
+    ],
+    "Stop": [
+        ("", "quality-check.sh"),
+        ("", "save-session.sh"),
+    ],
+    "SessionEnd": [
+        ("", "session-end.sh"),
+    ],
+}
+def build_hook_group(matcher: str, script: str) -> dict:
+    """Build a single Augment hook group (merge-safe shape)."""
+    group: dict = {
+        "_source": SOURCE_TAG,
+        "hooks": [
+            {
+                "type": "command",
+                "command": f"{HOOKS_PREFIX}{script}\"",
+            }
+        ],
+    }
+    # Augment ignores `matcher` on session events; omit cleanly so it doesn't
+    # show up as a spurious regex-against-nothing in their logs.
+    if matcher:
+        group["matcher"] = matcher
+    return group
+def build_toolkit_hooks() -> dict[str, list[dict]]:
+    return {event: [build_hook_group(m, s) for m, s in entries]
+            for event, entries in AUGMENT_HOOKS.items()}
+def _is_toolkit_entry(entry: dict) -> bool:
+    if not isinstance(entry, dict):
+        return False
+    if entry.get("_source") == SOURCE_TAG:
+        return True
+    # Pre-2.13 layout tagged the inner hook dict instead of the outer group.
+    for h in entry.get("hooks", []) or []:
+        if isinstance(h, dict) and h.get("_source") == SOURCE_TAG:
+            return True
+    return False
+def strip_toolkit_hooks(hooks: dict) -> dict:
+    kept: dict = {}
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            kept[event] = entries
+            continue
+        survivors = [e for e in entries if not _is_toolkit_entry(e)]
+        if survivors:
+            kept[event] = survivors
+    return kept
+def merge_hooks(existing: dict, toolkit: dict) -> dict:
+    merged = strip_toolkit_hooks(existing)
+    for event, entries in toolkit.items():
+        merged.setdefault(event, []).extend(entries)
+    return merged
+def _resolve_target_dir(argv: list[str]) -> Path:
+    """Accept an explicit target dir or fall back to $HOME."""
+    if len(argv) > 1 and argv[1]:
+        return Path(argv[1])
+    home = os.environ.get("HOME")
+    if not home:
+        raise SystemExit("HOME is not set and no target directory was provided.")
+    return Path(home)
+def generate(target_dir: Path) -> Path:
+    """Write `<target_dir>/.augment/settings.json` and return its path."""
+    aug_dir = target_dir / ".augment"
+    aug_dir.mkdir(parents=True, exist_ok=True)
+    path = aug_dir / "settings.json"
+    settings: dict = {}
+    if path.is_file():
+        try:
+            with open(path, encoding="utf-8") as f:
+                settings = json.load(f)
+            if not isinstance(settings, dict):
+                settings = {}
+        except (json.JSONDecodeError, OSError):
+            settings = {}
+    existing_hooks = settings.get("hooks") if isinstance(settings.get("hooks"), dict) else {}
+    settings["hooks"] = merge_hooks(existing_hooks or {}, build_toolkit_hooks())
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=4, ensure_ascii=False, sort_keys=True)
+        f.write("\n")
+    return path
+def main() -> None:
+    target = _resolve_target_dir(sys.argv)
+    path = generate(target)
+    total = sum(len(v) for v in AUGMENT_HOOKS.values())
+    print(f"Generated: {path} ({total} hooks across {len(AUGMENT_HOOKS)} events)")
+if __name__ == "__main__":
+    main()

package/scripts/generate_augment_skills.py ADDED Viewed

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Generate an Augment skill pointer under ``.augment/skills/``.
+Augment's SKILL.md reader follows the Agent Skills standard at
+``.augment/skills/<skill-name>/SKILL.md``. To avoid duplicating the full
+ai-toolkit skill catalogue (99 SKILL.md files) into Augment's directory,
+we emit a single **pointer skill** that teaches Augment to resolve real
+skills from the canonical Claude Code locations:
+  * ``.claude/skills/<name>/SKILL.md`` (project-local install)
+  * ``~/.claude/skills/<name>/SKILL.md`` (global install)
+This mirrors the pattern used by ``generate_antigravity.py`` and
+``generate_gemini_skills.py``.
+Usage:
+  python3 scripts/generate_augment_skills.py [target-dir]
+Writes ``<target-dir>/.augment/skills/ai-toolkit-skill-catalogue/SKILL.md``.
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import emit_skills_bullets
+# ---------------------------------------------------------------------------
+# Skill pointer — a single SKILL.md that directs Augment to our catalogue
+# ---------------------------------------------------------------------------
+POINTER_SKILL_NAME = "ai-toolkit-skill-catalogue"
+def _pointer_skill_md() -> str:
+    """Build the SKILL.md body for the Augment pointer skill."""
+    body = (
+        "# AI Toolkit Skill Catalogue\n\n"
+        "This workspace uses the ai-toolkit. Real skills are installed "
+        "alongside Claude Code at `.claude/skills/` (project install) or "
+        "`~/.claude/skills/` (global install). If the ai-toolkit installer "
+        "has run, every skill below already exists as an agent-invocable "
+        "SKILL.md on disk.\n\n"
+        "## When to use this skill\n\n"
+        "- You are asked to run a task that maps to one of the catalogued "
+        "skills below.\n"
+        "- You want to discover which skills the user has installed before "
+        "reinventing the wheel.\n\n"
+        "## How to invoke a catalogue entry\n\n"
+        "1. Match the user's task to a skill name in the catalogue.\n"
+        "2. Read the skill's SKILL.md from `.claude/skills/<name>/SKILL.md` "
+        "or `~/.claude/skills/<name>/SKILL.md` (whichever exists).\n"
+        "3. Follow its Rules, Gotchas, and When NOT to Use sections.\n\n"
+        "## Catalogue (installed skills)\n\n"
+        f"{emit_skills_bullets()}\n"
+    )
+    return (
+        "---\n"
+        f"name: {POINTER_SKILL_NAME}\n"
+        "description: Index of ai-toolkit skills installed at .claude/skills/"
+        " or ~/.claude/skills/. Read this first when the user's request "
+        "matches a named skill.\n"
+        "---\n"
+        f"{body}"
+    )
+def _write_skill_pointer(target_dir: Path) -> None:
+    """Write the pointer SKILL.md under .augment/skills/<name>/."""
+    skill_dir = target_dir / ".augment" / "skills" / POINTER_SKILL_NAME
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(_pointer_skill_md(), encoding="utf-8")
+    print(f"  Generated: .augment/skills/{POINTER_SKILL_NAME}/SKILL.md")
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+def generate(target_dir: Path, *, emit_skill_pointer: bool = True) -> None:
+    """Write ``.augment/skills/ai-toolkit-skill-catalogue/SKILL.md``.
+    ``emit_skill_pointer`` controls whether the pointer SKILL.md is written.
+    Set to ``False`` to leave Augment's skills directory untouched.
+    """
+    if emit_skill_pointer:
+        _write_skill_pointer(target_dir)
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+if __name__ == "__main__":
+    main()