@softspark/ai-toolkit 1.0.0

package/app/skills/repeat/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: repeat
+description: "Run a prompt or slash command on a recurring interval until task complete or limits reached. Use when user wants to set up a recurring task, poll for status, or run something repeatedly on an interval."
+user-invocable: true
+effort: medium
+argument-hint: "[interval] [command or prompt] (e.g., /repeat 5m /test, defaults to 10m)"
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
+---
+
+# /repeat - Autonomous Recurring Execution
+
+$ARGUMENTS
+
+## Argument Parsing
+
+Parse the user input into three components:
+
+1. **Interval** — duration between iterations (default: `10m`)
+   - Accepts: `1m`, `5m`, `10m`, `30m`, `1h`
+   - Minimum: `1m` (enforced, reject anything lower)
+2. **Command or prompt** — the slash command or freeform prompt to execute each iteration
+3. **Flags**:
+   - `--iterations N` — maximum number of iterations (default: `5`)
+
+Examples of parsed input:
+- `/repeat 5m /test` -> interval=5m, command=/test, iterations=5
+- `/repeat 10m "check deploy status"` -> interval=10m, command="check deploy status", iterations=5
+- `/repeat --iterations 3 /review` -> interval=10m, command=/review, iterations=3
+- `/repeat 2m --iterations 10 /lint` -> interval=2m, command=/lint, iterations=10
+
+## Safety Controls
+
+These limits are constitutionally mandated (Article I, Section 4). Violating them is not permitted.
+
+### Max Iterations
+- Default: **5** iterations
+- Configurable via `--iterations N`
+- Hard ceiling: the loop MUST terminate after N iterations regardless of outcome
+
+### Circuit Breaker
+- Track consecutive failures (non-zero exit code, error output, exceptions)
+- **3 consecutive failures** -> immediate hard stop
+- Reset the failure counter on any successful iteration
+
+### Minimum Interval
+- **Never** execute faster than 1 minute between iterations
+- If user requests `<1m`, override to `1m` and warn
+
+### Exit Detection
+After each iteration, inspect the output for completion signals:
+- Exit code `0` combined with success markers
+- Output contains: `DONE`, `COMPLETE`, `ALL PASS`, `ALL TESTS PASSED`, `SUCCESS`
+- Case-insensitive matching
+- If detected: stop the loop early and report success
+
+## Execution Protocol
+
+```
+For iteration = 1 to max_iterations:
+    1. Log iteration start (timestamp, iteration number)
+    2. Execute the command or prompt
+    3. Capture output and exit status
+    4. Check exit detection:
+       - If completion marker found -> STOP, report success
+    5. Check circuit breaker:
+       - If failure: increment consecutive_failures
+       - If success: reset consecutive_failures to 0
+       - If consecutive_failures >= 3 -> HARD STOP, report failure
+    6. Log iteration result to stats
+    7. If not last iteration: wait for interval duration
+    8. Repeat
+
+After loop ends:
+    - Print summary: total iterations, pass/fail counts, elapsed time
+    - Final status: COMPLETED | EARLY_SUCCESS | CIRCUIT_BREAKER | MAX_ITERATIONS
+```
+
+## Stats Logging
+
+Each iteration MUST be logged to `~/.ai-toolkit/stats.json`:
+
+```json
+{
+  "loop_runs": [
+    {
+      "id": "loop-<timestamp>",
+      "command": "/test",
+      "interval": "5m",
+      "max_iterations": 5,
+      "started_at": "2026-04-01T10:00:00Z",
+      "iterations": [
+        {
+          "number": 1,
+          "timestamp": "2026-04-01T10:00:00Z",
+          "result": "pass",
+          "exit_code": 0,
+          "summary": "All 42 tests passed"
+        },
+        {
+          "number": 2,
+          "timestamp": "2026-04-01T10:05:00Z",
+          "result": "fail",
+          "exit_code": 1,
+          "summary": "3 tests failed"
+        }
+      ],
+      "final_status": "EARLY_SUCCESS",
+      "ended_at": "2026-04-01T10:10:00Z"
+    }
+  ]
+}
+```
+
+Ensure the stats directory and file exist before writing. Append to existing data, never overwrite.
+
+## Usage Examples
+
+```bash
+# Run tests every 5 minutes until all pass (max 5 iterations)
+/repeat 5m /test
+
+# Poll deployment status every 10 minutes
+/repeat 10m "check deploy status"
+
+# Run review max 3 times at default interval
+/repeat --iterations 3 /review
+
+# Lint every 2 minutes, up to 10 times
+/repeat 2m --iterations 10 /lint
+
+# Monitor CI pipeline every 5 minutes
+/repeat 5m "check if CI pipeline passed for current branch"
+```
+
+## When to Use
+
+- Polling deployment or CI/CD pipeline status
+- Running tests repeatedly until green
+- Monitoring an external process for completion
+- Retrying a flaky operation with intervals
+- Watching for a condition to become true
+
+## When NOT to Use
+
+- Anything requiring human judgment between iterations
+- Tasks where each iteration depends on user feedback
+- Long-running computations that should be a single background job
+- Destructive operations (deletes, drops, force pushes) -- never loop these
+- Intervals shorter than 1 minute -- use a proper scheduler instead

