@softspark/ai-toolkit 1.0.0

package/scripts/generate_aider_conf.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Generate .aider.conf.yml configuration.
+
+Usage: ./scripts/generate_aider_conf.py > .aider.conf.yml
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+def main() -> None:
+    print("# Aider configuration generated by ai-toolkit")
+    print("# Regenerate using: ai-toolkit install --local")
+    print()
+    print("# Use the architect mode for complex tasks, aligned with our 2-phase workflow")
+    print("architect: true")
+    print()
+    print("# Read global rules ")
+    print("read:")
+    print('  - ".claude/CLAUDE.md"')
+    print('  - ".claude/constitution.md"')
+    print('  - "AGENTS.md"')
+    print()
+    print("# Linting commands for quality gates")
+    print("lint-cmd:")
+    print('  - "python: ruff check"')
+    print('  - "typescript: npx eslint"')
+    print('  - "javascript: npx eslint"')
+    print('  - "php: ./vendor/bin/phpstan analyse"')
+    print('  - "go: go vet"')
+    print()
+    print("# Model configuration")
+    print("model: claude-sonnet-4-6")
+    print("editor-model: claude-sonnet-4-6")
+    print()
+    print("# Auto-commit message formatting (matches our conventional commits)")
+    print(
+        'commit_prompt: "Write a short, concise commit message following'
+        ' Conventional Commits (feat/fix/chore/docs/test/refactor)."'
+    )
+    print()
+    print("# Disable auto-commits if you prefer using the /commit slash skill explicitly")
+    print("# auto-commits: false")
+    print()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_cline.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Generate .clinerules from app/agents/*.md and app/skills/*/SKILL.md.
+
+Usage: ./scripts/generate_cline.py > .clinerules
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from generator_base import render_generator
+
+if __name__ == "__main__":
+    render_generator({
+        "title": "# Cline Rules — generated from ai-toolkit agents",
+        "header_lines": [
+            "# Auto-generated by scripts/generate-cline.sh — do not edit manually.",
+            "# Regenerate: ./scripts/generate-cline.sh > .clinerules",
+        ],
+        "intro_template": (
+            "This repository uses the ai-toolkit — a shared AI development toolkit"
+            " with {agents} specialized agent personas and {skills} skills."
+        ),
+        "agents_section": "## Available Agent Personas",
+        "agents_intro": "Apply the expertise of these agents when working on relevant tasks:",
+        "agents_format": "headings",
+        "agents_level": "##",
+        "skills_section": "## Available Skills",
+        "skills_intro": "The following skills are available as slash commands or knowledge sources:",
+        "skills_format": "headings",
+        "skills_level": "##",
+        "trailing_newline_after_skills": True,
+        "guidelines": ["general"],
+    })

package/scripts/generate_copilot.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Generate .github/copilot-instructions.md from app/agents/*.md and app/skills/*/SKILL.md.
+
+Usage: ./scripts/generate_copilot.py > .github/copilot-instructions.md
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from generator_base import render_generator
+
+if __name__ == "__main__":
+    render_generator({
+        "title": "# GitHub Copilot Instructions",
+        "intro_template": (
+            "This repository uses the ai-toolkit — a shared AI development toolkit"
+            " with {agents} specialized agent personas and {skills} skills."
+        ),
+        "agents_section": "## Available Agent Personas",
+        "agents_intro": "Apply the expertise of these agents when working on relevant tasks:",
+        "agents_format": "headings",
+        "agents_level": "###",
+        "skills_section": "## Available Skills",
+        "skills_intro": "The following skills are available as slash commands or knowledge sources:",
+        "skills_format": "headings",
+        "skills_level": "###",
+        "guidelines": ["quality"],
+    })

