@softspark/ai-toolkit 1.0.0

package/app/skills/fix/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: fix
+description: "Auto-fix lint errors, type issues, and simple bugs"
+effort: low
+disable-model-invocation: true
+argument-hint: "[test or lint target]"
+allowed-tools: Bash, Read, Edit, Grep
+---
+
+# Fix Command
+
+$ARGUMENTS
+
+Attempts to fix code errors autonomously.
+
+## Usage
+
+```bash
+/fix <file_or_scope>
+# Example: /fix src/utils.ts
+```
+
+## Automated Error Classification
+
+Before entering the fix loop, classify errors to prioritize auto-fixable ones:
+
+```bash
+# Pipe lint or test output
+ruff check . 2>&1 | python3 "$(dirname "$0")/scripts/error-classifier.py"
+mypy src/ 2>&1 | python3 scripts/error-classifier.py
+npx eslint . 2>&1 | python3 scripts/error-classifier.py
+```
+
+The script outputs JSON with:
+- **total_errors**: count of all parsed errors
+- **auto_fixable_count**: errors that tools can fix automatically (e.g., F401 unused imports, formatting)
+- **manual_count**: errors requiring human/agent intervention
+- **tools_detected**: which linters produced the output (ruff, mypy, eslint, tsc, phpstan)
+- **errors[]**: each error with file, line, code, message, and auto_fixable flag
+- **suggested_order**: files to fix, auto-fixable first
+- **fix_strategy**: recommended approach (auto-fix first, then manual)
+
+Use this to run auto-fixers (e.g., `ruff check --fix .`) before spending time on manual fixes.
+
+---
+
+## Protocol (The "Fix Loop")
+
+1. **Analyze**: Run validation to get the exact error message.
+   ```bash
+   # Get error
+   npm test src/utils.ts 2>&1 | tee error.log
+   ```
+
+2. **Diagnose**: Analyze `error.log`.
+   - Use `debugging-tactics` skill.
+   - Trace the error to the source line.
+
+3. **Patch**: Apply a fix.
+   - Use `sed` or `write_file`.
+
+4. **Verify**: Run validation again.
+   - If PASS: Stop.
+   - If FAIL: Repeat (Max 3 retries).
+
+## Safety Limits
+- **Max Retries**: 3
+- **Scope**: Only modify the specified files.
+- **Stop Condition**: If new errors appear that are totally different, STOP and ask user.
+
+## Example Flow
+```
+User: /fix app.py
+Agent: Running tests... FAIL (NameError)
+Agent: Fixing app.py (Import missing module)
+Agent: Running tests... PASS
+Agent: Fixed NameError in app.py
+```

package/app/skills/fix/scripts/error-classifier.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Parse lint/test error output from stdin and classify as auto-fixable or manual.
+
+Reads multi-tool error output (ruff, mypy, ESLint, tsc, phpstan) from
+stdin, parses each line into structured records, and classifies every
+error as either auto-fixable or requiring manual intervention. The
+output is a JSON object with error counts, a prioritised file order
+(auto-fixable first), and a suggested fix strategy.
+
+Usage::
+
+    ruff check . 2>&1 | python3 error-classifier.py
+    mypy src/ 2>&1 | python3 error-classifier.py
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from typing import Any
+
+
+# Patterns to parse error formats: (file, line, col_or_none, code_or_none, message)
+ERROR_PARSERS: dict[str, re.Pattern[str]] = {
+    "ruff": re.compile(r"^(.+?):(\d+):(\d+):\s+([A-Z]\d+)\s+(.+)$"),
+    "mypy": re.compile(r"^(.+?):(\d+):\s+error:\s+(.+?)(?:\s+\[(.+)\])?$"),
+    "eslint": re.compile(r"^\s*(\d+):(\d+)\s+(error|warning)\s+(.+?)\s+(\S+)$"),
+    "tsc": re.compile(r"^(.+?)\((\d+),(\d+)\):\s+error\s+(TS\d+):\s+(.+)$"),
+    "phpstan": re.compile(r"^(.+?):(\d+)\s+(.+)$"),
+}
+
+# Auto-fixable error codes/patterns
+AUTO_FIXABLE: dict[str, str] = {
+    # Ruff
+    "F401": "unused import",
+    "F841": "unused variable",
+    "W291": "trailing whitespace",
+    "W292": "no newline at end of file",
+    "W293": "whitespace before ':'",
+    "E301": "expected blank lines",
+    "E302": "expected 2 blank lines",
+    "E303": "too many blank lines",
+    "E501": "line too long",
+    "I001": "import sort order",
+    "C408": "unnecessary dict/list call",
+    "UP": "pyupgrade",
+    # ESLint
+    "no-unused-vars": "unused variable",
+    "semi": "missing semicolon",
+    "indent": "indentation",
+    "quotes": "quote style",
+    "comma-dangle": "trailing comma",
+    "eol-last": "newline at end",
+}
+
+
+def is_auto_fixable(code: str | None) -> bool:
+    """Check if an error code is auto-fixable.
+
+    Matches exact codes and short prefix patterns (e.g. ``"UP"`` matches
+    ``"UP006"``).
+
+    Args:
+        code: The error code string, or ``None``.
+
+    Returns:
+        ``True`` if the error can be fixed automatically.
+    """
+    if not code:
+        return False
+    if code in AUTO_FIXABLE:
+        return True
+    # Check prefix matches (e.g., UP006 matches "UP")
+    for prefix in AUTO_FIXABLE:
+        if len(prefix) <= 3 and code.startswith(prefix):
+            return True
+    return False
+
+
+def _err(
+    tool: str,
+    file: str,
+    line: str | int,
+    col: str | int,
+    code: str | None,
+    msg: str,
+) -> dict[str, Any]:
+    """Build a structured error dictionary.
+
+    Args:
+        tool: Name of the tool that produced the error.
+        file: Source file path.
+        line: Line number (converted to int).
+        col: Column number (converted to int).
+        code: Error code or rule identifier.
+        msg: Human-readable error message.
+
+    Returns:
+        Dictionary with tool, file, line, column, code, message, and
+        auto_fixable flag.
+    """
+    return {"tool": tool, "file": file, "line": int(line), "column": int(col),
+            "code": code, "message": msg, "auto_fixable": is_auto_fixable(code)}
+
+
+def parse_errors(text: str) -> list[dict[str, Any]]:
+    """Parse multi-tool error output and return structured error records.
+
+    Supports ruff, mypy, tsc, and ESLint output formats. ESLint is
+    detected via a file-header line followed by indented error lines.
+
+    Args:
+        text: Raw error output text, typically from stdout/stderr.
+
+    Returns:
+        List of structured error dictionaries.
+    """
+    errors: list[dict[str, Any]] = []
+    eslint_file: str | None = None
+    for line in text.strip().split("\n"):
+        line = line.rstrip()
+        if not line:
+            continue
+        m = ERROR_PARSERS["ruff"].match(line)
+        if m:
+            errors.append(_err("ruff", m[1], m[2], m[3], m[4], m[5]))
+            continue
+        m = ERROR_PARSERS["mypy"].match(line)
+        if m:
+            errors.append(_err("mypy", m[1], m[2], 0, m[4] or "mypy", m[3]))
+            continue
+        m = ERROR_PARSERS["tsc"].match(line)
+        if m:
+            errors.append(_err("tsc", m[1], m[2], m[3], m[4], m[5]))
+            continue
+        # ESLint: file header then indented errors
+        if re.match(r"^[/.]", line) and not re.search(r":\d+", line):
+            eslint_file = line.strip()
+            continue
+        m = ERROR_PARSERS["eslint"].match(line)
+        if m and eslint_file:
+            errors.append(_err("eslint", eslint_file, m[1], m[2], m[5], m[4]))
+    return errors
+
+
+def main() -> None:
+    """Entry point: read stdin, classify errors, and print JSON to stdout."""
+    text = sys.stdin.read()
+    if not text.strip():
+        print(json.dumps({"error": "No input provided. Pipe lint/test output to stdin."}))
+        return
+
+    errors = parse_errors(text)
+    auto_fixable = [e for e in errors if e["auto_fixable"]]
+    manual = [e for e in errors if not e["auto_fixable"]]
+
+    # Group by file for suggested order
+    file_order: list[str] = []
+    seen: set[str] = set()
+    # Auto-fixable files first
+    for e in auto_fixable:
+        if e["file"] not in seen:
+            seen.add(e["file"])
+            file_order.append(e["file"])
+    # Then manual files
+    for e in manual:
+        if e["file"] not in seen:
+            seen.add(e["file"])
+            file_order.append(e["file"])
+
+    # Tool summary
+    tools_detected = list(set(e["tool"] for e in errors))
+
+    result: dict[str, Any] = {
+        "total_errors": len(errors),
+        "auto_fixable_count": len(auto_fixable),
+        "manual_count": len(manual),
+        "tools_detected": tools_detected,
+        "errors": errors,
+        "suggested_order": file_order,
+        "fix_strategy": (
+            "Run auto-fix first (e.g., ruff check --fix .), then address manual errors."
+            if auto_fixable
+            else "All errors require manual intervention."
+        ),
+    }
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,254 @@
+---
+name: flutter-patterns
+description: "Loaded when user asks about Flutter or Dart development patterns"
+effort: medium
+user-invocable: false
+---
+
+# Flutter Patterns Skill
+
+## Project Structure
+
+```
+lib/
+├── main.dart
+├── app.dart
+├── core/
+│   ├── constants/
+│   ├── errors/
+│   ├── network/
+│   └── utils/
+├── features/
+│   └── feature_name/
+│       ├── data/
+│       │   ├── models/
+│       │   ├── repositories/
+│       │   └── sources/
+│       ├── domain/
+│       │   ├── entities/
+│       │   └── usecases/
+│       └── presentation/
+│           ├── bloc/
+│           ├── pages/
+│           └── widgets/
+└── shared/
+    ├── widgets/
+    └── theme/
+```
+
+---
+
+## State Management
+
+### BLoC Pattern
+```dart
+// Event
+abstract class AuthEvent {}
+class LoginRequested extends AuthEvent {
+  final String email;
+  final String password;
+  LoginRequested(this.email, this.password);
+}
+
+// State
+abstract class AuthState {}
+class AuthInitial extends AuthState {}
+class AuthLoading extends AuthState {}
+class AuthSuccess extends AuthState {
+  final User user;
+  AuthSuccess(this.user);
+}
+class AuthFailure extends AuthState {
+  final String message;
+  AuthFailure(this.message);
+}
+
+// BLoC
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  AuthBloc() : super(AuthInitial()) {
+    on<LoginRequested>(_onLoginRequested);
+  }
+
+  Future<void> _onLoginRequested(
+    LoginRequested event,
+    Emitter<AuthState> emit,
+  ) async {
+    emit(AuthLoading());
+    try {
+      final user = await authRepository.login(event.email, event.password);
+      emit(AuthSuccess(user));
+    } catch (e) {
+      emit(AuthFailure(e.toString()));
+    }
+  }
+}
+```
+
+### Riverpod
+```dart
+final userProvider = FutureProvider<User>((ref) async {
+  final repository = ref.watch(userRepositoryProvider);
+  return repository.getUser();
+});
+
+// Usage
+Consumer(
+  builder: (context, ref, child) {
+    final userAsync = ref.watch(userProvider);
+    return userAsync.when(
+      data: (user) => Text(user.name),
+      loading: () => CircularProgressIndicator(),
+      error: (e, s) => Text('Error: $e'),
+    );
+  },
+)
+```
+
+---
+
+## Navigation (GoRouter)
+
+```dart
+final router = GoRouter(
+  routes: [
+    GoRoute(
+      path: '/',
+      builder: (context, state) => HomeScreen(),
+      routes: [
+        GoRoute(
+          path: 'details/:id',
+          builder: (context, state) => DetailsScreen(
+            id: state.pathParameters['id']!,
+          ),
+        ),
+      ],
+    ),
+  ],
+);
+
+// Navigation
+context.go('/details/123');
+context.push('/details/123');
+context.pop();
+```
+
+---
+
+## Widget Patterns
+
+### Responsive Layout
+```dart
+class ResponsiveLayout extends StatelessWidget {
+  final Widget mobile;
+  final Widget? tablet;
+  final Widget desktop;
+
+  @override
+  Widget build(BuildContext context) {
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        if (constraints.maxWidth < 600) {
+          return mobile;
+        } else if (constraints.maxWidth < 1200) {
+          return tablet ?? desktop;
+        }
+        return desktop;
+      },
+    );
+  }
+}
+```
+
+### Sliver Patterns
+```dart
+CustomScrollView(
+  slivers: [
+    SliverAppBar(
+      floating: true,
+      title: Text('Title'),
+    ),
+    SliverPadding(
+      padding: EdgeInsets.all(16),
+      sliver: SliverList(
+        delegate: SliverChildBuilderDelegate(
+          (context, index) => ListTile(title: Text('Item $index')),
+          childCount: 100,
+        ),
+      ),
+    ),
+  ],
+)
+```
+
+---
+
+## Performance
+
+### const Constructors
+```dart
+// Good
+const Text('Hello');
+const SizedBox(height: 8);
+
+// Widget with const constructor
+class MyWidget extends StatelessWidget {
+  const MyWidget({super.key});
+}
+```
+
+### RepaintBoundary
+```dart
+RepaintBoundary(
+  child: ComplexAnimatedWidget(),
+)
+```
+
+### Image Optimization
+```dart
+Image.network(
+  url,
+  cacheWidth: 200,  // Resize in memory
+  cacheHeight: 200,
+)
+```
+
+---
+
+## Testing
+
+### Widget Testing
+```dart
+testWidgets('Counter increments', (tester) async {
+  await tester.pumpWidget(MyApp());
+
+  expect(find.text('0'), findsOneWidget);
+
+  await tester.tap(find.byIcon(Icons.add));
+  await tester.pump();
+
+  expect(find.text('1'), findsOneWidget);
+});
+```
+
+### BLoC Testing
+```dart
+blocTest<AuthBloc, AuthState>(
+  'emits [loading, success] when login succeeds',
+  build: () => AuthBloc(),
+  act: (bloc) => bloc.add(LoginRequested('email', 'pass')),
+  expect: () => [AuthLoading(), isA<AuthSuccess>()],
+);
+```
+
+---
+
+## Best Practices
+
+- ✅ Use const constructors
+- ✅ Extract widgets to separate files
+- ✅ Use named routes
+- ✅ Implement proper error handling
+- ✅ Use proper state management
+- ❌ Avoid setState for complex state
+- ❌ Don't nest too many widgets
+- ❌ Avoid magic numbers

