@softspark/ai-toolkit 1.0.0

package/app/skills/health/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: health
+description: "Report service and infrastructure health status"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[service]"
+allowed-tools: Bash, Read
+---
+
+# Health Check
+
+$ARGUMENTS
+
+Check the health of all project services.
+
+## Project context
+
+- Services: !`docker compose ps 2>/dev/null || echo "no-docker"`
+
+## Auto-Detection
+
+Detect services from `docker-compose.yml`, `.env`, or project configuration.
+
+### Quick Check
+```bash
+# If using Docker Compose
+docker compose ps
+
+# Process check (bare metal)
+ps aux | grep -E "(node|python|java|php)" | grep -v grep
+```
+
+## Common Service Checks
+
+| Service | Health Check |
+|---------|-------------|
+| HTTP API | `curl -f http://localhost:{port}/health` |
+| PostgreSQL | `pg_isready -h localhost -p 5432` |
+| MySQL | `mysqladmin ping -h localhost` |
+| Redis | `redis-cli ping` |
+| MongoDB | `mongosh --eval "db.runCommand({ping:1})"` |
+| Elasticsearch | `curl -f http://localhost:9200/_cluster/health` |
+| RabbitMQ | `curl -f http://localhost:15672/api/healthchecks/node` |
+
+## Diagnostics
+
+```bash
+# Container logs (if Docker)
+docker compose logs --tail 50 {service}
+
+# Resource usage
+docker stats --no-stream   # Docker
+htop                       # Bare metal
+
+# Disk usage
+df -h                      # System
+docker system df           # Docker
+
+# Network
+netstat -tlnp              # Listening ports
+curl -I http://localhost:{port}  # Connectivity
+```
+
+## Common Issues
+
+| Symptom | Check | Solution |
+|---------|-------|----------|
+| Service not responding | Process running? Port open? | Restart service |
+| Slow responses | Resource usage, connections | Scale or optimize |
+| Connection refused | Network, firewall, port | Check config |
+| Out of memory | `free -h`, container limits | Increase limits |
+
+## Automated Health Check
+
+Run the bundled script for a JSON health report:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/health_check.py http://localhost:8000
+```
+
+## Health Report Format
+
+```yaml
+services:
+  {service-name}:
+    status: healthy|degraded|down
+    uptime: Xd Xh
+    cpu: X%
+    memory: XMB
+    notes: "any issues"
+```

package/app/skills/health/scripts/health_check.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Health check script for common services.
+
+Probes Docker services, an HTTP health endpoint, disk usage, and
+available memory. Returns a JSON object with status information for
+each detected subsystem.
+
+Usage::
+
+    python3 health_check.py [service-url]
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    """Run a command, capturing output as text. Never raises."""
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _command_exists(name: str) -> bool:
+    """Return True if *name* is found on PATH."""
+    return shutil.which(name) is not None
+
+
+def _check_docker() -> dict[str, Any] | None:
+    """Return Docker service info, or None if Docker is unavailable."""
+    if not _command_exists("docker"):
+        return None
+    result = _run(["docker", "compose", "ps", "--format", "json"])
+    if result.returncode != 0:
+        return None
+    services: list[dict[str, str]] = []
+    for line in result.stdout.strip().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            svc = json.loads(line)
+            services.append({
+                "name": svc.get("Service", ""),
+                "state": svc.get("State", ""),
+            })
+        except json.JSONDecodeError:
+            continue
+    if not services:
+        return None
+    return {"status": "running", "services": services}
+
+
+def _check_http(url: str) -> dict[str, Any] | None:
+    """Probe *url*/health via curl and return status info."""
+    if not _command_exists("curl"):
+        return None
+    health_url = f"{url}/health"
+
+    # Status code
+    code_result = _run([
+        "curl", "-sf", "-o", "/dev/null", "-w", "%{http_code}", health_url,
+    ])
+    status_code = int(code_result.stdout.strip()) if code_result.stdout.strip().isdigit() else 0
+
+    # Response time
+    time_result = _run([
+        "curl", "-sf", "-o", "/dev/null", "-w", "%{time_total}", health_url,
+    ])
+    try:
+        response_time_s = float(time_result.stdout.strip())
+    except (ValueError, TypeError):
+        response_time_s = 0.0
+    response_time_ms = round(response_time_s * 1000, 2)
+
+    return {
+        "url": health_url,
+        "status_code": status_code,
+        "response_time_ms": response_time_ms,
+    }
+
+
+def _check_disk() -> dict[str, Any]:
+    """Return disk usage percentage for the current working directory."""
+    try:
+        usage = shutil.disk_usage(os.getcwd())
+        percent = round(usage.used / usage.total * 100) if usage.total else 0
+    except OSError:
+        percent = 0
+    return {"usage_percent": percent}
+
+
+def _check_memory() -> dict[str, Any]:
+    """Return available memory info, platform-aware."""
+    system = platform.system()
+    if system == "Darwin":
+        result = _run(["vm_stat"])
+        if result.returncode == 0:
+            for line in result.stdout.splitlines():
+                if "Pages free" in line:
+                    parts = line.split()
+                    # Last token is the number, possibly with a trailing period
+                    raw = parts[-1].rstrip(".")
+                    try:
+                        return {"free_pages": int(raw)}
+                    except ValueError:
+                        pass
+        return {"free_pages": 0}
+
+    if system == "Linux":
+        try:
+            with open("/proc/meminfo", "r") as fh:
+                for line in fh:
+                    if line.startswith("MemAvailable"):
+                        parts = line.split()
+                        try:
+                            return {"available_kb": int(parts[1])}
+                        except (IndexError, ValueError):
+                            pass
+        except OSError:
+            pass
+        return {"available_kb": 0}
+
+    return {}
+
+
+def main() -> None:
+    """Entry point: run all checks and print JSON to stdout."""
+    url = sys.argv[1] if len(sys.argv) > 1 else "http://localhost"
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    checks: dict[str, Any] = {}
+
+    docker_info = _check_docker()
+    if docker_info is not None:
+        checks["docker"] = docker_info
+
+    http_info = _check_http(url)
+    if http_info is not None:
+        checks["http"] = http_info
+
+    checks["disk"] = _check_disk()
+    checks["memory"] = _check_memory()
+
+    output = {
+        "timestamp": now,
+        "checks": checks,
+    }
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/app/skills/hive-mind/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: hive-mind
+description: "Loaded when orchestrating multi-agent swarms or consensus workflows"
+effort: medium
+user-invocable: false
+---
+
+# Hive Mind Skill
+
+You are part of a Swarm. You are not alone.
+
+## 🔴 Swarm Protocols
+
+### 1. Consensus (The Vote)
+When agents disagree:
+1. Each agent generates a solution + confidence score.
+2. **Weighted Voting**: Higher confidence = Higher weight.
+3. **Majority Rule**: >50% wins.
+
+### 2. Aggregation (The Merge)
+When multiple agents produce outputs:
+1. **Format Standardization**: Ensure all JSON/Markdown matches.
+2. **De-duplication**: Remove identical findings.
+3. **Synthesis**: Combine unique insights into one report.
+
+### 3. File Ownership (Agent Teams Mode)
+
+**With Agent Teams enabled**: File conflicts are prevented by **file ownership assignment** at spawn time. Each teammate gets distinct files/directories. No locking needed.
+
+- Lead assigns ownership when creating the team
+- Teammates respect boundaries in their prompts
+- Quality hooks verify completeness on `TaskCompleted`
+
+**Without Agent Teams** (fallback):
+1. Before editing a file: Check if another agent is editing.
+2. Use `touch .lock.{filename}`.
+3. Remove lock after edit.
+
+### 4. Communication (Agent Teams Mode)
+
+- **message**: Send to ONE specific teammate (targeted, low cost)
+- **broadcast**: Send to ALL teammates (use sparingly — costs N×)
+- **Shared task list**: `~/.claude/tasks/{team-name}/` — all agents can see/claim
+
+## Example Workflow (Map-Reduce)
+
+### With Agent Teams
+1. **Map**: Lead spawns 5 teammates, each scanning 20 files
+2. **Parallel**: All teammates execute simultaneously in tmux panes
+3. **Reduce**: Lead waits, collects results, applies Aggregation protocol
+4. **Report**: `final_report.md` synthesized from all findings
+
+### Without Agent Teams (Fallback)
+1. **Map**: "Scan 100 files for leaks." → 10 Agents × 10 Files.
+2. **Reduce**: Agents output `leaks_{i}.json`.
+3. **Hive Mind**: Merge all `leaks_*.json` → `final_report.json`.

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

@@ -0,0 +1,107 @@
+---
+name: hook-creator
+description: "Creates new Claude Code hooks with guided workflow, strict conventions, and validation"
+effort: high
+disable-model-invocation: true
+argument-hint: "[hook event or description]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Hook Creator
+
+$ARGUMENTS
+
+Create a new Claude Code hook following ai-toolkit conventions.
+
+## Supported Hook Events
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `SessionStart` | Session begins or resumes after compact | `startup\|compact` | Context injection, rules reminder |
+| `Notification` | Claude sends a notification | any | OS alerts, Slack pings |
+| `PreToolUse` | Before a tool executes | tool name (e.g. `Bash`) | Safety guards, validation |
+| `PostToolUse` | After a tool executes | tool name | Feedback loops, logging |
+| `Stop` | Claude finishes responding | any | Quality checks, session save |
+| `PreCompact` | Before context compaction | any | Context preservation |
+| `SubagentStop` | Subagent completes | any | Result validation |
+| `UserPromptSubmit` | User submits a prompt | any | Prompt governance |
+| `TaskCompleted` | Agent Teams task done | any | Lint, type check |
+| `TeammateIdle` | Agent Teams member idle | any | Completeness reminder |
+
+## Workflow
+
+1. **Capture intent** -- ask: what should the hook do? Which lifecycle event?
+2. **Select event** -- pick from the Supported Hook Events table above
+3. **Define matcher** -- tool name for PreToolUse/PostToolUse, empty for global
+4. **Write script** -- create `app/hooks/{event-name-kebab}.sh`
+5. **Register in hooks.json** -- add entry to `app/hooks.json`
+6. **Validate** -- run `scripts/validate.py`
+
+## Hook Script Conventions
+
+- Location: `app/hooks/{event-name-kebab}.sh`
+- Shebang: `#!/bin/bash`
+- Header comment: script name, purpose, event, matcher
+- Respect `TOOLKIT_HOOK_PROFILE` env var (`minimal` = skip non-essential hooks)
+- Always `exit 0` on success (non-zero blocks the operation for Pre* hooks)
+- Output goes to Claude's context as plain text
+- No external dependencies -- bash builtins and coreutils only
+- Keep output concise -- hooks fire frequently
+
+## hooks.json Entry Format
+
+```json
+{
+    "_source": "ai-toolkit",
+    "matcher": "",
+    "hooks": [
+        {
+            "type": "command",
+            "command": "\"$HOME/.ai-toolkit/hooks/{script-name}.sh\""
+        }
+    ]
+}
+```
+
+Required fields:
+- `_source`: always `"ai-toolkit"` (used by merge/strip logic)
+- `matcher`: tool name or regex for Pre/PostToolUse, empty string for global events
+- `hooks[].type`: always `"command"`
+- `hooks[].command`: path to script using `$HOME/.ai-toolkit/hooks/` prefix
+
+## Script Template
+
+```bash
+#!/bin/bash
+# {script-name}.sh — {One-line purpose}.
+#
+# Fires on: {EventName}
+# Matcher: {matcher or "all"}
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+PROFILE="${TOOLKIT_HOOK_PROFILE:-standard}"
+[ "$PROFILE" = "minimal" ] && exit 0
+
+# --- Hook logic here ---
+
+exit 0
+```
+
+## Rules
+
+- One script per hook entry (no inline multi-line commands)
+- Script filename must use kebab-case matching the event purpose
+- Pre* hooks can block operations -- keep them fast and deterministic
+- Never write secrets or credentials to stdout (output goes to LLM context)
+- Test the script standalone before registering: `bash app/hooks/{name}.sh`
+
+## Validation Checklist
+
+After creating the hook:
+
+- [ ] Script exists in `app/hooks/` and is executable (`chmod +x`)
+- [ ] Entry added to `app/hooks.json` with `_source: "ai-toolkit"`
+- [ ] Event name matches a supported lifecycle event
+- [ ] `scripts/validate.py` passes
+- [ ] Script runs without errors: `bash app/hooks/{name}.sh`
+- [ ] Hook count in README.md and docs updated if needed

