@softspark/ai-toolkit 1.0.0

package/app/skills/tdd/reference/interface-design.md

@@ -0,0 +1,32 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+## 1. Accept dependencies, don't create them
+
+```typescript
+// Testable
+function processOrder(order, paymentGateway) {}
+
+// Hard to test
+function processOrder(order) {
+  const gateway = new StripeGateway();
+}
+```
+
+## 2. Return results, don't produce side effects
+
+```typescript
+// Testable
+function calculateDiscount(cart): Discount {}
+
+// Hard to test
+function applyDiscount(cart): void {
+  cart.total -= discount;
+}
+```
+
+## 3. Small surface area
+
+- Fewer methods = fewer tests needed
+- Fewer params = simpler test setup

package/app/skills/tdd/reference/mocking.md

@@ -0,0 +1,52 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes — prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+### 1. Use dependency injection
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+### 2. Prefer SDK-style interfaces over generic fetchers
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/app/skills/tdd/reference/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** — Extract function/class
+- **Long methods** — Break into private helpers (keep tests on public interface)
+- **Shallow modules** — Combine or deepen
+- **Feature envy** — Move logic to where data lives
+- **Primitive obsession** — Introduce value objects
+- **Existing code** the new code reveals as problematic

package/app/skills/tdd/reference/tests.md

