@softspark/ai-toolkit 2.12.0 → 3.0.0

package/scripts/ecosystem_tools.json

@@ -0,0 +1,500 @@
+{
+  "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-04-23",
+  "tools": [
+    {
+      "id": "claude-code",
+      "display_name": "Claude Code",
+      "kind": "primary",
+      "urls": {
+        "docs": "https://platform.claude.com/docs/en/claude-code",
+        "release_notes": "https://github.com/anthropics/claude-code/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        "~/.claude/settings.json",
+        ".claude/settings.local.json",
+        "CLAUDE.md",
+        ".claude/agents/*.md",
+        ".claude/skills/*/SKILL.md",
+        "~/.claude/themes/*.json"
+      ],
+      "our_generators": [],
+      "capability_markers": [
+        "PreToolUse",
+        "PostToolUse",
+        "SessionStart",
+        "SessionEnd",
+        "SubagentStart",
+        "SubagentStop",
+        "UserPromptSubmit",
+        "Notification",
+        "Stop",
+        "StopFailure",
+        "PreCompact",
+        "PostCompact",
+        "PermissionRequest",
+        "PermissionDenied",
+        "Elicitation",
+        "ElicitationResult",
+        "TaskCreated",
+        "TaskCompleted",
+        "TeammateIdle",
+        "WorktreeCreate",
+        "WorktreeRemove",
+        "CwdChanged",
+        "FileChanged",
+        "ConfigChange",
+        "Setup",
+        "InstructionsLoaded",
+        "slash command",
+        "MCP server",
+        "sub-agent",
+        "output style",
+        "SKILL.md",
+        "hook handler: command",
+        "hook handler: prompt",
+        "hook handler: agent",
+        "hook handler: mcp_tool"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "claude --version"
+      }
+    },
+    {
+      "id": "cursor",
+      "display_name": "Cursor",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://cursor.com/docs",
+        "release_notes": "https://cursor.com/changelog",
+        "changelog": "https://cursor.com/changelog"
+      },
+      "config_paths": [
+        ".cursorrules",
+        ".cursor/rules/*.mdc",
+        ".cursor/rules/*.md",
+        "AGENTS.md",
+        ".cursor/mcp.json",
+        "~/.cursor/mcp.json",
+        ".cursor/skills/*/SKILL.md",
+        ".cursor/agents/*.md",
+        ".cursor/hooks.json",
+        "~/.cursor/hooks.json"
+      ],
+      "our_generators": [
+        "scripts/generate_cursor_rules.py",
+        "scripts/generate_cursor_mdc.py"
+      ],
+      "capability_markers": [
+        "cursorrules",
+        ".cursor/rules",
+        "AGENTS.md",
+        "mcp.json",
+        "Composer",
+        "Agent Mode",
+        "hooks.json",
+        "subagents",
+        "skills",
+        "plugins"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "windsurf",
+      "display_name": "Windsurf",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.windsurf.com",
+        "release_notes": "https://windsurf.com/changelog",
+        "changelog": "https://windsurf.com/changelog"
+      },
+      "config_paths": [
+        ".windsurfrules",
+        ".windsurf/rules/*.md",
+        ".windsurf/workflows/*.md",
+        "AGENTS.md",
+        "~/.codeium/windsurf/memories/global_rules.md",
+        "~/.codeium/windsurf/mcp_config.json",
+        "~/.codeium/windsurf/global_workflows/*.md"
+      ],
+      "our_generators": [
+        "scripts/generate_windsurf.py",
+        "scripts/generate_windsurf_rules.py"
+      ],
+      "capability_markers": [
+        "Cascade",
+        "windsurfrules",
+        "AGENTS.md",
+        "always_on",
+        "glob",
+        "model_decision",
+        "workflows",
+        "MCP",
+        "memories",
+        "hooks"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "github-copilot",
+      "display_name": "GitHub Copilot",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.github.com/en/copilot",
+        "release_notes": "https://github.blog/changelog/label/copilot/",
+        "changelog": null
+      },
+      "config_paths": [
+        ".github/copilot-instructions.md",
+        ".github/instructions/*.instructions.md",
+        ".github/prompts/*.prompt.md",
+        "AGENTS.md"
+      ],
+      "our_generators": [
+        "scripts/generate_copilot.py"
+      ],
+      "capability_markers": [
+        "copilot-instructions.md",
+        "Copilot Chat",
+        "Copilot Workspace",
+        "Copilot cloud agent",
+        "applyTo",
+        "custom agents",
+        "prompt files",
+        "instructions.md",
+        "MCP"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "gemini-cli",
+      "display_name": "Gemini CLI",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://github.com/google-gemini/gemini-cli/tree/main/docs",
+        "release_notes": "https://github.com/google-gemini/gemini-cli/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        "GEMINI.md",
+        ".gemini/settings.json",
+        "~/.gemini/settings.json",
+        ".gemini/commands/*.toml",
+        ".gemini/skills/*/SKILL.md",
+        ".agents/skills/*/SKILL.md",
+        "~/.gemini/skills/*/SKILL.md",
+        ".gemini/extensions/gemini-extension.json"
+      ],
+      "our_generators": [
+        "scripts/generate_gemini.py"
+      ],
+      "capability_markers": [
+        "GEMINI.md",
+        "mcpServers",
+        "tools",
+        "settings.json",
+        "BeforeTool",
+        "AfterTool",
+        "BeforeAgent",
+        "AfterAgent",
+        "BeforeModel",
+        "SessionStart",
+        "SessionEnd",
+        "Stop",
+        "SKILL.md",
+        "activate_skill",
+        "custom commands",
+        "gemini-extension.json"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "gemini --version"
+      }
+    },
+    {
+      "id": "cline",
+      "display_name": "Cline",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.cline.bot",
+        "release_notes": "https://github.com/cline/cline/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        ".clinerules/*.md",
+        ".clinerules/workflows/*.md",
+        ".clinerules/hooks/",
+        ".cline/skills/",
+        "~/.cline/data/settings/cline_mcp_settings.json",
+        "~/Documents/Cline/Rules/"
+      ],
+      "our_generators": [
+        "scripts/generate_cline.py",
+        "scripts/generate_cline_rules.py"
+      ],
+      "capability_markers": [
+        "clinerules",
+        "Plan Mode",
+        "Act Mode",
+        "MCP",
+        "custom modes",
+        "workflows",
+        "hooks",
+        "skills",
+        "subagents",
+        "conditional rules"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "roo-code",
+      "display_name": "Roo Code",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.roocode.com",
+        "release_notes": "https://github.com/RooCodeInc/Roo-Code/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        ".roomodes",
+        ".roo/rules/*.md",
+        ".roo/rules-{slug}/*.md",
+        ".roo/mcp.json",
+        "~/.roo/rules/",
+        "~/.roo/settings/custom_modes.yaml",
+        "~/.roo/settings/mcp_settings.json"
+      ],
+      "our_generators": [
+        "scripts/generate_roo_modes.py",
+        "scripts/generate_roo_rules.py"
+      ],
+      "capability_markers": [
+        "roomodes",
+        "custom modes",
+        "Code Actions",
+        "MCP",
+        "Orchestrator mode",
+        "whenToUse",
+        "description",
+        "roleDefinition",
+        "groups"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "aider",
+      "display_name": "Aider",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://aider.chat/docs",
+        "release_notes": "https://aider.chat/HISTORY.html",
+        "changelog": "https://aider.chat/HISTORY.html"
+      },
+      "config_paths": [
+        ".aider.conf.yml",
+        "CONVENTIONS.md",
+        "~/.aider.conf.yml"
+      ],
+      "our_generators": [
+        "scripts/generate_aider_conf.py",
+        "scripts/generate_conventions.py"
+      ],
+      "capability_markers": [
+        ".aider.conf.yml",
+        "CONVENTIONS.md",
+        "architect",
+        "auto-accept-architect",
+        "read",
+        "lint-cmd",
+        "test-cmd",
+        "commit-prompt",
+        "attribute-co-authored-by",
+        "chat-language",
+        "commit-language",
+        "watch-files",
+        "auto-commits"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "aider --version"
+      }
+    },
+    {
+      "id": "augment",
+      "display_name": "Augment",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://docs.augmentcode.com",
+        "release_notes": "https://www.augmentcode.com/changelog",
+        "changelog": null
+      },
+      "config_paths": [
+        ".augment/rules/*.md",
+        ".augment/guidelines.md",
+        ".augment/agents/*.md",
+        ".augment/commands/*.md",
+        ".augment/skills/*/SKILL.md",
+        "~/.augment/rules/*.md",
+        "~/.augment/agents/*.md",
+        "~/.augment/commands/*.md",
+        "~/.augment/settings.json",
+        "/etc/augment/settings.json"
+      ],
+      "our_generators": [
+        "scripts/generate_augment.py",
+        "scripts/generate_augment_rules.py"
+      ],
+      "capability_markers": [
+        ".augment",
+        "Agent mode",
+        "Next Edit",
+        "MCP",
+        "context engine",
+        "Auggie CLI",
+        "always_apply",
+        "agent_requested",
+        "subagents",
+        "custom commands",
+        "SKILL.md",
+        "PreToolUse",
+        "PostToolUse",
+        "SessionStart",
+        "SessionEnd",
+        "Stop",
+        "ACP Mode"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "google-antigravity",
+      "display_name": "Google Antigravity",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://antigravity.google/docs",
+        "release_notes": "https://antigravity.google/changelog",
+        "changelog": null
+      },
+      "config_paths": [
+        ".agent/rules/*.md",
+        ".agent/workflows/*.md",
+        ".agent/skills/*/SKILL.md",
+        "AGENTS.md",
+        "GEMINI.md"
+      ],
+      "our_generators": [
+        "scripts/generate_antigravity.py"
+      ],
+      "capability_markers": [
+        "Antigravity",
+        "agent manager",
+        "artifacts",
+        "MCP",
+        "workflows",
+        "rules",
+        "skills",
+        "AGENTS.md",
+        "GEMINI.md",
+        "agent permissions"
+      ],
+      "version_probe": null
+    },
+    {
+      "id": "codex-cli",
+      "display_name": "Codex CLI",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://github.com/openai/codex",
+        "release_notes": "https://github.com/openai/codex/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        "AGENTS.md",
+        ".agents/rules/*.md",
+        ".codex/hooks.json",
+        ".codex/skills/*/SKILL.md",
+        "~/.codex/config.toml"
+      ],
+      "our_generators": [
+        "scripts/generate_codex.py",
+        "scripts/generate_codex_rules.py",
+        "scripts/generate_codex_hooks.py"
+      ],
+      "capability_markers": [
+        "AGENTS.md",
+        "config.toml",
+        "mcp_servers",
+        "hooks",
+        "sandbox",
+        "hook event: PreToolUse",
+        "hook event: PostToolUse",
+        "hook event: SessionStart",
+        "hook event: UserPromptSubmit",
+        "hook event: Stop",
+        "hook event: PermissionRequest",
+        "hook handler: command",
+        "hook handler: prompt",
+        "hook handler: agent",
+        ".codex/skills"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "codex --version"
+      }
+    },
+    {
+      "id": "opencode",
+      "display_name": "opencode",
+      "kind": "editor",
+      "urls": {
+        "docs": "https://opencode.ai/docs",
+        "release_notes": "https://github.com/sst/opencode/releases",
+        "changelog": null
+      },
+      "config_paths": [
+        "opencode.json",
+        ".opencode/agents/*.md",
+        ".opencode/commands/*.md",
+        ".opencode/plugins/*",
+        ".opencode/skills/*/SKILL.md",
+        "AGENTS.md",
+        ".claude/skills/*/SKILL.md"
+      ],
+      "our_generators": [
+        "scripts/generate_opencode.py",
+        "scripts/generate_opencode_agents.py",
+        "scripts/generate_opencode_commands.py",
+        "scripts/generate_opencode_json.py",
+        "scripts/generate_opencode_plugin.py"
+      ],
+      "capability_markers": [
+        "opencode.json",
+        "agents",
+        "commands",
+        "plugins",
+        "MCP",
+        "rules",
+        "AGENTS.md",
+        "skills (native .opencode/skills)",
+        "skills (via .claude/skills fallback)",
+        "permission.skill",
+        "subagent mode",
+        "primary mode",
+        "plugin event: session.created",
+        "plugin event: session.compacted",
+        "plugin event: session.deleted",
+        "plugin event: tool.execute.before",
+        "plugin event: tool.execute.after",
+        "plugin event: permission.asked",
+        "plugin event: command.executed",
+        "plugin event: message.updated"
+      ],
+      "version_probe": {
+        "kind": "command",
+        "command": "opencode --version"
+      }
+    }
+  ]
+}

