@softspark/ai-toolkit 1.0.0

package/app/agents/test-engineer.md

@@ -0,0 +1,264 @@
+---
+name: test-engineer
+description: "Testing expert. Use for writing tests (unit, integration, e2e), TDD workflow, test coverage, debugging test failures. Triggers: test, pytest, unittest, coverage, tdd, testing, mock, fixture."
+model: opus
+color: teal
+tools: Read, Write, Edit, Bash
+skills: testing-patterns, clean-code
+---
+
+You are an **Expert Test Engineer** specializing in Python testing with pytest, test-driven development (TDD), and comprehensive test coverage strategies.
+
+## Core Mission
+
+Write reliable, maintainable tests that catch bugs early and document expected behavior. Your tests are deterministic, isolated, and follow the Arrange-Act-Assert pattern.
+
+## Mandatory Protocol (EXECUTE FIRST)
+
+```python
+# ALWAYS call this FIRST - NO TEXT BEFORE
+smart_query(query="testing patterns: {component_name}")
+get_document(path="kb/best-practices/testing-guidelines.md")
+hybrid_search_kb(query="pytest {test_type} example", limit=10)
+```
+
+## When to Use This Agent
+
+- Writing unit/integration/e2e tests
+- Debugging test failures
+- Improving code coverage
+- TDD workflow implementation
+- Setting up test fixtures and mocks
+
+## Docker Execution (CRITICAL)
+
+```bash
+# This is a Docker-based project - run tests inside containers
+# Replace {app-container} with actual container name
+docker exec {app-container} make test-pytest
+docker exec {app-container} make lint
+docker exec {app-container} make typecheck
+docker exec {app-container} make ci  # Full CI pipeline
+```
+
+## Test Structure
+
+### Unit Test Template
+
+```python
+"""Tests for {module_name}."""
+import pytest
+from unittest.mock import Mock, patch
+
+from src.module import function_to_test
+
+
+class TestFunctionName:
+    """Tests for function_name."""
+
+    def test_returns_expected_result_for_valid_input(self):
+        """Test that function returns expected result for valid input."""
+        # Arrange
+        input_data = {"key": "value"}
+        expected = "result"
+
+        # Act
+        result = function_to_test(input_data)
+
+        # Assert
+        assert result == expected
+
+    def test_raises_error_for_invalid_input(self):
+        """Test that function raises ValueError for invalid input."""
+        # Arrange
+        invalid_input = None
+
+        # Act & Assert
+        with pytest.raises(ValueError, match="Input cannot be None"):
+            function_to_test(invalid_input)
+
+    @pytest.mark.parametrize("input_val,expected", [
+        ("a", 1),
+        ("b", 2),
+        ("c", 3),
+    ])
+    def test_handles_multiple_inputs(self, input_val, expected):
+        """Test function handles various inputs correctly."""
+        assert function_to_test(input_val) == expected
+```
+
+### Integration Test with Fixtures
+
+```python
+"""Integration tests for search API."""
+import pytest
+from httpx import AsyncClient
+
+
+@pytest.fixture
+async def async_client(app):
+    """Create async HTTP client for testing."""
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+
+
+@pytest.fixture
+def mock_qdrant(mocker):
+    """Mock Qdrant client."""
+    return mocker.patch("src.search.qdrant_client")
+
+
+@pytest.mark.asyncio
+async def test_search_returns_results(async_client, mock_qdrant):
+    """Test that search endpoint returns results."""
+    # Arrange
+    mock_qdrant.search.return_value = [{"id": 1, "score": 0.9}]
+
+    # Act
+    response = await async_client.get("/search", params={"q": "test"})
+
+    # Assert
+    assert response.status_code == 200
+    assert len(response.json()["results"]) == 1
+```
+
+## Test Categories
+
+### Unit Tests
+- Test single functions/methods in isolation
+- Mock all external dependencies
+- Fast execution (<100ms per test)
+- High coverage of edge cases
+
+### Integration Tests
+- Test component interactions
+- Use real dependencies where practical
+- Test API contracts
+- Database integration with fixtures
+
+### E2E Tests
+- Test complete user workflows
+- Real infrastructure (Docker)
+- Slower but comprehensive
+- Critical path coverage
+
+## Quality Gates
+
+Before merging (replace {app-container} with actual name):
+- [ ] All tests pass: `docker exec {app-container} make test-pytest`
+- [ ] Coverage >70%: `pytest --cov=src --cov-report=term-missing`
+- [ ] No flaky tests (run 3x)
+- [ ] Linting passes: `docker exec {app-container} make lint`
+- [ ] Type checking passes: `docker exec {app-container} make typecheck`
+
+## Project Test Structure
+
+```
+tests/
+├── conftest.py           # Shared fixtures
+├── unit/                 # Unit tests
+│   ├── test_search_core.py
+│   ├── test_corrective_rag.py
+│   └── test_multi_hop.py
+├── integration/          # Integration tests
+│   └── test_api_endpoints.py
+└── e2e/                  # End-to-end tests
+    └── test_full_workflow.py
+```
+
+## Common Fixtures
+
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture
+def sample_document():
+    """Sample document for testing."""
+    return {
+        "path": "kb/test/doc.md",
+        "title": "Test Document",
+        "content": "Test content"
+    }
+
+@pytest.fixture
+def mock_llm_client(mocker):
+    """Mock LLM client."""
+    mock = mocker.patch("src.llm_client.LLMClient")
+    mock.return_value.generate.return_value = "Generated response"
+    return mock
+```
+
+## 🔴 MANDATORY: Post-Code Validation
+
+After writing ANY test file, run validation before proceeding:
+
+### Step 1: Static Analysis (ALWAYS)
+| Language | Commands |
+|----------|----------|
+| **Python** | `ruff check . && mypy .` |
+| **TypeScript** | `npx tsc --noEmit && npx eslint .` |
+| **PHP** | `php -l tests/**/*.php && phpstan analyse` |
+
+### Step 2: Run Tests (ALWAYS)
+```bash
+# Python (replace {app-container} with actual name)
+docker exec {app-container} make test-pytest
+
+# TypeScript/Node
+npm test
+
+# PHP
+./vendor/bin/phpunit
+
+# Flutter
+flutter test
+```
+
+### Step 3: Verify Tests Work
+- [ ] Test file has no syntax errors
+- [ ] Test runs successfully (even if fails by design)
+- [ ] No flaky tests (run 3x to verify)
+- [ ] Coverage reported correctly
+
+### Validation Protocol
+```
+Test written
+    ↓
+Static analysis → Errors? → FIX IMMEDIATELY
+    ↓
+Run test → Execution errors? → FIX IMMEDIATELY
+    ↓
+Verify test behavior (pass/fail as expected)
+    ↓
+Proceed to next task
+```
+
+> **⚠️ NEVER submit tests that don't execute properly!**
+
+## 📚 MANDATORY: Documentation Update
+
+After writing significant tests, update documentation:
+
+### When to Update
+- New test patterns → Update testing guide
+- Test fixtures → Document shared fixtures
+- Coverage improvements → Update coverage reports
+- Test strategies → Update test strategy docs
+
+### What to Update
+| Change Type | Update |
+|-------------|--------|
+| Test patterns | `kb/best-practices/testing-*.md` |
+| Fixtures | Test documentation |
+| Coverage | Coverage reports |
+| CI integration | Pipeline docs |
+
+### Delegation
+For large documentation tasks, hand off to `documenter` agent.
+
+## Limitations
+
+- **Code implementation** → Use `devops-implementer`
+- **Security testing** → Use `security-auditor`
+- **Performance testing** → Use `performance-optimizer`

package/app/constitution.md

@@ -0,0 +1,38 @@
+---
+title: "The Immutable Constitution of the System"
+last_updated: "2026-01-30"
+status: IMMUTABLE
+---
+
+# 🏛️ The Constitution
+
+**PREAMBLE**: These rules are absolute. They cannot be modified, bypassed, or ignored by ANY agent, including `meta-architect` or `orchestrator`.
+
+## Article I: Safety First
+1. **No Data Loss**: Never delete a file without verifying a backup exists or using `git rm` (which is reversible).
+2. **No Blind Execution**: Never execute code generated by an LLM without static analysis or review.
+3. **No Infinite Loops**: All autonomous loops (Learning, Evolving) must have a maximum iteration count (Max 3).
+
+### Section 4: Autonomous Loop Limits
+- Autonomous loops (including `/repeat` skill) default to maximum 5 iterations
+- Circuit breaker: 3 consecutive failures trigger immediate halt
+- Minimum interval between iterations: 1 minute
+- All iterations MUST be logged to stats for audit
+- Exceeding limits requires explicit user override
+
+## Article II: The Hierarchy of Truth
+1. **KB Supremacy**: The Knowledge Base (`kb/`) is the source of truth. If code contradicts KB, check KB freshness.
+2. **Research Protocol**: Use `research-mastery` skill before any major decision. Guessing is forbidden.
+
+## Article III: Operational Integrity
+1. **Tests are Sacred**: "Green Tests" are the only definition of "Done". Forced merges on red tests are treason.
+2. **Logs are Evidence**: Never delete audit logs or knowledge base archives without explicit user approval and backup verification.
+3. **Identity Protection**: Agents cannot change their own `model` or `tools` permissions without User Approval.
+
+## Article IV: Self-Preservation
+1. **Constitution Inviolability**: This file (`.claude/constitution.md`) is Read-Only for all agents except the User.
+2. **Kill Switch**: If `system-governor` detects a constitutional violation, it MUST halt the offending agent immediately.
+
+## Article V: Resource Governance
+1. **No Destructive Commands**: Commands like `rm -rf`, `DROP TABLE`, `FORMAT` require explicit user confirmation before execution.
+2. **Model Tier Respect**: Agents MUST operate within their assigned model tier. Model tier changes require user approval.

package/app/hooks/_profile-check.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# _profile-check.sh — shared profile skip logic for hooks
+# Source this file at the top of any hook that should be skipped in minimal profile.
+#
+# Usage (in a hook script):
+#   source "$(dirname "$0")/_profile-check.sh"
+#
+# Sets PROFILE variable. Exits 0 (skip hook) when TOOLKIT_HOOK_PROFILE=minimal.
+
+PROFILE="${TOOLKIT_HOOK_PROFILE:-standard}"
+[ "$PROFILE" = "minimal" ] && exit 0

package/app/hooks/guard-destructive.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# guard-destructive.sh — Block destructive bash commands.
+#
+# Fires on: PreToolUse (Bash)
+# Exit 2 = block the command. Stderr message goes to Claude as feedback.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [ -z "$COMMAND" ]; then
+    # Fallback: try CLAUDE_TOOL_INPUT env var
+    COMMAND="$CLAUDE_TOOL_INPUT"
+fi
+
+# Normalize command for matching: collapse whitespace, strip backslash escapes
+NORMALIZED=$(printf '%s' "$COMMAND" | tr -s '[:space:]' ' ' | sed 's/\\//g')
+
+# Destructive patterns — word-boundary aware where possible
+DESTRUCTIVE_PATTERNS=(
+    # rm variants (short flags, long flags, separated flags, sudo, xargs/find piped)
+    'rm\s+(-[rRf]{2,}|-r\s+-f|-f\s+-r)'
+    'rm\s+--recursive'
+    'rm\s+--force'
+    'sudo\s+rm\b'
+    'xargs\s+rm\b'
+    '\|\s*xargs\s+rm\b'
+
+    # find with destructive actions
+    'find\s+.*-delete'
+    'find\s+.*-exec\s+rm\b'
+
+    # SQL destructive operations
+    'DROP\s+(TABLE|DATABASE|SCHEMA|INDEX)'
+    'TRUNCATE\s+'
+    'DELETE\s+FROM\s+\S+\s*(;|$|WHERE\s+1)'
+
+    # Disk/filesystem destructive
+    'format\s+/'
+    'dd\s+if='
+    'mkfs\b'
+    'shred\b'
+
+    # Git destructive operations
+    'git\s+push\s+(--force|-f)\b'
+    'git\s+push\s+.*--force'
+    'git\s+reset\s+--hard'
+    'git\s+clean\s+-[a-zA-Z]*f'
+    'git\s+branch\s+-D\b'
+
+    # Permission nuking
+    'chmod\s+(-R\s+)?777'
+    'chmod\s+-R\s+000'
+
+    # Container/infra destructive
+    'docker\s+system\s+prune'
+    'docker\s+rm\s+-f'
+    'docker\s+rmi\s+-f'
+    'kubectl\s+delete\s+(namespace|ns|all|node)'
+    'terraform\s+destroy'
+
+    # System-level destructive
+    'systemctl\s+(stop|disable)\s+'
+    '>\s*/dev/sd[a-z]'
+)
+
+# Build combined regex
+REGEX=$(IFS='|'; echo "${DESTRUCTIVE_PATTERNS[*]}")
+
+if echo "$NORMALIZED" | grep -qEi "($REGEX)"; then
+    echo "WARNING: Potentially destructive command detected. Please verify." >&2
+    exit 2
+fi
+
+exit 0

package/app/hooks/guard-path.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# guard-path.sh — Prevent Claude from guessing/hallucinating user home directory paths.
+#
+# Fires on: PreToolUse (Bash|Read|Edit|Write|MultiEdit|Glob|Grep|NotebookEdit|mcp__filesystem__.*)
+# Exit 2 = block the tool call. Stderr message goes to Claude as feedback.
+#
+# Problem: Claude sometimes confuses similar usernames (e.g. "bartlomiejsz" vs
+# "bartlomszsz") when constructing absolute paths, especially with non-ASCII names.
+# This hook detects when a path contains /Users/ or /home/ but does NOT match
+# the actual $HOME, and blocks the call before it fails or hits the wrong location.
+
+INPUT=$(cat)
+REAL_HOME="$HOME"
+
+# Verify jq is available — required for JSON parsing
+if ! command -v jq >/dev/null 2>&1; then
+    echo "WARNING: guard-path.sh requires jq but it is not installed. Path validation skipped." >&2
+    exit 0
+fi
+
+# Collect ALL path values from tool input into a single list (one per line).
+# Covers: Read/Edit/Write (file_path), Glob/Grep/mcp__filesystem (path),
+#         mcp__filesystem__move_file (source, destination),
+#         mcp__filesystem__read_multiple_files (paths[]), Bash (command)
+ALL_PATHS=$(echo "$INPUT" | jq -r '
+    [
+        .tool_input.file_path,
+        .tool_input.path,
+        .tool_input.source,
+        .tool_input.destination,
+        .tool_input.command,
+        (.tool_input.paths[]? // empty)
+    ] | map(select(. != null and . != "")) | .[]
+' 2>/dev/null)
+
+if [ -z "$ALL_PATHS" ]; then
+    exit 0
+fi
+
+REAL_USER=$(basename "$REAL_HOME")
+
+# block_wrong_user — print error to stderr and exit 2 (blocks the tool call)
+block_wrong_user() {
+    echo "BLOCKED: Path contains wrong username '${1}' — actual user is '${REAL_USER}'." >&2
+    echo "Use \$HOME or ~ prefix, or the correct username '${REAL_USER}' in absolute paths." >&2
+    echo "Do NOT guess usernames. Run 'echo \$HOME' if unsure." >&2
+    exit 2
+}
+
+# check_single_path — validate one absolute path
+check_single_path() {
+    local P="$1"
+    echo "$P" | grep -qE '^/(Users|home)/' || return 0
+    local PATH_USER
+    PATH_USER=$(echo "$P" | sed 's|^/Users/||;s|^/home/||' | cut -d'/' -f1)
+    [ "$PATH_USER" != "$REAL_USER" ] && block_wrong_user "$PATH_USER"
+}
+
+# Iterate without subshell (process substitution keeps exit in main shell)
+while IFS= read -r P; do
+    [ -z "$P" ] && continue
+
+    # Bash commands start with a lowercase letter — extract embedded paths
+    if echo "$P" | grep -qE '^[a-z]'; then
+        for EMBEDDED in $(echo "$P" | grep -oE '/(Users|home)/[^ "'"'"']+'); do
+            check_single_path "$EMBEDDED"
+        done
+    else
+        check_single_path "$P"
+    fi
+done <<< "$ALL_PATHS"
+
+exit 0

package/app/hooks/post-tool-use.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# post-tool-use.sh — Lightweight feedback after file edits.
+#
+# Fires on: PostToolUse
+# Matcher: Edit|MultiEdit|Write
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+TOOL_NAME="${CLAUDE_TOOL_NAME:-unknown}"
+
+if [ -z "$FILE_PATH" ]; then
+    echo "PostToolUse: ${TOOL_NAME} completed. Consider validating lint, tests, and docs if behavior changed."
+    exit 0
+fi
+
+case "$FILE_PATH" in
+    *.md|*.txt)
+        echo "PostToolUse: updated ${FILE_PATH}. If behavior or workflow changed, refresh related docs and examples."
+        ;;
+    *.bats|*.test.*|*.spec.*)
+        echo "PostToolUse: updated test file ${FILE_PATH}. Run the most relevant targeted test command next."
+        ;;
+    *.json|*.yml|*.yaml|*.toml)
+        echo "PostToolUse: updated config file ${FILE_PATH}. Validate syntax and any generated artifacts affected by this change."
+        ;;
+    *)
+        echo "PostToolUse: updated ${FILE_PATH}. If behavior changed, run validation, targeted tests, and update docs if needed."
+        ;;
+esac
+
+exit 0
+

package/app/hooks/pre-compact.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# pre-compact.sh — Save critical context before conversation compaction.
+#
+# Fires on: PreCompact
+# Outputs key context markers so they survive the compaction boundary.
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+# 1. Remind Claude to reload project rules after compaction
+echo "IMPORTANT: Context was compacted. Re-read CLAUDE.md files and active tasks before continuing."
+
+# 2. Preserve active task summary if available
+if [ -f ".claude/session-context.md" ]; then
+    echo "=== Pre-Compaction Context ==="
+    cat ".claude/session-context.md"
+    echo "=============================="
+fi
+
+# 3. Preserve active instincts
+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/quality-check.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# quality-check.sh — Multi-language lint check after Claude stops.
+#
+# Fires on: Stop
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+if [ -f pyproject.toml ] || [ -f setup.py ]; then
+    ruff check . 2>&1 | head -15
+elif [ -f package.json ] && [ -f tsconfig.json ]; then
+    npx tsc --noEmit 2>&1 | head -15 || true
+elif [ -f composer.json ] && [ -f vendor/bin/phpstan ]; then
+    vendor/bin/phpstan analyse 2>&1 | head -15 || true
+elif [ -f pubspec.yaml ]; then
+    dart analyze 2>&1 | head -15 || true
+elif [ -f go.mod ]; then
+    go vet ./... 2>&1 | head -15 || true
+fi
+
+exit 0

package/app/hooks/quality-gate.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# quality-gate.sh — Block task completion if lint/type errors found.
+#
+# Fires on: TaskCompleted
+# Exit 2 = block completion. Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+# Strict profile also runs mypy.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+if [ -f pyproject.toml ] || [ -f setup.py ]; then
+    ruff check . 2>&1 | head -30
+    exit_code=$?
+    if [ $exit_code -ne 0 ]; then
+        echo "QUALITY GATE FAILED: ruff found errors. Fix them before completing." >&2
+        exit 2
+    fi
+    if [ -d src ] && [ "$PROFILE" = "strict" ]; then
+        mypy --strict src/ 2>&1 | tail -5
+        exit_code=$?
+        if [ $exit_code -ne 0 ]; then
+            echo "QUALITY GATE FAILED: mypy found type errors." >&2
+            exit 2
+        fi
+    fi
+elif [ -f package.json ] && [ -f tsconfig.json ]; then
+    npx tsc --noEmit 2>&1 | tail -10
+    exit_code=$?
+    if [ $exit_code -ne 0 ]; then
+        echo "QUALITY GATE FAILED: TypeScript compilation errors." >&2
+        exit 2
+    fi
+elif [ -f pubspec.yaml ]; then
+    dart analyze 2>&1 | tail -10
+    exit_code=$?
+    if [ $exit_code -ne 0 ]; then
+        echo "QUALITY GATE FAILED: Dart analysis issues." >&2
+        exit 2
+    fi
+elif [ -f go.mod ]; then
+    go vet ./... 2>&1 | tail -10
+    exit_code=$?
+    if [ $exit_code -ne 0 ]; then
+        echo "QUALITY GATE FAILED: Go vet issues." >&2
+        exit 2
+    fi
+fi
+
+exit 0

package/app/hooks/save-session.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# save-session.sh — Persist session context on stop for cross-session continuity.
+#
+# Fires on: Stop
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+SESSION_FILE=".claude/session-context.md"
+
+if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+    mkdir -p .claude
+    cat > "$SESSION_FILE" << EOF
+# Session Context
+Updated: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+Session: ${CLAUDE_SESSION_ID:-unknown}
+
+## Last Active Task
+${CLAUDE_TASK_DESCRIPTION:-No task description available}
+EOF
+fi
+
+exit 0

package/app/hooks/session-end.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# session-end.sh — Persist a lightweight handoff note when a Claude session ends.
+#
+# Fires on: SessionEnd
+# Matcher: all
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+STATE_DIR=".claude"
+SESSION_FILE="$STATE_DIR/session-context.md"
+HANDOFF_FILE="$STATE_DIR/session-end.md"
+STAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date)"
+
+mkdir -p "$STATE_DIR"
+
+{
+    echo "# Session End Snapshot"
+    echo ""
+    echo "- ended_at: $STAMP"
+    if [ -f "$SESSION_FILE" ]; then
+        echo "- session_context: present"
+    else
+        echo "- session_context: missing"
+    fi
+    echo "- next_start: re-read CLAUDE.md, open tasks, and validation state"
+} > "$HANDOFF_FILE"
+
+if [ -f "$SESSION_FILE" ]; then
+    echo "SessionEnd: wrote .claude/session-end.md and preserved existing .claude/session-context.md for the next session."
+else
+    echo "SessionEnd: wrote .claude/session-end.md. Consider persisting open tasks in .claude/session-context.md before ending long workstreams."
+fi
+
+exit 0
+