package/scripts/generate_cursor_rules.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Generate .cursorrules from app/agents/*.md and app/skills/*/SKILL.md.
+
+Usage: ./scripts/generate_cursor_rules.py > .cursorrules
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from generator_base import render_generator
+
+if __name__ == "__main__":
+    render_generator({
+        "title": "# Cursor Rules — generated from ai-toolkit agents",
+        "header_lines": [
+            "# Auto-generated by scripts/generate-cursor-rules.sh — do not edit manually.",
+            "# Regenerate: ./scripts/generate-cursor-rules.sh > .cursorrules",
+        ],
+        "intro_template": (
+            "This repository uses the ai-toolkit — a shared AI development toolkit"
+            " with {agents} specialized agent personas and {skills} skills."
+        ),
+        "agents_section": "## Available Agent Personas",
+        "agents_intro": "Apply the expertise of these agents when working on relevant tasks:",
+        "agents_format": "headings",
+        "agents_level": "##",
+        "skills_section": "## Available Skills",
+        "skills_intro": "The following skills are available as slash commands or knowledge sources:",
+        "skills_format": "headings",
+        "skills_level": "##",
+        "trailing_newline_after_skills": True,
+        "guidelines": ["general"],
+    })

package/scripts/generate_gemini.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Generate GEMINI.md from app/agents/*.md and app/skills/*/SKILL.md.
+
+Usage: ./scripts/generate_gemini.py > GEMINI.md
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from generator_base import render_generator
+
+if __name__ == "__main__":
+    render_generator({
+        "title": "# AI Toolkit — Gemini CLI Configuration",
+        "intro_template": (
+            "Shared AI development toolkit with {agents} specialized agents,"
+            " {skills} skills, quality hooks, and a safety constitution."
+        ),
+        "agents_section": "## Available Agents ({agents})",
+        "agents_intro": "Specialized agent personas — apply their expertise for relevant tasks:",
+        "agents_format": "bullets",
+        "skills_section": "## Available Skills ({skills})",
+        "skills_intro": "Skills are invocable slash commands or auto-loaded knowledge sources:",
+        "skills_format": "bullets",
+        "guidelines": ["quality_standards", "workflow"],
+    })