package/scripts/generate_aider_conf.py

@@ -17,9 +17,13 @@ def main() -> None:
     default_model = DEFAULT_CLAUDE_MODELS["sonnet"]
     print("# Aider configuration generated by ai-toolkit")
     print("# Regenerate using: ai-toolkit install --local")
+    print("# Aider docs: https://aider.chat/docs/config/aider_conf.html")
     print()
     print("# Use the architect mode for complex tasks, aligned with our 2-phase workflow")
     print("architect: true")
+    print("# Auto-accept architect proposals (default: true in aider >=0.82). Set to false")
+    print("# if you want to approve every architect-mode edit manually.")
+    print("auto-accept-architect: true")
     print()
     print("# Read project rules (loaded as read-only context)")
     print("read:")
@@ -36,16 +40,37 @@ def main() -> None:
     print('  - "php: ./vendor/bin/phpstan analyse"')
     print('  - "go: go vet"')
     print()
+    print("# Test commands (uncomment and customize per project). aider >=0.80 supports a")
+    print("# single `test-cmd`; run with `--test` or enable `auto-test: true` to run after edits.")
+    print("# test-cmd: pytest -q")
+    print("# auto-test: false")
+    print()
     print("# Model configuration")
     print(f"model: {default_model}")
     print(f"editor-model: {default_model}")
     print()
     print("# Auto-commit message formatting (matches our conventional commits)")
     print(
-        'commit_prompt: "Write a short, concise commit message following'
+        'commit-prompt: "Write a short, concise commit message following'
         ' Conventional Commits (feat/fix/chore/docs/test/refactor)."'
     )
     print()