@@ -0,0 +1,59 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/app/skills/teams/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: teams
+description: "Launch pre-configured Agent Teams for common workflows"
+effort: max
+user-invocable: true
+argument-hint: "<preset> [task-description]"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# /teams - Agent Teams Presets
+
+$ARGUMENTS
+
+## What This Does
+
+Launches a pre-configured Agent Teams composition for your task.
+
+Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+
+## Available Presets
+
+| Preset | Agents | Use Case |
+|--------|--------|----------|
+| `review` | code-reviewer, security-auditor, performance-optimizer | PR code review |
+| `debug` | debugger, backend-specialist, incident-responder | Multi-file bug investigation |
+| `feature` | orchestrator, backend-specialist, frontend-specialist, test-engineer | Full feature implementation |
+| `fullstack` | backend-specialist, frontend-specialist, database-architect, devops-implementer | Full-stack task |
+| `research` | technical-researcher, data-analyst, prompt-engineer | Deep research task |
+| `security` | security-architect, security-auditor, backend-specialist | Security audit |
+| `migration` | database-architect, backend-specialist, devops-implementer | Database migration |
+
+## Usage Examples
+
+```
+/teams review           # Launch review team on current changes
+/teams debug            # Launch debug team for current issue
+/teams feature          # Launch feature team for new feature
+/teams security         # Launch security audit team
+/teams migration        # Launch migration team
+```
+
+## Preset Definitions
+
+### review
+- **Agents**: code-reviewer (lead), security-auditor, performance-optimizer
+- **Ownership**: code-reviewer owns review summary; others own their domain reports
+- **Aggregation**: consensus — flag issues found by 2+ agents as high priority
+- **Output**: `REVIEW.md` with severity-ranked findings
+
+### debug
+- **Agents**: debugger (lead), backend-specialist, incident-responder
+- **Ownership**: debugger owns root-cause analysis; others own hypothesis testing
+- **Aggregation**: relay — debugger synthesizes findings from others
+- **Output**: `DEBUG_REPORT.md` with root cause and fix
+
+### feature
+- **Agents**: orchestrator (lead), backend-specialist, frontend-specialist, test-engineer
+- **Ownership**: orchestrator owns plan; specialists own their files; test-engineer owns tests
+- **Aggregation**: map-reduce — orchestrator integrates all outputs
+- **Output**: implemented feature + tests
+
+### fullstack
+- **Agents**: backend-specialist, frontend-specialist, database-architect, devops-implementer
+- **Ownership**: each agent owns their layer (API, UI, DB, infra)
+- **Aggregation**: relay — backend-specialist synthesizes integration
+- **Output**: full stack implementation
+
+### research
+- **Agents**: technical-researcher (lead), data-analyst, prompt-engineer
+- **Ownership**: technical-researcher owns synthesis; others own domain findings
+- **Aggregation**: consensus — areas of agreement highlighted
+- **Output**: `RESEARCH.md` with findings and recommendations
+
+### security
+- **Agents**: security-architect (lead), security-auditor, backend-specialist
+- **Ownership**: security-architect owns threat model; auditor owns findings; backend owns remediation
+- **Aggregation**: relay — security-architect integrates all
+- **Output**: `SECURITY_AUDIT.md` with CVSS-scored findings
+
+### migration
+- **Agents**: database-architect (lead), backend-specialist, devops-implementer
+- **Ownership**: database-architect owns schema; backend owns code changes; devops owns deployment
+- **Aggregation**: relay — database-architect coordinates sequence
+- **Output**: migration scripts + rollback plan + deployment runbook
+
+## Steps
+
+1. Parse `$ARGUMENTS` to extract `<preset>` and optional `[task-description]`
+2. Validate preset is one of: review, debug, feature, fullstack, research, security, migration
+3. Check `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set; warn if not
+4. Display the team composition and ownership rules
+5. Ask user to confirm before launching
+6. Launch the appropriate agents using the Agent tool with the task description
+7. Apply the aggregation strategy to synthesize results
+8. Produce the defined output document
+
+## Environment
+
+```bash
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+```

package/app/skills/test/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: test
+description: "Run tests with coverage analysis and reporting"
+effort: medium
+disable-model-invocation: true
+argument-hint: "[file or pattern]"
+allowed-tools: Bash, Read, Grep
+hooks:
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "echo 'Reminder: check test coverage meets threshold (>70%)'"
+---
+
+# Test Runner
+
+$ARGUMENTS
+
+Run tests based on detected project type.
+
+## Project context
+
+- Project config: !`cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat pubspec.yaml 2>/dev/null || echo "unknown"`
+
+## Auto-Detection
+
+Run the bundled script to detect test framework:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/detect-runner.py .
+```
+
+| File Found | Runner | Command |
+|------------|--------|---------|
+| `pyproject.toml` / `setup.py` | pytest | `pytest --cov=src --cov-report=term-missing tests/` |
+| `package.json` (vitest) | vitest | `npx vitest run --coverage` |
+| `package.json` (jest) | jest | `npx jest --coverage` |
+| `pubspec.yaml` | flutter test | `flutter test --coverage` |
+| `go.mod` | go test | `go test -cover ./...` |
+| `Cargo.toml` | cargo test | `cargo test` |
+| `composer.json` | phpunit | `./vendor/bin/phpunit --coverage-text` |
+
+## Usage
+
+```
+/test                        # Run all tests
+/test path/to/test_file      # Run specific test file
+/test -k "test_name"         # Run tests matching pattern
+/test --coverage             # Run with coverage report
+```
+
+## Common Options by Runner
+
+### Python (pytest)
+```bash
+pytest tests/                          # All tests
+pytest tests/unit/test_example.py      # Specific file
+pytest -k "test_search"               # Pattern match
+pytest --lf                            # Last failed only
+pytest -v                              # Verbose
+```
+
+### JavaScript/TypeScript (vitest/jest)
+```bash
+npx vitest run                         # All tests
+npx vitest run src/utils.test.ts       # Specific file
+npx vitest run --reporter=verbose      # Verbose
+npx jest --testPathPattern=utils       # Pattern match
+```
+
+### PHP (phpunit)
+```bash
+./vendor/bin/phpunit                   # All tests
+./vendor/bin/phpunit tests/Unit/ExampleTest.php  # Specific
+./vendor/bin/phpunit --filter testName # Pattern match
+```
+
+### Flutter/Dart
+```bash
+flutter test                           # All tests
+flutter test test/widget_test.dart     # Specific file
+dart test --name="pattern"             # Pattern match
+```
+
+### Go
+```bash
+go test ./...                          # All tests
+go test ./pkg/utils/                   # Specific package
+go test -run TestName ./...            # Pattern match
+go test -v ./...                       # Verbose
+```
+
+## Coverage Targets
+
+- Overall: >70%
+- Core modules: >80%
+- New code: 100% (for PRs)
+
+## Test Structure Convention
+
+```
+tests/               # or test/, spec/, __tests__/
+├── unit/            # Fast, isolated tests
+├── integration/     # Tests with external dependencies
+└── e2e/             # End-to-end tests
+```

