@softspark/ai-toolkit 1.0.0

package/llms.txt

@@ -0,0 +1,39 @@
+# ai-toolkit
+
+> Professional-grade Claude Code toolkit: 85 skills, 47 agents, machine-enforced constitution, quality hooks.
+
+## Documentation
+
+- [README](README.md): Installation, usage, and feature overview
+- [CHANGELOG](CHANGELOG.md): Version history
+- [ARCHITECTURE](app/ARCHITECTURE.md): System design
+- [CONSTITUTION](app/constitution.md): Safety rules
+
+## Knowledge Base
+
+- [Best Practices](kb/best-practices/README.md)
+- [How-To Guides](kb/howto/README.md)
+- [SOP: Claude Toolkit Maintenance](kb/procedures/maintenance-sop.md)
+- [Agents Catalog (47 agents)](kb/reference/agents-catalog.md)
+- [Anti-Pattern Registry Format](kb/reference/anti-pattern-registry-format.md)
+- [AI Toolkit Architecture](kb/reference/architecture-overview.md)
+- [Config Benchmark](kb/reference/benchmark-config.md)
+- [CI Integration](kb/reference/ci-integration.md)
+- [Claude Ecosystem Benchmark Snapshot](kb/reference/claude-ecosystem-benchmark-snapshot.md)
+- [Claude Ecosystem Expansion Foundations](kb/reference/claude-ecosystem-expansion-foundations.md)
+- [Commands Catalog (DEPRECATED)](kb/reference/commands-catalog.md)
+- [Distribution Model](kb/reference/distribution-model.md)
+- [Global Install Model](kb/reference/global-install-model.md)
+- [Hierarchical Override Pattern](kb/reference/hierarchical-override-pattern.md)
+- [Hooks Catalog](kb/reference/hooks-catalog.md)
+- [External Integrations](kb/reference/integrations.md)
+- [Language Plugin Packs](kb/reference/language-packs.md)
+- [Merge-Friendly Install Model](kb/reference/merge-friendly-install-model.md)
+- [Plugin Pack Conventions](kb/reference/plugin-pack-conventions.md)
+- [Quick Wins Implementation Summary](kb/reference/quick-wins-implementation-summary.md)
+- [Skill Templates](kb/reference/skill-templates.md)
+- [Skills Catalog (85 skills)](kb/reference/skills-catalog.md)
+- [Skills Unification Model](kb/reference/skills-unification.md)
+- [Usage Statistics](kb/reference/stats.md)
+- [Config Sync](kb/reference/sync.md)
+- [Troubleshooting](kb/troubleshooting/README.md)

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@softspark/ai-toolkit",
+  "version": "1.0.0",
+  "description": "Professional-grade AI coding toolkit: 85 skills, 47 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider), machine-enforced safety constitution, Iron Law enforcement, persistent memory, visual brainstorming, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai",
+    "agents",
+    "skills",
+    "llm",
+    "toolkit",
+    "developer-tools",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "gemini",
+    "cline",
+    "roo-code",
+    "roo",
+    "aider",
+    "multi-platform"
+  ],
+  "homepage": "https://github.com/softspark/ai-toolkit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/softspark/ai-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/softspark/ai-toolkit/issues"
+  },
+  "license": "MIT",
+  "author": "SoftSpark <biuro@softspark.eu>",
+  "main": "bin/ai-toolkit.js",
+  "bin": {
+    "ai-toolkit": "bin/ai-toolkit.js"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run generate:all && python3 scripts/validate.py && npm test",
+    "test": "bats tests/ --jobs 4 --no-parallelize-within-files",
+    "validate": "python3 scripts/validate.py",
+    "evaluate": "python3 scripts/evaluate_skills.py",
+    "benchmark:ecosystem": "python3 scripts/benchmark_ecosystem.py --offline",
+    "benchmark:harvest": "python3 scripts/harvest_ecosystem.py --offline",
+    "generate:agents": "python3 scripts/generate_agents_md.py > AGENTS.md",
+    "generate:cursor": "python3 scripts/generate_cursor_rules.py > .cursorrules",
+    "generate:llms": "python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt",
+    "generate:windsurf": "python3 scripts/generate_windsurf.py > .windsurfrules",
+    "generate:copilot": "python3 scripts/generate_copilot.py > .github/copilot-instructions.md",
+    "generate:gemini": "python3 scripts/generate_gemini.py > GEMINI.md",
+    "generate:cline": "python3 scripts/generate_cline.py > .clinerules",
+    "generate:roo": "python3 scripts/generate_roo_modes.py > .roomodes",
+    "generate:aider": "python3 scripts/generate_aider_conf.py > .aider.conf.yml",
+    "generate:all": "npm run generate:agents && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
+  },
+  "files": [
+    "bin/",
+    "app/",
+    "scripts/",
+    "kb/",
+    "benchmarks/",
+    "action.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "AGENTS.md",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "bats": ">=1.8.0 — install via: brew install bats-core (macOS) or apt install bats (Ubuntu)"
+  }
+}

