@softspark/ai-toolkit 1.0.0

package/app/skills/security-patterns/reference/oauth-csrf-audit.md

@@ -0,0 +1,131 @@
+# OAuth2, CSRF Protection & Audit Logging
+
+## OAuth2 Flows
+
+### Authorization Code Flow (FastAPI)
+```python
+from authlib.integrations.starlette_client import OAuth
+from starlette.config import Config
+
+config = Config('.env')
+oauth = OAuth(config)
+
+oauth.register(
+    name='google',
+    client_id=config('GOOGLE_CLIENT_ID'),
+    client_secret=config('GOOGLE_CLIENT_SECRET'),
+    authorize_url='https://accounts.google.com/o/oauth2/auth',
+    access_token_url='https://oauth2.googleapis.com/token',
+    client_kwargs={'scope': 'openid email profile'},
+)
+
+@app.get('/login')
+async def login(request: Request):
+    redirect_uri = request.url_for('auth_callback')
+    return await oauth.google.authorize_redirect(request, redirect_uri)
+
+@app.get('/auth/callback')
+async def auth_callback(request: Request):
+    token = await oauth.google.authorize_access_token(request)
+    user_info = token.get('userinfo')
+    return {"email": user_info['email']}
+```
+
+---
+
+## CSRF Protection
+
+```python
+from fastapi import FastAPI, Request, Depends
+from fastapi_csrf_protect import CsrfProtect
+from pydantic import BaseModel
+
+class CsrfSettings(BaseModel):
+    secret_key: str = "your-secret-key-min-32-chars-long!"
+    cookie_samesite: str = "lax"
+    cookie_secure: bool = True
+
+@CsrfProtect.load_config
+def get_csrf_config():
+    return CsrfSettings()
+
+@app.get("/csrf-token")
+async def get_csrf_token(csrf_protect: CsrfProtect = Depends()):
+    token = csrf_protect.generate_csrf()
+    return {"csrf_token": token}
+
+@app.post("/protected")
+async def protected_route(request: Request, csrf_protect: CsrfProtect = Depends()):
+    await csrf_protect.validate_csrf(request)
+    return {"status": "ok"}
+```
+
+### CSRF Best Practices
+| Technique | Implementation |
+|-----------|---------------|
+| SameSite Cookie | `cookie_samesite: "strict"` or `"lax"` |
+| Double Submit | Token in cookie + header |
+| Origin Validation | Check `Origin`/`Referer` headers |
+| Secure Flag | `cookie_secure: True` in production |
+
+---
+
+## Audit Logging
+
+```python
+import structlog
+from enum import Enum
+from datetime import datetime
+from typing import Any
+
+logger = structlog.get_logger()
+
+class AuditAction(str, Enum):
+    CREATE = "create"
+    READ = "read"
+    UPDATE = "update"
+    DELETE = "delete"
+    LOGIN = "login"
+    LOGOUT = "logout"
+    ACCESS_DENIED = "access_denied"
+
+def audit_log(
+    action: AuditAction,
+    user_id: str,
+    resource: str,
+    resource_id: str | None = None,
+    details: dict[str, Any] | None = None,
+    ip_address: str | None = None
+) -> None:
+    logger.info(
+        "audit_event",
+        action=action.value,
+        user_id=user_id,
+        resource=resource,
+        resource_id=resource_id,
+        details=details or {},
+        ip_address=ip_address,
+        timestamp=datetime.utcnow().isoformat()
+    )
+
+# Usage in FastAPI
+@app.delete("/users/{user_id}")
+async def delete_user(user_id: str, request: Request, current_user: User = Depends()):
+    audit_log(
+        action=AuditAction.DELETE,
+        user_id=current_user.id,
+        resource="users",
+        resource_id=user_id,
+        ip_address=request.client.host
+    )
+    # ... delete logic
+```
+
+### Audit Log Requirements
+| Event | Must Log |
+|-------|----------|
+| Authentication | Login, logout, failed attempts |
+| Authorization | Access denied, permission changes |
+| Data Changes | Create, update, delete with before/after |
+| Admin Actions | User management, config changes |
+| Security Events | Password reset, MFA changes |

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