package/app/skills/test/scripts/detect-runner.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Auto-detect test framework and runner from project configuration files.
+
+Scans a project directory for well-known config files (pyproject.toml,
+package.json, pubspec.yaml, go.mod, Cargo.toml, composer.json) and
+returns a JSON object describing the detected test runner, suggested
+command, test directories, estimated test-file count, and whether
+coverage reporting is configured.
+
+Usage::
+
+    python3 detect-runner.py [project_directory]
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+from _lib.detect_utils import count_files, read_json, read_text, run_detector
+
+
+def detect(project_dir: Path) -> dict[str, Any]:
+    """Detect the test runner for the given project directory."""
+    result: dict[str, Any] = {
+        "runner": None, "command": None, "test_dirs": [],
+        "test_count_estimate": 0, "coverage_enabled": False,
+        "detected_from": None
+    }
+
+    # Python: pyproject.toml / setup.py
+    pyproject = read_text(project_dir / "pyproject.toml")
+    if pyproject or (project_dir / "setup.py").exists():
+        result["runner"] = "pytest"
+        result["command"] = "pytest --cov=src --cov-report=term-missing tests/"
+        result["detected_from"] = "pyproject.toml" if pyproject else "setup.py"
+        if pyproject and "pytest" in pyproject:
+            result["coverage_enabled"] = "cov" in pyproject
+        for d in ["tests", "test"]:
+            if (project_dir / d).is_dir():
+                result["test_dirs"].append(d)
+        result["test_count_estimate"] = count_files(project_dir, [r'test_.*\.py$', r'.*_test\.py$'])
+        return result
+
+    # Node.js: package.json
+    pkg = read_json(project_dir / "package.json")
+    if pkg:
+        dev_deps = {**pkg.get("devDependencies", {}), **pkg.get("dependencies", {})}
+        scripts = pkg.get("scripts", {})
+        test_cmd = scripts.get("test", "")
+
+        if "vitest" in dev_deps or "vitest" in test_cmd:
+            result["runner"] = "vitest"
+            result["command"] = "npx vitest run --coverage"
+        elif "jest" in dev_deps or "jest" in test_cmd:
+            result["runner"] = "jest"
+            result["command"] = "npx jest --coverage"
+        elif "mocha" in dev_deps or "mocha" in test_cmd:
+            result["runner"] = "mocha"
+            result["command"] = "npx mocha"
+        else:
+            result["runner"] = "npm-test"
+            result["command"] = "npm test"
+
+        result["detected_from"] = "package.json"
+        result["coverage_enabled"] = "coverage" in test_cmd or "c8" in dev_deps or "istanbul" in str(dev_deps)
+        for d in ["__tests__", "test", "tests", "spec"]:
+            if (project_dir / d).is_dir():
+                result["test_dirs"].append(d)
+        result["test_count_estimate"] = count_files(project_dir, [r'\.test\.[jt]sx?$', r'\.spec\.[jt]sx?$', r'test_.*\.[jt]s$'])
+        return result
+
+    # Flutter/Dart
+    if (project_dir / "pubspec.yaml").exists():
+        result.update(runner="flutter", command="flutter test --coverage",
+                      detected_from="pubspec.yaml", coverage_enabled=True)
+        if (project_dir / "test").is_dir():
+            result["test_dirs"].append("test")
+        result["test_count_estimate"] = count_files(project_dir, [r'_test\.dart$'])
+        return result
+
+    # Go
+    if (project_dir / "go.mod").exists():
+        result.update(runner="go", command="go test -cover ./...",
+                      detected_from="go.mod", coverage_enabled=True)
+        result["test_count_estimate"] = count_files(project_dir, [r'_test\.go$'])
+        return result
+
+    # Rust
+    if (project_dir / "Cargo.toml").exists():
+        result.update(runner="cargo", command="cargo test", detected_from="Cargo.toml")
+        result["test_count_estimate"] = count_files(project_dir, [r'\.rs$'])
+        return result
+
+    # PHP
+    if (project_dir / "composer.json").exists():
+        result.update(runner="phpunit", command="./vendor/bin/phpunit --coverage-text",
+                      detected_from="composer.json")
+        for d in ["tests", "test"]:
+            if (project_dir / d).is_dir():
+                result["test_dirs"].append(d)
+        result["test_count_estimate"] = count_files(project_dir, [r'Test\.php$', r'test_.*\.php$'])
+        return result
+
+    result["runner"] = "unknown"
+    result["command"] = None
+    result["detected_from"] = None
+    return result
+
+
+if __name__ == "__main__":
+    run_detector(detect)