package/app/skills/research-mastery/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: research-mastery
+description: "Loaded when user asks to research, verify, or synthesize information"
+effort: medium
+user-invocable: false
+---
+
+# Research Mastery Skill
+
+You are not a guessing machine. You are an information retrieval engine.
+
+## 🔴 The Hierarchy of Truth (Strict Order)
+
+You MUST search in this order. Do not skip steps.
+
+### 1. Local Knowledge (RAG-MCP)
+**Source of Truth**: The project's Knowledge Base (`kb/`).
+**Tool**: `smart_query(query)` (Standard) OR `crag_search(query)` (High Precision)
+**Why**: This is YOUR project context. It overrides everything else.
+**Protocol**:
+1. Try `smart_query("task context")`.
+2. **CRITIC (Self-Correction)**:
+   - "Did the docs answer the specific question?"
+   - **If NO**: Use `crag_search(query, relevance_threshold=0.7)`.
+   - **If STILL NO**: 
+     1. **LOG GAP**: Append query to `kb/gaps.log`
+     2. Proceed to Step 2.
+
+### 2. Context7 (External MCPs)
+**Source of Truth**: Connected MCP servers (e.g., databases, external APIs).
+**Tool**: `use_mcp_tool(...)`
+**Why**: Live data from the environment.
+
+### 3. External Search (Internet)
+**Source of Truth**: The Web.
+**Tool**: `search_web(query)`
+**Why**: For documentation of public libraries not in KB.
+**Rule**: ONLY if Step 1 & 2 yield nothing.
+
+### 4. Built-in Knowledge (LLM Training)
+**Source of Truth**: Your training data.
+**Why**: Fallback for general programming concepts.
+**Rule**: Use only for generic syntax/logic, NEVER for project specifics.
+
+## 🛑 Validation Protocol
+Before acting on information:
+1. **Cite the Source**: "According to `kb/architecture.md`..."
+2. **Verify Freshness**: Is the doc from 2023 or 2025?
+3. **Cross-Reference**: Does the code match the doc?
+
+## Example Workflow
+Task: "Fix the login bug."
+1. `smart_query("login architecture")` -> Found `kb/auth/login_flow.md`.
+2. `smart_query("known login bugs")` -> Found nothing.
+3. Code analysis of `src/auth/Login.ts`.
+4. Fix implemented based on `login_flow.md`.