@@ -0,0 +1,154 @@
+---
+name: skill-creator
+description: "Create new skills from templates with guided workflow"
+effort: high
+disable-model-invocation: true
+argument-hint: "[skill name or description]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Skill Creator
+
+$ARGUMENTS
+
+Create a new skill following the Agent Skills standard.
+
+## Workflow
+
+1. **Capture intent** -- ask: what should the skill do? Who invokes it?
+2. **Classify** -- task, hybrid, or knowledge? (see Classification Guide below)
+3. **Interview** -- gather: framework, tools, scope, output format, constraints
+4. **Write SKILL.md** -- frontmatter + body, under 500 lines
+5. **Create supporting files** -- reference/, templates/, scripts/ as needed
+6. **Test and iterate** -- invoke, observe, refine
+
+## Frontmatter Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Lowercase, hyphens only, max 64 chars |
+| `description` | string | yes | Third person, max 1024 chars, include key terms |
+| `effort` | low/medium/high/max | no | Controls model thinking budget |
+| `disable-model-invocation` | bool | no | `true` = only user can trigger (task skills) |
+| `user-invocable` | bool | no | `false` = knowledge skill, Claude auto-loads |
+| `allowed-tools` | csv | no | Restrict tool access for safety |
+| `model` | string | no | Override default model |
+| `context` | string | no | `fork` to run in isolated subagent |
+| `agent` | string | no | Agent type to use when `context: fork` |
+| `argument-hint` | string | no | Shown in autocomplete, e.g. `"[target]"` |
+| `hooks` | object | no | Lifecycle hooks (PreToolUse, PostToolUse, Stop) |
+
+## Classification Guide
+
+| Type | When to use | Key fields |
+|------|-------------|------------|
+| **Task** | User-triggered actions with side effects (build, deploy, commit) | `disable-model-invocation: true`, `allowed-tools` |
+| **Hybrid** | Both user and Claude invoke (review, analyze) | defaults |
+| **Knowledge** | Domain patterns Claude auto-loads (clean-code, api-patterns) | `user-invocable: false` |
+
+## Writing Guidelines
+
+- **Description**: third person ("Generates...", "Provides..."), include searchable key terms
+- **Name**: lowercase, hyphens, max 64 chars -- match the directory name
+- **Length**: SKILL.md under 500 lines; use `reference/` for overflow
+- **Be concise**: Claude is smart -- give structure, not lectures
+- **Degrees of freedom**: be specific on format/constraints, flexible on implementation
+- **File references**: max 1 level deep (e.g., `reference/details.md`)
+- **Use `$ARGUMENTS`**: place it early so user input is visible
+- **Tables over prose**: for options, patterns, mappings
+
+## Directory Structure
+
+```
+skill-name/
+  SKILL.md              # Main instructions (required, <500 lines)
+  reference/            # Detailed docs (loaded on-demand)
+  templates/            # Reusable templates for output
+  scripts/              # Executable helper scripts
+```
+
+Only create subdirectories when the skill needs them. Most skills are a single SKILL.md.
+
+## SKILL.md Template
+
+```markdown
+---
+name: {name}
+description: "{Third-person description with key terms}"
+argument-hint: "[hint]"
+allowed-tools: Read, Grep, Glob
+---
+
+# {Title}
+
+$ARGUMENTS
+
+{One-line purpose statement.}
+
+## Usage
+
+\`\`\`
+/{name} [arguments]
+\`\`\`
+
+## What This Command Does
+
+1. **Step one**
+2. **Step two**
+3. **Step three**
+
+## Output Format
+
+{Expected output structure}
+
+## Rules
+
+- {Constraint 1}
+- {Constraint 2}
+```
+
+## Quality Checklist
+
+Before finalizing, verify:
+
+- [ ] Description is specific with searchable key terms
+- [ ] SKILL.md is under 500 lines
+- [ ] No time-sensitive information (versions, dates)
+- [ ] Consistent terminology throughout
+- [ ] Examples are concrete, not abstract
+- [ ] File references max 1 level deep
+- [ ] Workflows have numbered steps
+- [ ] Frontmatter fields match classification type
+- [ ] `$ARGUMENTS` is present for task/hybrid skills
+- [ ] `allowed-tools` is minimal (principle of least privilege)
+
+## Evaluation
+
+After creating the skill, test it:
+
+1. Invoke with a representative prompt
+2. Check output matches expected structure
+3. Verify dynamic injection (`$ARGUMENTS`) works
+4. Test with varied argument patterns
+5. Confirm `allowed-tools` are sufficient but not excessive
+6. Iterate: tighten instructions where output diverges
+
+## Installation
+
+After creating the skill:
+
+1. Verify the skill directory exists under `app/skills/{name}/`
+2. Update `skills-catalog.md` if it exists
+3. Update `ARCHITECTURE.md` skill counts if referenced
+4. Run `validate.sh` if available
+5. Run `evaluate-skills.sh` if available
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Description too vague | Add specific terms: "Python", "REST API", "migration" |
+| SKILL.md too long | Move details to `reference/` subdirectory |
+| Missing `$ARGUMENTS` | Add after the H1 heading for task/hybrid skills |
+| Over-specifying steps | Give structure, let Claude fill details |
+| Wrong classification | Task = side effects, Knowledge = patterns, Hybrid = both |

package/app/skills/skill-creator/templates/dashboard/index.html

