@softspark/ai-toolkit 1.0.0

package/scripts/emission.py

@@ -0,0 +1,256 @@
+"""Markdown emission helpers for agent/skill listing and generator content blocks.
+
+Provides functions to emit agents and skills as markdown headings or
+bullet lists, plus shared content blocks (guidelines, quality standards)
+used by the various ``generate_*.py`` scripts.
+
+Stdlib-only.
+
+Usage::
+
+    from emission import emit_agents_headings, emit_skills_bullets
+    from emission import generate_general_guidelines
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from frontmatter import frontmatter_field
+
+
+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"
+
+
+# ---------------------------------------------------------------------------
+# Counting
+# ---------------------------------------------------------------------------
+
+def agent_count() -> int:
+    """Count agent .md files in app/agents/."""
+    if not agents_dir.is_dir():
+        return 0
+    return sum(1 for f in agents_dir.iterdir() if f.suffix == ".md" and f.is_file())
+
+
+def skill_count() -> int:
+    """Count skill directories containing SKILL.md in app/skills/.
+
+    Directories starting with ``_`` (like ``_lib``) are excluded.
+    """
+    if not skills_dir.is_dir():
+        return 0
+    return sum(1 for d in skills_dir.iterdir()
+               if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").is_file())
+
+
+def count_agents_and_skills() -> tuple[int, int]:
+    """Return (agent_count, skill_count) as a convenience tuple."""
+    return agent_count(), skill_count()
+
+
+# ---------------------------------------------------------------------------
+# Markdown emission
+# ---------------------------------------------------------------------------
+
+def emit_agents_headings(level: str = "##") -> str:
+    """Emit agents as markdown headings with descriptions."""
+    lines: list[str] = []
+    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
+        lines.append(f"{level} {name}")
+        lines.append(description)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def emit_agents_bullets() -> str:
+    """Emit agents as bullet list: - **name**: description."""
+    lines: list[str] = []
+    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
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+def emit_skills_headings(level: str = "##") -> str:
+    """Emit skills as markdown headings with descriptions."""
+    lines: list[str] = []
+    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
+        name = frontmatter_field(skill_file, "name")
+        description = frontmatter_field(skill_file, "description")
+        if not name or not description:
+            continue
+        lines.append(f"{level} {name}")
+        lines.append(description)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def emit_skills_bullets() -> str:
+    """Emit skills as bullet list: - **name**: description."""
+    lines: list[str] = []
+    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
+        name = frontmatter_field(skill_file, "name")
+        description = frontmatter_field(skill_file, "description")
+        if not name or not description:
+            continue
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Toolkit markers (print helpers)
+# ---------------------------------------------------------------------------
+
+def print_toolkit_start() -> None:
+    """Print the standard toolkit start marker and auto-generated comment."""
+    print("<!-- TOOLKIT:ai-toolkit START -->")
+    print("<!-- Auto-generated by ai-toolkit. Re-run to update. -->")
+    print()
+
+
+def print_toolkit_end() -> None:
+    """Print the standard toolkit end marker."""
+    print("<!-- TOOLKIT:ai-toolkit END -->")
+
+
+# ---------------------------------------------------------------------------
+# Shared content blocks for generators
+# ---------------------------------------------------------------------------
+
+def generate_general_guidelines() -> str:
+    """Return the general guidelines block used by cursor/cline/windsurf generators."""
+    lines = [
+        "## General Guidelines",
+        "",
+        '- Apply "Safety First": no data loss, no blind execution, max 3 loop iterations',
+        "- Research before acting: check existing code and context before proposing changes",
+        "- Use structured commits: feat/fix/docs/refactor/test/chore prefixes",
+        "- Quality gates: lint must pass, types must check, tests must be green before done",
+        "- Prefer editing existing files over creating new ones",
+        "- Never commit secrets or credentials",
+    ]
+    return "\n".join(lines)
+
+
+def generate_quality_standards() -> str:
+    """Return the full constitution-based quality standards for Gemini."""
+    lines = [
+        "## Quality Standards",
+        "",
+        "Derived from the immutable safety constitution (5 articles):",
+        "",
+        "**Article I — Safety First**",
+        "- No data loss: never delete files without backup verification"
+        " or using reversible operations",
+        "- No blind execution: never run LLM-generated code without"
+        " static analysis or review",
+        "- No infinite loops: all autonomous loops must have a maximum"
+        " iteration count (max 3)",
+        "",
+        "**Article II — Hierarchy of Truth**",
+        "- The Knowledge Base (`kb/`) is the source of truth;"
+        " if code contradicts KB, check KB freshness",
+        "- Use the research-mastery skill before any major decision;"
+        " guessing is forbidden",
+        "",
+        "**Article III — Operational Integrity**",
+        '- "Green Tests" is the only definition of Done;'
+        " forced merges on red tests are unacceptable",
+        "- Never delete audit logs or KB archives without explicit"
+        " user approval and backup verification",
+        "- Agents cannot change their own model or tool permissions"
+        " without user approval",
+        "",
+        "**Article IV — Self-Preservation**",
+        "- The constitution file is read-only for all agents except the user",
+        "- If a constitutional violation is detected, halt the offending"
+        " operation immediately",
+        "",
+        "**Article V — Resource Governance**",
+        "- Commands like `rm -rf`, `DROP TABLE`, `FORMAT` require explicit"
+        " user confirmation",
+        "- Operate within assigned model tiers; model tier changes"
+        " require user approval",
+    ]
+    return "\n".join(lines)
+
+
+def generate_workflow_guidelines() -> str:
+    """Return the workflow guidelines block used by the Gemini generator."""
+    lines = [
+        "## Workflow Guidelines",
+        "",
+        "- **Plan First**: Tasks longer than 1 hour require a plan,"
+        " success criteria, and pre-mortem",
+        "- **Multi-Agent**: Use minimum 3 agents for complex tasks;"
+        " single-agent for simple tasks",
+        "- **2-Phase Execution**: Plan \u2192 User Approval \u2192 Implement"
+        " (never skip the approval checkpoint)",
+        "- **KB-First Research**: Search the knowledge base before writing"
+        " code or answering questions",
+        "- **Structured Commits**: Use `feat/fix/docs/refactor/test/chore`"
+        " prefixes (Conventional Commits)",
+        "- **Quality Gates**: Run `ruff check .` (Python), `tsc` (TypeScript),"
+        " `go vet` (Go) before marking done",
+        "- **Cite Sources**: Always reference `[PATH: ...]` when making"
+        " decisions based on existing knowledge",
+        "- **Read-Only Exploration**: Discovery agents never write;"
+        " writing agents never explore blindly",
+        "- **No Secrets in Code**: Never commit credentials, API keys,"
+        " or sensitive configuration values",
+    ]
+    return "\n".join(lines)
+
+
+def generate_quality_guidelines() -> str:
+    """Return the quality guidelines block used by the Copilot generator."""
+    lines = [
+        "## Quality Guidelines",
+        "",
+        '- **Safety First**: No data loss, no blind execution,'
+        " maximum 3 autonomous loop iterations",
+        "- **No Blind Execution**: Never run LLM-generated code"
+        " without static analysis or review",
+        '- **Tests are Sacred**: "Green Tests" is the only definition of Done;'
+        " never force-merge on red tests",
+        "- **No Destructive Commands**: Commands like `rm -rf`, `DROP TABLE`,"
+        " `FORMAT` require explicit user confirmation",
+        "- **No Secrets in Code**: Never commit secrets, credentials,"
+        " or API keys to the repository",
+        "- **Research Before Acting**: Check existing code and context"
+        " before proposing changes",
+        "- **Structured Commits**: Use `feat/fix/docs/refactor/test/chore`"
+        " prefixes (Conventional Commits)",
+        "- **Quality Gates**: Lint must pass, types must check,"
+        " tests must be green before marking done",
+        "- **Prefer Editing**: Edit existing files over creating new ones;"
+        " avoid unnecessary churn",
+        "- **Cite Sources**: Always reference where information came from"
+        " when making architectural decisions",
+    ]
+    return "\n".join(lines)

package/scripts/evaluate_skills.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""AI Toolkit Skill Evaluation.
+
+Validates all skills against the Agent Skills standard.
+Checks frontmatter fields, naming, classification, reference links,
+template directories, and dependency resolution.
+
+Usage:
+  evaluate_skills.py
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import frontmatter_block, frontmatter_field, skills_dir
+
+# Deprecated frontmatter fields and their replacements
+_DEPRECATED_FIELDS: list[tuple[str, str]] = [
+    ("version", "deprecated 'version' field in frontmatter"),
+    ("color", "deprecated 'color' field in frontmatter"),
+    ("tools", "deprecated 'tools' field (use 'allowed-tools')"),
+    ("delegate-agent", "deprecated 'delegate-agent' field (rename to 'agent:')"),
+    ("run-mode", "deprecated 'run-mode' field (rename to 'context:')"),
+]
+
+
+def _fm_has(fm_text: str, field: str) -> bool:
+    """Check if frontmatter text contains a field line."""
+    return any(
+        line.startswith(f"{field}:")
+        for line in fm_text.splitlines()
+    )
+
+
+def _fm_value(fm_text: str, field: str) -> str:
+    """Extract a field value from raw frontmatter text."""
+    for line in fm_text.splitlines():
+        if line.startswith(f"{field}:"):
+            val = line[len(field) + 1:].strip()
+            if len(val) >= 2 and val[0] == val[-1] and val[0] in ('"', "'"):
+                val = val[1:-1]
+            return val
+    return ""
+
+
+def _check_frontmatter_fields(fm: str, skill_path: Path, line_count: int) -> list[str]:
+    """Check required fields, name format, description, line count, and deprecated fields."""
+    issues: list[str] = []
+
+    if not _fm_has(fm, "name"):
+        issues.append("missing name field")
+    if not _fm_has(fm, "description"):
+        issues.append("missing description field")
+
+    name_value = _fm_value(fm, "name")
+    if name_value:
+        if len(name_value) > 64:
+            issues.append(f"name exceeds 64 chars ({len(name_value)})")
+        if re.search(r"[^a-z0-9-]", name_value):
+            issues.append(f"name has invalid chars: {name_value}")
+
+    desc_value = _fm_value(fm, "description")
+    if desc_value and re.match(r"^(I |You |We )", desc_value):
+        issues.append("description not in third person")
+
+    if line_count > 500:
+        issues.append(f"SKILL.md has {line_count} lines (max: 500)")
+
+    for field, message in _DEPRECATED_FIELDS:
+        if _fm_has(fm, field):
+            issues.append(message)
+
+    return issues
+
+
+def _check_references_and_templates(skill_path: Path, content: str) -> list[str]:
+    """Check reference links, orphan files, and template directories."""
+    issues: list[str] = []
+
+    ref_dir = skill_path / "reference"
+    if ref_dir.is_dir():
+        for match in re.finditer(r"\(reference/([^)]+)\)", content):
+            ref_link = match.group(0).strip("()")
+            if not (skill_path / ref_link).is_file():
+                issues.append(f"broken reference link: {ref_link}")
+        for ref_file in sorted(ref_dir.glob("*.md")):
+            if f"reference/{ref_file.name}" not in content:
+                issues.append(f"orphan reference file: reference/{ref_file.name}")
+
+    tmpl_dir = skill_path / "templates"
+    if tmpl_dir.is_dir():
+        tmpl_files = [f for f in tmpl_dir.rglob("*") if f.is_file()]
+        if not tmpl_files:
+            issues.append("empty templates/ directory")
+
+    return issues
+
+
+def _determine_type_label(fm: str) -> str:
+    """Determine skill type from frontmatter fields."""
+    has_disable = _fm_has(fm, "disable-model-invocation") and "true" in _fm_value(fm, "disable-model-invocation")
+    has_user_invocable_false = _fm_has(fm, "user-invocable") and "false" in _fm_value(fm, "user-invocable")
+
+    if has_disable:
+        return "task"
+    elif has_user_invocable_false:
+        return "knowledge"
+    return "hybrid"
+
+
+def _evaluate_skill(skill_path: Path) -> tuple[str, list[str]]:
+    """Evaluate a single skill directory.
+
+    Returns:
+        (type_label, issues) where type_label is "task", "knowledge", or "hybrid"
+        and issues is a list of problem descriptions (empty if passing).
+    """
+    skill_file = skill_path / "SKILL.md"
+
+    if not skill_file.is_file():
+        return ("unknown", ["Missing SKILL.md"])
+
+    fm = frontmatter_block(skill_file)
+    content = skill_file.read_text(encoding="utf-8")
+    line_count = content.count("\n") + (1 if content and not content.endswith("\n") else 0)
+
+    issues = _check_frontmatter_fields(fm, skill_path, line_count)
+    issues.extend(_check_references_and_templates(skill_path, content))
+
+    return (_determine_type_label(fm), issues)
+
+
+def _evaluate_all_skills() -> tuple[int, int, int, int, int]:
+    """Evaluate all skills and print per-skill results.
+
+    Returns (total, pass_count, fail_count, task_count, knowledge_count).
+    """
+    pass_count = 0
+    fail_count = 0
+    total = 0
+    task_count = 0
+    knowledge_count = 0
+
+    for skill_path in sorted(skills_dir.iterdir()):
+        if not skill_path.is_dir() or skill_path.name.startswith("_"):
+            continue
+        total += 1
+        skill_file = skill_path / "SKILL.md"
+
+        if not skill_file.is_file():
+            print(f"FAIL: {skill_path.name} - Missing SKILL.md")
+            fail_count += 1
+            continue
+
+        content = skill_file.read_text(encoding="utf-8")
+        line_count = content.count("\n") + (1 if content and not content.endswith("\n") else 0)
+
+        type_label, issues = _evaluate_skill(skill_path)
+
+        if issues:
+            print(f"FAIL: {skill_path.name} ({line_count} lines)")
+            for issue in issues:
+                print(f"  {issue}")
+            print()
+            fail_count += 1
+        else:
+            print(f"PASS: {skill_path.name} ({type_label}, {line_count} lines)")
+            pass_count += 1
+
+        if type_label == "task":
+            task_count += 1
+        elif type_label == "knowledge":
+            knowledge_count += 1
+
+    return total, pass_count, fail_count, task_count, knowledge_count
+
+
+def _collect_quality_metrics() -> tuple[int, int, int, int, int, int]:
+    """Collect quality metrics across all skills.
+
+    Returns (ref_count, tmpl_count, inject_count, over500, depends_count, orphan_deps).
+    """
+    ref_count = sum(1 for _ in skills_dir.rglob("reference/*.md"))
+    tmpl_count = sum(1 for _ in skills_dir.rglob("templates/*") if _.is_file())
+
+    inject_count = 0
+    over500 = 0
+    depends_count = 0
+    orphan_deps = 0
+
+    for sf in skills_dir.glob("*/SKILL.md"):
+        text = sf.read_text(encoding="utf-8")
+        lc = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
+        if "!`" in text:
+            inject_count += 1
+        if lc > 500:
+            over500 += 1
+        fm = frontmatter_block(sf)
+        dep_line = _fm_value(fm, "depends-on")
+        if dep_line:
+            depends_count += 1
+            for dep in dep_line.split(","):
+                dep = dep.strip()
+                if not dep:
+                    continue
+                if not (skills_dir / dep / "SKILL.md").is_file():
+                    orphan_deps += 1
+
+    return ref_count, tmpl_count, inject_count, over500, depends_count, orphan_deps
+
+
+def main() -> None:
+    """Run evaluation across all skills and print report."""
+    print("AI Toolkit Skill Evaluation")
+    print("================================")
+    print()
+
+    if not skills_dir.is_dir():
+        print("No skills directory found.")
+        sys.exit(1)
+
+    total, pass_count, fail_count, task_count, knowledge_count = _evaluate_all_skills()
+    hybrid_count = total - task_count - knowledge_count
+
+    print()
+    print("================================")
+    print(f"Total: {total} skills")
+    print(f"Pass:  {pass_count}")
+    print(f"Fail:  {fail_count}")
+    print()
+
+    print("Classification:")
+    print(f"  Task:      {task_count}")
+    print(f"  Hybrid:    {hybrid_count}")
+    print(f"  Knowledge: {knowledge_count}")
+    print()
+
+    ref_count, tmpl_count, inject_count, over500, depends_count, orphan_deps = _collect_quality_metrics()
+
+    print("Quality Metrics:")
+    print(f"  Reference files:        {ref_count}")
+    print(f"  Template files:         {tmpl_count}")
+    print(f"  Dynamic injection:      {inject_count} skills")
+    print(f"  Over 500 lines:         {over500}")
+    print(f"  Skills with depends-on: {depends_count}")
+    print(f"  Orphan dependencies:    {orphan_deps}")
+    print()
+
+    if fail_count > 0:
+        print("EVALUATION: ISSUES FOUND")
+        sys.exit(1)
+    else:
+        print("EVALUATION: ALL SKILLS PASS")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/frontmatter.py

@@ -0,0 +1,58 @@
+"""YAML frontmatter parsing for agent and skill markdown files.
+
+Stdlib-only. Extracts fields from ``---`` delimited frontmatter blocks.
+
+Usage::
+
+    from frontmatter import frontmatter_field, frontmatter_block
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def frontmatter_field(filepath: str | Path, field: str) -> str:
+    """Extract a YAML frontmatter field value from a file.
+
+    Reads lines between the first pair of ``---`` delimiters and returns
+    the value for the given field. Strips surrounding quotes.
+    """
+    filepath = Path(filepath)
+    if not filepath.is_file():
+        return ""
+    in_frontmatter = False
+    with open(filepath, encoding="utf-8") as f:
+        for line in f:
+            stripped = line.rstrip("\n")
+            if stripped == "---":
+                if in_frontmatter:
+                    break
+                in_frontmatter = True
+                continue
+            if in_frontmatter and stripped.startswith(f"{field}:"):
+                value = stripped[len(field) + 1:].strip()
+                # Strip surrounding quotes
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                    value = value[1:-1]
+                return value
+    return ""
+
+
+def frontmatter_block(filepath: str | Path) -> str:
+    """Return the raw frontmatter text (excluding --- delimiters)."""
+    filepath = Path(filepath)
+    if not filepath.is_file():
+        return ""
+    lines: list[str] = []
+    in_fm = False
+    with open(filepath, encoding="utf-8") as f:
+        for line in f:
+            stripped = line.rstrip("\n")
+            if stripped == "---":
+                if in_fm:
+                    break
+                in_fm = True
+                continue
+            if in_fm:
+                lines.append(stripped)
+    return "\n".join(lines)

