@softspark/ai-toolkit 4.5.0 → 4.6.0

package/scripts/ecosystem_tools.json

@@ -1,16 +1,16 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-05-30",
+  "last_updated": "2026-06-05",
   "tools": [
     {
       "id": "claude-code",
       "display_name": "Claude Code",
       "kind": "primary",
       "urls": {
-        "docs": "https://platform.claude.com/docs/en/claude-code",
+        "docs": "https://code.claude.com/docs",
         "release_notes": "https://github.com/anthropics/claude-code/releases",
-        "changelog": null
+        "changelog": "https://code.claude.com/docs/en/changelog"
       },
       "config_paths": [
         "~/.claude/settings.json",
@@ -97,6 +97,8 @@
       "our_generators": [
         "scripts/generate_cursor_rules.py",
         "scripts/generate_cursor_mdc.py",
+        "scripts/generate_cursor_hooks.py",
+        "scripts/generate_cursor_agents.py",
         "scripts/generate_cursor_skills.py"
       ],
       "capability_markers": [
@@ -118,9 +120,9 @@
       "display_name": "Windsurf",
       "kind": "editor",
       "urls": {
-        "docs": "https://docs.windsurf.com",
-        "release_notes": "https://windsurf.com/changelog",
-        "changelog": "https://windsurf.com/changelog"
+        "docs": "https://docs.devin.ai/desktop",
+        "release_notes": "https://docs.devin.ai/desktop/changelog",
+        "changelog": "https://docs.devin.ai/desktop/changelog"
       },
       "config_paths": [
         ".windsurfrules",
@@ -219,12 +221,12 @@
         "BeforeModel",
         "SessionStart",
         "SessionEnd",
-        "Stop",
         "SKILL.md",
         "activate_skill",
         "custom commands",
         "gemini-extension.json"
       ],
+      "status_note": "Gemini CLI drops free + paid (AI Pro/Ultra) tiers on 2026-06-18 in favor of the new Antigravity CLI (we ship generate_antigravity.py); enterprise Gemini Code Assist Standard/Enterprise keeps full Gemini CLI support. The .gemini/* generators remain valid for the enterprise audience.",
       "version_probe": {
         "kind": "command",
         "command": "gemini --version"
@@ -242,12 +244,11 @@
       "config_paths": [
         ".clinerules/*.md",
         ".clinerules/workflows/*.md",
-        ".cline/rules/*.md",
-        ".cline/hooks/",
+        ".clinerules/skills/*/SKILL.md",
+        ".clinerules/hooks/",
         ".cline/skills/*/SKILL.md",
-        "~/.cline/rules/*.md",
-        "~/.cline/hooks/",
         "~/.cline/skills/*/SKILL.md",
+        "~/Documents/Cline/Rules/Hooks/",
         "~/.cline/data/settings/cline_mcp_settings.json",
         ".claude/skills/*/SKILL.md"
       ],
@@ -275,10 +276,12 @@
       "display_name": "Roo Code",
       "kind": "editor",
       "urls": {
-        "docs": "https://docs.roocode.com",
+        "docs": "https://roocodeinc.github.io/Roo-Code",
         "release_notes": "https://github.com/RooCodeInc/Roo-Code/releases",
         "changelog": null
       },
+      "status": "archived",
+      "status_note": "Upstream RooCodeInc/Roo-Code repo archived/read-only as of 2026-05-15, frozen at v3.54.0; docs.roocode.com 301-redirects to roocodeinc.github.io/Roo-Code. A community fork reportedly continues maintenance. JSON .roomodes is NOT deprecated; both generators remain valid.",
       "config_paths": [
         ".roomodes",
         ".roo/rules/*.md",
@@ -399,6 +402,8 @@
         "changelog": null
       },
       "config_paths": [
+        ".agents/rules/*.md",
+        ".agents/workflows/*.md",
         ".agent/rules/*.md",
         ".agent/workflows/*.md",
         ".agent/skills/*/SKILL.md",
@@ -427,20 +432,18 @@
       "display_name": "Codex CLI",
       "kind": "editor",
       "urls": {
-        "docs": "https://github.com/openai/codex",
+        "docs": "https://developers.openai.com/codex",
         "release_notes": "https://github.com/openai/codex/releases",
         "changelog": null
       },
       "config_paths": [
         "AGENTS.md",
-        ".agents/rules/*.md",
         ".agents/skills/*/SKILL.md",
         ".codex/hooks.json",
         "~/.codex/config.toml"
       ],
       "our_generators": [
         "scripts/generate_codex.py",
-        "scripts/generate_codex_rules.py",
         "scripts/generate_codex_hooks.py",
         "scripts/generate_codex_skills.py"
       ],

package/scripts/generate_antigravity.py

@@ -1,12 +1,15 @@
 #!/usr/bin/env python3
-"""Generate Antigravity IDE ``.agent/rules/``, ``.agent/workflows/``, and
+"""Generate Antigravity IDE ``.agents/rules/``, ``.agents/workflows/``, and
 skill pointer files.
 
+Antigravity 2.0 reads rules/workflows from the plural ``.agents/`` directory by
+default; singular ``.agent/`` is still accepted as a backward-compatible
+fallback (Antigravity checks plural first, then singular). We emit plural.
 Antigravity reads rules from:
   * ``GEMINI.md`` (highest priority) — generated by ``generate_gemini.py``
   * ``AGENTS.md`` (cross-tool) — generated by ``generate_agents_md.py``
-  * ``.agent/rules/*.md`` — per-category rule files (this generator)
-  * ``.agent/workflows/*.md`` — workflow templates (this generator)
+  * ``.agents/rules/*.md`` — per-category rule files (this generator)
+  * ``.agents/workflows/*.md`` — workflow templates (this generator)
 
 Antigravity also supports the Agent Skills standard via ``.agent/skills/
 <skill-name>/SKILL.md`` (the changelog entry "Agent Skills now available in
@@ -19,7 +22,8 @@ that teaches Antigravity to look up the real catalogue in
 Usage:
   python3 scripts/generate_antigravity.py [target-dir]
 
-Writes files directly to target-dir/.agent/{rules,workflows,skills}/.
+Writes rules/workflows to target-dir/.agents/{rules,workflows}/ and the skill
+pointer to target-dir/.agent/skills/ (skills location is unchanged upstream).
 """
 from __future__ import annotations
 
@@ -93,7 +97,7 @@ def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
              rules_dir: Path | None = None,
              emit_skill_pointer: bool = True) -> None:
-    """Write ``.agent/rules/``, ``.agent/workflows/``, and ``.agent/skills/``.
+    """Write ``.agents/rules/``, ``.agents/workflows/``, and ``.agent/skills/``.
 
     ``emit_skill_pointer`` controls whether the pointer SKILL.md is written.
     Set to ``False`` if you manage ``.agent/skills/`` yourself.
@@ -101,8 +105,8 @@ def generate(target_dir: Path, *,
     rules = dict(STANDARD_RULES)
     rules.update(build_language_rules(language_modules))
     rules.update(build_registered_rules(rules_dir))
-    write_rules(target_dir, rules, ".agent/rules")
-    write_rules(target_dir, STANDARD_WORKFLOWS, ".agent/workflows")
+    write_rules(target_dir, rules, ".agents/rules")
+    write_rules(target_dir, STANDARD_WORKFLOWS, ".agents/workflows")
     if emit_skill_pointer:
         _write_skill_pointer(target_dir)
 

package/scripts/generate_augment_agents.py

@@ -2,12 +2,12 @@
 """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:
+subagent. Augment's subagent frontmatter (per docs.augmentcode.com/cli/subagents)
+documents: name, description, color, model, tools, disabled_tools.
 
     ---
     name: <slug>
     description: "<single-line description>"
-    model: inherit            # or explicit model id
     color: <color-name>       # optional UI hint
     tools: [Read, Write, ...]
     disabled_tools: []
@@ -17,9 +17,10 @@ subagent. Augment's subagent frontmatter (per docs.augmentcode.com) supports:
 
 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.
+* ``model`` is omitted. The docs state "If not specified, the CLI default model
+  is used" and do not document ``inherit`` as a value. ai-toolkit stores short
+  aliases (``opus``/``sonnet``/``haiku``) that do not map to Augment's full
+  model ids, so we omit the field to defer to the CLI default.
 * ``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.
@@ -79,11 +80,9 @@ def _render_augment_agent(agent_file: Path) -> str:
     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")
+    # `model` is omitted: Augment's docs say the CLI default model is used when
+    # absent, and `inherit` is not a documented value. Our short aliases do not
+    # map to Augment's provider-qualified ids, so we defer to the CLI default.
     if color:
         lines.append(f"color: {color}")
     if tools:

package/scripts/generate_augment_commands.py

@@ -5,13 +5,13 @@ 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:
+Per docs.augmentcode.com/cli/custom-commands, 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). The documented frontmatter fields
+are ``description``, ``argument-hint``, and ``model`` (no ``agent`` field):
 
     ---
     description: "<short one-liner shown in the palette>"
-    agent: <optional agent slug to route into>
     argument-hint: "<optional hint shown after the command name>"
     ---
 
@@ -44,20 +44,9 @@ def _skill_body(skill_file: Path) -> str:
     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()
 
@@ -65,8 +54,6 @@ def _render_augment_command(skill_file: Path) -> 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}"')

package/scripts/generate_augment_hooks.py

@@ -1,11 +1,13 @@
 #!/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 reads hooks from several settings.json layers (per
+docs.augmentcode.com/cli/hooks): `<workspace>/.augment/settings.local.json`,
+`<workspace>/.augment/settings.json`, `~/.augment/settings.json` (user scope),
+and `/etc/augment/settings.json` (system policy). This generator writes the
+user-scope file: it accepts an optional target directory and defaults to the
+user's `$HOME`, writing `~/.augment/settings.json`. Project-local hook emission
+for `--local` installs is a possible future extension.
 
 Augment hook events (per docs.augmentcode.com/cli/hooks.md):
     PreToolUse, PostToolUse, SessionStart, SessionEnd, Stop

package/scripts/generate_codex.py

@@ -13,6 +13,12 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from codex_skill_adapter import codex_skill_description
+from dir_rules_shared import (
+    rule_code_style,
+    rule_output_mode,
+    rule_security,
+    rule_testing,
+)
 from emission import (
     agents_dir,
     skills_dir,
@@ -54,6 +60,23 @@ def _emit_skills() -> str:
     return "\n".join(lines)
 
 
+def _emit_coding_rules() -> str:
+    """Inline the universal coding-rule bodies so Codex receives them.
+
+    Codex reads project instructions only from AGENTS.md (and AGENTS.override.md);
+    it does not read a ``.agents/rules/`` directory. Workflow + quality standards
+    are already emitted above, so this adds code-style, testing, security, and
+    output-mode under a single ``## Coding Rules`` section (H1 demoted to H3).
+    """
+    sections: list[str] = []
+    for rule_fn in (rule_code_style, rule_testing, rule_security, rule_output_mode):
+        body = rule_fn().rstrip()
+        if body.startswith("# "):
+            body = "### " + body[2:]
+        sections.append(body)
+    return "## Coding Rules\n\n" + "\n\n".join(sections)
+
+
 def main() -> None:
     print_toolkit_start()
 
@@ -86,6 +109,11 @@ def main() -> None:
     print()
     print(generate_workflow_guidelines())
 
+    # Universal coding rules — Codex reads instructions only from AGENTS.md,
+    # so inline them here (previously emitted to the unread .agents/rules/).
+    print()
+    print(_emit_coding_rules())
+
     print_toolkit_end()
 
     # Registered custom rules from ~/.softspark/ai-toolkit/rules/

package/scripts/generate_codex_hooks.py

@@ -8,7 +8,8 @@ Codex exposes 10 lifecycle events (PascalCase in config.toml / hooks.json):
 ``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``PreCompact``,
 ``PostCompact``, ``SessionStart``, ``UserPromptSubmit``, ``SubagentStart``,
 ``SubagentStop``, ``Stop``. PreToolUse/PostToolUse only support the ``Bash``
-matcher. We currently wire the subset defined in ``CODEX_HOOKS`` below.
+matcher. We wire all 10 events in ``CODEX_HOOKS`` below to the shared toolkit
+hook scripts, mirroring the Claude Code mapping in ``app/hooks.json``.
 
 Handler types in Codex: ``command`` (what we emit), ``prompt``, and ``agent``.
 Reference: codex-rs/config/src/hook_config.rs.
@@ -39,6 +40,12 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
         ("Bash", "commit-quality.sh"),
         ("Bash", "revert-guard.sh"),
     ],
+    "PostToolUse": [
+        # Fires after Bash/apply_patch/MCP tool output. Capture governance
+        # signals and detect repetition loops (mirrors app/hooks.json).
+        ("Bash", "governance-capture.sh"),
+        ("Bash", "loop-guard.sh"),
+    ],
     "PermissionRequest": [
         # Fires when Codex asks the user to approve a tool call. Our guard
         # reviews the tool input and can veto destructive patterns before the
@@ -49,6 +56,21 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
         ("", "user-prompt-submit.sh"),
         ("", "track-usage.sh"),
     ],
+    "SubagentStart": [
+        ("", "subagent-start.sh"),
+    ],
+    "SubagentStop": [
+        ("", "subagent-stop.sh"),
+    ],
+    "PreCompact": [
+        # Capture session memory before Codex compacts the conversation.
+        ("", "pre-compact.sh"),
+        ("", "pre-compact-save.sh"),
+    ],
+    "PostCompact": [
+        # Re-establish working context after compaction.
+        ("", "session-context.sh"),
+    ],
     "Stop": [
         ("", "quality-check.sh"),
         ("", "save-session.sh"),

package/scripts/generate_cursor_agents.py

@@ -2,25 +2,24 @@
 """Generate ``.cursor/agents/ai-toolkit-*.md`` files for Cursor IDE.
 
 Each ai-toolkit agent is mirrored as a Cursor custom agent. Per Cursor's
-docs (docs.cursor.com -> custom agents), agent files use YAML frontmatter:
+subagent docs (cursor.com/docs/subagents) the frontmatter schema documents
+only these fields:
 
     ---
-    name: <slug>
-    description: "<one-line summary shown in the picker>"
-    model: <model-id>     # optional, inherits user default if absent
-    color: <color-name>   # optional UI hint
-    tools: [Read, Write, ...]  # list of allowed tool names
+    name: <slug>              # lowercase letters and hyphens
+    description: "<one-line summary shown in the Task picker>"
+    model: inherit            # `inherit` (default) or a specific model id
     ---
 
     <system prompt body>
 
 Design choices:
 
-* ``model`` is omitted. Our agents store short aliases (``opus``, ``sonnet``,
-  ``haiku``) that do not map to Cursor's provider-qualified model ids.
-  Omitting the field makes Cursor fall back to the user's default model,
-  which is the same behaviour our opencode generator uses.
-* ``tools`` is emitted as a YAML flow-list parsed verbatim from the source.
+* ``model: inherit`` is emitted — the documented default value. Our agents
+  store short aliases (``opus``/``sonnet``/``haiku``) that do not map to
+  Cursor's provider-qualified model ids, so we use the literal ``inherit``.
+* ``tools`` and ``color`` are NOT emitted — the current Cursor schema documents
+  only name/description/model/readonly/is_background (tools/color were dropped).
 * Files are prefixed ``ai-toolkit-`` so install/uninstall can identify ours.
 * Regeneration removes stale ``ai-toolkit-*.md`` files whose source agent
   no longer exists, but leaves user-authored agents untouched.
@@ -53,34 +52,19 @@ def _agent_body(agent_file: Path) -> str:
     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_cursor_agent(agent_file: Path) -> str:
     """Render a single Cursor custom agent .md file."""
     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)
 
     safe_desc = description.replace('"', "'")
 
     lines: list[str] = ["---"]
     lines.append(f"name: {name}")
     lines.append(f'description: "{safe_desc}"')
-    # model intentionally omitted — Cursor falls back to the user default.
-    if color:
-        lines.append(f"color: {color}")
-    if tools:
-        tools_flow = ", ".join(tools)
-        lines.append(f"tools: [{tools_flow}]")
-    else:
-        lines.append("tools: []")
+    # `inherit` is the documented default model value; our short aliases do not
+    # map to Cursor's provider-qualified model ids.
+    lines.append("model: inherit")
     lines.append("---")
     lines.append("")
     body = _agent_body(agent_file).rstrip()

package/scripts/generate_opencode_commands.py

@@ -5,8 +5,10 @@ User-invocable skills become opencode slash commands. Knowledge skills
 (``user-invocable: false``) are excluded — they load automatically via
 AGENTS.md context instead of `/` invocation.
 
-Generated commands use the required ``template`` frontmatter field.
-Files are prefixed ``ai-toolkit-`` for clean uninstall.
+Generated commands put the prompt in the markdown BODY. opencode reads the
+body as the prompt template; the ``template`` frontmatter field is JSON-config
+only and is ignored in .md command files. Files are prefixed ``ai-toolkit-``
+for clean uninstall.
 
 opencode commands: https://opencode.ai/docs/commands/
 """
@@ -47,12 +49,11 @@ def _skill_body(skill_file: Path) -> str:
 
 def _render_opencode_command(skill_file: Path) -> str:
     """Render a single opencode command .md file from a user-invocable skill."""
-    name = frontmatter_field(skill_file, "name")
     description = frontmatter_field(skill_file, "description")
     agent_field = frontmatter_field(skill_file, "agent")
-    # opencode does NOT read "body" — the prompt is entirely in the `template`
-    # frontmatter field. We embed the SKILL.md body as the template using a
-    # YAML block scalar (``|``) which preserves newlines without escaping.
+    # opencode reads the command prompt from the markdown BODY of the file.
+    # The frontmatter only defines command properties; the `template` field is
+    # JSON-config-only and is ignored in .md command files.
     body = _skill_body(skill_file).rstrip()
 
     lines: list[str] = ["---"]
@@ -62,11 +63,10 @@ def _render_opencode_command(skill_file: Path) -> str:
     if agent_field:
         # opencode accepts an `agent` frontmatter field pointing at a subagent
         lines.append(f"agent: {_map_agent_name(agent_field)}")
-    lines.append("template: |")
-    for tpl_line in body.splitlines() or [""]:
-        lines.append(f"  {tpl_line}" if tpl_line else "  ")
     lines.append("---")
     lines.append("")
+    lines.append(body)
+    lines.append("")
     return "\n".join(lines)
 
 

package/scripts/install.py

@@ -14,7 +14,7 @@ Claude Code (~/.claude/):
 Other tools (global config locations):
   - Windsurf: ~/.codeium/windsurf/memories/global_rules.md + ~/.codeium/windsurf/skills/
   - Gemini:   ~/.gemini/GEMINI.md
-  - Cline:    ~/.cline/rules/ + ~/.cline/skills/
+  - Cline:    ~/Documents/Cline/Rules/ + ~/.cline/skills/
   - Roo Code: ~/.roo/rules/
   - Aider:    ~/.aider.conf.yml (created only if absent)
   - Augment:  ~/.augment/rules/ai-toolkit.md