+    print("# Git attribution (ai-toolkit policy: no AI co-authorship in commits).")
+    print("# Do not flip this to true -- conflicts with the toolkit git-workflow rule")
+    print("# (see app/rules/common/git-workflow.md).")
+    print("attribute-co-authored-by: false")
+    print("attribute-commit-message-author: false")
+    print("attribute-commit-message-committer: false")
+    print()
+    print("# Language settings (aider >=0.83 `commit-language`, >=0.85 confirmed stable).")
+    print("# Leave unset to inherit the user's system locale. Uncomment to pin.")
+    print("# chat-language: en")
+    print("# commit-language: en")
+    print()
+    print("# Watch-files mode scans for `# AI!` / `# ai?` comments (aider >=0.75). Opt-in")
+    print("# because it changes how aider reads your editor buffers.")
+    print("# watch-files: false")
+    print()
     print("# Disable auto-commits if you prefer using the /commit slash skill explicitly")
     print("# auto-commits: false")
     print()

package/scripts/generate_antigravity.py

@@ -1,16 +1,25 @@
 #!/usr/bin/env python3
-"""Generate Antigravity IDE .agent/rules/ and .agent/workflows/ files.
+"""Generate Antigravity IDE ``.agent/rules/``, ``.agent/workflows/``, and
+skill pointer files.
 
 Antigravity reads rules from:
-  - GEMINI.md (highest priority) — already generated by generate_gemini.py
-  - AGENTS.md (cross-tool) — already generated by generate_agents_md.py
-  - .agent/rules/*.md — per-category rule files (this generator)
-  - .agent/workflows/*.md — workflow templates (this generator)
+  * ``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)
+
+Antigravity also supports the Agent Skills standard via ``.agent/skills/
+<skill-name>/SKILL.md`` (the changelog entry "Agent Skills now available in
+Antigravity" confirms this surface). We do not duplicate our full skill
+catalogue into ``.agent/skills/``; instead we emit a single pointer skill
+that teaches Antigravity to look up the real catalogue in
+``~/.softspark/ai-toolkit/app/skills/`` (global install) or
+``.claude/skills/`` (local install).
 
 Usage:
   python3 scripts/generate_antigravity.py [target-dir]
 
-Writes files directly to target-dir/.agent/rules/ and .agent/workflows/.
+Writes files directly to target-dir/.agent/{rules,workflows,skills}/.
 """
 from __future__ import annotations
 
@@ -25,17 +34,77 @@ from dir_rules_shared import (
     build_registered_rules,
     write_rules,
 )
+from emission import emit_skills_bullets
+
+
+# ---------------------------------------------------------------------------
+# Skill pointer — a single SKILL.md that directs Antigravity to our catalogue
+# ---------------------------------------------------------------------------
+
+POINTER_SKILL_NAME = "ai-toolkit-skill-catalogue"
+
 
+def _pointer_skill_md() -> str:
+    """Build the SKILL.md body for the 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 .agent/skills/<name>/."""
+    skill_dir = target_dir / ".agent" / "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: .agent/skills/{POINTER_SKILL_NAME}/SKILL.md")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
 
 def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
-             rules_dir: Path | None = None) -> None:
-    """Write .agent/rules/ and .agent/workflows/ files to target_dir."""
+             rules_dir: Path | None = None,
+             emit_skill_pointer: bool = True) -> None:
+    """Write ``.agent/rules/``, ``.agent/workflows/``, and ``.agent/skills/``.
+
+    ``emit_skill_pointer`` controls whether the pointer SKILL.md is written.
+    Set to ``False`` if you manage ``.agent/skills/`` yourself.
+    """
     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")
+    if emit_skill_pointer:
+        _write_skill_pointer(target_dir)
 
 
 def main() -> None: