@softspark/ai-toolkit 1.0.0

package/app/plugins/memory-pack/hooks/observation-capture.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# observation-capture.sh — Capture tool actions into SQLite memory database.
+#
+# Fires on: PostToolUse
+# Reads tool name and result from JSON on stdin (Claude Code hook protocol).
+# Strips private tags, truncates to 2000 chars, inserts into observations table.
+# Never blocks the user — always exits 0.
+
+DB_PATH="${HOME}/.ai-toolkit/memory.db"
+STRIP_PRIVATE="${HOME}/.ai-toolkit/plugin-scripts/memory-pack/strip_private.py"
+MAX_CONTENT_LENGTH=2000
+
+# Bail silently if database does not exist
+if [ ! -f "$DB_PATH" ]; then
+    exit 0
+fi
+
+# Read JSON input from stdin (Claude Code hook protocol)
+INPUT=$(cat)
+
+# Check if jq is available; bail silently if not
+if ! command -v jq &>/dev/null; then
+    exit 0
+fi
+
+# Parse hook input
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // "unknown"')
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
+TOOL_INPUT=$(printf '%s' "$INPUT" | jq -r '.tool_input | if type == "object" then (to_entries | map(.key + "=" + (.value | tostring)) | join(", ")) else tostring end // empty' 2>/dev/null)
+
+# No session ID means we cannot associate the observation
+if [ -z "$SESSION_ID" ]; then
+    exit 0
+fi
+
+# Build content string
+CONTENT=""
+if [ -n "$FILE_PATH" ]; then
+    CONTENT="${TOOL_NAME}: ${FILE_PATH}"
+elif [ -n "$TOOL_INPUT" ]; then
+    CONTENT="${TOOL_NAME}: ${TOOL_INPUT}"
+else
+    CONTENT="${TOOL_NAME}: (no input captured)"
+fi
+
+# Strip private content
+if [ -f "$STRIP_PRIVATE" ]; then
+    CONTENT=$(printf '%s' "$CONTENT" | python3 "$STRIP_PRIVATE")
+fi
+
+# Truncate to max length
+if [ ${#CONTENT} -gt $MAX_CONTENT_LENGTH ]; then
+    CONTENT="${CONTENT:0:$MAX_CONTENT_LENGTH}..."
+fi
+
+# Ensure session row exists (upsert — ignore if already present)
+sqlite3 "$DB_PATH" "INSERT OR IGNORE INTO sessions (session_id, project_dir, started_at)
+  VALUES ('$(printf '%s' "$SESSION_ID" | sed "s/'/''/g")', '$(pwd)', datetime('now'));" 2>/dev/null || true
+
+# Insert observation
+sqlite3 "$DB_PATH" "INSERT INTO observations (session_id, tool_name, content)
+  VALUES ('$(printf '%s' "$SESSION_ID" | sed "s/'/''/g")',
+          '$(printf '%s' "$TOOL_NAME" | sed "s/'/''/g")',
+          '$(printf '%s' "$CONTENT" | sed "s/'/''/g")');" 2>/dev/null || true
+
+exit 0

package/app/plugins/memory-pack/hooks/session-summary.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# session-summary.sh — Summarize session observations on stop.
+#
+# Fires on: Stop
+# Queries all observations for the current session, builds a compact summary
+# (observation count, tools used, time range), and stores it in the sessions table.
+# Auto-prunes observations older than RETENTION_DAYS (default 90).
+# Never blocks the user — always exits 0.
+
+DB_PATH="${HOME}/.ai-toolkit/memory.db"
+RETENTION_DAYS="${MEMORY_RETENTION_DAYS:-90}"
+
+# Read JSON input from stdin (Claude Code hook protocol)
+INPUT=$(cat)
+
+# Parse session ID from stdin JSON, fall back to env var
+if command -v jq &>/dev/null && [ -n "$INPUT" ]; then
+    SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')
+fi
+SESSION_ID="${SESSION_ID:-${CLAUDE_SESSION_ID:-}}"
+
+# Bail silently if database or session ID missing
+if [ ! -f "$DB_PATH" ] || [ -z "$SESSION_ID" ]; then
+    exit 0
+fi
+
+# Escape session ID for SQL
+SAFE_SESSION_ID=$(printf '%s' "$SESSION_ID" | sed "s/'/''/g")
+
+# Count observations for this session
+OBS_COUNT=$(sqlite3 "$DB_PATH" \
+    "SELECT COUNT(*) FROM observations WHERE session_id = '${SAFE_SESSION_ID}';" 2>/dev/null || echo "0")
+
+# No observations — nothing to summarize
+if [ "$OBS_COUNT" -eq 0 ] 2>/dev/null; then
+    exit 0
+fi
+
+# Gather distinct tools used
+TOOLS_USED=$(sqlite3 "$DB_PATH" \
+    "SELECT GROUP_CONCAT(tool_name, ', ')
+     FROM (SELECT DISTINCT tool_name FROM observations
+           WHERE session_id = '${SAFE_SESSION_ID}' ORDER BY tool_name);" 2>/dev/null || echo "unknown")
+
+# Get time range
+FIRST_OBS=$(sqlite3 "$DB_PATH" \
+    "SELECT MIN(created_at) FROM observations WHERE session_id = '${SAFE_SESSION_ID}';" 2>/dev/null || echo "")
+LAST_OBS=$(sqlite3 "$DB_PATH" \
+    "SELECT MAX(created_at) FROM observations WHERE session_id = '${SAFE_SESSION_ID}';" 2>/dev/null || echo "")
+
+# Build summary text
+SUMMARY="Session captured ${OBS_COUNT} observations. Tools: ${TOOLS_USED}. Time range: ${FIRST_OBS} to ${LAST_OBS}."
+
+# Escape summary for SQL
+SAFE_SUMMARY=$(printf '%s' "$SUMMARY" | sed "s/'/''/g")
+
+# Update session with summary and end time
+sqlite3 "$DB_PATH" \
+    "UPDATE sessions
+     SET summary = '${SAFE_SUMMARY}',
+         ended_at = datetime('now')
+     WHERE session_id = '${SAFE_SESSION_ID}';" 2>/dev/null || true
+
+# Auto-prune old observations and empty sessions
+sqlite3 "$DB_PATH" \
+    "DELETE FROM observations WHERE created_at < datetime('now', '-${RETENTION_DAYS} days');
+     DELETE FROM sessions WHERE session_id NOT IN (SELECT DISTINCT session_id FROM observations)
+       AND ended_at IS NOT NULL;
+     VACUUM;" 2>/dev/null || true
+
+exit 0

package/app/plugins/memory-pack/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "memory-pack",
+  "description": "Persistent memory across Claude Code sessions with SQLite storage, full-text search, and progressive disclosure",
+  "version": "1.0.0",
+  "domain": "memory",
+  "type": "plugin-pack",
+  "status": "experimental",
+  "requires": {
+    "ai-toolkit": ">=1.0.0",
+    "claude-code": ">=1.0.33"
+  },
+  "includes": {
+    "agents": [],
+    "skills": ["mem-search"],
+    "rules": [],
+    "hooks": ["observation-capture.sh", "session-summary.sh"]
+  },
+  "hook_events": {
+    "observation-capture.sh": "PostToolUse",
+    "session-summary.sh": "Stop"
+  }
+}

package/app/plugins/memory-pack/scripts/init_db.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Initialize SQLite memory database for ai-toolkit memory-pack.
+
+Creates ~/.ai-toolkit/memory.db with sessions, observations, and FTS5 tables.
+Safe to run multiple times (uses IF NOT EXISTS).
+
+Usage: python3 app/plugins/memory-pack/scripts/init_db.py
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+DB_DIR = Path.home() / ".ai-toolkit"
+DB_PATH = DB_DIR / "memory.db"
+
+SCHEMA = """
+-- Sessions table: one row per Claude Code session
+CREATE TABLE IF NOT EXISTS sessions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT UNIQUE NOT NULL,
+  project_dir TEXT,
+  started_at TEXT DEFAULT (datetime('now')),
+  ended_at TEXT,
+  summary TEXT
+);
+
+-- Observations table: captured tool actions within a session
+CREATE TABLE IF NOT EXISTS observations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  tool_name TEXT,
+  content TEXT NOT NULL,
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+-- Full-text search index on observations
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+  content,
+  tool_name,
+  content='observations',
+  content_rowid='id'
+);
+
+-- Trigger: keep FTS index in sync on INSERT
+CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+  INSERT INTO observations_fts(rowid, content, tool_name)
+  VALUES (new.id, new.content, new.tool_name);
+END;
+
+-- Trigger: keep FTS index in sync on DELETE
+CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, content, tool_name)
+  VALUES ('delete', old.id, old.content, old.tool_name);
+END;
+
+-- Trigger: keep FTS index in sync on UPDATE
+CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, content, tool_name)
+  VALUES ('delete', old.id, old.content, old.tool_name);
+  INSERT INTO observations_fts(rowid, content, tool_name)
+  VALUES (new.id, new.content, new.tool_name);
+END;
+"""
+
+
+def main() -> None:
+    DB_DIR.mkdir(parents=True, exist_ok=True)
+    existed = DB_PATH.is_file()
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.executescript(SCHEMA)
+    conn.close()
+    if existed:
+        print(f"memory-pack: database verified at {DB_PATH} (data preserved)")
+    else:
+        print(f"memory-pack: database created at {DB_PATH}")
+
+
+if __name__ == "__main__":
+    main()

package/app/plugins/memory-pack/scripts/strip_private.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""Remove <private>...</private> blocks from stdin.
+
+Used by observation-capture.sh to sanitize content before storage.
+Handles multi-line private blocks and nested angle brackets.
+
+Usage: echo "text <private>secret</private> more" | python3 strip_private.py
+"""
+from __future__ import annotations
+
+import re
+import sys
+
+
+def main() -> None:
+    content = sys.stdin.read()
+    cleaned = re.sub(r"<private>[^<]*</private>", "", content)
+    sys.stdout.write(cleaned)
+
+
+if __name__ == "__main__":
+    main()

package/app/plugins/memory-pack/skills/mem-search/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: mem-search
+description: "Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work."
+effort: medium
+argument-hint: "[search query]"
+allowed-tools: Bash, Read
+user-invocable: true
+---
+
+# Search Session Memory
+
+Search the persistent memory database for past coding observations, decisions, and context.
+
+$ARGUMENTS
+
+## How It Works
+
+This skill queries the SQLite FTS5 full-text search index at `~/.ai-toolkit/memory.db` to find relevant observations from past sessions.
+
+## Instructions
+
+1. **Parse the search query** from `$ARGUMENTS`. If empty, prompt the user for a query.
+
+2. **Initialize the database** if it does not exist:
+   ```bash
+   python3 "$HOME/.ai-toolkit/hooks/../plugins/memory-pack/scripts/init_db.py" 2>/dev/null || true
+   ```
+
+3. **Run the FTS5 search** against the observations table:
+   ```bash
+   sqlite3 ~/.ai-toolkit/memory.db "
+     SELECT o.id, o.session_id, o.tool_name, o.content, o.created_at,
+            s.project_dir, s.summary
+     FROM observations_fts fts
+     JOIN observations o ON o.id = fts.rowid
+     LEFT JOIN sessions s ON s.session_id = o.session_id
+     WHERE observations_fts MATCH '<query>'
+     ORDER BY rank
+     LIMIT 10;
+   "
+   ```
+   Replace `<query>` with the user's search terms. Escape single quotes by doubling them.
+
+4. **Progressive disclosure** -- present results in two stages:
+
+   **Stage 1: Summary view** (show first)
+   ```markdown
+   ## Memory Search: "<query>"
+
+   Found N results across M sessions.
+
+   | # | Session | Project | Tool | Time | Preview |
+   |---|---------|---------|------|------|---------|
+   | 1 | abc123  | /path   | Edit | 2025-01-15 | First 80 chars... |
+   ```
+
+   **Stage 2: Detail view** (on request)
+   Show the full observation content, session summary, and related observations from the same session.
+
+5. **If no results found**, suggest:
+   - Trying broader search terms
+   - Checking if memory-pack hooks are installed
+   - Running `init-db.sh` if the database is missing
+
+## Query Tips
+
+- Use simple keywords: `mem-search database migration`
+- FTS5 supports prefix matching: `migrat*` matches "migration", "migrate"
+- Boolean operators: `database AND NOT test`
+- Column filters: `tool_name:Edit` to search only Edit tool observations

package/app/plugins/research-pack/README.md

@@ -0,0 +1,14 @@
+# research-pack
+
+Curated research and synthesis pack.
+
+## Includes
+- Agents: `research-synthesizer`, `technical-researcher`, `fact-checker`, `search-specialist`
+- Skills: `/search`, `/docs`, `research-mastery`, `plan-writing`
+- Hooks: `user-prompt-submit.sh`
+
+## Use When
+- validating claims before implementation,
+- benchmarking external ecosystems,
+- writing architecture notes, audits, and synthesis reports.
+

package/app/plugins/research-pack/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "research-pack",
+  "description": "Domain plugin pack for research, synthesis, source validation, and benchmark-backed discovery.",
+  "version": "1.0.0",
+  "domain": "research",
+  "type": "plugin-pack",
+  "status": "experimental",
+  "requires": {
+    "ai-toolkit": ">=1.0.0",
+    "claude-code": ">=1.0.33"
+  },
+  "includes": {
+    "agents": ["research-synthesizer", "technical-researcher", "fact-checker", "search-specialist"],
+    "skills": ["search", "docs", "research-mastery", "plan-writing"],
+    "rules": [],
+    "hooks": ["user-prompt-submit.sh"]
+  },
+  "hook_events": {
+    "user-prompt-submit.sh": "UserPromptSubmit"
+  }
+}
+

package/app/plugins/ruby-pack/README.md

@@ -0,0 +1,11 @@
+# ruby-pack
+
+Curated Ruby development patterns pack.
+
+## Includes
+- Skills: `ruby-patterns`
+
+## Use When
+- writing Ruby code and need idiomatic patterns (blocks, modules, metaprogramming),
+- setting up new Rails or Sinatra projects,
+- reviewing Ruby code for RSpec, ActiveRecord, and performance best practices.

package/app/plugins/ruby-pack/plugin.json

@@ -0,0 +1,18 @@
+{
+    "name": "ruby-pack",
+    "description": "Domain plugin pack for Ruby development patterns and Rails conventions.",
+    "version": "1.0.0",
+    "domain": "ruby",
+    "type": "plugin-pack",
+    "status": "experimental",
+    "requires": {
+        "ai-toolkit": ">=1.0.0",
+        "claude-code": ">=1.0.33"
+    },
+    "includes": {
+        "agents": [],
+        "skills": ["ruby-patterns"],
+        "rules": [],
+        "hooks": []
+    }
+}

package/app/plugins/rust-pack/README.md

@@ -0,0 +1,11 @@
+# rust-pack
+
+Curated Rust development patterns pack.
+
+## Includes
+- Skills: `rust-patterns`
+
+## Use When
+- writing Rust code and need idiomatic patterns,
+- setting up new Rust projects with Cargo,
+- reviewing Rust code for ownership, borrowing, and lifetime best practices.

package/app/plugins/rust-pack/plugin.json

@@ -0,0 +1,18 @@
+{
+    "name": "rust-pack",
+    "description": "Domain plugin pack for Rust development patterns and idiomatic conventions.",
+    "version": "1.0.0",
+    "domain": "rust",
+    "type": "plugin-pack",
+    "status": "experimental",
+    "requires": {
+        "ai-toolkit": ">=1.0.0",
+        "claude-code": ">=1.0.33"
+    },
+    "includes": {
+        "agents": [],
+        "skills": ["rust-patterns"],
+        "rules": [],
+        "hooks": []
+    }
+}

package/app/plugins/security-pack/README.md

@@ -0,0 +1,15 @@
+# security-pack
+
+Curated security-focused plugin pack.
+
+## Includes
+- Agents: `security-auditor`, `security-architect`, `code-reviewer`
+- Skills: `/review`, `security-patterns`, `/panic`
+- Rules: `quality-gates`
+- Hooks: `guard-destructive.sh`, `guard-path.sh`, `quality-gate.sh`
+
+## Use When
+- running security audits,
+- reviewing authentication / authorization changes,
+- hardening deployments and operational workflows.
+

package/app/plugins/security-pack/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "security-pack",
+  "description": "Domain plugin pack for secure coding, architecture review, and hardening workflows.",
+  "version": "1.0.0",
+  "domain": "security",
+  "type": "plugin-pack",
+  "status": "experimental",
+  "requires": {
+    "ai-toolkit": ">=1.0.0",
+    "claude-code": ">=1.0.33"
+  },
+  "includes": {
+    "agents": ["security-auditor", "security-architect", "code-reviewer"],
+    "skills": ["review", "security-patterns", "panic"],
+    "rules": ["quality-gates"],
+    "hooks": ["guard-destructive.sh", "quality-gate.sh"]
+  },
+  "hook_events": {
+    "guard-destructive.sh": "PreToolUse",
+    "quality-gate.sh": "TaskCompleted"
+  }
+}
+

package/app/plugins/swift-pack/README.md

@@ -0,0 +1,11 @@
+# swift-pack
+
+Curated Swift and iOS development patterns pack.
+
+## Includes
+- Skills: `swift-patterns`
+
+## Use When
+- writing Swift code and need idiomatic patterns (protocol-oriented, optionals, concurrency),
+- setting up new Swift Package Manager or Xcode projects,
+- reviewing Swift code for SwiftUI, async/await, and actor isolation best practices.

package/app/plugins/swift-pack/plugin.json

@@ -0,0 +1,18 @@
+{
+    "name": "swift-pack",
+    "description": "Domain plugin pack for Swift and iOS development patterns.",
+    "version": "1.0.0",
+    "domain": "swift",
+    "type": "plugin-pack",
+    "status": "experimental",
+    "requires": {
+        "ai-toolkit": ">=1.0.0",
+        "claude-code": ">=1.0.33"
+    },
+    "includes": {
+        "agents": [],
+        "skills": ["swift-patterns"],
+        "rules": [],
+        "hooks": []
+    }
+}

package/app/rules/claude-toolkit-rules.md

@@ -0,0 +1,21 @@
+# Claude Toolkit
+
+Shared AI development toolkit — 85 skills, 47 agents, lifecycle hooks, safety constitution.
+
+## Skill Tiers
+
+- **Tier 1** — single-agent: `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/triage-issue`
+- **Tier 1.5** — planning: `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues`; design: `/design-an-interface`, `/architecture-audit`, `/refactor-plan`
+- **Tier 2** — multi-agent: `/workflow <type>` (feature-development, backend-feature, frontend-feature, api-design, database-evolution, test-coverage, security-audit, debugging, incident-response, spike, codebase-onboarding, performance-optimization, infrastructure-change, application-deploy, proactive-troubleshooting)
+- **Tier 3** — custom: `/orchestrate <desc>` (3–6 agents) | `/swarm <mode> <desc>` (map-reduce | consensus | relay)
+
+## Path Safety
+- NEVER guess or hallucinate user home directory paths
+- Use `~` or `$HOME` instead of hardcoded `/Users/<username>/` or `/home/<username>/`
+- When an absolute path is needed, run `echo $HOME` first to get the correct value
+
+## User Preferences
+
+- **Style:** Direct & efficient. No pleasantries. Measurable results.
+- **Methodology:** Provide >=3 alternatives. Use Socratic questioning.
+- **Review:** Apply "Devil's Advocate" critique to decisions.

package/app/rules/git-conventions.md

@@ -0,0 +1,5 @@
+# Git Conventions
+
+- Do NOT add `Co-Authored-By: Claude` or any AI co-authorship to commits
+- Do NOT add Claude signatures or attribution to commit messages
+- Conventional commits format: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`

package/app/rules/quality-gates.md

@@ -0,0 +1,10 @@
+# Quality Gates & Mandatory Practices
+
+## MANDATORY PRACTICES
+1.  **Plan First:** Tasks >1h require Plan, Success Criteria, and Pre-Mortem.
+2.  **Quality Gates:**
+    *   `ruff check .` (0 errors)
+    *   `mypy --strict src/` (0 errors)
+    *   `pytest --cov=src` (>70% coverage)
+    *   **Type Safety:** 100% public APIs, >60% internal.
+3.  **Security:** No secrets in code, sanitization, auth z/n.

package/app/skills/_lib/__init__.py

@@ -0,0 +1 @@
+# Shared utilities for skill detection scripts.