package/scripts/generate_agents_md.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Generate AGENTS.md from app/agents/*.md frontmatter.
+
+Output is compatible with Codex, OpenCode, and Gemini CLI AGENTS.md format.
+Usage: ./scripts/generate_agents_md.py > AGENTS.md
+"""
+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 main() -> None:
+    print("# AGENTS.md")
+    print()
+    print(
+        "This file describes the specialized AI agents bundled with ai-toolkit."
+    )
+    print(
+        "It is auto-generated from `app/agents/*.md` frontmatter"
+        " — do not edit manually."
+    )
+    print()
+    print("To regenerate: `python3 scripts/generate_agents_md.py > AGENTS.md`")
+    print()
+    print("Compatible with: Claude Code, Codex, OpenCode, Gemini CLI.")
+    print()
+    print("---")
+    print()
+    print("## Usage")
+    print()
+    print("### Claude Code")
+    print(
+        "Agents are loaded automatically from `.claude/agents/`"
+        " after running `install.sh`."
+    )
+    print("Invoke via the Agent tool:")
+    print("```")
+    print(
+        'Use subagent_type: "backend-specialist" to implement the API endpoint.'
+    )
+    print("```")
+    print()
+    print("### Codex / OpenCode")
+    print("Reference agents by name in your prompts:")
+    print("```")
+    print("@backend-specialist implement the payment API")
+    print("```")
+    print()
+    print("### Gemini CLI")
+    print("Use agent descriptions as system context:")
+    print("```")
+    print(
+        'gemini --system "$(cat .claude/agents/backend-specialist.md)"'
+        ' "implement the API"'
+    )
+    print("```")
+    print()
+    print("---")
+    print()
+    print("## Agents")
+    print()
+
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        if not agent_file.is_file():
+            continue
+
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        tools = frontmatter_field(agent_file, "tools")
+
+        if not name:
+            continue
+
+        print(f"### `{name}`")
+        print()
+        if description:
+            print(description)
+            print()
+        if tools:
+            print(f"**Tools:** `{tools}`")
+            print()
+        print("---")
+        print()
+
+
+if __name__ == "__main__":
+    main()