@softspark/ai-toolkit 1.0.0

package/app/skills/_lib/detect_utils.py

@@ -0,0 +1,150 @@
+"""Shared utilities for skill detection scripts.
+
+Provides common constants, file helpers, and a standard main() wrapper
+used by detect-linters.py, detect-build.py, detect-runner.py, ci-detect.py,
+and other project-scanning scripts under app/skills/*/scripts/.
+
+All functions are stdlib-only.
+
+Usage::
+
+    from _lib.detect_utils import read_json, read_text, IGNORE_DIRS, run_detector
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+# Directories to skip during project walks
+IGNORE_DIRS: frozenset[str] = frozenset({
+    ".git", "node_modules", "__pycache__", ".venv", "venv",
+    "dist", "build", ".next", "vendor",
+})
+
+# Common project markers → project type
+PROJECT_MARKERS: dict[str, list[str]] = {
+    "python": ["pyproject.toml", "setup.py", "requirements.txt"],
+    "node": ["package.json"],
+    "flutter": ["pubspec.yaml"],
+    "go": ["go.mod"],
+    "rust": ["Cargo.toml"],
+    "php": ["composer.json"],
+    "docker": ["Dockerfile"],
+}
+
+
+# ---------------------------------------------------------------------------
+# File I/O helpers
+# ---------------------------------------------------------------------------
+
+def read_json(path: Path) -> dict[str, Any] | None:
+    """Read and parse a JSON file, returning None on failure."""
+    try:
+        with open(path, "r") as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def read_text(path: Path) -> str | None:
+    """Read a text file, returning None when it does not exist."""
+    try:
+        with open(path, "r") as f:
+            return f.read()
+    except FileNotFoundError:
+        return None
+
+
+def is_installed(binary: str) -> bool:
+    """Check whether a binary is available on PATH."""
+    return shutil.which(binary) is not None
+
+
+# ---------------------------------------------------------------------------
+# Project detection
+# ---------------------------------------------------------------------------
+
+def detect_project_type(project_dir: Path) -> str | None:
+    """Detect project type from well-known marker files."""
+    for ptype, markers in PROJECT_MARKERS.items():
+        for marker in markers:
+            if (project_dir / marker).exists():
+                return ptype
+    return None
+
+
+def count_files(root: Path, patterns: list[str]) -> int:
+    """Walk root and count files matching any regex pattern.
+
+    Directories in IGNORE_DIRS are pruned.
+    """
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS]
+        for f in filenames:
+            for pat in patterns:
+                if re.search(pat, f):
+                    count += 1
+                    break
+    return count
+
+
+def parse_makefile_targets(project_dir: Path) -> list[str]:
+    """Extract non-hidden target names from a Makefile."""
+    content = read_text(project_dir / "Makefile")
+    if not content:
+        return []
+    targets: list[str] = []
+    for line in content.split("\n"):
+        m = re.match(r"^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:", line)
+        if m and not m.group(1).startswith("."):
+            targets.append(m.group(1))
+    return targets
+
+
+# ---------------------------------------------------------------------------
+# Standard main() wrapper
+# ---------------------------------------------------------------------------
+
+def run_detector(
+    detect_fn: Any,
+    *,
+    extra_args: bool = False,
+) -> None:
+    """Standard entry point wrapper for detection scripts.
+
+    Parses argv for project directory, calls detect_fn(project_dir, ...),
+    and prints JSON result to stdout. Handles errors uniformly.
+
+    Args:
+        detect_fn: Callable(project_dir: Path, ...) -> dict
+        extra_args: If True, passes remaining argv items to detect_fn
+    """
+    project_dir = Path.cwd()
+    extra: list[str] = []
+
+    for arg in sys.argv[1:]:
+        if os.path.isdir(arg):
+            project_dir = Path(arg).resolve()
+        else:
+            extra.append(arg)
+
+    if not project_dir.is_dir():
+        print(json.dumps({"error": f"Not a directory: {project_dir}"}))
+        sys.exit(1)
+
+    try:
+        if extra_args and extra:
+            result = detect_fn(project_dir, *extra)
+        else:
+            result = detect_fn(project_dir)
+        result["project_dir"] = str(project_dir)
+        print(json.dumps(result, indent=2))
+    except Exception as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)

package/app/skills/agent-creator/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: agent-creator
+description: "Creates new specialized agents with frontmatter, tool selection, and delegation guidance"
+effort: high
+disable-model-invocation: true
+argument-hint: "[agent name or role]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Agent Creator
+
+$ARGUMENTS
+
+Create a new specialized agent following ai-toolkit conventions.
+
+## Workflow
+
+1. **Capture role** -- what problem space should the agent own?
+2. **Define triggers** -- which keywords or task types should route to this agent?
+3. **Choose tools** -- minimal tool set, least privilege first
+4. **Choose model** -- `opus` for deep reasoning, `sonnet` for lighter pattern work
+5. **Map supporting skills** -- which knowledge skills should the agent reference?
+6. **Write instructions** -- capabilities, constraints, escalation rules, deliverables
+7. **Validate** -- frontmatter, naming, skills references, tool whitelist
+
+## Required Frontmatter
+
+```yaml
+---
+name: agent-name
+description: "When to use this agent. Triggers: keyword1, keyword2."
+tools: Read, Write, Edit
+model: sonnet
+skills: skill-one, skill-two
+---
+```
+
+## Authoring Rules
+
+- Match filename and `name` exactly using lowercase-hyphen format
+- Keep the description trigger-rich and operational
+- Give the agent a clear boundary: what it owns and what it should escalate
+- Prefer specialized, narrow responsibility over generic “do everything” agents
+- Reference only existing skills unless the task also includes creating the missing skill
+- Avoid tool bloat; every extra tool increases risk and ambiguity
+
+## Agent Skeleton
+
+```markdown
+---
+name: {agent-name}
+description: "When to use this agent. Triggers: keyword1, keyword2."
+tools: Read, Edit
+model: sonnet
+skills: relevant-skill
+---
+
+You are a specialized agent for {domain}.
+
+## Responsibilities
+- Responsibility one
+- Responsibility two
+
+## Constraints
+- Do not edit files outside owned scope unless required
+- Escalate security, data-loss, or architecture risks
+
+## Deliverables
+- Clear findings
+- Specific edits or recommendations
+- Validation notes
+```
+
+## Validation Checklist
+
+- [ ] Filename matches `name:` in frontmatter
+- [ ] Description includes trigger words and use cases
+- [ ] Tools are from the approved Claude Code tool set
+- [ ] Referenced skills exist
+- [ ] Model choice matches expected complexity
+- [ ] `scripts/validate.py` passes after adding the agent
+

package/app/skills/analyze/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: analyze
+description: "Analyze code quality, complexity, and patterns"
+user-invocable: true
+effort: medium
+argument-hint: "[path or pattern]"
+allowed-tools: Read, Grep, Glob
+---
+
+# Code Analysis
+
+$ARGUMENTS
+
+Analyze code quality, complexity, and patterns.
+
+## Usage
+
+```
+/analyze [path] [--type=<type>]
+```
+
+## What This Command Does
+
+1. **Scans** codebase or specific path
+2. **Analyzes** code quality metrics
+3. **Identifies** patterns and anti-patterns
+4. **Reports** findings with recommendations
+
+## Analysis Types
+
+| Type | Description |
+|------|-------------|
+| `quality` | Code quality metrics (default) |
+| `security` | Security vulnerability scan |
+| `complexity` | Cyclomatic complexity |
+| `dependencies` | Dependency analysis |
+| `coverage` | Test coverage gaps |
+
+## Output Format
+
+```markdown
+## Code Analysis Report
+
+### Summary
+- **Files Analyzed**: [count]
+- **Issues Found**: [count]
+- **Quality Score**: [score]/100
+
+### Metrics
+| Metric | Value | Threshold |
+|--------|-------|-----------|
+| Complexity | [avg] | <10 |
+| Duplication | [%] | <5% |
+| Coverage | [%] | >70% |
+
+### Issues by Severity
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+
+### Top Issues
+1. **[Issue]** - [file:line]
+   - [Description]
+   - Fix: [Recommendation]
+
+### Patterns Detected
+- [Pattern 1]: [locations]
+- [Pattern 2]: [locations]
+
+### Recommendations
+1. [Recommendation with priority]
+```
+
+## Automated Complexity Analysis
+
+Run the bundled script for a quick complexity report:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/complexity.py .
+```
+
+Reports file counts by type, largest files, TODO/FIXME counts, and total code lines.
+
+## Tools Used
+
+| Language | Tools |
+|----------|-------|
+| Python | ruff, mypy, pylint |
+| JavaScript | eslint, tsc |
+| Go | golangci-lint |
+| Rust | clippy |

package/app/skills/analyze/scripts/complexity.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Code complexity analysis script.
+
+Scans a project directory and reports file counts by extension, largest
+files by line count, TODO/FIXME/HACK/XXX markers, and a summary with
+total file and line counts.
+
+Usage::
+
+    python3 complexity.py [directory]
+"""
+from __future__ import annotations
+
+import os
+import sys
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+
+IGNORE_DIRS: set[str] = {
+    ".git", "node_modules", "__pycache__", ".venv",
+    "vendor", "dist", "build",
+}
+
+IGNORE_DIRS_LARGEST: set[str] = IGNORE_DIRS  # same exclusions for largest-file scan
+
+IGNORE_LOCK_NAMES: set[str] = {
+    "package-lock.json",
+}
+
+IGNORE_LOCK_EXTENSIONS: set[str] = {
+    ".lock",
+}
+
+CODE_EXTENSIONS: set[str] = {
+    ".py", ".ts", ".tsx", ".js", ".jsx",
+    ".go", ".php", ".dart", ".rs", ".rb",
+}
+
+
+def _is_ignored(path: Path, ignored: set[str]) -> bool:
+    """Return True if any component of *path* matches the ignored set."""
+    return bool(set(path.parts) & ignored)
+
+
+def _walk_files(root: Path, ignored: set[str]) -> list[Path]:
+    """Collect all regular files under *root*, skipping ignored dirs."""
+    files: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in ignored]
+        dp = Path(dirpath)
+        for fn in filenames:
+            files.append(dp / fn)
+    return files
+
+
+def _count_lines(path: Path) -> int:
+    """Count lines in a file, returning 0 on read errors."""
+    try:
+        with open(path, "rb") as fh:
+            return sum(1 for _ in fh)
+    except (OSError, PermissionError):
+        return 0
+
+
+def _file_counts(files: list[Path]) -> list[tuple[int, str]]:
+    """Return (count, extension) pairs sorted descending, top 15."""
+    ext_counter: Counter[str] = Counter()
+    for f in files:
+        ext = f.suffix.lstrip(".") if f.suffix else f.name
+        ext_counter[ext] += 1
+    return ext_counter.most_common(15)
+
+
+def _largest_files(root: Path) -> list[tuple[int, str]]:
+    """Return (line_count, path) for the 10 largest files."""
+    all_files = _walk_files(root, IGNORE_DIRS_LARGEST)
+    eligible = [
+        f for f in all_files
+        if f.suffix not in IGNORE_LOCK_EXTENSIONS
+        and f.name not in IGNORE_LOCK_NAMES
+    ]
+    counted: list[tuple[int, str]] = []
+    for f in eligible:
+        lines = _count_lines(f)
+        if lines > 0:
+            counted.append((lines, str(f)))
+    counted.sort(reverse=True)
+    return counted[:10]
+
+
+def _debt_markers(root: Path, files: list[Path]) -> dict[str, int]:
+    """Count files containing each debt marker in code files."""
+    code_files = [f for f in files if f.suffix in CODE_EXTENSIONS]
+    markers = ["TODO", "FIXME", "HACK", "XXX"]
+    results: dict[str, int] = {}
+    for marker in markers:
+        count = 0
+        for cf in code_files:
+            try:
+                with open(cf, "r", errors="replace") as fh:
+                    for line in fh:
+                        if marker in line:
+                            count += 1
+                            break
+            except (OSError, PermissionError):
+                continue
+        results[marker] = count
+    return results
+
+
+def _summary(root: Path, all_files: list[Path]) -> tuple[int, int]:
+    """Return (total_files, total_code_lines) for the summary."""
+    total_files = len(all_files)
+
+    code_files = _walk_files(root, IGNORE_DIRS)
+    code_only = [f for f in code_files if f.suffix in CODE_EXTENSIONS]
+    total_lines = sum(_count_lines(f) for f in code_only)
+    return total_files, total_lines
+
+
+def main() -> None:
+    """Entry point: analyse directory and print text report to stdout."""
+    root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd().resolve()
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    all_files = _walk_files(root, IGNORE_DIRS)
+
+    print("=== Code Complexity Report ===")
+    print(f"Directory: {root}")
+    print(f"Date: {now}")
+    print()
+
+    # File counts by extension
+    print("## File Counts")
+    for count, ext in _file_counts(all_files):
+        print(f"   {count} {ext}")
+    print()
+
+    # Largest files
+    print("## Largest Files (top 10)")
+    largest = _largest_files(root)
+    for lines, path in largest:
+        print(f"  {lines} {path}")
+    # Include total line if there are entries (mirrors wc behavior)
+    if len(largest) > 1:
+        total = sum(lc for lc, _ in largest)
+        print(f"  {total} total")
+    print()
+
+    # Debt markers
+    print("## Code Debt Markers")
+    for marker, count in _debt_markers(root, all_files).items():
+        print(f"  {marker}: {count} files")
+    print()
+
+    # Summary
+    print("## Summary")
+    total_files, total_lines = _summary(root, all_files)
+    print(f"  Total files: {total_files}")
+    print(f"  Total code lines: {total_lines}")
+
+
+if __name__ == "__main__":
+    main()