package/app/skills/testing-patterns/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: testing-patterns
+description: "Loaded when user asks about testing strategy, fixtures, or mocking"
+effort: medium
+user-invocable: false
+---
+
+# Testing Patterns Skill
+
+## Test Structure (AAA Pattern)
+
+```python
+def test_function_does_expected_thing():
+    """Test description explaining what and why."""
+    # Arrange - Set up test data and preconditions
+    input_data = {"key": "value"}
+    expected = "result"
+
+    # Act - Execute the code under test
+    result = function_under_test(input_data)
+
+    # Assert - Verify the outcome
+    assert result == expected
+```
+
+---
+
+## Test Organization
+
+```
+tests/
+├── conftest.py           # Shared fixtures
+├── unit/                 # Unit tests (isolated)
+│   ├── test_search_core.py
+│   └── test_utils.py
+├── integration/          # Integration tests
+│   └── test_api.py
+└── e2e/                  # End-to-end tests
+    └── test_workflow.py
+```
+
+---
+
+## Quality Targets
+
+| Metric | Target |
+|--------|--------|
+| Coverage | >70% overall |
+| New code | 100% |
+| Core modules | >80% |
+| No flaky tests | 0 |
+
+---
+
+## Language-Specific References
+
+| Language | Reference | Key Topics |
+|----------|-----------|------------|
+| Python | [reference/python-pytest.md](reference/python-pytest.md) | Fixtures, mocking, parametrize, markers, conftest, running tests |
+| TypeScript | [reference/typescript-vitest.md](reference/typescript-vitest.md) | Vitest/Jest, React Testing Library, mocking, running tests |
+| PHP | [reference/php-phpunit.md](reference/php-phpunit.md) | PHPUnit test cases, mocking, running tests |
+| Go | [reference/go-testing.md](reference/go-testing.md) | Table-driven tests, testify mocking, running tests |
+| Flutter/Dart | [reference/flutter-testing.md](reference/flutter-testing.md) | Widget tests, unit tests, running tests |
+
+For Python pytest patterns, see [reference/python-pytest.md](reference/python-pytest.md).
+
+For TypeScript Vitest/Jest patterns, see [reference/typescript-vitest.md](reference/typescript-vitest.md).
+
+For PHP PHPUnit patterns, see [reference/php-phpunit.md](reference/php-phpunit.md).
+
+For Go testing patterns, see [reference/go-testing.md](reference/go-testing.md).
+
+For Flutter/Dart testing patterns, see [reference/flutter-testing.md](reference/flutter-testing.md).

package/app/skills/testing-patterns/reference/flutter-testing.md

@@ -0,0 +1,33 @@
+# Flutter/Dart Testing Patterns
+
+## Widget Test
+
+```dart
+testWidgets('Counter increments', (WidgetTester tester) async {
+  await tester.pumpWidget(const MyApp());
+  expect(find.text('0'), findsOneWidget);
+  await tester.tap(find.byIcon(Icons.add));
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+});
+```
+
+## Unit Test
+
+```dart
+test('User model parses JSON', () {
+  final json = {'name': 'Test', 'email': 'test@test.com'};
+  final user = User.fromJson(json);
+  expect(user.name, equals('Test'));
+  expect(user.email, equals('test@test.com'));
+});
+```
+
+## Running
+
+```bash
+flutter test                          # All tests
+flutter test --coverage               # With coverage
+flutter test test/widget_test.dart    # Specific file
+dart test --name="pattern"            # Pattern match
+```

package/app/skills/testing-patterns/reference/go-testing.md

@@ -0,0 +1,52 @@
+# Go Testing Patterns
+
+## Table-Driven Tests
+
+```go
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive", 1, 2, 3},
+        {"negative", -1, -2, -3},
+        {"zero", 0, 0, 0},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            if result != tt.expected {
+                t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+## Mocking (testify)
+
+```go
+type MockRepo struct { mock.Mock }
+func (m *MockRepo) Find(id string) (*User, error) {
+    args := m.Called(id)
+    return args.Get(0).(*User), args.Error(1)
+}
+
+func TestService(t *testing.T) {
+    repo := new(MockRepo)
+    repo.On("Find", "1").Return(&User{Name: "Test"}, nil)
+    svc := NewService(repo)
+    user, _ := svc.GetUser("1")
+    assert.Equal(t, "Test", user.Name)
+}
+```
+
+## Running
+
+```bash
+go test ./...                  # All tests
+go test -cover ./...           # With coverage
+go test -run TestAdd ./pkg/    # Specific test
+go test -v ./...               # Verbose
+```

package/app/skills/testing-patterns/reference/php-phpunit.md

@@ -0,0 +1,39 @@
+# PHP PHPUnit Patterns
+
+## Basic Test
+
+```php
+class UserServiceTest extends TestCase
+{
+    public function test_creates_user_with_valid_data(): void
+    {
+        $service = new UserService();
+        $user = $service->create(['name' => 'Test', 'email' => 't@t.com']);
+        $this->assertEquals('Test', $user->name);
+    }
+
+    public function test_throws_on_invalid_email(): void
+    {
+        $this->expectException(ValidationException::class);
+        $service = new UserService();
+        $service->create(['name' => 'Test', 'email' => 'invalid']);
+    }
+}
+```
+
+## Mocking
+
+```php
+$mock = $this->createMock(Repository::class);
+$mock->method('find')->willReturn(new User('Test'));
+$service = new UserService($mock);
+```
+
+## Running
+
+```bash
+./vendor/bin/phpunit                          # All tests
+./vendor/bin/phpunit --coverage-text          # With coverage
+./vendor/bin/phpunit tests/Unit/UserTest.php  # Specific file
+./vendor/bin/phpunit --filter testName        # Pattern match
+```