package/scripts/_common.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Shared library for ai-toolkit Python scripts.
+
+This module is a **facade** that re-exports from focused sub-modules:
+  - frontmatter.py — YAML frontmatter parsing
+  - injection.py  — marker-based section injection and rule management
+  - emission.py   — markdown emission, counting, and generator helpers
+
+All functions are stdlib-only. Import and use from any scripts/*.py file.
+
+Usage:
+    from _common import toolkit_dir, frontmatter_field, inject_section
+"""
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Re-exports from frontmatter module
+# ---------------------------------------------------------------------------
+from frontmatter import frontmatter_field, frontmatter_block  # noqa: F401
+
+# ---------------------------------------------------------------------------
+# Re-exports from injection module
+# ---------------------------------------------------------------------------
+from injection import (  # noqa: F401
+    markers_start,
+    markers_end,
+    inject_section,
+    inject_rule,
+    remove_rule_section,
+    # Internal helpers re-exported for backwards compat (install.py uses them)
+    strip_section as _strip_section,
+    trim_trailing_blanks as _trim_trailing_blanks,
+    collapse_blank_runs as _collapse_blank_runs,
+)
+
+# ---------------------------------------------------------------------------
+# Re-exports from emission module
+# ---------------------------------------------------------------------------
+from emission import (  # noqa: F401
+    agent_count,
+    skill_count,
+    count_agents_and_skills,
+    emit_agents_headings,
+    emit_agents_bullets,
+    emit_skills_headings,
+    emit_skills_bullets,
+    print_toolkit_start,
+    print_toolkit_end,
+    generate_general_guidelines,
+    generate_quality_standards,
+    generate_workflow_guidelines,
+    generate_quality_guidelines,
+)
+
+# ---------------------------------------------------------------------------
+# Path constants (canonical source — emission.py also resolves these)
+# ---------------------------------------------------------------------------
+
+def _resolve_toolkit_dir() -> Path:
+    """Resolve the toolkit root directory (parent of scripts/)."""
+    return Path(__file__).resolve().parent.parent
+
+
+toolkit_dir: Path = _resolve_toolkit_dir()
+app_dir: Path = toolkit_dir / "app"
+agents_dir: Path = app_dir / "agents"
+skills_dir: Path = app_dir / "skills"
+
+
+# ---------------------------------------------------------------------------
+# Component filtering (for install/update)
+# ---------------------------------------------------------------------------
+
+def should_install(component: str, only: str = "", skip: str = "") -> bool:
+    """Check if a component should be installed (respects --only and --skip)."""
+    if only:
+        allowed = [c.strip() for c in only.split(",")]
+        if component not in allowed:
+            return False
+    if skip:
+        skipped = [c.strip() for c in skip.split(",")]
+        if component in skipped:
+            return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# OS detection (for dependency checker)
+# ---------------------------------------------------------------------------
+
+def detect_os() -> dict[str, str]:
+    """Detect operating system and package manager.
+
+    Returns dict with keys: os, distro, pkg_manager, install_cmd.
+    """
+    system = platform.system().lower()
+
+    if system == "darwin":
+        return {
+            "os": "macOS",
+            "distro": platform.mac_ver()[0],
+            "pkg_manager": "brew" if shutil.which("brew") else "none",
+            "install_cmd": "brew install",
+        }
+
+    if system == "linux":
+        distro = ""
+        pkg_manager = "none"
+        install_cmd = ""
+
+        # Read os-release
+        for path in ("/etc/os-release", "/usr/lib/os-release"):
+            if os.path.isfile(path):
+                with open(path) as f:
+                    for line in f:
+                        if line.startswith("ID="):
+                            distro = line.strip().split("=", 1)[1].strip('"')
+                        elif line.startswith("ID_LIKE="):
+                            if not distro:
+                                distro = line.strip().split("=", 1)[1].strip('"').split()[0]
+                break
+
+        # Map distro to package manager
+        if distro in ("ubuntu", "debian", "linuxmint", "pop"):
+            pkg_manager = "apt"
+            install_cmd = "sudo apt install -y"
+        elif distro in ("fedora", "rhel", "centos", "rocky", "alma"):
+            pkg_manager = "dnf" if shutil.which("dnf") else "yum"
+            install_cmd = f"sudo {pkg_manager} install -y"
+        elif distro in ("arch", "manjaro", "endeavouros"):
+            pkg_manager = "pacman"
+            install_cmd = "sudo pacman -S --noconfirm"
+        elif distro == "alpine":
+            pkg_manager = "apk"
+            install_cmd = "sudo apk add"
+        elif distro in ("opensuse", "suse"):
+            pkg_manager = "zypper"
+            install_cmd = "sudo zypper install -y"
+
+        # Check for WSL
+        is_wsl = "microsoft" in platform.release().lower()
+
+        return {
+            "os": "WSL" if is_wsl else "Linux",
+            "distro": distro,
+            "pkg_manager": pkg_manager,
+            "install_cmd": install_cmd,
+        }
+
+    return {
+        "os": system,
+        "distro": "",
+        "pkg_manager": "none",
+        "install_cmd": "",
+    }

package/scripts/add_rule.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""add-rule -- Register a rule file in ~/.ai-toolkit/rules/.
+
+Registered rules are automatically injected into all AI tool configs
+(Claude, Cursor, Windsurf, Gemini) on next 'ai-toolkit install',
+and into project-local configs (Copilot, Cline) on 'ai-toolkit install --local'.
+
+Usage:
+  add_rule.py <rule-file> [rule-name]
+
+Arguments:
+  rule-file   Path to .md file with the rule content
+  rule-name   Override the rule name (default: filename without .md)
+"""
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+def main() -> None:
+    """Register a rule file in the global rules directory."""
+    if len(sys.argv) < 2:
+        print("Usage: add_rule.py <rule-file> [rule-name]", file=sys.stderr)
+        sys.exit(1)
+
+    rule_file = Path(sys.argv[1])
+    if not rule_file.is_file():
+        print(f"Rule file not found: {rule_file}", file=sys.stderr)
+        sys.exit(1)
+
+    rule_name = sys.argv[2] if len(sys.argv) > 2 else rule_file.stem
+    rules_dir = Path.home() / ".ai-toolkit" / "rules"
+    rules_dir.mkdir(parents=True, exist_ok=True)
+
+    dest = rules_dir / f"{rule_name}.md"
+    shutil.copy2(rule_file, dest)
+
+    print(f"Registered: '{rule_name}' -> {dest}")
+    print()
+    print("Apply now:")
+    print("  ai-toolkit update            # global (Claude, Cursor, Windsurf, Gemini)")
+    print("  ai-toolkit update --local    # project-local (Copilot, Cline)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/benchmark_config.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""ai-toolkit benchmark --my-config — Compare user config vs toolkit vs ecosystem."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import toolkit_dir
+
+CLAUDE_DIR = Path.home() / ".claude"
+HOOKS_DIR = Path.home() / ".ai-toolkit" / "hooks"
+DASHBOARD = toolkit_dir / "benchmarks" / "ecosystem-dashboard.json"
+
+
+def count_files(directory: Path, pattern: str, min_depth: int = 0) -> int:
+    """Count files matching pattern in directory."""
+    if not directory.is_dir():
+        return 0
+    count = 0
+    for p in directory.iterdir():
+        if min_depth > 0 and not p.is_dir():
+            continue
+        if p.name.endswith(pattern.lstrip("*")) if "*" in pattern else p.name == pattern:
+            count += 1
+        if min_depth > 0 and p.is_dir():
+            count += 1
+    return count
+
+
+def main() -> None:
+    tk_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else toolkit_dir
+
+    print("AI Toolkit Config Benchmark")
+    print("========================")
+    print()
+
+    # --- User's installed components ---
+    print("## Your Configuration (~/.claude/)")
+
+    user_agents = sum(1 for f in (CLAUDE_DIR / "agents").glob("*.md")) if (CLAUDE_DIR / "agents").is_dir() else 0
+    user_skills = sum(1 for d in (CLAUDE_DIR / "skills").iterdir() if d.is_dir() or d.is_symlink()) if (CLAUDE_DIR / "skills").is_dir() else 0
+    user_hooks = sum(1 for f in HOOKS_DIR.glob("*.sh")) if HOOKS_DIR.is_dir() else 0
+
+    print(f"  Agents:  {user_agents}")
+    print(f"  Skills:  {user_skills}")
+    print(f"  Hooks:   {user_hooks}")
+    print()
+
+    # --- Toolkit totals ---
+    print("## Toolkit Totals")
+
+    tk_agents = sum(1 for f in (tk_dir / "app" / "agents").glob("*.md"))
+    tk_skills = sum(1 for d in (tk_dir / "app" / "skills").iterdir() if d.is_dir())
+    tk_hooks = sum(1 for f in (tk_dir / "app" / "hooks").glob("*.sh"))
+
+    print(f"  Agents:  {tk_agents}")
+    print(f"  Skills:  {tk_skills}")
+    print(f"  Hooks:   {tk_hooks}")
+    print()
+
+    # --- Coverage ---
+    print("## Coverage")
+
+    agent_pct = (user_agents * 100 // tk_agents) if tk_agents > 0 else 0
+    skill_pct = (user_skills * 100 // tk_skills) if tk_skills > 0 else 0
+    hook_pct = (user_hooks * 100 // tk_hooks) if tk_hooks > 0 else 0
+
+    print(f"  Agents:  {agent_pct}%  ({user_agents} / {tk_agents})")
+    print(f"  Skills:  {skill_pct}%  ({user_skills} / {tk_skills})")
+    print(f"  Hooks:   {hook_pct}%  ({user_hooks} / {tk_hooks})")
+    print()
+
+    # --- Missing components ---
+    if user_agents < tk_agents or user_skills < tk_skills:
+        print("## Missing Components")
+        shown = 0
+        if (tk_dir / "app" / "agents").is_dir() and (CLAUDE_DIR / "agents").is_dir():
+            for agent in sorted((tk_dir / "app" / "agents").glob("*.md")):
+                if not (CLAUDE_DIR / "agents" / agent.name).exists():
+                    print(f"  Agent: {agent.name}")
+                    shown += 1
+                    if shown >= 10:
+                        break
+            missing = tk_agents - user_agents
+            if missing > 10:
+                print(f"  ... and {missing - 10} more agents")
+
+        if (tk_dir / "app" / "skills").is_dir() and (CLAUDE_DIR / "skills").is_dir():
+            for skill_dir in sorted((tk_dir / "app" / "skills").iterdir()):
+                if not skill_dir.is_dir():
+                    continue
+                if not (CLAUDE_DIR / "skills" / skill_dir.name).exists():
+                    print(f"  Skill: {skill_dir.name}")
+                    shown += 1
+                    if shown >= 20:
+                        break
+            missing = tk_skills - user_skills
+            if missing > 10:
+                print(f"  ... and {missing - 10} more skills")
+        print()
+
+    # --- Ecosystem comparison ---
+    if DASHBOARD.is_file():
+        print("## Ecosystem Comparison")
+        with open(DASHBOARD) as f:
+            data = json.load(f)
+
+        header = f"{'Repo':<40} {'Agents':>7} {'Skills':>7} {'Hooks':>6}"
+        print(header)
+        print("-" * 62)
+        print(f"{'Your config':<40} {user_agents:>7} {user_skills:>7} {user_hooks:>6}")
+        print("-" * 62)
+        for repo in data.get("repos", []):
+            name = repo.get("repo", "unknown")
+            agents = repo.get("agents_md", 0)
+            skills = repo.get("skills", 0) + repo.get("commands_md", 0)
+            hooks = repo.get("hook_settings_files", 0)
+            print(f"{name:<40} {agents:>7} {skills:>7} {hooks:>6}")
+
+    print()
+    print("Run 'ai-toolkit install' to sync missing components.")
+
+
+if __name__ == "__main__":
+    main()