package/app/skills/index/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: index
+description: "Index codebase into the knowledge base"
+effort: low
+disable-model-invocation: true
+argument-hint: "[path or scope]"
+allowed-tools: Bash
+---
+
+# Knowledge Base Indexing
+
+$ARGUMENTS
+
+Reindex the knowledge base for semantic search.
+
+> **Prerequisite**: This command requires a vector store (e.g., Qdrant) and an indexing pipeline configured for your project. If not configured, this command provides guidance on setup.
+
+## Usage
+
+```
+/index              # Incremental index (detect changes)
+/index --full       # Full rebuild
+```
+
+## Execution
+
+### Direct Execution
+```bash
+# Incremental index (auto-detects changes)
+make index
+
+# Full rebuild
+make index-full
+```
+
+### Docker Execution
+```bash
+docker exec {app-container} make index
+docker exec {app-container} make index-full
+```
+
+## Change Detection
+
+The indexer uses content hashing to detect changes:
+
+| Scenario | Action |
+|----------|--------|
+| New document | Index |
+| Changed content | Reindex |
+| No changes | Skip |
+| Deleted document | Remove from index |
+
+## Frontmatter Validation
+
+Before indexing, ensure all KB documents have valid frontmatter:
+
+```yaml
+---
+title: "Document Title"
+service: {service-name}
+category: reference|howto|procedures|troubleshooting|decisions|best-practices
+tags: [tag1, tag2]
+last_updated: "YYYY-MM-DD"
+---
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Index not updating | Check file timestamps, run full rebuild |
+| Missing documents | Verify frontmatter is valid |
+| Slow indexing | Check embedding service performance |
+| No vector store | Set up Qdrant or compatible vector DB |

package/app/skills/instinct-review/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: instinct-review
+description: "Review and manage learned instincts from past sessions"
+effort: low
+user-invocable: true
+argument-hint: "[--list | --promote <id> | --remove <id> | --clear]"
+allowed-tools: Bash, Read, Write, Glob
+---
+
+# /instinct-review - Manage Learned Instincts
+
+$ARGUMENTS
+
+## What This Does
+
+Manages the instinct system that learns patterns from your sessions.
+
+Instincts are stored in `.claude/instincts/` and loaded at session start.
+
+## Commands
+
+### List all instincts
+```
+/instinct-review --list
+```
+Shows all instincts with confidence scores and source sessions.
+
+### Review and curate
+```
+/instinct-review
+```
+Interactive review: shows each instinct and asks promote/remove/keep.
+
+### Promote instinct (always apply)
+```
+/instinct-review --promote <filename>
+```
+
+### Remove instinct
+```
+/instinct-review --remove <filename>
+```
+
+### Clear all instincts
+```
+/instinct-review --clear
+```
+
+## How Instincts Work
+
+1. **Extraction**: At session end, the Stop hook extracts patterns from the session
+2. **Storage**: Saved as `.claude/instincts/<pattern-name>.md` with confidence score
+3. **Loading**: At session start, instincts are loaded and shown to Claude
+4. **Curation**: Use `/instinct-review` to promote good ones and remove bad ones
+
+## Instinct Format
+
+```markdown
+# Pattern: [pattern name]
+Confidence: 0.85
+Sessions: 3
+Last seen: 2026-03-25
+
+[Description of the pattern or preference]
+```
+
+## Steps
+
+1. Run `ls .claude/instincts/ 2>/dev/null || echo "No instincts yet"`
+2. For each instinct file, read it and display confidence/summary
+3. Based on `$ARGUMENTS`:
+   - `--list`: display table of all instincts
+   - `--promote <id>`: set confidence to 1.0, add "pinned" tag
+   - `--remove <id>`: delete the file
+   - `--clear`: delete all files in `.claude/instincts/`
+   - no args: interactive review of each instinct
+4. Report summary of changes made