package/scripts/generate_llms_txt.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Generate llms.txt and llms-full.txt from kb/ docs.
+
+Usage:
+  ./scripts/generate_llms_txt.py          -> llms.txt (index only)
+  ./scripts/generate_llms_txt.py --full   -> llms-full.txt (full content)
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import agents_dir, frontmatter_field, skill_count, skills_dir, toolkit_dir
+
+
+def _relative(path: Path) -> str:
+    """Return path relative to toolkit_dir."""
+    return str(path.relative_to(toolkit_dir))
+
+
+def _title_from_md(filepath: Path) -> str:
+    """Extract the first ``# `` heading from a markdown file, or fallback to stem."""
+    with open(filepath, encoding="utf-8") as f:
+        for line in f:
+            if line.startswith("# "):
+                return line[2:].strip()
+    return filepath.stem
+
+
+def _find_kb_files() -> list[Path]:
+    """Find all .md files under kb/, sorted."""
+    kb_dir = toolkit_dir / "kb"
+    if not kb_dir.is_dir():
+        return []
+    return sorted(kb_dir.rglob("*.md"))
+
+
+def _find_skill_files() -> list[Path]:
+    """Find all SKILL.md files, sorted."""
+    return sorted(skills_dir.rglob("SKILL.md"))
+
+
+def _find_agent_files() -> list[Path]:
+    """Find all agent .md files, sorted."""
+    return sorted(agents_dir.glob("*.md"))
+
+
+def _count_skills() -> int:
+    """Count skill directories containing SKILL.md."""
+    return skill_count()
+
+
+def _count_agents() -> int:
+    """Count agent .md files."""
+    return sum(1 for f in agents_dir.glob("*.md") if f.is_file())
+
+
+def generate_index() -> None:
+    """Print the llms.txt index."""
+    skills = _count_skills()
+    agents = _count_agents()
+
+    print("# ai-toolkit")
+    print()
+    print(
+        f"> Professional-grade Claude Code toolkit: {skills} skills,"
+        f" {agents} agents, machine-enforced constitution, quality hooks."
+    )
+    print()
+    print("## Documentation")
+    print()
+
+    readme = toolkit_dir / "README.md"
+    if readme.is_file():
+        print("- [README](README.md): Installation, usage, and feature overview")
+    changelog = toolkit_dir / "CHANGELOG.md"
+    if changelog.is_file():
+        print("- [CHANGELOG](CHANGELOG.md): Version history")
+    contributing = toolkit_dir / "CONTRIBUTING.md"
+    if contributing.is_file():
+        print("- [CONTRIBUTING](CONTRIBUTING.md): How to add agents and skills")
+    architecture = toolkit_dir / "app" / "ARCHITECTURE.md"
+    if architecture.is_file():
+        print("- [ARCHITECTURE](app/ARCHITECTURE.md): System design")
+    constitution = toolkit_dir / "app" / "constitution.md"
+    if constitution.is_file():
+        print("- [CONSTITUTION](app/constitution.md): Safety rules")
+
+    kb_files = _find_kb_files()
+    if kb_files:
+        print()
+        print("## Knowledge Base")
+        print()
+        for f in kb_files:
+            rel = _relative(f)
+            title = _title_from_md(f)
+            print(f"- [{title}]({rel})")
+
+
+def generate_skills_listing() -> None:
+    """Print the skills listing section."""
+    print()
+    print("## Skills")
+    print()
+
+    for skill_file in _find_skill_files():
+        skill_name = frontmatter_field(skill_file, "name")
+        if not skill_name:
+            skill_name = skill_file.parent.name
+        skill_desc = frontmatter_field(skill_file, "description")
+        print(f"- **{skill_name}**: {skill_desc}")
+
+
+def generate_agents_listing() -> None:
+    """Print the agents listing section."""
+    print()
+    print("## Agents")
+    print()
+
+    for agent_file in _find_agent_files():
+        if not agent_file.is_file():
+            continue
+        agent_name = frontmatter_field(agent_file, "name")
+        if not agent_name:
+            agent_name = agent_file.stem
+        agent_desc = frontmatter_field(agent_file, "description")
+        print(f"- **{agent_name}**: {agent_desc}")
+
+
+def generate_full() -> None:
+    """Print full llms-full.txt with all KB content inlined."""
+    generate_index()
+    generate_skills_listing()
+    generate_agents_listing()
+
+    kb_files = _find_kb_files()
+    if kb_files:
+        print()
+        print("---")
+        print()
+
+        for f in kb_files:
+            rel = _relative(f)
+            print(f"## {rel}")
+            print()
+            sys.stdout.write(f.read_text(encoding="utf-8"))
+            print()
+            print("---")
+            print()
+
+
+def main() -> None:
+    full_mode = "--full" in sys.argv[1:]
+
+    if full_mode:
+        generate_full()
+    else:
+        generate_index()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_roo_modes.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Generate .roomodes JSON from app/agents/*.md.
+
+Usage: ./scripts/generate_roo_modes.py > .roomodes
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import agents_dir, frontmatter_field
+
+
+def _json_escape(s: str) -> str:
+    """Escape a string for safe JSON embedding (no stdlib json dependency needed)."""
+    s = s.replace("\\", "\\\\")
+    s = s.replace('"', '\\"')
+    s = s.replace("\n", "\\n")
+    s = s.replace("\t", "\\t")
+    s = s.replace("\r", "")
+    return s
+
+
+def _read_body(filepath: Path) -> str:
+    """Read file content after YAML frontmatter (after second --- delimiter).
+
+    Trailing blank lines are stripped to match bash ``$(...)`` behaviour.
+    """
+    lines: list[str] = []
+    fence_count = 0
+    with open(filepath, encoding="utf-8") as f:
+        for line in f:
+            stripped = line.rstrip("\n")
+            if stripped == "---":
+                fence_count += 1
+                continue
+            if fence_count >= 2:
+                lines.append(line.rstrip("\n"))
+    # Strip trailing empty lines (bash command substitution strips trailing newlines)
+    while lines and not lines[-1]:
+        lines.pop()
+    return "\n".join(lines)
+
+
+def main() -> None:
+    first = True
+    sys.stdout.write('{\n  "customModes": [\n')
+
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        if not agent_file.is_file():
+            continue
+
+        slug = agent_file.stem
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+
+        if not name or not description:
+            continue
+
+        role_def = _read_body(agent_file)
+        role_text = f"{description}\n\n{role_def}"
+
+        if first:
+            first = False
+        else:
+            sys.stdout.write(",\n")
+
+        sys.stdout.write("    {\n")
+        sys.stdout.write(f'      "slug": "{_json_escape(slug)}",\n')
+        sys.stdout.write(f'      "name": "{_json_escape(name)}",\n')
+        sys.stdout.write(f'      "roleDefinition": "{_json_escape(role_text)}",\n')
+        sys.stdout.write('      "groups": ["read", "edit", "command", "mcp"]\n')
+        sys.stdout.write("    }")
+
+    sys.stdout.write("\n  ]\n}\n")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_windsurf.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Generate .windsurfrules from app/agents/*.md and app/skills/*/SKILL.md.
+
+Usage: ./scripts/generate_windsurf.py > .windsurfrules
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from generator_base import render_generator
+
+if __name__ == "__main__":
+    render_generator({
+        "title": "# Windsurf Rules — generated from ai-toolkit agents",
+        "header_lines": [
+            "# Auto-generated by scripts/generate-windsurf.sh — do not edit manually.",
+            "# Regenerate: ./scripts/generate-windsurf.sh > .windsurfrules",
+        ],
+        "intro_template": (
+            "This repository uses the ai-toolkit — a shared AI development toolkit"
+            " with {agents} specialized agent personas and {skills} skills."
+        ),
+        "agents_section": "## Available Agent Personas",
+        "agents_intro": "Apply the expertise of these agents when working on relevant tasks:",
+        "agents_format": "headings",
+        "agents_level": "##",
+        "skills_section": "## Available Skills",
+        "skills_intro": "The following skills are available as slash commands or knowledge sources:",
+        "skills_format": "headings",
+        "skills_level": "##",
+        "trailing_newline_after_skills": True,
+        "guidelines": ["general"],
+    })