@@ -0,0 +1,130 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>ai-toolkit Dashboard</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
+<style>
+  :root { --bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff; --green: #3fb950; }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; background: var(--bg); color: var(--text); min-height: 100vh; padding: 24px; }
+  h1 { font-size: 1.5rem; font-weight: 600; margin-bottom: 8px; }
+  .subtitle { color: var(--muted); margin-bottom: 24px; font-size: 0.875rem; }
+  .stats-row { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 16px; margin-bottom: 24px; }
+  .stat-card { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
+  .stat-card .label { color: var(--muted); font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; }
+  .stat-card .value { font-size: 2rem; font-weight: 700; color: var(--accent); margin-top: 4px; }
+  .charts { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 24px; }
+  .chart-card { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
+  .chart-card h2 { font-size: 0.875rem; color: var(--muted); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.05em; }
+  .upload-area { background: var(--surface); border: 2px dashed var(--border); border-radius: 8px; padding: 32px; text-align: center; cursor: pointer; transition: border-color 0.2s; }
+  .upload-area:hover { border-color: var(--accent); }
+  .upload-area p { color: var(--muted); margin-top: 8px; font-size: 0.875rem; }
+  #file-input { display: none; }
+  #paste-area { width: 100%; min-height: 80px; background: var(--bg); border: 1px solid var(--border); border-radius: 6px; color: var(--text); padding: 12px; font-family: monospace; font-size: 0.8rem; margin-top: 12px; resize: vertical; }
+  button { background: var(--accent); color: var(--bg); border: none; padding: 8px 16px; border-radius: 6px; cursor: pointer; font-weight: 600; margin-top: 8px; }
+  button:hover { opacity: 0.9; }
+  #dashboard { display: none; }
+  @media (max-width: 768px) { .charts { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<h1>ai-toolkit Dashboard</h1>
+<p class="subtitle">Load stats.json to visualize skill usage, top agents, and session metrics.</p>
+
+<div id="loader">
+  <div class="upload-area" onclick="document.getElementById('file-input').click()">
+    <strong>Drop stats.json or click to upload</strong>
+    <p>Or paste JSON below and click Load</p>
+  </div>
+  <input type="file" id="file-input" accept=".json">
+  <textarea id="paste-area" placeholder='{"skills": {...}, "agents": {...}, "sessions": 0}'></textarea>
+  <button onclick="loadFromPaste()">Load</button>
+</div>
+
+<div id="dashboard">
+  <div class="stats-row">
+    <div class="stat-card"><div class="label">Total Sessions</div><div class="value" id="total-sessions">0</div></div>
+    <div class="stat-card"><div class="label">Skills Used</div><div class="value" id="skills-used">0</div></div>
+    <div class="stat-card"><div class="label">Top Agent</div><div class="value" id="top-agent" style="font-size:1.2rem">-</div></div>
+    <div class="stat-card"><div class="label">Most Used Skill</div><div class="value" id="top-skill" style="font-size:1.2rem">-</div></div>
+  </div>
+  <div class="charts">
+    <div class="chart-card"><h2>Skill Usage Frequency</h2><canvas id="skills-chart"></canvas></div>
+    <div class="chart-card"><h2>Top Agents</h2><canvas id="agents-chart"></canvas></div>
+  </div>
+</div>
+
+<script>
+let skillsChart = null, agentsChart = null;
+
+document.getElementById('file-input').addEventListener('change', (e) => {
+  const file = e.target.files[0];
+  if (!file) return;
+  const reader = new FileReader();
+  reader.onload = (ev) => render(JSON.parse(ev.target.result));
+  reader.readAsText(file);
+});
+
+function loadFromPaste() {
+  const raw = document.getElementById('paste-area').value.trim();
+  if (!raw) return;
+  try { render(JSON.parse(raw)); } catch (err) { alert('Invalid JSON: ' + err.message); }
+}
+
+function render(data) {
+  document.getElementById('loader').style.display = 'none';
+  document.getElementById('dashboard').style.display = 'block';
+
+  const skills = data.skills || {};
+  const agents = data.agents || {};
+  const sessions = data.sessions || 0;
+
+  document.getElementById('total-sessions').textContent = sessions;
+  document.getElementById('skills-used').textContent = Object.keys(skills).length;
+
+  const sortedSkills = Object.entries(skills).sort((a, b) => b[1] - a[1]);
+  const sortedAgents = Object.entries(agents).sort((a, b) => b[1] - a[1]);
+
+  document.getElementById('top-skill').textContent = sortedSkills[0] ? sortedSkills[0][0] : '-';
+  document.getElementById('top-agent').textContent = sortedAgents[0] ? sortedAgents[0][0] : '-';
+
+  const top15Skills = sortedSkills.slice(0, 15);
+  const top10Agents = sortedAgents.slice(0, 10);
+
+  if (skillsChart) skillsChart.destroy();
+  if (agentsChart) agentsChart.destroy();
+
+  const chartDefaults = { color: '#8b949e', borderColor: '#30363d' };
+  Chart.defaults.color = chartDefaults.color;
+
+  skillsChart = new Chart(document.getElementById('skills-chart'), {
+    type: 'bar',
+    data: {
+      labels: top15Skills.map(s => s[0]),
+      datasets: [{ label: 'Invocations', data: top15Skills.map(s => s[1]),
+        backgroundColor: '#58a6ff', borderRadius: 4, barThickness: 18 }]
+    },
+    options: {
+      indexAxis: 'y', responsive: true, plugins: { legend: { display: false } },
+      scales: { x: { grid: { color: '#21262d' } }, y: { grid: { display: false } } }
+    }
+  });
+
+  agentsChart = new Chart(document.getElementById('agents-chart'), {
+    type: 'bar',
+    data: {
+      labels: top10Agents.map(a => a[0]),
+      datasets: [{ label: 'Delegations', data: top10Agents.map(a => a[1]),
+        backgroundColor: '#3fb950', borderRadius: 4, barThickness: 18 }]
+    },
+    options: {
+      indexAxis: 'y', responsive: true, plugins: { legend: { display: false } },
+      scales: { x: { grid: { color: '#21262d' } }, y: { grid: { display: false } } }
+    }
+  });
+}
+</script>
+</body>
+</html>

package/app/skills/skill-creator/templates/reasoning-engine/assets/example.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": "example-pattern-1",
+    "name": "Example Pattern",
+    "domain": "general",
+    "description": "A template entry showing the expected format",
+    "tags": ["template", "example"],
+    "anti_patterns": ["conflicting-pattern"],
+    "severity": "info",
+    "auto_fixable": false
+  }
+]

package/app/skills/skill-creator/templates/reasoning-engine/search.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Generic domain reasoning engine for ai-toolkit skills.
+
+Multi-domain search across a categorized knowledge base with anti-pattern filtering.
+Python stdlib only, JSON to stdout, zero external deps.
+
+Usage: python3 search.py <query> [--domain <domain>] [--limit <n>]
+
+Threshold rule: Use this pattern when skill has >50 options across >3
+compatibility dimensions. Below that threshold, Markdown tables suffice.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def load_catalog(assets_dir: Path) -> list[dict]:
+    """Load all JSON asset files from the assets directory."""
+    items: list[dict] = []
+    for f in sorted(assets_dir.glob("*.json")):
+        with open(f) as fh:
+            data = json.load(fh)
+            if isinstance(data, list):
+                items.extend(data)
+            else:
+                items.append(data)
+    return items
+
+
+def match_query(
+    items: list[dict], query: str, domain: str | None = None
+) -> list[dict]:
+    """Score items against query using keyword matching."""
+    query_terms = query.lower().split()
+    scored: list[dict] = []
+    for item in items:
+        if domain and item.get("domain", "") != domain:
+            continue
+        searchable = " ".join(str(v) for v in item.values()).lower()
+        score = sum(1 for term in query_terms if term in searchable)
+        if score > 0:
+            scored.append({**item, "_score": score})
+    return sorted(scored, key=lambda x: x["_score"], reverse=True)
+
+
+def filter_anti_patterns(
+    items: list[dict], selected: list[str]
+) -> list[dict]:
+    """Remove items that conflict with already-selected items."""
+    conflicts: set[str] = set()
+    for item in items:
+        if item.get("id") in selected:
+            conflicts.update(item.get("anti_patterns", []))
+    return [i for i in items if i.get("id") not in conflicts]
+
+
+def main() -> None:
+    """CLI entrypoint."""
+    if len(sys.argv) < 2:
+        print(
+            json.dumps(
+                {"error": "Usage: search.py <query> [--domain D] [--limit N]"}
+            )
+        )
+        sys.exit(1)
+
+    query = sys.argv[1]
+    domain: str | None = None
+    limit = 10
+
+    args = sys.argv[2:]
+    for i, arg in enumerate(args):
+        if arg == "--domain" and i + 1 < len(args):
+            domain = args[i + 1]
+        elif arg == "--limit" and i + 1 < len(args):
+            limit = int(args[i + 1])
+
+    assets_dir = Path(__file__).parent / "assets"
+    if not assets_dir.exists():
+        print(
+            json.dumps(
+                {"error": f"Assets directory not found: {assets_dir}"}
+            )
+        )
+        sys.exit(1)
+
+    catalog = load_catalog(assets_dir)
+    results = match_query(catalog, query, domain)
+    results = filter_anti_patterns(results, [])[:limit]
+
+    # Remove internal score from output
+    for r in results:
+        r.pop("_score", None)
+
+    print(
+        json.dumps(
+            {
+                "query": query,
+                "domain": domain,
+                "results": results,
+                "total": len(results),
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()