package/app/skills/review/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: review
+description: "Review code for quality, security, and correctness"
+user-invocable: true
+effort: high
+argument-hint: "[target: branch, pr, file path, or staged changes]"
+agent: code-reviewer
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Code Review
+
+$ARGUMENTS
+
+Reviews code changes for quality and issues.
+
+## Changed files context
+
+- Changes: !`git diff --stat main...HEAD 2>/dev/null || git diff --cached --stat 2>/dev/null || echo "no changes detected"`
+
+## Automated Diff Analysis
+
+Before starting manual review, run the diff analyzer script to get a structured risk assessment:
+
+```bash
+python3 "$(dirname "$0")/scripts/diff-analyzer.py" [base_branch]
+# Default base branch: main
+# Example: python3 scripts/diff-analyzer.py develop
+```
+
+The script outputs JSON with:
+- **files**: each changed file with additions, deletions, category (security/test/config/migration/infra/docs/logic), and risk level
+- **risk_score**: overall assessment (high/medium/low)
+- **hotspots**: top 5 files by additions
+- **secrets_scan**: potential secret leaks detected in added lines
+- **test_coverage_estimate**: whether test files accompany logic changes (good/partial/none)
+- **parallel_review_recommended**: boolean flag
+
+If the script reports `parallel_review_recommended: true`, use the Parallel Review (Agent Teams) mode below.
+
+---
+
+## Parallel Review (Agent Teams)
+
+For significant PRs or large changesets, create a parallel review team:
+
+```
+Create an agent team to review [target]:
+- Teammate 1 (security-auditor): "Review for security vulnerabilities, auth issues,
+  injection risks, secret leaks. Report with severity ratings." Use Opus.
+- Teammate 2 (performance-optimizer): "Check for N+1 queries, memory leaks,
+  unnecessary allocations, caching opportunities. Report with impact ratings." Use Opus.
+- Teammate 3 (test-engineer): "Validate test coverage, edge cases, mock quality,
+  missing assertions. Report coverage gaps." Use Opus.
+Each reviewer should report findings independently. Do NOT modify files.
+```
+
+After all reviewers complete:
+1. Synthesize findings into unified Code Review Report
+2. Prioritize by severity (Critical > Major > Minor)
+3. Issue verdict: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION
+
+> **When to use**: PRs with >5 files changed, cross-module changes, security-sensitive code.
+> **READ-ONLY**: No teammate should modify files during review.
+
+---
+
+## Sequential Review (Default)
+
+1. **Reads** changed files
+2. **Analyzes** for issues
+3. **Checks** best practices
+4. **Reports** findings
+
+## Review Scope
+
+| Target | What's Reviewed |
+|--------|-----------------|
+| (none) | Staged changes |
+| `branch` | Branch vs main |
+| `pr` | Pull request changes |
+| `file.ts` | Specific file |
+
+## Review Checklist
+
+### Code Quality
+- [ ] Clear naming
+- [ ] Proper error handling
+- [ ] No code duplication
+- [ ] Appropriate abstractions
+
+### Security
+- [ ] No hardcoded secrets
+- [ ] Input validation
+- [ ] Proper auth checks
+- [ ] SQL injection prevention
+
+### Performance
+- [ ] No N+1 queries
+- [ ] Appropriate caching
+- [ ] No memory leaks
+- [ ] Optimized loops
+
+### Testing
+- [ ] Tests for new code
+- [ ] Edge cases covered
+- [ ] Mocks appropriate
+
+## Output Format
+
+```markdown
+## Code Review Report
+
+### Summary
+- **Files Changed**: [count]
+- **Lines Added**: [+count]
+- **Lines Removed**: [-count]
+- **Issues Found**: [count]
+
+### Findings
+
+#### Critical
+- **[file:line]**: [issue]
+  - [explanation]
+  - Suggested fix: [code]
+
+#### Suggestions
+- **[file:line]**: [suggestion]
+  - [explanation]
+
+### Positive Notes
+- [What's good about the code]
+
+### Verdict
+[APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION]
+```
+
+## READ-ONLY
+
+This skill only analyzes. It does NOT modify any files.