package/app/skills/git-mastery/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: git-mastery
+description: "Loaded when user asks about advanced Git workflows or history rewriting"
+effort: medium
+user-invocable: false
+allowed-tools: Bash
+---
+
+# Git Mastery Skill
+
+## 🛡️ Safety First Protocol
+- **Never** force push to `main` / `master` / `develop`.
+- **Always** use `--force-with-lease` instead of `--force`.
+- **Always** create a backup branch before complex operations:
+  `git branch backup/feature-xyz-pre-rebase`
+
+## Advanced Workflows
+
+### 1. Automated Bug Hunting (Git Bisect)
+Find the specific commit that introduced a bug.
+```bash
+# Start
+git bisect start
+git bisect bad              # Current version is broken
+git bisect good <commit-sha> # Version that worked
+
+# Automate with test script
+git bisect run pytest tests/test_failing_feature.py
+```
+
+### 2. Interactive Interactive Rebase
+Clean up commit history before merge.
+```bash
+git rebase -i HEAD~n
+```
+- **squash**: Combine commits.
+- **reword**: Fix messages.
+- **dropped**: Remove junk commits.
+
+### 3. Log Analysis
+Visualize branch topology.
+```bash
+git log --graph --oneline --decorate --all
+```
+
+### 4. Recovery (Reflog)
+Recover "lost" commits after a bad reset/rebase.
+```bash
+git reflog
+git reset --hard HEAD@{n}
+```
+
+### 5. Cherry Picking
+Pick specific commits from other branches.
+```bash
+git cherry-pick <commit-sha>
+# If valid conflict
+git add .
+git cherry-pick --continue
+```
+
+## Commit Message Standard (Conventional Commits)
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation only
+- `style:` Formatting (white-space, etc)
+- `refactor:` Code change that neither fixes a bug nor adds a feature
+- `perf:` Performance improvement
+- `test:` Adding missing tests
+- `chore:` Build process/auxiliary tools

package/app/skills/grill-me/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: grill-me
+description: "Stress-test a plan or design through relentless Socratic questioning, walking down each decision branch until reaching shared understanding. Use when user wants to stress-test a plan, get grilled, validate assumptions, or mentions 'grill me'."
+user-invocable: true
+effort: medium
+argument-hint: "[plan or design to stress-test]"
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Grill Me
+
+$ARGUMENTS
+
+Interview relentlessly about every aspect of the plan until reaching shared understanding.
+
+## Usage
+
+```
+/grill-me [plan or design to stress-test]
+```
+
+## What This Command Does
+
+1. **Reads** the plan or design (from context, file, or user description)
+2. **Walks** down each branch of the decision tree
+3. **Resolves** dependencies between decisions one-by-one
+4. **Provides** recommended answers for each question
+5. **Continues** until shared understanding is reached
+
+## Rules
+
+- Ask questions **one at a time**
+- For each question, provide your **recommended answer**
+- If a question can be answered by **exploring the codebase**, explore instead of asking
+- Resolve dependencies between decisions — don't skip ahead
+- Be relentless — don't settle for vague or hand-wavy answers
+- Challenge assumptions, not just surface decisions
+- Apply Devil's Advocate critique to every major decision