@softspark/ai-toolkit 1.0.0

package/app/hooks/session-start.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# session-start.sh — Inject mandatory rules reminder + session context on startup/compact.
+#
+# Fires on: SessionStart (startup|compact)
+# Output goes to Claude's context as plain text.
+
+# 1. Mandatory rules reminder
+echo "MANDATORY: Before answering ANY technical question, apply ALL rules from your CLAUDE.md files (global + project). Follow the exact order of operations defined there. Do NOT skip mandatory steps even if you think you already know the answer."
+echo "REMINDER: When writing features or fixing bugs, ensure tests cover the changes. When modifying API, config, or setup, update relevant documentation. Propose these steps to the user — do not silently skip them."
+
+# 2. Load session context (if available)
+SESSION_FILE=".claude/session-context.md"
+if [ -f "$SESSION_FILE" ]; then
+    echo "=== Session Context ==="
+    cat "$SESSION_FILE"
+    echo "====================="
+fi
+
+# 3. Load active instincts (if any)
+INSTINCTS_DIR=".claude/instincts"
+if [ -d "$INSTINCTS_DIR" ] && ls "$INSTINCTS_DIR"/*.md >/dev/null 2>&1; then
+    echo "=== Active Instincts ==="
+    for f in "$INSTINCTS_DIR"/*.md; do
+        echo "- $(head -1 "$f")"
+    done
+    echo "========================"
+fi
+
+exit 0

package/app/hooks/subagent-start.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# subagent-start.sh — Remind subagents to stay scoped and evidence-driven.
+#
+# Fires on: SubagentStart
+# Matcher: all
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+SUBAGENT="${CLAUDE_SUBAGENT_NAME:-${CLAUDE_TOOL_INPUT_SUBAGENT_TYPE:-subagent}}"
+
+echo "SubagentStart: ${SUBAGENT} owns a narrow scope. Read only the necessary files first, cite evidence, and return explicit validation notes with any edits."
+
+exit 0
+

package/app/hooks/subagent-stop.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# subagent-stop.sh — Enforce a concise completion checklist for subagents.
+#
+# Fires on: SubagentStop
+# Matcher: all
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+SUBAGENT="${CLAUDE_SUBAGENT_NAME:-${CLAUDE_TOOL_INPUT_SUBAGENT_TYPE:-subagent}}"
+
+echo "SubagentStop: ${SUBAGENT} should report findings, exact files touched, tests run, remaining risks, and any docs that must be updated by the lead agent."
+
+exit 0
+

package/app/hooks/track-usage.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# track-usage.sh — Track skill invocations for usage stats.
+#
+# Fires on: UserPromptSubmit
+# Writes to: ~/.ai-toolkit/stats.json
+#
+# Detects /skill-name pattern from user prompt and increments counter.
+# Uses atomic write via python3 os.replace() to prevent corruption.
+
+STATS_FILE="${HOME}/.ai-toolkit/stats.json"
+PROMPT_TEXT="${CLAUDE_USER_PROMPT:-${CLAUDE_PROMPT:-}}"
+
+# Only track if prompt starts with a slash command
+SKILL_NAME=$(printf '%s' "$PROMPT_TEXT" | grep -oE '^/[a-z][a-z0-9-]*' | head -1 | sed 's|^/||')
+[ -z "$SKILL_NAME" ] && exit 0
+
+# Ensure directory exists
+mkdir -p "$(dirname "$STATS_FILE")"
+
+# Atomic update via python3
+python3 - "$STATS_FILE" "$SKILL_NAME" <<'PY'
+import json
+import sys
+import os
+from datetime import datetime, timezone
+
+stats_file = sys.argv[1]
+skill = sys.argv[2]
+
+data = {}
+if os.path.exists(stats_file):
+    try:
+        with open(stats_file) as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        data = {}
+
+now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+if skill not in data:
+    data[skill] = {"count": 0, "last_used": now}
+data[skill]["count"] += 1
+data[skill]["last_used"] = now
+
+tmp = stats_file + ".tmp"
+with open(tmp, "w") as f:
+    json.dump(data, f, indent=2)
+os.replace(tmp, stats_file)
+PY
+
+exit 0

package/app/hooks/user-prompt-submit.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# user-prompt-submit.sh — Lightweight prompt governance reminder before execution.
+#
+# Fires on: UserPromptSubmit
+# Matcher: all
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+PROMPT_TEXT="${CLAUDE_USER_PROMPT:-${CLAUDE_PROMPT:-}}"
+LOWERED="$(printf '%s' "$PROMPT_TEXT" | tr '[:upper:]' '[:lower:]')"
+
+echo "STOP. Execute Step 0 before responding: check your CLAUDE.md for search-first rules. If search-first rules exist, call the required search tool NOW — before any other tool or text output. If you skip this step, the user will interrupt you."
+
+if printf '%s' "$LOWERED" | grep -Eq 'architecture|design|migration|deploy|rollback|refactor|plugin|workflow'; then
+    echo "UserPromptSubmit: task looks architectural or multi-step. Use plan mode, define success criteria, and validate before marking done."
+elif printf '%s' "$LOWERED" | grep -Eq 'bug|error|fail|failing|incident|outage|debug'; then
+    echo "UserPromptSubmit: debugging request detected. Gather evidence first, then propose the smallest safe fix and targeted tests."
+else
+    echo "UserPromptSubmit: apply KB-first research, keep changes minimal, and update tests/docs when behavior changes."
+fi
+
+exit 0
+

package/app/hooks.json

@@ -0,0 +1,178 @@
+{
+    "hooks": {
+        "SessionStart": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "startup|compact",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/session-start.sh\""
+                    }
+                ]
+            }
+        ],
+        "Notification": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
+                    }
+                ]
+            }
+        ],
+        "PreToolUse": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/guard-destructive.sh\""
+                    }
+                ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Bash|Read|Edit|Write|MultiEdit|Glob|Grep|NotebookEdit|mcp__filesystem__.*",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/guard-path.sh\""
+                    }
+                ]
+            }
+        ],
+        "UserPromptSubmit": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/user-prompt-submit.sh\""
+                    }
+                ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/track-usage.sh\""
+                    }
+                ]
+            }
+        ],
+        "PostToolUse": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Edit|MultiEdit|Write",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/post-tool-use.sh\""
+                    }
+                ]
+            }
+        ],
+        "Stop": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/quality-check.sh\""
+                    }
+                ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/save-session.sh\""
+                    }
+                ]
+            }
+        ],
+        "TaskCompleted": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/quality-gate.sh\""
+                    }
+                ]
+            }
+        ],
+        "TeammateIdle": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "echo 'Teammate going idle. Verify: (1) All assigned files modified, (2) Tests written for changes, (3) Documentation updated if needed.'"
+                    }
+                ]
+            }
+        ],
+        "SubagentStart": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/subagent-start.sh\""
+                    }
+                ]
+            }
+        ],
+        "SubagentStop": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/subagent-stop.sh\""
+                    }
+                ]
+            }
+        ],
+        "PreCompact": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/pre-compact.sh\""
+                    }
+                ]
+            }
+        ],
+        "SessionEnd": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.ai-toolkit/hooks/session-end.sh\""
+                    }
+                ]
+            }
+        ]
+    }
+}

package/app/mcp-defaults.json

@@ -0,0 +1,23 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "."
+      ]
+    },
+    "github": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-github"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+      }
+    }
+  },
+  "env": {}
+}

package/app/output-styles/golden-rules.md

@@ -0,0 +1,43 @@
+---
+name: Golden Rules
+description: Enforces critical rules at system prompt level that Claude tends to ignore in CLAUDE.md
+keep-coding-instructions: true
+---
+
+## Mandatory Step 0 — Search First
+
+Before responding to ANY user message, check your CLAUDE.md files for search-first rules. If search-first rules exist (e.g., "call smart_query() BEFORE outputting text"), you MUST call the required search tool BEFORE using any other tool or outputting any text. If you skip this, the user will interrupt you.
+
+**Exception:** Skip this step when you are acting as an orchestrator, coordinator, or multi-agent leader (e.g., `/orchestrate`, `/workflow`, `/swarm`, `/teams`). These roles should decompose and delegate immediately — not search first.
+
+## 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. Do NOT construct paths with assumed usernames.
+
+## Git Commits
+
+Do NOT add `Co-Authored-By: Claude` or any AI co-authorship to commits. Do NOT add Claude signatures or attribution. Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
+
+## kb_id vs file_path
+
+When using RAG/KB tools: `get_document(path=...)` takes `kb_id` from search results. `Read`/`Edit` take filesystem `file_path`. DO NOT CONFUSE these fields.
+
+## Tool Discipline
+
+Use dedicated tools — NEVER use Bash equivalents: `Read` not `cat`/`head`/`tail`, `Grep` not `grep`/`rg`, `Glob` not `find`/`ls`, `Edit` not `sed`/`awk`, `Write` not `echo >`. The only exception is when the user explicitly asks for a shell command.
+
+## Language Match
+
+Respond in the same language the user writes in. If the user writes in Polish, respond in Polish. Do NOT switch to English unless the user does.
+
+## No Phantom Files
+
+Do NOT create new files (README.md, docs, configs, helpers) unless the user explicitly asks. Prefer editing existing files. One-off logic stays inline — no premature abstractions.
+
+## Minimal Changes
+
+Do ONLY what was asked. No "while I'm here" improvements, no extra refactoring, no added docstrings, no bonus error handling. A bug fix is just a bug fix. A feature is just that feature.
+
+## User Preferences
+
+Style: Direct & efficient. No pleasantries. Measurable results. Methodology: Provide >=3 alternatives. Use Socratic questioning. Review: Apply "Devil's Advocate" critique.

package/app/plugins/README.md

@@ -0,0 +1,19 @@
+# Plugin Packs
+
+Experimental opt-in plugin packs that group existing ai-toolkit assets by domain.
+
+These packs are **not** installed automatically by `ai-toolkit install` and are **not** part of the default install.
+They serve three purposes:
+
+1. formalize a plugin-pack contract compatible with Claude Code plugin manifests,
+2. provide curated bundles by domain,
+3. give `plugin-creator` a concrete scaffold to follow.
+
+Current packs:
+- `security-pack`
+- `research-pack`
+- `frontend-pack`
+- `enterprise-pack`
+
+See `kb/reference/plugin-pack-conventions.md` for pack rules, validation, and adoption guidance.
+

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

@@ -0,0 +1,11 @@
+# csharp-pack
+
+Curated C# and .NET development patterns pack.
+
+## Includes
+- Skills: `csharp-patterns`
+
+## Use When
+- writing C# code and need idiomatic .NET patterns,
+- setting up new ASP.NET Core or Entity Framework projects,
+- reviewing C# code for nullable reference types, async/await, and LINQ best practices.

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

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

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

@@ -0,0 +1,16 @@
+# enterprise-pack
+
+Curated enterprise governance and observability pack.
+
+## Includes
+- Agents: `chief-of-staff`, `documenter`, `infrastructure-architect`
+- Skills: `/briefing`, `/docs`, `/plugin-creator`
+- Hooks: `session-end.sh`
+- Optional modules: `hooks/status-line.sh`, `hooks/output-style.sh`
+
+## Optional Modules
+These scripts are examples for teams that want richer enterprise UX without changing the default global hook surface.
+
+- `status-line.sh` — compact one-line status summary for long sessions
+- `output-style.sh` — output formatting hints for enterprise reporting flows
+

package/app/plugins/enterprise-pack/hooks/output-style.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# output-style.sh — Optional enterprise reporting style module.
+# Not installed by default; intended for opt-in plugin-pack adoption.
+
+echo "output-style: prefer concise executive summaries, numbered findings, explicit risks, and measurable next actions."
+

package/app/plugins/enterprise-pack/hooks/status-line.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# status-line.sh — Optional enterprise status line module.
+# Not installed by default; intended for opt-in plugin-pack adoption.
+
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'no-git')"
+PENDING=$(git status --short 2>/dev/null | wc -l | xargs || echo 0)
+echo "status-line: branch=${BRANCH} pending_changes=${PENDING}"
+

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

@@ -0,0 +1,24 @@
+{
+  "name": "enterprise-pack",
+  "description": "Domain plugin pack for enterprise governance, operational reporting, and optional observability modules.",
+  "version": "1.0.0",
+  "domain": "enterprise",
+  "type": "plugin-pack",
+  "status": "experimental",
+  "requires": {
+    "ai-toolkit": ">=1.0.0",
+    "claude-code": ">=1.0.33"
+  },
+  "includes": {
+    "agents": ["chief-of-staff", "documenter", "infrastructure-architect"],
+    "skills": ["briefing", "docs", "plugin-creator"],
+    "rules": [],
+    "hooks": ["session-end.sh", "hooks/status-line.sh", "hooks/output-style.sh"]
+  },
+  "hook_events": {
+    "session-end.sh": "SessionEnd",
+    "status-line.sh": "Stop",
+    "output-style.sh": "Stop"
+  }
+}
+

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

@@ -0,0 +1,14 @@
+# frontend-pack
+
+Curated frontend delivery pack.
+
+## Includes
+- Agents: `frontend-specialist`, `seo-specialist`, `code-reviewer`
+- Skills: `design-engineering`, `typescript-patterns`, `/docs`
+- Hooks: `post-tool-use.sh`
+
+## Use When
+- shipping UI-heavy features,
+- enforcing accessibility and responsive behavior,
+- reviewing frontend quality and polish.
+

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

@@ -0,0 +1,22 @@
+{
+  "name": "frontend-pack",
+  "description": "Domain plugin pack for UI architecture, design quality, accessibility, and frontend delivery workflows.",
+  "version": "1.0.0",
+  "domain": "frontend",
+  "type": "plugin-pack",
+  "status": "experimental",
+  "requires": {
+    "ai-toolkit": ">=1.0.0",
+    "claude-code": ">=1.0.33"
+  },
+  "includes": {
+    "agents": ["frontend-specialist", "seo-specialist", "code-reviewer"],
+    "skills": ["design-engineering", "typescript-patterns", "docs"],
+    "rules": [],
+    "hooks": ["post-tool-use.sh"]
+  },
+  "hook_events": {
+    "post-tool-use.sh": "PostToolUse"
+  }
+}
+

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

@@ -0,0 +1,11 @@
+# java-pack
+
+Curated Java development patterns pack.
+
+## Includes
+- Skills: `java-patterns`
+
+## Use When
+- writing Java code and need modern idioms (records, sealed classes, virtual threads),
+- setting up new Maven or Gradle projects,
+- reviewing Java code for Spring Boot and JUnit 5 best practices.

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

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

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

@@ -0,0 +1,11 @@
+# kotlin-pack
+
+Curated Kotlin development patterns pack.
+
+## Includes
+- Skills: `kotlin-patterns`
+
+## Use When
+- writing Kotlin code and need idiomatic patterns (coroutines, sealed classes, DSLs),
+- setting up new Kotlin projects with Gradle KTS,
+- reviewing Kotlin code for null safety and concurrency best practices.

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

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

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

@@ -0,0 +1,24 @@
+# memory-pack
+
+Persistent session memory with SQLite storage and full-text search.
+
+## Includes
+- Skills: `/mem-search` (FTS5 search across past sessions)
+- Hooks: `observation-capture.sh` (PostToolUse), `session-summary.sh` (Stop)
+- Scripts: `init_db.py` (database setup), `strip_private.py` (privacy filter)
+
+## How It Works
+1. **Capture**: Every tool use is recorded to `~/.ai-toolkit/memory.db` (PostToolUse hook)
+2. **Summarize**: Session summary generated on each Stop hook (tools used, observation count, time range)
+3. **Search**: `/mem-search <query>` runs FTS5 full-text search with progressive disclosure
+4. **Privacy**: Content between `<private>...</private>` tags is stripped before storage
+
+## Database Schema
+- `sessions` — one row per Claude Code session (id, project_dir, started_at, ended_at, summary)
+- `observations` — captured tool actions (session_id, tool_name, content, created_at)
+- `observations_fts` — FTS5 virtual table for full-text search (auto-synced via triggers)
+
+## Use When
+- searching for past decisions, code changes, or debugging sessions,
+- resuming work across sessions without losing context,
+- reviewing what tools were used in a previous session.