package/scripts/generator_base.py

@@ -0,0 +1,140 @@
+"""Shared generator pipeline for producing AI tool configs.
+
+Each generator declares its output format via a config dict.
+This module handles the shared pipeline: count → emit → wrap.
+
+Stdlib-only.
+
+Usage::
+
+    from generator_base import render_generator
+
+    render_generator({
+        "title": "# Cursor Rules",
+        "header_lines": ["# Auto-generated..."],
+        "intro_template": "This repo uses ai-toolkit with {agents} agents and {skills} skills.",
+        "agents_section": "## Available Agent Personas",
+        "agents_format": "headings",    # "headings" or "bullets"
+        "agents_level": "##",           # heading level (for "headings" format)
+        "skills_section": "## Available Skills",
+        "skills_format": "headings",    # "headings" or "bullets"
+        "skills_level": "##",           # heading level (for "headings" format)
+        "guidelines_fn": "general",     # "general"|"quality"|"quality_standards"|"workflow"|None
+        "use_markers": True,            # wrap in TOOLKIT markers
+        "trailing_newline_after_skills": True,  # extra blank line after skills
+    })
+"""
+from __future__ import annotations
+
+import sys
+
+from emission import (
+    count_agents_and_skills,
+    emit_agents_bullets,
+    emit_agents_headings,
+    emit_skills_bullets,
+    emit_skills_headings,
+    generate_general_guidelines,
+    generate_quality_guidelines,
+    generate_quality_standards,
+    generate_workflow_guidelines,
+    print_toolkit_end,
+    print_toolkit_start,
+)
+
+# Map guideline names to functions
+_GUIDELINES = {
+    "general": generate_general_guidelines,
+    "quality": generate_quality_guidelines,
+    "quality_standards": generate_quality_standards,
+    "workflow": generate_workflow_guidelines,
+}
+
+
+def render_generator(config: dict) -> None:
+    """Render a generator output based on a declarative config.
+
+    Config keys:
+        title: str — main heading line
+        header_lines: list[str] — additional header lines (comments etc)
+        intro_template: str — format string with {agents} and {skills}
+        agents_section: str — heading for agents section
+        agents_format: "headings" | "bullets"
+        agents_level: str — heading level for headings format (default "##")
+        skills_section: str — heading for skills section
+        skills_format: "headings" | "bullets"
+        skills_level: str — heading level for headings format (default "##")
+        guidelines: list[str] — list of guideline block names to include
+        use_markers: bool — wrap in TOOLKIT markers (default True)
+        trailing_newline_after_skills: bool — extra blank line after skills emit
+    """
+    agents, skills = count_agents_and_skills()
+
+    if config.get("use_markers", True):
+        print_toolkit_start()
+
+    # Title
+    if "title" in config:
+        print(config["title"])
+
+    # Header lines
+    for line in config.get("header_lines", []):
+        print(line)
+
+    # Intro
+    if "intro_template" in config:
+        if config.get("header_lines") or "title" in config:
+            print()
+        print(config["intro_template"].format(agents=agents, skills=skills))
+
+    # Agents section
+    if "agents_section" in config:
+        print()
+        print(config["agents_section"].format(agents=agents, skills=skills))
+        print()
+        agents_intro = config.get("agents_intro")
+        if agents_intro:
+            print(agents_intro)
+            print()
+
+        fmt = config.get("agents_format", "headings")
+        level = config.get("agents_level", "##")
+        if fmt == "bullets":
+            print(emit_agents_bullets())
+        else:
+            print(emit_agents_headings(level))
+
+    # Skills section
+    if "skills_section" in config:
+        # Bullets format needs a separator; headings already end with blank line
+        if config.get("agents_format") == "bullets":
+            print()
+        print(config["skills_section"].format(agents=agents, skills=skills))
+        print()
+        skills_intro = config.get("skills_intro")
+        if skills_intro:
+            print(skills_intro)
+            print()
+
+        fmt = config.get("skills_format", "headings")
+        level = config.get("skills_level", "##")
+        if fmt == "bullets":
+            print(emit_skills_bullets())
+        else:
+            # Use sys.stdout.write to match original output (no trailing newline)
+            sys.stdout.write(emit_skills_headings(level))
+
+        if config.get("trailing_newline_after_skills", False):
+            print()
+
+    # Guidelines
+    for guideline_name in config.get("guidelines", []):
+        print()
+        fn = _GUIDELINES.get(guideline_name)
+        if fn:
+            print(fn())
+
+    # End marker
+    if config.get("use_markers", True):
+        print()
+        print_toolkit_end()

package/scripts/harvest_ecosystem.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""harvest-ecosystem — Refresh machine-readable ecosystem snapshot.
+
+Usage:
+    harvest_ecosystem.py [--offline] [--out FILE]
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import toolkit_dir
+
+OUTFILE = toolkit_dir / "benchmarks" / "ecosystem-harvest.json"
+
+
+def main() -> None:
+    outfile = str(OUTFILE)
+    passthrough: list[str] = []
+
+    args = sys.argv[1:]
+    i = 0
+    while i < len(args):
+        if args[i] == "--out":
+            i += 1
+            if i < len(args):
+                outfile = args[i]
+        else:
+            passthrough.append(args[i])
+        i += 1
+
+    Path(outfile).parent.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        sys.executable,
+        str(toolkit_dir / "scripts" / "benchmark_ecosystem.py"),
+        "--dashboard-json",
+        *passthrough,
+        "--out", outfile,
+    ]
+    result = subprocess.run(cmd)
+    if result.returncode == 0:
+        print(f"Harvested ecosystem snapshot: {outfile}")
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()