package/app/skills/review/scripts/diff-analyzer.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Analyze a git diff for risk assessment, file categorization, and secrets detection.
+
+Compares the current branch against a base branch (default ``main``),
+categorises each changed file (security, test, config, migration,
+infra, docs, logic), scans added lines for potential secrets, computes
+a composite risk score, and outputs a JSON report suitable for
+pre-review triage.
+
+Usage::
+
+    python3 diff-analyzer.py [base_branch]
+    # Default base branch: main
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from typing import Any
+
+
+CATEGORY_PATTERNS: dict[str, str] = {
+    "security": r"(auth|login|password|token|secret|crypto|session|permission|role|access)",
+    "test": r"(test_|_test\.|spec\.|\.test\.|__tests__|tests/)",
+    "config": r"(\.(yml|yaml|json|toml|env|ini|cfg)$|config|settings|\.lock$)",
+    "migration": r"(migration|alembic|schema|migrate)",
+    "infra": r"(docker|kubernetes|k8s|terraform|ansible|ci|deploy|\.github)",
+    "docs": r"(readme|changelog|docs/|\.md$|license)",
+}
+
+SECRET_PATTERNS: list[str] = [
+    r'(?i)(api[_-]?key|secret[_-]?key|password|token|bearer)\s*[=:]\s*["\'][^"\']{8,}',
+    r"AKIA[0-9A-Z]{16}",
+    r"sk-[a-zA-Z0-9]{20,}",
+    r"ghp_[a-zA-Z0-9]{36}",
+]
+
+
+def categorize(path: str) -> str:
+    """Categorize a file path into a review domain.
+
+    Args:
+        path: Relative file path from the diff.
+
+    Returns:
+        Category name (``"security"``, ``"test"``, ``"config"``,
+        ``"migration"``, ``"infra"``, ``"docs"``, or ``"logic"``).
+    """
+    for cat, pattern in CATEGORY_PATTERNS.items():
+        if re.search(pattern, path, re.IGNORECASE):
+            return cat
+    return "logic"
+
+
+def main() -> None:
+    """Entry point: analyze diff and print JSON risk report to stdout."""
+    base = sys.argv[1] if len(sys.argv) > 1 else "main"
+
+    # Get diff stats (try base...HEAD first, fall back to --cached)
+    r = subprocess.run(
+        ["git", "diff", "--numstat", f"{base}...HEAD"],
+        stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+    )
+    if r.returncode != 0:
+        r = subprocess.run(
+            ["git", "diff", "--numstat", "--cached"],
+            capture_output=True, text=True,
+        )
+    diff_stat = r.stdout.strip()
+    files: list[dict[str, Any]] = []
+    total_add, total_del = 0, 0
+
+    for line in diff_stat.split("\n"):
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        add = int(parts[0]) if parts[0] != "-" else 0
+        delete = int(parts[1]) if parts[1] != "-" else 0
+        path = parts[2]
+        cat = categorize(path)
+        if cat in ("security", "migration") or add > 100:
+            risk = "high"
+        elif add > 30:
+            risk = "medium"
+        else:
+            risk = "low"
+        files.append(
+            {
+                "path": path,
+                "additions": add,
+                "deletions": delete,
+                "category": cat,
+                "risk": risk,
+            }
+        )
+        total_add += add
+        total_del += delete
+
+    # Category summary
+    categories: dict[str, int] = {}
+    for f in files:
+        categories[f["category"]] = categories.get(f["category"], 0) + 1
+
+    # Hotspots - files with most additions
+    hotspots: list[str] = [
+        f"{f['path']} - {f['additions']} lines added ({f['category']})"
+        for f in sorted(files, key=lambda x: x["additions"], reverse=True)[:5]
+        if f["additions"] > 20
+    ]
+
+    # Secrets scan on added lines (try base...HEAD first, fall back to --cached)
+    r = subprocess.run(
+        ["git", "diff", f"{base}...HEAD"],
+        stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+    )
+    if r.returncode != 0:
+        r = subprocess.run(
+            ["git", "diff", "--cached"],
+            capture_output=True, text=True,
+        )
+    diff_content = r.stdout.strip()
+    secrets: list[dict[str, Any]] = []
+    for i, line in enumerate(diff_content.split("\n")):
+        if line.startswith("+") and not line.startswith("+++"):
+            for p in SECRET_PATTERNS:
+                if re.search(p, line):
+                    secrets.append({"line": i, "preview": line[:80]})
+
+    # Risk score
+    has_security = any(f["category"] == "security" for f in files)
+    has_migration = any(f["category"] == "migration" for f in files)
+    if has_security or has_migration or secrets or len(files) > 20:
+        risk_score = "high"
+    elif len(files) > 10 or total_add > 500:
+        risk_score = "medium"
+    else:
+        risk_score = "low"
+
+    # Test coverage estimate
+    test_file_count = sum(1 for f in files if f["category"] == "test")
+    logic_files = sum(1 for f in files if f["category"] == "logic")
+    if test_file_count >= logic_files and logic_files > 0:
+        coverage = "good"
+    elif test_file_count > 0:
+        coverage = "partial"
+    else:
+        coverage = "none"
+
+    result: dict[str, Any] = {
+        "base": base,
+        "files_changed": len(files),
+        "additions": total_add,
+        "deletions": total_del,
+        "files": files,
+        "categories": categories,
+        "risk_score": risk_score,
+        "hotspots": hotspots,
+        "test_coverage_estimate": coverage,
+        "secrets_scan": secrets,
+        "parallel_review_recommended": risk_score == "high" or len(files) > 10,
+    }
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/app/skills/rollback/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rollback
+description: "Roll back a deployment safely with verification"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[target: git/db/deploy]"
+allowed-tools: Bash, Read
+hooks:
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "echo 'Reminder: verify rollback was successful and services are healthy'"
+scripts:
+  - scripts/rollback_info.py
+---
+
+# /rollback - Safe Rollback
+
+$ARGUMENTS
+
+## What This Command Does
+
+Safely revert changes with appropriate safety checks and confirmation.
+
+## Rollback Types
+
+### 1. Git Rollback
+```bash
+# Revert last commit (creates new commit)
+git revert HEAD --no-edit
+
+# Revert specific commit
+git revert <commit-sha> --no-edit
+
+# Revert to specific state (CAUTION)
+git reset --soft <commit-sha>  # Keep changes staged
+```
+
+### 2. Database Migration Rollback
+
+| Tool | Command |
+|------|---------|
+| Alembic | `alembic downgrade -1` |
+| Prisma | `npx prisma migrate resolve --rolled-back <name>` |
+| Laravel | `php artisan migrate:rollback --step=1` |
+| Django | `python manage.py migrate <app> <previous>` |
+| Flyway | `flyway undo` |
+
+### 3. Deployment Rollback
+
+| Platform | Command |
+|----------|---------|
+| Kubernetes | `kubectl rollout undo deployment/<name>` |
+| Docker Compose | `docker compose up -d --force-recreate` (with previous image tag) |
+| Heroku | `heroku rollback` |
+
+## Gather Rollback Context
+
+Run the rollback info script to assess current state before rolling back:
+```bash
+bash scripts/rollback_info.py
+```
+
+Returns JSON with:
+- `git{}` - current/previous commit, branch, commits ahead, uncommitted changes
+- `migrations{}` - detected tool (alembic/prisma/laravel/django/drizzle), rollback command
+- `docker{}` - running services and image tags
+
+## Safety Checks (MANDATORY)
+
+Before any rollback:
+1. Confirm what will be reverted (show diff/plan)
+2. Check for dependent changes that may break
+3. Verify backup exists (for database rollbacks)
+4. Get explicit user confirmation
+
+## Usage Examples
+
+```
+/rollback                    # Interactive - asks what to rollback
+/rollback git last           # Revert last git commit
+/rollback migration          # Rollback last database migration
+/rollback deploy             # Rollback to previous deployment
+```
+
+> **CRITICAL: Always confirm with the user before executing destructive rollback operations.**